Annotations and labels

Lookup for Kollect-owned metadata keys on Kubernetes objects and Helm-managed operator resources. Constants live in api/v1alpha1/constants.go.

Assumptions

This reference assumes you understand watch scope and sink probes. For context, read Understand the basics and ADR-0205.

Watch scope

Control which namespaces and resources the collection engine watches (ADR-0205).

Key	Type	On	Values	Effect
kollect.dev/watch	Label	Namespace, namespaced resource	enabled, disabled	Opt in or out a namespace or single resource
kollect.dev/namespace-watch	Annotation	Namespace	enabled, disabled	Applies to all resources in the namespace unless a resource label overrides

Precedence (ShouldCollect)

1. Resource label kollect.dev/watch: disabled — always skip (wins over everything).
2. Resource label kollect.dev/watch: enabled — collect (overrides namespace disabled).
3. Namespace label kollect.dev/watch: disabled or annotation kollect.dev/namespace-watch: disabled — skip all resources in namespace (unless step 2).
4. KollectTarget.spec.watchMode: OptIn — require namespace or resource enabled; otherwise skip.
5. watchMode: All (default) — collect when selectors match and no opt-out applies.

Interaction with watchMode

Under OptIn, only explicitly enabled namespaces or resources are collected. Under All, matching selectors are collected except where disabled applies. See Multi-tenant watch scope.

Examples

Opt-out a noisy namespace (default All mode):

apiVersion: v1
kind: Namespace
metadata:
  name: kube-system
  annotations:
    kollect.dev/namespace-watch: disabled

Opt-in cluster (watchMode: OptIn on the target):

kubectl label namespace team-a kollect.dev/watch=enabled --overwrite

Opt-out one Deployment in an otherwise watched namespace:

# kollect-doc: ignore workload metadata, not a kollect CR
metadata:
  labels:
    kollect.dev/watch: disabled

Connection test

Key	Type	On	Values	Effect
kollect.dev/test-connection	Annotation	Family sinks (KollectSnapshotSink, KollectDatabaseSink, KollectEventSink)	"true"	One-shot connectivity probe; sets ConnectionVerified on status

Equivalent to spec.connectionTest: true on the sink CR (ADR-0403). The reconciler removes the annotation after a successful probe (kept when the probe fails).

Production probes

Keep spec.connectionTest: false in Git-managed manifests. Use the annotation for ad-hoc re-tests:

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

See Connection test example.

Deletion escape hatch

Key	Type	On	Values	Effect
kollect.dev/force-cleanup	Annotation	KollectInventory, KollectClusterInventory	"true"	While the object is deleting: drops the cleanup finalizer without contacting sinks, so Terminating unblocks after a terminal cleanup failure (CleanupTerminal). Exported objects are not retracted — remove them manually if required. Ignored on live objects. Records a CleanupForced Warning Event.

Multi-cluster identity

Fleet installs distinguish clusters via spec.cluster on inventory and export rows (ADR-0501). Remote-cluster registration labels and hub ingest headers are not used in the default architecture.

Profile and export metadata

Key	Type	On	Values	Effect
kollect.dev/allow-secret-extraction	Annotation	KollectProfile	"true"	Admission allows CEL/JSONPath paths into Secret.data
kollect.dev/collectedGeneration	Annotation	Exported source objects (metadata) — the embedded copy inside Resource-mode exports (export.mode: Resource), never written back to live cluster objects	"<n>" — the source object's metadata.generation at collection time	Records the source generation on the embedded copy for staleness detection. Applied after profile pruning and scrubbing, so prune paths and scrub rules cannot remove or redact it. Written whenever a metadata map survives the profile's include section (generation 0 included); no metadata map → no stamp. The default include: SpecAndStatus drops metadata, so Resource-mode exports that should carry the stamp set include: All or MetadataOnly. Attributes-mode exports have no embedded copy and carry no stamp
kollect.dev/requestedAt	Annotation	KollectInventory, KollectClusterInventory	RFC3339 timestamp (convention)	Manual re-export trigger: changing the value — set on an object that had none, removed after being set, or a different value — forces one immediate export to every bound sink past the export debounce; afterwards the steady-state debounce resumes unchanged. The value is not parsed (any non-empty string works, absence counts as a value)

Secret extraction

Profiles that read Secret.data require explicit opt-in via kollect.dev/allow-secret-extraction: "true". Prefer indirect references (e.g. cert-manager status) when possible (KollectProfile).

Export payload inline cap

Not an annotation — operator policy for marshalled inventory size (ADR-0103, KollectInventory maxExportBytes). There is no automatic spill write path: a payload above the inline cap that targets a non-object-store sink is not written anywhere else — it fails loudly instead.

Signal	When	Meaning
Log export payload exceeds spill warn threshold	Payload ≥ 1 MiB	Approaching the 1 MiB inline cap
kollect_export_spill_warn_total	Payload ≥ 1 MiB	Counter — tune targets or add S3/GCS before hard block
Inventory Degraded SpillRequired	Payload > 1 MiB, no s3/gcs in snapshotSinkRefs	Add object-store sink or reduce payload; the export is not buffered elsewhere
Inventory Degraded PayloadTooLarge	Payload > maxExportBytes (~1.5 MiB default)	Split targets, trim attributes, or raise cap within global limit
kollect_sink_errors_total{reason="spill_required"}	Inline-cap gate blocked export	Same remediation as SpillRequired

Family sink spec.pathTemplate (snapshot/object-store backends) controls where snapshot payloads land in Git/S3/GCS (not related to watch labels above).

Tenant and example labels

Sample manifests and e2e fixtures use conventional labels — not enforced by the operator unless referenced in target selectors:

Key	Example value	Usage
kollect.dev/tenant	platform, team-a	Tenant isolation in samples and cluster rollup selectors
kollect.dev/collect-certificates	enabled	cert-manager example target selector

Helm chart labels

Standard labels on operator Deployments, Services, and webhooks (charts/kollect/templates/_helpers.tpl):

Label	Value	Meaning
helm.sh/chart	kollect-<version>	Chart identity
app.kubernetes.io/name	kollect	Application name
app.kubernetes.io/version	Chart AppVersion	Operator version
app.kubernetes.io/managed-by	Helm release service	Managed by Helm
control-plane	controller-manager	Selector for manager pods

List operator pods:

kubectl get pods -n kollect-system -l app.kubernetes.io/name=kollect

Related

• ADR-0205: Watch labels
• ADR-0403: Connection test
• Operator manual — Watch scope
• Troubleshooting · Best practices