Skip to content

FAQ

Symptom-oriented answers for platform operators running Kollect. For step-by-step install and upgrade, see Operator manual. For pipeline walkthroughs, see Examples.

First checks

When export stalls, run kubectl describe on the sink and inventory — ConnectionVerified, SinkReachable, and Synced conditions usually pinpoint credential, namespace, or selector issues before diving into controller logs.

Installation and upgrades

Why do CRD schema changes not apply on helm upgrade?

Helm installs CRDs from crds/ on first install but does not upgrade them on helm upgrade. Kollect documents an explicit two-step path: kubectl apply -f dist/install-crds.yaml, then helm upgrade (ADR-0704, Operator manual — Upgrade).

Should I delete CRDs to fix a schema mismatch?

No. Deleting a CRD garbage-collects all custom resources. Apply the new CRD bundle instead; never delete CRDs in production.

tenantMode: true
watchNamespaces:
  - team-a
mode: single

See Operator manual — Watch scope and Multi-tenant watch scope.

Same-namespace references

Why does my inventory show SinkNotFound or SinkReachable=False?

KollectInventory.spec.sinkRefs must name KollectSink objects in the same namespace as the Inventory. Cross-namespace sink refs are not supported for namespaced inventory (ADR-0201, ADR-0201).

kubectl get kollectsink -n <inventory-namespace>
kubectl describe kollectinventory <name> -n <inventory-namespace>

The same rule applies to KollectTarget.spec.profileRef → KollectProfile in the target namespace, and KollectConnectionTest.spec.sinkRef → sink in the test namespace.

Same-namespace sink refs

Create sinks in the same namespace as KollectInventory before expecting export. Cluster-wide rollup uses KollectClusterInventory with spec.sinkNamespace instead.

I moved the sink to another namespace — why did export stop?

Update sinkRefs on the Inventory to names in the new namespace, or recreate the Inventory in the sink namespace. The operator does not follow cross-namespace sink references for namespaced inventory.

SinkReachable and connection conditions

What is the difference between ConnectionVerified and SinkReachable?

Condition Object Meaning
ConnectionVerified KollectSink Last connectivity probe succeeded (credentials, TLS, network)
SinkReachable KollectInventory / KollectTarget Export pipeline can resolve and reach the referenced sink
Synced KollectInventory / KollectTarget Last export cycle completed successfully

A sink can show ConnectionVerified=True while inventory shows SinkReachable=False if the name or namespace in sinkRefs is wrong — fix the reference, not just credentials.

How do I re-test sink connectivity without editing the CR?

Annotate the sink for a one-shot probe (ADR-0403):

kubectl annotate kollectsink <name> -n <namespace> kollect.dev/test-connection=true --overwrite
kubectl wait --for=condition=ConnectionVerified kollectsink/<name> -n <namespace> --timeout=60s

Production manifests should keep spec.connectionTest: false and use the annotation for ad-hoc tests.

Export never runs — what should I check?

Symptom Likely cause
SinkReachable=False, reason SinkNotFound sinkRefs name or namespace mismatch
SinkReachable=False, reason SinkUnreachable Backend down, bad DSN, or TLS failure — check ConnectionVerified on the sink
ConnectionVerified=False Missing secretRef, wrong Secret key, or unreachable endpoint
Synced=False Prior export failed — see manager logs and Degraded condition
Empty status.itemCount No resources match target selector, target suspended, or scope denied

Detailed table: Deployment inventory — Troubleshooting.

Does exportMinInterval delay exports after a change?

No. The interval debounces re-export of an identical payload only. A material change (payload checksum or metadata.generation bump) exports immediately per sink, regardless of the configured interval. Set exportMinInterval: 0s for material-change only semantics (typical for Kafka/NATS event sinks): instant export on change, identical payloads never re-sent. 0 and sub-second durations are valid (cap: 24h), but wake-ups floor at 1s, so anything below 1s behaves like 0s. See DATA-FLOWS §1 and ADR-0413.

Pre-beta expectations

Is Kollect safe for production today?

Pre-beta API

APIs and defaults may change until the first release candidate. v1alpha1 has no conversion webhook — schema changes may require CRD re-apply and CR updates (ADR-0206, ROADMAP).

Evaluate against your risk tolerance. Use pinned chart and image versions; read Unreleased notes in CHANGELOG.md before upgrading.

Why did my CR stop working after an upgrade?

Pre-beta CRD fields can change without conversion. After upgrading CRDs (install-crds.yaml), validate sample manifests and kubectl explain for renamed or removed fields. Breaking changes use feat!: or BREAKING CHANGE: in commit messages (CONTRIBUTING.md).

Is the export JSON format stable?

Sink payloads and Read API responses are moving toward a versioned envelope — today many exports emit a bare JSON array (ADR-0405). Plan downstream consumers for possible wrapper fields before v1.0.

Multi-cluster fleet

How do I inventory many clusters?

Default path: run one Kollect operator per cluster with mode: single and export to a shared sink (Postgres, Kafka, NATS, Git) with spec.cluster set on inventory. The sink backend merges rows by cluster id — no central hub tier (ADR-0501, ADR-0401).

Walkthrough: Multi-cluster fleet.

Is there a KollectHub CRD?

No. Hub/spoke runtime was removed in v0.3. Multi-cluster uses N single-mode operators exporting to a shared sink with spec.cluster (ADR-0501).

Performance and scope

My operator uses too much memory — what can I tune?

Restrict watchNamespaces, use tenantMode, narrow KollectTarget selectors, and increase exportMinInterval on inventories. See Performance tuning and ADR-0603.

A namespace is skipped even though a target exists

Check kollect.dev/namespace-watch: disabled on the namespace, kollect.dev/watch: disabled on resources, watchMode: OptIn without enabled labels, or KollectScope deny rules (ADR-0205).