certctl/docs/reference/connectors/k8s.md

Kubernetes Secrets Connector — Operator Deep-Dive

Last reviewed: 2026-05-05

Per Phase 14 of the deploy-hardening II master bundle. For the connector-development context (interface contract, registry, atomic deploy primitive shared across all targets), see the connector index.

Overview

The K8s connector (internal/connector/target/k8ssecret/) deploys TLS certs into kubernetes.io/tls Secrets. Atomic at the API server level (Update is transactional); the post-deploy verify SHA-256-compares the returned Secret data against deployed bytes (defends against admission webhooks that modify cert data).

Vendor versions tested

• Kubernetes 1.28 LTS
• Kubernetes 1.30
• Kubernetes 1.31 (current stable)

Per-quirk operator guidance

Kubelet sync wait contract

TestVendorEdge_K8s_KubeletSyncWaitContract_DefaultTimeout60s_E2E

After Secret update, kubelet projects new cert bytes into pod-mounted volumes. Default sync interval ~60s. The connector waits up to CERTCTL_K8S_DEPLOY_KUBELET_SYNC_TIMEOUT (default 60s).

Operator action: for slow clusters (large pod count, slow node DNS), tune the env var upward. For fast clusters, the default is fine.

Admission webhook mutation

TestVendorEdge_K8s_AdmissionWebhookModifiesSecretData_DeployDetectsViaSHA256Compare_E2E

Some admission webhooks (Vault Agent Injector, OPA Gatekeeper) mutate Secret data on Update. The connector pulls the Secret back after Update and SHA-256-compares against deployed bytes. Mismatch surfaces as deploy failure.

Multi-version API stability

TestVendorEdge_K8s_K8s128LTS_vs_130_vs_131_SecretAPIContractStable_E2E

kubernetes.io/tls Secret schema (data.tls.crt + data.tls.key) is stable across 1.28-1.31. No per-version branch needed.

Typed vs Opaque Secret

TestVendorEdge_K8s_TypedKubernetesIOTLSVsUntypedOpaque_DeployRespectsType_E2E

Connector preserves operator-supplied Secret type. Typed kubernetes.io/tls is the canonical form; untyped Opaque is preserved for operators with legacy automation that expects it.

Cert-manager interop

TestVendorEdge_K8s_CertManagerInterop_RawSecretVsCertificateCRD_E2E

Connector targets raw Secrets, NOT cert-manager Certificate CRs. Operators using cert-manager should NOT also point certctl at the same Secret name (cert-manager will overwrite). Documented coexistence: certctl handles non-cert-manager Secrets; cert-manager handles its own.

Multi-namespace

TestVendorEdge_K8s_MultiNamespaceDeploy_DeployUpdatesCorrectNamespace_E2E

Connector targets the configured Namespace only. Cross-namespace deploys require multiple connector entries.

RBAC errors

TestVendorEdge_K8s_RBACInsufficientPermissions_DeployFailsWithActionableError_E2E

Connector surfaces the K8s API's forbidden: secrets is restricted error verbatim. Operator action: bind a Role with secrets: get,update,create verbs to the agent's ServiceAccount.

Labels + annotations preservation

TestVendorEdge_K8s_LabelsAnnotationsPreserved_E2E

Connector merges (not replaces) operator-supplied metadata. Custom labels/annotations on the Secret survive cert rotation.

Pod-mounted Secret rollover

TestVendorEdge_K8s_PodMountedSecretRollover_E2E

When a pod mounts the Secret as a volume, kubelet projects new cert bytes into the pod's filesystem after sync. Pods watching the file (via inotify or polling) pick up the new cert without restart.

Immutable Secret flag

TestVendorEdge_K8s_ImmutableSecretFlag_E2E

K8s Secrets can be marked immutable: true for performance. Update fails with actionable error; operator must drop the flag, update, then re-apply if desired.

V3-Pro deferrals

• cert-manager Certificate CR interop as first-class deploy target (V3-Pro: certctl as cert-manager external issuer).
• Multi-cluster federation (deploy a single cert across N clusters with single connector entry).

Related docs

• Atomic deploy + post-verify + rollback
• Vendor compatibility matrix