Updated credentials rotation topic#1004
Conversation
✅ Deploy Preview for gardener-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe credential rotation documentation now classifies credential types, links detailed procedures, explains two-phase and automatic rotation, and documents infrastructure credential storage and usage. ChangesCredential Rotation Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
gardener-prow
Bot
added
cla: yes
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Core Problems in the Documentation1. Conceptual overload without a simple mental modelThe doc immediately introduces:
➡️ But it never gives a simple “big picture” first. Impact: Stakeholders cannot answer basic questions like:
✅ What’s missing:
2. Two completely different processes are mixed togetherThe doc contains two fundamentally different workflows: A. Gardener-managed credentials
B. User-provided credentials (cloud keys)
➡️ These are described in the same flow, with weak separation. Impact: Users blend the models incorrectly, e.g.:
✅ What’s missing:
3. The “two-phase rotation” is explained abstractly, not operationallyThe documentation says:
But it does NOT clearly answer:
➡️ It explains mechanics, not usage. Impact: Stakeholders don’t trust the process because:
✅ What’s missing:
4. Too much Kubernetes-native detail, not enough user intentExamples: ➡️ These are implementation details, not user guidance. Impact:
✅ What’s missing:
5. Ambiguous ownership messagingTable says:
Class | Who rotates
-- | --
User-provided | You
Gardener-managed | You
➡️ Both say “You” → this is misleading. Impact: Users ask:
✅ Reality (not clearly expressed):
✅ What’s missing:
6. No clear failure modes or risksThe doc never clearly explains:
➡️ This is critical for operational confidence. Impact:
7. User-provided credentials section is underspecifiedIt says:
But lacks:
➡️ Especially weak for shared credentials. 8. Repetition without clarity improvementThe update repeats ideas like:
➡️ But repetition ≠ clarity Impact:
9. No concrete examplesThere are zero real-world scenarios, such as:
➡️ All credentials are treated generically, but they behave very differently. 🧠 Why Stakeholders Still Don’t Understand It1. They think in tasks, not in systemsThey want:
But the doc answers:
2. They need decision guidance, not reference textMissing:
3. The doc assumes deep Gardener/Kubernetes knowledgeConcepts like:
are not re-explained. 4. It lacks operational confidence signalsNo:
✅ What Would Fix It1. Add a decision entry point2. Split into two completely separate guides
3. Add worked examplesAt least:
4. Add checklistsExample: Before completing rotation:
5. Add a diagramVisualizing:
🟢 Bottom lineThe documentation improved accuracy, but not usability. 👉 The real issue is not missing information That’s why stakeholders still say:
|
gardener-prow
Bot
added
the
needs-rebase
ec76ecf to
36ac829
Compare
gardener-prow
Bot
removed
the
needs-rebase
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hugo/content/docs/getting-started/features/credential-rotation.md`:
- Around line 49-57: Update the “Automatic Rotation” section to explicitly list
the OpenVPN TLS auth key as a credential that cannot be rotated manually or
automatically. Distinguish it from certificate authorities and the
ServiceAccount signing key, which require manual rotation between phases, and
preserve the existing automatic-rotation list.
- Around line 20-25: Update the credential responsibility table and surrounding
explanation to distinguish user actions from Gardener-managed rotation
mechanics: users choose timing, update dependent clients, and trigger
completion, while Gardener creates, distributes, and invalidates Shoot
credentials. Add a concise decision guide explaining when to use the
infrastructure-credentials workflow versus the Shoot-credentials workflow,
anchored to the existing “Infrastructure credentials” and “Shoot credentials”
sections.
- Around line 61-68: Expand the credential-rotation guidance around “When you
rotate these credentials” with actionable verification: specify how to confirm
every referencing Shoot has reconciled successfully, the expected timing or
polling interval, and the status conditions to check. Add failure handling for
an individual Shoot, including investigating or remediating it and keeping the
old provider keys active until all shared-Shoot reconciliations succeed.
- Around line 31-43: Expand the “Two-Phase Rotation Model” section with concrete
readiness checks before completing rotation, including how to verify all CA and
kubeconfig consumers use the new credentials. Describe the access failures
caused by completing with a missed client and document the recovery path for a
failed completion, using the existing rotation status reference where
applicable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: ab21d948-05ad-4052-9a21-abf5161a40ca
📒 Files selected for processing (1)
hugo/content/docs/getting-started/features/credential-rotation.md
| | Class | Examples | Scope | Who rotates | | ||
| |---|---|---|---| | ||
| | **Infrastructure credentials** | Cloud provider keys (AWS, Azure, GCP, OpenStack) | Project-scoped — shared across Shoots via `CredentialsBinding` | You | | ||
| | **Shoot credentials** | CAs, SSH key pair, ETCD encryption key, ServiceAccount signing key, observability passwords | Per-Shoot — generated and managed by Gardener | You, via `kubectl annotate` operations on the Shoot | | ||
|
|
||
|  | ||
| Infrastructure credentials are **not** part of the Shoot itself — they are `Secret`s in the garden cluster's project namespace, referenced by Shoots via a `CredentialsBinding`. Shoot credentials are generated per Shoot by Gardener and rotate through well-defined phases. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Clarify user versus Gardener responsibilities.
“Who rotates: You” and “You, via kubectl annotate” can imply that users perform the rotation mechanics. State explicitly that users choose the timing, update dependent clients, and trigger completion, while Gardener creates, distributes, and invalidates Gardener-managed credentials. Add a short decision guide for choosing between the two workflows.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hugo/content/docs/getting-started/features/credential-rotation.md` around
lines 20 - 25, Update the credential responsibility table and surrounding
explanation to distinguish user actions from Gardener-managed rotation
mechanics: users choose timing, update dependent clients, and trigger
completion, while Gardener creates, distributes, and invalidates Shoot
credentials. Add a concise decision guide explaining when to use the
infrastructure-credentials workflow versus the Shoot-credentials workflow,
anchored to the existing “Infrastructure credentials” and “Shoot credentials”
sections.
| ## Two-Phase Rotation Model | ||
|
|
||
| Where possible, the rotation happens in two phases - Preparing and Completing. | ||
| For Gardener-managed credentials, rotation happens in two phases where possible. | ||
|
|
||
| ### Prepare Rotation of All Credentials | ||
|  | ||
|
|
||
| The Preparing phase introduces new keys while the old ones are still valid. | ||
| Users can safely exchange keys / CA bundles wherever they are used. | ||
| It is possible to start the preparation by annotating the shoot resource accordingly: | ||
| In the **Preparing phase**, new credentials are created alongside the old ones — both sets are valid simultaneously. | ||
| This gives you time to update any API clients, kubeconfigs, or tooling that depend on the old credentials before they are invalidated. | ||
|
|
||
| ```bash | ||
| kubectl -n <shoot-namespace> annotate shoot <shoot-name> gardener.cloud/operation=rotate-credentials-start | ||
| ``` | ||
| In the **Completing phase**, the old credentials are invalidated and only the new set remains. | ||
| You should only trigger this phase after all clients have been updated to use the new credentials. | ||
|
|
||
| ### Complete Rotation of All Credentials | ||
| The shoot's status always reflects the current rotation phase, readable at `.status.credentials.rotation`. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Add readiness checks and failure consequences to the two-phase workflow.
The page tells users to update clients before completing rotation, but does not identify how to verify readiness, what happens if a client is missed, or how to recover from a failed completion. This is especially risky for CA and kubeconfig consumers, where premature completion can break access.
Suggested addition
In the **Completing phase**, the old credentials are invalidated and only the new set remains.
You should only trigger this phase after all clients have been updated to use the new credentials.
+Before completing, verify every affected client and confirm the rotation status is ready.
+If any client still uses the old credentials, it may lose access after completion; document the
+recovery procedure and whether another rotation is required.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Two-Phase Rotation Model | |
| Where possible, the rotation happens in two phases - Preparing and Completing. | |
| For Gardener-managed credentials, rotation happens in two phases where possible. | |
| ### Prepare Rotation of All Credentials | |
|  | |
| The Preparing phase introduces new keys while the old ones are still valid. | |
| Users can safely exchange keys / CA bundles wherever they are used. | |
| It is possible to start the preparation by annotating the shoot resource accordingly: | |
| In the **Preparing phase**, new credentials are created alongside the old ones — both sets are valid simultaneously. | |
| This gives you time to update any API clients, kubeconfigs, or tooling that depend on the old credentials before they are invalidated. | |
| ```bash | |
| kubectl -n <shoot-namespace> annotate shoot <shoot-name> gardener.cloud/operation=rotate-credentials-start | |
| ``` | |
| In the **Completing phase**, the old credentials are invalidated and only the new set remains. | |
| You should only trigger this phase after all clients have been updated to use the new credentials. | |
| ### Complete Rotation of All Credentials | |
| The shoot's status always reflects the current rotation phase, readable at `.status.credentials.rotation`. | |
| ## Two-Phase Rotation Model | |
| For Gardener-managed credentials, rotation happens in two phases where possible. | |
|  | |
| In the **Preparing phase**, new credentials are created alongside the old ones — both sets are valid simultaneously. | |
| This gives you time to update any API clients, kubeconfigs, or tooling that depend on the old credentials before they are invalidated. | |
| In the **Completing phase**, the old credentials are invalidated and only the new set remains. | |
| You should only trigger this phase after all clients have been updated to use the new credentials. | |
| Before completing, verify every affected client and confirm the rotation status is ready. | |
| If any client still uses the old credentials, it may lose access after completion; document the recovery procedure and whether another rotation is required. | |
| The shoot's status always reflects the current rotation phase, readable at `.status.credentials.rotation`. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hugo/content/docs/getting-started/features/credential-rotation.md` around
lines 31 - 43, Expand the “Two-Phase Rotation Model” section with concrete
readiness checks before completing rotation, including how to verify all CA and
kubeconfig consumers use the new credentials. Describe the access failures
caused by completing with a missed client and document the recovery path for a
failed completion, using the existing rotation status reference where
applicable.
| ## Automatic Rotation | ||
|
|
||
|  | ||
| Some Gardener-managed credential types support automatic rotation during the maintenance window via `.spec.maintenance.autoRotation.credentials`: | ||
|
|
||
| At the beginning, only the old set of credentials exists. | ||
| By triggering the rotation, new credentials are created in the Preparing phase and both sets are valid. | ||
| Now, all clients have to update and start using the new credentials. | ||
| Only afterward it is safe to trigger the Completing phase, which invalidates the old credentials. | ||
| - SSH key pair | ||
| - ETCD encryption key (enabled by default on new shoots) | ||
| - Observability passwords | ||
|
|
||
| The shoot's status will always show the current status / phase of the rotation. | ||
| Certificate authorities and the ServiceAccount signing key require user action between phases and therefore cannot be rotated automatically. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document credential types that cannot be rotated.
The automatic-rotation list omits the OpenVPN TLS auth key, which the detailed guide identifies as not rotatable manually or automatically. Explicitly distinguish manual-only credentials from credentials that cannot be rotated at all, so users do not search for or attempt an unavailable procedure.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hugo/content/docs/getting-started/features/credential-rotation.md` around
lines 49 - 57, Update the “Automatic Rotation” section to explicitly list the
OpenVPN TLS auth key as a credential that cannot be rotated manually or
automatically. Distinguish it from certificate authorities and the
ServiceAccount signing key, which require manual rotation between phases, and
preserve the existing automatic-rotation list.
| ## Infrastructure Credentials | ||
|
|
||
|  | ||
|
|
||
| You grant Gardener permissions to create resources by handing over cloud provider keys. | ||
| These keys are stored in a secret and referenced to a shoot via a SecretBinding. | ||
| Gardener uses the keys to create the network for the cluster resources, routes, VMs, disks, and IP addresses. | ||
| Infrastructure credentials are cloud provider keys you supply to Gardener so it can manage your cluster's infrastructure (networks, VMs, disks, load balancers). | ||
| These keys are stored in a `Secret` in the garden cluster's project namespace and referenced by your Shoot via a `CredentialsBinding`. A single `Secret` can be shared across multiple Shoots. | ||
|
|
||
| When you rotate credentials, the new keys have to be stored in the same secret and the shoot needs to reconcile successfully to ensure the replication to every controller. | ||
| Afterward, the old keys can be deleted safely from Gardener's perspective. | ||
|
|
||
| While the reconciliation can be triggered manually, there is no need for it (if you're not in a hurry). | ||
| Each shoot reconciles once within 24h and the new keys will be picked up during the next maintenance window. | ||
| When you rotate these credentials, you update the `Secret` with new keys, wait for all Shoots referencing that `Secret` to reconcile successfully, and only then deactivate the old keys in your cloud provider account. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Add verification and failure handling for shared infrastructure credentials.
The instruction to “wait for all Shoots” is not actionable enough. Provide the expected reconciliation/status checks, timing expectations, and a procedure for handling one Shoot that fails to reconcile. Because the Secret may be shared, deactivating old cloud keys prematurely can disrupt multiple Shoots.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@hugo/content/docs/getting-started/features/credential-rotation.md` around
lines 61 - 68, Expand the credential-rotation guidance around “When you rotate
these credentials” with actionable verification: specify how to confirm every
referencing Shoot has reconciled successfully, the expected timing or polling
interval, and the status conditions to check. Add failure handling for an
individual Shoot, including investigating or remediating it and keeping the old
provider keys active until all shared-Shoot reconciliations succeed.
2 participants
How to categorize this PR?
/kind enhancement
What this PR does / why we need it:
This PR updates the Credentials Rotation page to better reflect the user needs.
Which issue(s) this PR fixes:
Part of #1002
Special notes for your reviewer:
Summary by CodeRabbit