Example: Connection test¶

Prerequisites¶

A running operator and the family sink you want to probe.

Apply¶

Apply a validated sink sample, then use the annotation or KollectConnectionTest flow below.

Verify¶

kubectl get ksnap,kdb,kevt -n default
kubectl get kconn -n default

If it didn't work¶

Inspect the probe condition, Events, Secret reference, endpoint, and TLS trust.

Cleanup¶

Delete the one-shot test CR; completed tests also honor their configured TTL.

Overview¶

Mechanism	Best for	Writes to
`spec.connectionTest` (default true)	Automatic probe on create/update	Family sink `status`
`kollect.dev/test-connection` annotation	On-demand prod re-test	Family sink `status`
`KollectConnectionTest` CR	Audited / CI pipelines	`KollectConnectionTest.status`

Default: spec.connectionTest: true (CRD OpenAPI default). Set false to opt out.

Family sink CRDs (ADR-0414):

CRD	Role	Wired probe types
`KollectSnapshotSink`	Snapshot store	`git`, `gitlab`, `s3`, `gcs`
`KollectDatabaseSink`	Queryable state	`postgres`, `mongodb`, `bigquery`
`KollectEventSink`	Event emitter	`kafka`, `nats`

Reserved backend names (azureblob, http) are rejected by admission because no implementation ships. They cannot be used as placeholders in manifests.

Sink probe — `spec.connectionTest`¶

config/samples/advanced/kollect_v1alpha1_kollectdatabasesink.yaml sets connectionTest: true.

kubectl apply -f config/samples/advanced/kollect_v1alpha1_kollectdatabasesink.yaml
kubectl wait --for=condition=ConnectionVerified kollectdatabasesink/postgres-inventory-demo \
  -n default --timeout=60s
kubectl describe kdb postgres-inventory-demo -n default

Git snapshot sink sample (config/samples/advanced/kollect_v1alpha1_kollectsnapshotsink.yaml):

kubectl wait --for=condition=ConnectionVerified kollectsnapshotsink/git-inventory-demo \
  -n default --timeout=60s

Each family has a narrow reconciler whose sole job is connection-test status — not collection or export (ADR-0403).

Annotation re-test¶

Trigger a one-shot probe without editing spec:

kubectl annotate kollectdatabasesink postgres-inventory-demo -n default \
  kollect.dev/test-connection=true --overwrite

kubectl annotate kollectsnapshotsink git-inventory-demo -n default \
  kollect.dev/test-connection=true --overwrite

When spec.connectionTest: false, the annotation is the supported way to re-probe in production. After a successful annotation-only probe, the reconciler clears the annotation (kept when spec.connectionTest: true).

KollectConnectionTest CR¶

config/samples/advanced/kollect_v1alpha1_kollectconnectiontest.yaml — spec.sinkRef names exactly one family sink:

# kollect-doc: fragment KollectConnectionTest
spec:
  sinkRef:
    databaseSinkRef: postgres-inventory-demo
  ownerSink: true

Snapshot or event probes use snapshotSinkRef or eventSinkRef instead.

kubectl apply -f config/samples/advanced/kollect_v1alpha1_kollectconnectiontest.yaml
kubectl wait --for=condition=ConnectionVerified kollectconnectiontest/postgres-sink-probe \
  -n default --timeout=120s
kubectl get kconntest postgres-sink-probe -n default -o wide

Default spec.ttlSecondsAfterFinished: 300 (CR auto-deleted after probe completes + TTL).

Re-run after fixing credentials: delete and re-apply the CR, or patch spec to bump generation.

Status conditions¶

On family sink CRDs:

Condition	Meaning
`ConnectionVerified` `True`	Last probe succeeded
`ConnectionVerified` `False`	Probe failed (`ConnectionTestFailed`, `SecretResolveFailed`, …)
`Degraded` `True`	Set alongside failed probe
`TLSInsecure` `True`	`insecureSkipVerify` enabled (dev warning)

Operator metric: kollect_sink_connection_test_total{type,result}.

Pipeline reachability¶

ConnectionVerified on a family sink proves credentials and network to the backend. End-to-end export health belongs on reconciled objects:

Condition	Object	Meaning
`SinkReachable`	`KollectInventory`, `KollectTarget`	Family sink resolution before export
`Synced`	`KollectInventory`	Export succeeded for a sink ref

See Deployment inventory for the full Profile → Target → Inventory → family sink path.