mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-08 21:18:51 +00:00
shankar0123
633e440787
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.
123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
# 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](index.md).
|
|
|
|
## 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](deployment-atomicity.md)
|
|
- [Vendor compatibility matrix](deployment-vendor-matrix.md)
|