Architecture Decision Records
Architecture decisions for Kollect. Numbers are grouped by
theme (0Txx) so the index reads as a system overview — foundations → API → collection →
export → fleet → observability → project engineering.
Status: Current · Exploring (RFC / spike) · Parked · Dropped
Each ADR uses Context / Decision / Consequences — written for readers who need the design,
not the project timeline.
New readers: REQUIREMENTS.md → theme 02 (CRD model) → 03 (collection) → 04 (sinks).
Five ADRs that explain Kollect
Start here if forty-eight ADRs feels like a wall. Each stands alone; together they tell the product
story an adopter needs.
Then drill into 0414 — Sink family CRDs when wiring sinks, or
0603 — Performance targets when sizing a deployment.
01 · Foundations
| ADR |
Title |
Status |
| 0101 |
Kubebuilder v4 + controller-runtime |
Current |
| 0102 |
Prior art and OSS reference patterns |
Current |
| 0103 |
Data storage and the etcd size limit |
Current |
| 0104 |
Security model — secrets, TLS, RBAC, redaction |
Current |
| 0105 |
Webhook serving and certificate management |
Current |
02 · API & tenancy
| ADR |
Title |
Status |
| 0201 |
CRD model — prefixed kinds, static vs reconciled |
Current |
| 0202 |
Static config vs reconciled CRDs |
Current |
| 0203 |
Namespaced multi-tenancy and operator watch scope |
Current |
| 0204 |
Namespaced KollectProfile |
Current |
| 0205 |
Watch opt-in / opt-out labels |
Current |
| 0206 |
API versioning and conversion strategy |
Exploring |
| 0207 |
Target collection filtering |
Current |
| 0208 |
Cluster kinds reference namespaced profiles/sinks |
Exploring |
| ADR |
Title |
Status |
| 0301 |
Event-driven dynamic informers (one per GVK) |
Current |
| 0302 |
CEL and JSONPath attribute extraction |
Current |
| 0303 |
Helm / Argo release inventory sample + redaction |
Current |
| 0304 |
Custom-resource metrics and richer aggregation |
Exploring |
| 0305 |
Aggregation, row identity, and dedupe semantics |
Current |
| 0306 |
Full resource export with path pruning |
Accepted |
04 · Export, sinks, read API & UI
| ADR |
Title |
Status |
| 0401 |
Sink taxonomy — state stores vs event emitters |
Current |
| 0402 |
Postgres and Kafka sink backends |
Current |
| 0403 |
Connection test — sink probes + KollectConnectionTest CR |
Current |
| 0404 |
Inventory HTTP API authentication |
Current |
| 0405 |
Export data contract and schema versioning |
Current |
| 0406 |
Sink registry and the Backend interface |
Current |
| 0407 |
Git / object-store export layout and workflow |
Current |
| 0408 |
Read API and UI architecture (pluggable backing store) |
Current |
| 0409 |
Kollect UI deployment — separate static SPA image |
Current |
| 0410 |
UI engineering and quality gates |
Current |
| 0411 |
Read API extensions for UI |
Current |
| 0412 |
Mock Read API for UI development |
Current |
| 0413 |
Per-sink export interval scheduling |
Current |
| 0414 |
Sink family CRDs (KollectSnapshotSink, etc.) |
Current |
| 0415 |
Git sink commit ergonomics |
Current |
| 0416 |
Sink configuration layering |
Current |
| 0417 |
MongoDB database sink |
Current |
| 0418 |
Fleet console read plane (event-fed, cluster dimension) |
Exploring |
| 0419 |
Git export serialization and layout (YAML default, zero-config) |
Current |
05 · Multi-cluster fleet
| ADR |
Title |
Status |
| 0501 |
Multi-cluster fleet — shared sink fan-in |
Current |
06 · Observability & ops
| ADR |
Title |
Status |
| 0601 |
Operator metrics (no Prometheus export sink) |
Current |
| 0602 |
Error taxonomy and reconcile behavior |
Current |
| 0603 |
Performance and scalability targets |
Current |
| 0604 |
Target- and inventory-scoped Prometheus metrics |
Exploring |
| 0605 |
OpenTelemetry tracing |
Exploring |
07 · Project engineering
| ADR |
Title |
Status |
| 0701 |
MkDocs Material documentation site |
Current |
| 0702 |
Doc-sync / Confluence publication |
Dropped |
| 0704 |
Helm chart and CRD lifecycle |
Current |
| 0705 |
Release engineering and supply chain |
Current |
| 0706 |
Testing and merge-gate architecture |
Current |
See ARCHITECTURE.md, PLATFORM-DECISIONS.md,
development/adr-rfc-process.md.