diff --git a/hugo/content/docs/getting-started/features/credential-rotation.md b/hugo/content/docs/getting-started/features/credential-rotation.md index 1f0401e36..336a56ef2 100644 --- a/hugo/content/docs/getting-started/features/credential-rotation.md +++ b/hugo/content/docs/getting-started/features/credential-rotation.md @@ -13,71 +13,61 @@ next: false local: true --- -# Credential Rotation +## Overview -## Keys +Gardener deals with two distinct classes of credentials for Shoot clusters. They differ in scope, ownership, and how they are rotated: -There are plenty of keys in Gardener. -The ETCD needs one to store resources like secrets encrypted at rest. -Gardener generates certificate authorities (CAs) to ensure secured communication between the various components and actors and service account tokens are signed with a dedicated key. -There is also an SSH key pair to allow debugging of nodes and the observability stack has its own passwords too. +| 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 | -![keys](/docs/getting-started/features/images/keys.webp) +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. -All of these keys share a common property: they are managed by Gardener. -Rotating them, however, is potentially very disruptive. -Hence, Gardener does not do it automatically, but offers you means to perform these tasks easily. -For a single cluster, you may conveniently use the dashboard. +For step-by-step instructions, go directly to the relevant section in the [Credentials Rotation for Shoot Clusters](https://github.com/gardener/gardener/blob/master/docs/usage/shoot-operations/shoot_credentials_rotation.md) documentation: +- [Infrastructure credentials](https://github.com/gardener/gardener/blob/master/docs/usage/shoot-operations/shoot_credentials_rotation.md#infrastructure-credentials-project-scoped) (cloud provider keys) +- [Shoot credentials](https://github.com/gardener/gardener/blob/master/docs/usage/shoot-operations/shoot_credentials_rotation.md#shoot-credentials-gardener-managed) (CAs, SSH, ETCD, etc.) -![Prepare the rotation of all credentials from the Gardener dashboard](/docs/getting-started/features/images/prepare-rotation-of-all-credentials.webp) +## 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 +![rotation-phases](/docs/getting-started/features/images/rotation-phases.webp) -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 annotate shoot 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`. -Afterward, the Completing phase will invalidate the old keys / CA bundles. -Annotate the shoot resource accordingly: +You can also conveniently trigger rotation from the Gardener dashboard: -```bash -kubectl -n annotate shoot gardener.cloud/operation=rotate-credentials-complete -``` +![Prepare the rotation of all credentials from the Gardener dashboard](./images/prepare-rotation-of-all-credentials.webp) -## Rotation Phases +## Automatic Rotation -![rotation-phases](/docs/getting-started/features/images/rotation-phases.webp) +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. -For more information, see [Credentials Rotation for Shoot Clusters](/docs/gardener/shoot-operations/shoot_credentials_rotation/). +For configuration details, see [Automatic Credentials Rotation](https://github.com/gardener/gardener/blob/master/docs/usage/shoot/shoot_maintenance.md#automatic-credentials-rotation). -## User-Provided Credentials +## Infrastructure Credentials ![user-provided-keys](/docs/getting-started/features/images/user-provided-keys.webp) -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. > [!NOTE] -> It is not possible to move a shoot to a different infrastructure account (at all!). +> It is not possible to move a Shoot to a different infrastructure account. + +For the full rotation procedure, see [Infrastructure Credentials (Project-Scoped)](https://github.com/gardener/gardener/blob/master/docs/usage/shoot-operations/shoot_credentials_rotation.md#infrastructure-credentials-project-scoped) in the Credentials Rotation guide.