diff --git a/docs/en/security/cert/k8s-cert-rotator.mdx b/docs/en/security/cert/k8s-cert-rotator.mdx index 55fb1094a..96abbc0ae 100644 --- a/docs/en/security/cert/k8s-cert-rotator.mdx +++ b/docs/en/security/cert/k8s-cert-rotator.mdx @@ -7,6 +7,16 @@ title: Automated Kubernetes Certificate Rotation This guide helps you install, understand, and operate the Kubernetes Certificate Rotator in to automate the rotation of Kubernetes certificates within your clusters. +:::caution +**Use this plugin only when certificate rotation is required** + +Kubernetes certificates are valid for 10 years by default. Enabling this plugin changes certificates managed by the plugin to short-lived certificates: 91 days for kubelet certificates and 365 days for control-plane certificates. + +Automatic renewal restarts components such as the API server and kubelet, which may affect cluster availability and business workloads. If rotation takes longer than 30 seconds, a node may become `NotReady` and its pods may be evicted. + +If certificate rotation is not required, do not install this plugin. +::: + ## Installation See [Cluster Plugin](/extend/cluster_plugin.mdx) for installation instructions. @@ -18,6 +28,26 @@ See [Cluster Plugin](/extend/cluster_plugin.mdx) for installation instructions. > * On-Premises clusters > * DCS clusters +## Configuration + +The following are the plugin's default certificate settings. The controller uses the configured renewal threshold for each certificate type and checks certificates at the configured interval. + +### Certificate settings + +| Certificate | Validity period | Default renewal threshold | Approximate rotation point | +| --- | --- | --- | --- | +| Control plane | `8760h` (365 days) | `1752h` (73 days remaining) | About 292 days after issuance | +| Kubelet | `2184h` (91 days) | `720h` (30 days remaining) | About 61 days after issuance | + +With the default settings, certificates are renewed when the remaining validity is less than 20% or 30 days, whichever threshold is reached first. This corresponds to about 292 days for control-plane certificates and about 61 days for kubelet certificates after issuance. Actual timing can vary by one check interval. If you override the deployment values, the configured renewal thresholds take precedence. + +### Operation settings + +| Setting | Default | Description | +| --- | --- | --- | +| Check interval | `24h` | Interval between certificate checks. | +| Renew kubelet client certificate | Disabled | Also renew the client certificate referenced by `kubelet.conf`. | + ## How it works This plugin handles automatic rotation for the following certificates. @@ -44,7 +74,7 @@ This plugin handles automatic rotation for the following certificates. 2. **Rotation Trigger Condition** - The `notBefore` and `notAfter` fields of the certificate indicate the validity period. Rotation is triggered if the remaining validity period is less than 20% or 30 days. + The `notBefore` and `notAfter` fields of the certificate indicate the validity period. By default, rotation is triggered when the remaining validity is less than 20% or 30 days, whichever threshold is reached first. The controller applies the configured renewal threshold for each certificate type, so overridden values take precedence. A certificate whose validity period differs from the expected duration is also renewed. 3. **Rotation queue** @@ -69,11 +99,6 @@ This plugin handles automatic rotation for the following certificates. * Etcd can auto-reload the certificates. -6. **Rotation Timelines** - - * `kubelet` certificates: Rotate at 61 days (91-day validity) - * Control plane certificates: Rotate at 292 days (365-day validity) - ## Operation Considerations If `kubelet` is in an abnormal state during the rotation window and cannot rotate certificates automatically, manual rotation is required: