Repository navigation
docs(operator-guide): webhook certificate rotation and key compromise - #655
Conversation
Document the webhook certificate Secret, who can read it, the cert-controller defaults, how to inspect and verify the CA injection, a planned rotation and the steps after a suspected key compromise. Link the section from the chart README. Closes #650 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: MaxRink <maximilian.rink@telekom.de>
Output DeltaNo output differences were detected for this PR.
The compare job downloads artifacts only; it does not checkout or execute pull-request code. |
📊 Output Delta ReportNo output differences were detected for this PR. No full diff content was generated for this run. |
There was a problem hiding this comment.
🟡 Changes recommended
The operator guide contains incorrect resource names, a verification check that can falsely report success, incomplete certificate and token rotation instructions, and audit guidance that excludes potentially compromised operator identities.
5 open issues
Use the chart fullname, not the release name, for resource names · New Treat failed or empty CA reads as verification errors · New Document both certificate and trust-bundle mismatch windows · New Rotate API server webhook tokens alongside the Secret · New Investigate operator ServiceAccount Secret reads instead of excluding them · New
What changed in this PR
Adds operational guidance for managing Auth Operator’s webhook certificates, covering routine rotation and suspected key compromise.
Changes:
- Documents certificate storage, Secret access, rotation defaults, and certificate verification commands.
- Adds planned rotation and compromise-response procedures, including admission outage warnings and separate
/authorizeconfiguration updates. - Links the new guidance from the Helm chart README.
| File | Description |
|---|---|
docs/operator-guide.md |
Adds certificate inspection, rotation, and key-compromise guidance under Security Considerations. |
chart/auth-operator/README.md |
Links the certificate auto-rotation note to the new operator-guide section. |
Review effort: Balanced
Security scan reportCommit: Security findings are advisory, not merge blockers. Build, test and licensing checks remain blocking. A successful job is not proof of a clean scan; findings and scanner errors are called out below.
See the linked logs for complete findings and any scanner setup failures. |
Use the chart full name instead of the release name for object names, report unreadable webhook configurations and an empty CA instead of ok, describe both admission failure windows of a rotation, update the API server kubeconfig when rotating the /authorize token, and keep the operator ServiceAccounts in the audit search. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: MaxRink <maximilian.rink@telekom.de>
The caBundle check selects webhook configurations by the Helm instance label, which Kustomize installs do not set, so the loop printed nothing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: MaxRink <maximilian.rink@telekom.de>

Closes #650
Description
Adds a "Webhook Certificate Rotation" section to
docs/operator-guide.md(under Security Considerations) and links it from the chart README. The section covers:<release>-webhook-certs, its four keys, and who can read it with the chart defaults. This includes the controller-manager ServiceAccount, whose ClusterRole grantsget/list/watchon*.caBundleinto every configuration passed with--cert-rotation-*-webhook. That is the binder webhook, plus the namespace webhooks and the pod deletion guard when they are enabled./authorizekubeconfig on the API servers is not updated by the rotator.caBundlecheck across all webhook configurations of the release, and anopenssl s_clientcheck of the served chain..data, restart the deployment, verify. It also describes the admission outage window caused byfailurePolicy: Fail./authorizetoken, and check the audit logs for Secret reads.The defaults match
t-caas-go-librarypkg/certrotationv0.1.5, which uses cert-controller v0.16.0 defaults. telekom/t-caas-go-library#52 makes them configurable and does not change the defaults.Relation to #642
Draft #642 (external CA through chart values) is still open. This PR documents the current main behaviour and does not conflict with it: #642 adds its own "Providing the Webhook CA" section, including how to replace a provided CA. Once #642 merges, the "Planned Rotation" step "remove
.data" does not apply to a provided CA, because removing it makes the rotator generate a CA that the API servers do not trust. A follow-up should add a pointer to #642's section at that point.Type of Change
Testing
Every command in the section was run verbatim (extracted from the Markdown) against a kind cluster. The cluster ran the Helm chart from this branch with image
0.5.0-rc.26(equal to main), 2 webhook replicas andnamespaceAdmission.enabled=true:ok. Right after the Secret was emptied, the loop reports all three asSTALEuntil the new leader injected the CA, about 20 to 30 seconds later.openssl s_clientverifies the served chain against the newca.crt, and a server-side dry-run of a BindDefinition and a Namespace passes the webhooks.kubectl auth can-iconfirms Secret access for the webhook-server and controller-manager ServiceAccounts.The audit-log step is prose only, because audit backends differ.
PSA PSM-13.10
🤖 Generated with Claude Code