Custom resource reference¶

Detailed reference for each Kollect API kind. These pages document purpose, spec fields, status conditions, RBAC, sample usage, and failure modes for operators and platform teams.

Pre-beta API

All kinds are v1alpha1. Field names, status conditions, and webhook rules may change before beta. Treat PLATFORM-DECISIONS.md as the locked decision summary; per-kind pages track current behavior.

Architecture context¶

Doc	Contents
concepts/architecture.md	CRD model, reconciliation, deployment defaults
concepts/export-pipeline.md	Debouncing, collection pipeline, scope gates, connection tests
PLATFORM-DECISIONS.md	Locked product decisions (2026-06-05 pivot)
getting-started/first-inventory.md	End-to-end Profile → Sink → Target → Inventory
examples/helm-release-inventory.md	Argo / Helm release walkthrough

Pipeline overview¶

flowchart LR
  Profile[KollectProfile<br/>what to extract]
  Scope[KollectScope<br/>policy]
  Target[KollectTarget<br/>what to watch]
  Inv[KollectInventory<br/>aggregate + export]
  Snap[KollectSnapshotSink]
  Db[KollectDatabaseSink]
  Ev[KollectEventSink]
  ConnTest[KollectConnectionTest<br/>probe]
  CTarget[KollectClusterTarget]
  CInv[KollectClusterInventory]

  Profile --> Target
  Scope -.-> Target
  Scope -.-> Inv
  Target --> Inv
  Inv --> Snap
  Inv --> Db
  Inv --> Ev
  ConnTest -.-> Snap
  ConnTest -.-> Db
  ConnTest -.-> Ev
  Profile -.->|"profileRef (name + namespace)"| CTarget
  CTarget -.-> CInv
  CInv -.-> Snap
  CInv -.-> Db
  CInv -.-> Ev

Typical team flow: create Profile and family Sinks → bind Target to Profile → point Inventory at snapshot/database/event sink refs. Optional Scope constrains GVKs, namespaces, and sinks. Use ConnectionTest to verify sink reachability before export.

Namespace rules

On namespaced kinds, profileRef, family sink refs (snapshotSinkRefs, databaseSinkRefs, eventSinkRefs), and connection-test sinkRef resolve CRs in the same namespace as the referring object. On cluster kinds, profileRef requires an explicit name + namespace; cluster-inventory sink refs resolve by name + namespace, defaulting to spec.sinkNamespace when a ref omits namespace. There are no cluster-scoped static config kinds (ADR-0208).

Platform flow: publish a namespaced KollectProfile (and family sinks) in kollect-system, then KollectClusterTarget → KollectClusterInventory roll up and export cross-namespace. Both cluster reconciled kinds reference the namespaced static config by name + namespace (ADR-0208).

Snapshot export layout and inline cap¶

KollectSnapshotSink.spec.pathTemplate selects the Git/object-store object path (default inventory/{namespace}/{name}.json; placeholders {cluster}, {namespace}, {name}, {generation}, {extension}) — see ADR-0407.

Payloads ≥ 1 MiB warn; > 1 MiB require an s3 or gcs snapshot sink in spec.snapshotSinkRefs (Git receives smaller exports only). There is no automatic spill write path: an oversize payload for a non-object-store sink fails loudly with Degraded/SpillRequired instead of being silently dropped. The hard cap ~1.5 MiB maxExportBytes blocks export entirely. The ceiling is configurable per sink binding: each inventory family ref accepts a maxExportBytes override that replaces the inventory-wide value (or, on cluster inventories, the global cap) for that sink only — see KollectInventory. Multipart partitioning applies to snapshot-family bindings only; database and event sinks always receive one complete payload. Because the inline cap applies per part, a Git binding that must carry more than 1 MiB in total should set its per-binding maxExportBytes at or below 1 MiB so every part stays under the cap; otherwise the oversize part fails with SpillRequired.

For database and event sinks the per-binding maxExportBytes is a soft bound: because those sinks cannot be split, the complete set is still exported and a Warning Event (ExportCeilingExceeded) records that the configured ceiling was exceeded.

Per-sink export cadence is configured on inventory/cluster-inventory family refs (string or object), optional sink defaults, and scope floors — ADR-0413.

Kinds¶

Kind	Scope	Reconciled	Reference
`KollectProfile`	Namespace	No	crds/kollectprofile.md
`KollectSnapshotSink`	Namespace	Probe only	crds/kollectsnapshotsink.md
`KollectDatabaseSink`	Namespace	Probe only	crds/kollectdatabasesink.md
`KollectEventSink`	Namespace	Probe only	crds/kollecteventsink.md
`KollectTarget`	Namespace	Yes	crds/kollecttarget.md
`KollectInventory`	Namespace	Yes	crds/kollectinventory.md
`KollectScope`	Namespace	No (enforced)	crds/kollectscope.md
`KollectConnectionTest`	Namespace	Yes	crds/kollectconnectiontest.md
`KollectClusterScope`	Cluster	No (enforced)	crds/kollectclusterscope.md
`KollectClusterTarget`	Cluster	Yes	crds/kollectclustertarget.md
`KollectClusterInventory`	Cluster	Yes	crds/kollectclusterinventory.md

Reserved kinds (stubs pending)¶

Kind	Scope	Notes
~~`KollectSink`~~	—	Removed — use family sinks (ADR-0414)
~~`KollectClusterProfile`~~	—	Removed — reference a namespaced `KollectProfile` by `name` + `namespace` (ADR-0208)
~~`KollectCluster*Sink`~~	—	Removed — reference namespaced family sinks per ref namespace (ADR-0208)
~~`KollectRemoteCluster`~~	—	Removed — shared sink + `spec.cluster` (ADR-0501)

Short names¶

Kind	Short name	`kubectl` example
`KollectInventory`	`kinv`	`kubectl get kinv -A`
`KollectTarget`	`ktgt`	`kubectl get ktgt -n default`
`KollectClusterTarget`	`kctgt`	`kubectl get kctgt`
`KollectClusterInventory`	`kcinv`	`kubectl get kcinv`
`KollectConnectionTest`	`kconntest`	`kubectl get kconntest -A`
`KollectScope`	`kscope`	`kubectl get kscope -A`

Quick apply¶

kubectl apply -k config/samples/            # profiles / targets / scopes
kubectl apply -k config/samples/advanced/  # sinks + inventories (Secrets required)
kubectl get kprof,ksnap,kdb,kevt,ktgt,kinv,kscope,kconntest -A

See getting-started/install.md for kind cluster install prerequisites.