From 17fea67a9e267ecceb9902fc52b585d334b003d6 Mon Sep 17 00:00:00 2001 From: timonwong Date: Mon, 24 Aug 2026 12:40:47 +0800 Subject: [PATCH 1/5] docs: document cluster-cert-rotator v1.0.13 --- docs/en/security/cert/k8s-cert-rotator.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/en/security/cert/k8s-cert-rotator.mdx b/docs/en/security/cert/k8s-cert-rotator.mdx index 55fb1094a..85ecf803f 100644 --- a/docs/en/security/cert/k8s-cert-rotator.mdx +++ b/docs/en/security/cert/k8s-cert-rotator.mdx @@ -18,6 +18,21 @@ See [Cluster Plugin](/extend/cluster_plugin.mdx) for installation instructions. > * On-Premises clusters > * DCS clusters +## Configuration + +The plugin exposes the following certificate settings through its installation form: + +| Setting | Default | Description | +| --- | --- | --- | +| Control-plane certificate duration | `8760h` (365 days) | Validity period for renewed control-plane certificates. | +| Control-plane renewal threshold | `1752h` (73 days) | Renew when less than this duration remains. | +| Kubelet certificate duration | `2184h` (91 days) | Validity period for renewed kubelet certificates. | +| Kubelet renewal threshold | `720h` (30 days) | Renew when less than this duration remains. | +| Check interval | `24h` | Interval between certificate checks. | +| Renew kubelet client certificate | Disabled | Also renew the client certificate referenced by `kubelet.conf`. | + +The plugin applies the configured values to subsequent checks and rotations. + ## How it works This plugin handles automatic rotation for the following certificates. From eb1327aba5fcd95cc8bbac901dcb87c7a9906056 Mon Sep 17 00:00:00 2001 From: timonwong Date: Tue, 25 Aug 2026 12:49:54 +0800 Subject: [PATCH 2/5] docs: consolidate certificate rotation settings --- docs/en/security/cert/k8s-cert-rotator.mdx | 26 +++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/en/security/cert/k8s-cert-rotator.mdx b/docs/en/security/cert/k8s-cert-rotator.mdx index 85ecf803f..0291b30c9 100644 --- a/docs/en/security/cert/k8s-cert-rotator.mdx +++ b/docs/en/security/cert/k8s-cert-rotator.mdx @@ -20,19 +20,24 @@ See [Cluster Plugin](/extend/cluster_plugin.mdx) for installation instructions. ## Configuration -The plugin exposes the following certificate settings through its installation form: +The plugin exposes the following certificate settings through its installation form. The controller uses the configured renewal threshold for each certificate type and checks certificates at the configured interval. + +### Certificate settings + +| Certificate | Validity period | 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 | + +The approximate rotation point is derived from the validity period and renewal threshold. Actual timing can vary by one check interval. If you customize these values, the configured values take precedence. + +### Operation settings | Setting | Default | Description | | --- | --- | --- | -| Control-plane certificate duration | `8760h` (365 days) | Validity period for renewed control-plane certificates. | -| Control-plane renewal threshold | `1752h` (73 days) | Renew when less than this duration remains. | -| Kubelet certificate duration | `2184h` (91 days) | Validity period for renewed kubelet certificates. | -| Kubelet renewal threshold | `720h` (30 days) | Renew when less than this duration remains. | | Check interval | `24h` | Interval between certificate checks. | | Renew kubelet client certificate | Disabled | Also renew the client certificate referenced by `kubelet.conf`. | -The plugin applies the configured values to subsequent checks and rotations. - ## How it works This plugin handles automatic rotation for the following certificates. @@ -59,7 +64,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. Rotation is triggered when the remaining validity period reaches the configured renewal threshold for that certificate type. A certificate whose validity period differs from the expected duration is also renewed. 3. **Rotation queue** @@ -84,11 +89,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: From 0aa6787dcd5330e3635199db8b06ecbccb77af70 Mon Sep 17 00:00:00 2001 From: timonwong Date: Tue, 25 Aug 2026 13:34:04 +0800 Subject: [PATCH 3/5] docs: clarify default rotation settings --- docs/en/security/cert/k8s-cert-rotator.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/security/cert/k8s-cert-rotator.mdx b/docs/en/security/cert/k8s-cert-rotator.mdx index 0291b30c9..841fdfd37 100644 --- a/docs/en/security/cert/k8s-cert-rotator.mdx +++ b/docs/en/security/cert/k8s-cert-rotator.mdx @@ -20,16 +20,16 @@ See [Cluster Plugin](/extend/cluster_plugin.mdx) for installation instructions. ## Configuration -The plugin exposes the following certificate settings through its installation form. The controller uses the configured renewal threshold for each certificate type and checks certificates at the configured interval. +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 | Renewal threshold | Approximate rotation point | +| 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 | -The approximate rotation point is derived from the validity period and renewal threshold. Actual timing can vary by one check interval. If you customize these values, the configured values take precedence. +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 @@ -64,7 +64,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 when the remaining validity period reaches the configured renewal threshold for that certificate type. A certificate whose validity period differs from the expected duration is also renewed. + 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** From e3787bc163478bfd095039eb80cedad12e22e609 Mon Sep 17 00:00:00 2001 From: timonwong Date: Tue, 25 Aug 2026 13:51:15 +0800 Subject: [PATCH 4/5] docs: add certificate rotation installation warning --- docs/en/security/cert/k8s-cert-rotator.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/en/security/cert/k8s-cert-rotator.mdx b/docs/en/security/cert/k8s-cert-rotator.mdx index 841fdfd37..6ddf751a4 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. +:::warning +**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. From e73e39fca9648b4ff990db7d17437331d4be620b Mon Sep 17 00:00:00 2001 From: timonwong Date: Tue, 25 Aug 2026 13:52:38 +0800 Subject: [PATCH 5/5] docs: use caution for certificate rotation notice --- docs/en/security/cert/k8s-cert-rotator.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/security/cert/k8s-cert-rotator.mdx b/docs/en/security/cert/k8s-cert-rotator.mdx index 6ddf751a4..96abbc0ae 100644 --- a/docs/en/security/cert/k8s-cert-rotator.mdx +++ b/docs/en/security/cert/k8s-cert-rotator.mdx @@ -7,7 +7,7 @@ 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. -:::warning +:::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.