Simple to start · platform-grade to grow

Kollect

Turn Kubernetes state into durable inventory. Declare what matters once. Kollect keeps it current and delivers it to Git, object storage, databases, and event streams. Select resources by GVK, extract the attributes you need with CEL or JSONPath, and every sink receives the same canonical rows in parallel.

Start with one sink. Grow to a whole platform. A single pipeline can write an inspectable Git history, a queryable database record, an object-store snapshot, or an event stream—without scripts or API-server hammering. As adoption grows, nothing gets rebuilt: the same rows fan out to more sinks, and KollectScope keeps it multi-tenant. Every team owns its inventory as configuration, not code, in its own namespace; consumers read export data, never unbounded list/watch against the live cluster.

Read the docs: platformrelay.github.io/Kollect — architecture, quick start, CR reference, ADRs, and examples. This README is the front door; the site is the map.

Install paths: Helm OCI on GHCR is primary (oci://ghcr.io/platformrelay/charts/kollect — the chart moved off ghcr.io/platformrelay/kollect, which serves the controller image, see ADR-0709 and the install guide). The chart is listed on Artifact Hub. There is no classic Helm repository (helm repo add); install from the OCI coordinate. The OLM bundle is listed on OperatorHub.io and in the OpenShift community catalog (package kollect, channel stable), see ADR-0708. Both OLM catalogs lag behind the Helm chart and can be several releases old; for the current release, use Helm. The OLM badge above links the hub and OLM install notes.

Pre-1.0. Kollect is a public alpha with a v1alpha1 API: minor releases may break the API, defaults and export layout, and only the latest minor is supported. See Stability and support.

Why Kollect?

• Decoupled read model — consumers query a sink, not the apiserver. No RBAC blast radius, no watch-storm risk, no etcd size limits (why).
• Event-driven, no polling — one shared informer per GVK keeps inventory current as the cluster changes (ADR-0301).
• Schema-flexible — declare the attributes you want in a KollectProfile; no bespoke collector per resource kind.
• Pluggable sinks, no privileged backend — the same snapshot fans out to Git, Postgres, object store, or an event stream (sink taxonomy).
• Multi-tenant by design — KollectScope gates which teams, namespaces, and sinks each tenant may use.
• Fleet-ready — N single-mode operators → one shared sink, partitioned by spec.cluster; no central hub tier to operate (ADR-0501).
• Scale-aware architecture — shared informers, export sharding, and tunable reconcile/dispatch concurrency; the performance guide separates measured evidence from targets (performance).

See it end-to-end

A real pipeline is a handful of Kubernetes resources. The first-inventory walkthrough collects container images from Deployments and exports them to Git for an inspectable audit trail:

flowchart LR
  Profile["<b>KollectProfile</b><br/>Deployment schema"]
  Target["<b>KollectTarget</b><br/>select Deployments"]
  Inv["<b>KollectInventory</b><br/>aggregate · debounce · export"]
  Snap["<b>KollectSnapshotSink</b>"]
  Db["<b>KollectDatabaseSink</b>"]
  Ev["<b>KollectEventSink</b>"]
  K8s[("Kubernetes API")]

  Profile --> Target
  K8s -- "informer per GVK" --> Target
  Target --> Inv
  Inv --> Snap
  Inv --> Db
  Inv --> Ev
  Snap --> SnapOut["Git · GitLab · S3 · GCS"]
  Db --> DbOut["Postgres · MongoDB · BigQuery"]
  Ev --> EvOut["Kafka · NATS"]

Loading

Quick start (MVP)

Spin up a credential-free Git export on a local kind cluster in one command. It builds the operator from your checkout, so it needs Docker, kind, kubectl, Helm 3.8 or later, Git, curl, Go (the version in go.mod) and Task:

git clone https://github.com/platformrelay/kollect.git && cd kollect
task demo-up                      # kind + Forgejo + Ready Git inventory; about 3 minutes on a warm machine
# or: task dev-up                 # same hero path after build
kubectl get kinv,ktgt,ksnap -A    # demo-up has already waited for Ready + ConnectionVerified
kubectl get kinv demo-inventory -n default \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
task demo-down                    # delete the demo cluster when you are done

task demo-up (and task dev-up, which builds then runs the same hero harness) boots kind, installs Kollect, starts in-cluster Forgejo, and applies the golden Git-only sample — no cloud/DB Secrets. It waits for KollectInventory Ready and sink ConnectionVerified, then prints where to look: the clone of the exported repository (/tmp/kollect-hero-inventory; try git log --oneline there) and the Forgejo UI (http://127.0.0.1:13000/, user kollect, password kollect-demo). The get line lists the objects; the conditions line shows their state. Next to the exported files, the clone holds a .kollect-prune/ directory: the ownership records that stop two inventories from deleting each other's files (ADR-0422). The demo shop pod stays in ErrImagePull on purpose: its image does not exist, and Kollect reads the Deployment spec, not the running pod. Details: DEMO-GIF-GUIDE.

Postgres / S3 / Kafka / multi-sink samples are an explicit opt-in:

kubectl apply -k config/samples/advanced/

How it works

flowchart LR
  API["Kubernetes API"] -->|shared informers| Snapshot["Canonical inventory snapshot"]
  Snapshot -->|debounce| Inventory["KollectInventory"]
  Inventory --> SnapshotSinks["Git · GitLab · S3 · GCS"]
  Inventory --> DatabaseSinks["Postgres · MongoDB · BigQuery"]
  Inventory --> EventSinks["Kafka · NATS"]

Loading

The in-memory snapshot per inventory is canonical; every sink is a projection of it — no single backend is privileged (sink roles). Sinks are split into three CRD families (ADR-0414):

Sink family	Examples	Good for
KollectSnapshotSink	Git, GitLab, S3, GCS	Audit, diff, GitOps-friendly history
KollectDatabaseSink	Postgres, MongoDB	Rich queries for portals and dashboards
KollectEventSink	Kafka, NATS	Change streams, downstream consumers

Supported & planned sinks

Honest maturity tiers — see the roadmap for release timing.

Family CRD	spec.type	Status
KollectSnapshotSink	git	Core — production-ready
KollectSnapshotSink	gitlab	Core
KollectSnapshotSink	s3	Core
KollectSnapshotSink	gcs	Beta — shipped, maturing
KollectDatabaseSink	postgres	Core
KollectDatabaseSink	mongodb	Beta
KollectDatabaseSink	bigquery	Beta — analytics SQL
KollectEventSink	kafka	Beta
KollectEventSink	nats	Beta — JetStream emitter
KollectSnapshotSink	azureblob	Planned — needs real backend (roadmap)
KollectSnapshotSink	s3, gcs with serialization.format: parquet	Beta — shipped object-store output mode

Full payload lives in sinks; CR .status holds summaries only (etcd limits).

Performance

Kollect is designed for large single clusters and multi-cluster fleets. The performance guide distinguishes reproducible results from design targets and documents tuning for reconcile concurrency, export debounce, and sharding. Fleet fan-in uses shared sinks rather than a hub merge tier.

Learn more

Topic	Link
Problem statement, CRD model, reconciliation	Architecture
Locked platform decisions	Platform decisions
CR fields, RBAC, failure modes	CR reference
Multi-cluster fleet	ADR-0501
Sink taxonomy (state vs stream)	ADR-0401
Shipped, next, and later work	Roadmap
Examples index	Examples
Example: Deployment → Git export	Walkthrough
Demo inventory (Git sink, exported by an earlier release)	kollect-inventory-demo

Developers: run task lint, task test, and task verify before opening a PR — CONTRIBUTING.md.

Community

Contributing	CONTRIBUTING.md — DCO, PR workflow, good first tasks
Code of Conduct	CODE_OF_CONDUCT.md — Contributor Covenant v2.1
Governance	GOVERNANCE.md — roles, decisions, continuity

Security

Report vulnerabilities privately — see SECURITY.md. Security architecture: docs/ASSURANCE-CASE.md.

License

Copyright (c) 2026 Konrad Heimel. Licensed under the MIT License.