mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 17:51:29 +00:00

Files

T

shankar0123 9cec5cab65 docs: Phase 4 (structural) — move connectors.md + 5 deep dives into reference/connectors/

Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/.
Phase 4 in the audit recommended a full split of connectors.md (2055
lines) into an index + 27 per-connector pages (12 issuer + 15 target).
This commit lands the structural half of that work; full per-target
page extraction is deferred to follow-up commits.

Renames (all blame-preserving):
  docs/connectors.md         → docs/reference/connectors/index.md
  docs/connector-apache.md   → docs/reference/connectors/apache.md
  docs/connector-f5.md       → docs/reference/connectors/f5.md
  docs/connector-iis.md      → docs/reference/connectors/iis.md
  docs/connector-k8s.md      → docs/reference/connectors/k8s.md
  docs/connector-nginx.md    → docs/reference/connectors/nginx.md

Edits:
  - docs/reference/connectors/index.md gets a top-of-doc note
    explaining the per-connector deep-dive sibling pattern + a forward
    list of the 5 per-target pages.
  - The 5 per-connector deep-dive pages each get a `Last reviewed:
    2026-05-05` header + a back-link to the index.

Deferred to future commits (Phase 4b/c follow-on):
  - Extracting the 12 issuer sections from index.md into per-issuer
    pages at reference/connectors/{acme,awsacmpca,digicert,ejbca,
    entrust,globalsign,googlecas,local,openssl,sectigo,stepca,vault}.md
  - Extracting the 10 remaining target sections from index.md into
    per-target pages at reference/connectors/{caddy,traefik,envoy,
    haproxy,postfix-dovecot,ssh,javakeystore,wincertstore,awsacm,
    azurekv}.md

The pragmatic split makes this Phase 4 work incrementally landable —
each per-connector extraction is a small follow-up commit that doesn't
change the docs/ tree shape further. Cross-references from README.md
and other docs to docs/connectors.md still need fixing in Phase 11.

2026-05-05 03:14:39 +00:00

4.0 KiB

Raw Blame History

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).

4.0 KiB Raw Blame History