Skip to content

Home

OpenSSF Scorecard OpenSSF Best Practices CodeQL Release License: MIT

Declare your inventory. Kollect keeps it current. Select the resources and attributes that matter once, then deliver the same canonical inventory to Git, object storage, databases, and event streams. Start with one sink; grow to multi-tenant fan-out across teams without rebuilding your collection model.

Record the hero demo locally: DEMO-GIF-GUIDE.md.

Simple to start · platform-grade to grow — kollect.dev/v1alpha1 · event-driven · CRD-native · fleet-ready

Quick start CR reference

What Kollect does

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 — live state captured once, then served from export data:

Scope and Target select resources by GVK and namespace; Profile extracts the attributes that matter (CEL or JSONPath); Inventory rolls up matching objects, debounces churn, and exports snapshots to pluggable sinks (Git, object stores, databases, event streams). Every backend sees the same aggregated rows; sinks are interchangeable projections.

Inventory is configuration, not code — owned per team in its own namespace.

Pre-1.0 API

Kollect uses a v1alpha1 API. Breaking API or default changes may ship in minor releases before 1.0; release notes and migration guidance call them out. See the roadmap for current maturity.

Why Kollect?

Event-driven

Shared informers per GVK — inventory stays current without polling loops (ADR-0301).

CRD-native

Declare profiles, sinks, targets, and inventory in Kubernetes; GitOps-friendly from day one.

Multi-tenant

KollectScope gates which teams and namespaces can export to which sinks.

Fleet-ready

Each cluster runs mode: single and exports to shared sinks with a cluster label (ADR-0501).

How it works

flowchart LR
  API["Kubernetes API"] -->|watch| Informers["Shared informers<br/>per GVK"]
  Informers --> Store["Canonical<br/>inventory snapshot"]
  Store -->|debounce| Inventory["KollectInventory"]
  Inventory --> Snapshot["Git · GitLab<br/>S3 · GCS"]
  Inventory --> Database["Postgres · MongoDB<br/>BigQuery"]
  Inventory --> Event["Kafka · NATS"]

The in-memory snapshot per inventory is canonical; every sink is a projection of it — no single backend is privileged. Sink roles (snapshot store, relational store, event emitter) are documented in ADR-0401; reconciliation detail in Architecture and Data flows.

Supported & planned sinks

Family CRD spec.type Status
KollectSnapshotSink git, gitlab, s3 Core — production-ready
KollectSnapshotSink gcs Beta — shipped, maturing
KollectDatabaseSink postgres Core
KollectDatabaseSink mongodb, bigquery Beta
KollectEventSink kafka, nats Beta
KollectSnapshotSink azureblob Planned
KollectSnapshotSink S3/GCS serialization.format: parquet Beta — shipped output mode

Release timing and deferred backends: Roadmap — Supported & planned sinks.

The resource model

A pipeline is just a handful of Kubernetes resources: config you declare (KollectProfile, family sinks — KollectSnapshotSink, KollectDatabaseSink, KollectEventSink, KollectScope) and objects the operator reconciles (KollectTarget, KollectInventory). Cluster-scoped KollectCluster* variants add cross-namespace rollup.

flowchart LR
  K8s(["Kubernetes API"]):::api

  subgraph declare["You declare — static config"]
    direction TB
    Profile["<b>KollectProfile</b><br/>what to extract"]
    Scope["<b>KollectScope</b><br/>guardrails"]
    Snap["<b>KollectSnapshotSink</b><br/>snapshot store"]
    Db["<b>KollectDatabaseSink</b><br/>relational SoR"]
    Ev["<b>KollectEventSink</b><br/>event emitter"]
  end

  subgraph run["Operator reconciles"]
    direction TB
    Target["<b>KollectTarget</b><br/>what to watch"]
    Inv["<b>KollectInventory</b><br/>aggregate · debounce · export"]
  end

  subgraph out["Sink projections — choose any"]
    direction TB
    SnapOut["Git · GitLab · S3 · GCS<br/><i>snapshot store</i>"]
    Rel["Postgres · MongoDB<br/><i>relational SoR</i>"]
    EvtOut["Kafka<br/><i>event emitter</i>"]
  end

  K8s -- "informer per GVK" --> Target
  Profile --> Target
  Target --> Inv
  Scope -. gates .-> Target
  Scope -. gates .-> Inv
  Inv --> Snap
  Inv --> Db
  Inv --> Ev
  Snap --> SnapOut
  Db --> Rel
  Ev --> EvtOut

  classDef api fill:#1F2937,stroke:#6B7280,color:#fff;
  classDef config fill:#326CE5,stroke:#1b3a8c,color:#fff;
  classDef work fill:#18B6A3,stroke:#0e6f63,color:#fff;
  classDef proj fill:#7FB3FF,stroke:#326CE5,color:#081A4B;

  class Profile,Scope,Snap,Db,Ev config;
  class Target,Inv work;
  class SnapOut,Rel,EvtOut proj;
Kind You set Role
KollectProfile GVK + CEL / JSONPath attributes What to extract from each object
KollectTarget selectors + profileRef What to watch and collect
KollectInventory family sink refs + cadence Aggregate, debounce, and export
KollectSnapshotSink type + endpoint + secretRef Snapshot store (Git, GitLab, S3, GCS)
KollectDatabaseSink type + credentials Relational SoR (Postgres, MongoDB)
KollectEventSink type + brokers Event emitter (Kafka)
KollectScope allowed GVKs / namespaces / sinks Guardrails for the team namespace

Full fields: CR reference · model rationale: ADR-0201.

Performance

Kollect is designed for large single clusters and multi-cluster fleets. The performance guide distinguishes reproducible results from design targets and catalogues tuning knobs. Fleet fan-in uses shared sinks rather than a hub merge tier (ADR-0603).

Documentation map

Section Start here
Getting started Install Kollect · Your first inventory · All examples
Concepts The resource model · How collection works · Export pipeline and debouncing · Sink roles
Scale & tenancy Multi-tenancy and scopes · Multi-cluster fleet · Architecture (package graph)
Operate Operator manual · Helm values · Upgrading · Metrics
Run in production Performance and scaling · Production checklist · Troubleshooting
Reference Custom resources · Conditions and status · Annotations and labels · Glossary
Design & internals Architecture decisions · Requests for comments · Requirements
Contributing Contributor setup · Roadmap · Planned features · ADR and RFC process · Release process

Try an example

Go deeper