kollect

README

Kollect

Kollect is a Kubernetes operator that turns selected, live cluster state into a durable, queryable, diffable inventory — decoupled from the apiserver's availability, RBAC, and scale limits. Portals, automation, and auditors read export data, not unbounded list/watch against the live API.

Kubernetes is the source of truth for what is running; it is a poor system of record for stakeholder inventory. Kollect maintains a read model: select resources by GVK → extract the attributes that matter (CEL or JSONPath) → aggregate across targets → debounce → export to pluggable sinks. Inventory is configuration, not code — owned per team in its own namespace.

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

Pre-beta. APIs and defaults may change until the first release candidate. See the roadmap for current status.

How it works

Kubernetes API  →  shared informer (per GVK)  →  in-memory collect store
       →  KollectInventory debounce  →  sink projection(s)

The in-memory snapshot per inventory is canonical; every sink is a projection of it — no single backend is privileged (sink roles).

Sink role	Examples	Good for
Snapshot store	Git, GitLab, S3/GCS (JSON today)	Audit, diff, GitOps-friendly history
Relational store	Postgres	Rich SQL for portals and dashboards
Event emitter	Kafka / Redpanda / NATS	Change streams, downstream consumers

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

Quick start

Spin up Kollect on a local kind cluster in one command (needs Docker, kind, kubectl, and Task):

git clone https://github.com/konih/kollect.git && cd kollect
task dev-up                       # build, create kind cluster, install operator + sample CRs
kubectl get kinv,ktgt,ksink -A    # watch the pipeline come up

task dev-up builds the manager, boots a kollect-dev kind cluster, installs the operator, and applies the sample Profile → Sink → Target → Inventory pipeline. Then watch KollectInventory status and check your sink (Git demo repo, Postgres, Kafka, …).

Full walkthrough — prerequisites, Helm install, maturity notes: Quick start →

Why Kollect?

Event-driven	Shared informers per GVK — inventory stays current without polling loops (ADR-0301).
Schema-flexible	Declare attributes in KollectProfile; no bespoke collector per CRD.
CRD-native & GitOps-friendly	Profiles, sinks, targets, and inventory are Kubernetes resources in team namespaces.
Multi-tenant	KollectScope gates which teams and namespaces may export to which sinks.
Fleet-ready	Default path: spokes write to shared sinks with a cluster label. Optional hub mode (mode: hub|spoke on the same image) for Git fan-in or credential centralization — no hub CRD required.

Default install for new teams: namespaced Helm with tenantMode: true and scoped watchNamespaces. Platform-wide cluster operators remain supported.

Learn more

Topic	Link
Problem statement, CRD model, reconciliation	Architecture
Locked platform decisions	Platform decisions
CR fields, RBAC, failure modes	CR reference
Multi-cluster & hub/spoke	ADR-0501
Sink taxonomy (state vs stream)	ADR-0401
Build-order phases and status	Roadmap
Examples index	Examples
Example: Deployment → Git export	Walkthrough
Live demo inventory (Git sink)	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.