From dd1ebd7d8a592e72cd50ffa2497bca3d04f194ab Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Fri, 17 Jul 2026 10:51:08 +0000 Subject: [PATCH 1/2] add renewal policy scenarios and link release notes to docs Add worked, realistic scenarios (change-control windows, coordinating rotation with paired systems, avoiding renewal during a traffic freeze, and disabling renewal for manually-managed root CAs) to the existing renewal policies and renewal windows documentation. Also fix the v1.21 release notes entry for this feature: it referenced a non-existent `renewalPolicies` field (the actual field is `spec.renewal`), and linked to the implementation PR rather than to the user-facing documentation. Signed-off-by: Richard Wall --- .../release-notes/release-notes-1.21.md | 2 +- content/docs/usage/certificate.md | 75 +++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) diff --git a/content/docs/releases/release-notes/release-notes-1.21.md b/content/docs/releases/release-notes/release-notes-1.21.md index d91f62edaa2..1f60dd91d10 100644 --- a/content/docs/releases/release-notes/release-notes-1.21.md +++ b/content/docs/releases/release-notes/release-notes-1.21.md @@ -36,7 +36,7 @@ The Helm values `prometheus.servicemonitor.targetPort`, `prometheus.servicemonit - **ACME Renewal Information (ARI)**: experimental support for [RFC 9773](https://www.rfc-editor.org/rfc/rfc9773) behind the `ACMEUseARI` feature gate. When enabled, cert-manager queries the ACME server's `renewalInfo` endpoint for the recommended renewal window, allowing servers like Let's Encrypt to proactively prompt renewal during mass revocations or CA key rollovers. ([#8798](https://github.com/cert-manager/cert-manager/pull/8798)) - **`waitInsteadOfSelfCheck` solver option**: skip cert-manager's own self-check and instead wait a configured duration before asking the ACME server to validate. An escape hatch for split-horizon DNS and NAT hairpin environments. See [configuration details](../../configuration/acme/README.md#skip-the-self-check-with-waitinsteadofselfcheck). ([#8858](https://github.com/cert-manager/cert-manager/pull/8858)) - **AWS IAM authentication for Vault**: the Vault issuer now supports IRSA, EKS Pod Identity, and ambient EC2/ECS credentials, removing the need for long-lived AWS Secrets. ([#8422](https://github.com/cert-manager/cert-manager/pull/8422)) -- **Certificate renewal policies**: a new `renewalPolicies` field on the Certificate API provides more expressive control over renewal scheduling, complementing `renewBefore` and `renewBeforePercentage`. ([#8258](https://github.com/cert-manager/cert-manager/pull/8258)) +- **Certificate renewal policies**: a new `renewal` field on the Certificate API provides more expressive control over renewal scheduling, complementing `renewBefore` and `renewBeforePercentage` — including restricting renewal to approved maintenance windows and disabling automatic renewal entirely. See [renewal policies and renewal windows](../../usage/certificate.md#renewal-policies-and-windows). ([#8258](https://github.com/cert-manager/cert-manager/pull/8258)) - **Configurable CertificateRequest retry backoff**: the new `--certificate-request-maximum-backoff-duration` flag (default: 32 hours) caps the exponential backoff for failed CertificateRequests, useful for environments with scheduled CA maintenance windows. ([#8893](https://github.com/cert-manager/cert-manager/pull/8893)) - **Modern2026 PKCS#12 profile**: a new FIPS 140-3 compatible encoding profile using AES-256 + SHA-256 KDFs instead of legacy 3DES/RC2. ([#8841](https://github.com/cert-manager/cert-manager/pull/8841)) - **Webhook certificate renewal after system suspend**: the webhook now detects missed certificate renewals after system suspend (S3/S4) or VM live migration by polling wall-clock time, recovering within one minute of resume. ([#8464](https://github.com/cert-manager/cert-manager/pull/8464)) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index 91d5e466125..221efb210dc 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -322,6 +322,7 @@ It is also required that `spec.duration` > `spec.renewBefore`. Once an X.509 certificate has been issued, cert-manager will calculate the renewal time for the `Certificate`. By default this will be 2/3 through the X.509 certificate's duration. If `spec.renewBefore` or `spec.renewBeforePercentage` has been set, it will be the effective `spec.renewBefore` amount of time before expiry. cert-manager will set `Certificate`'s `status.RenewalTime` to the time when the renewal will be attempted. + ### Renewal policies and renewal windows In addition to `spec.renewBefore` and `spec.renewBeforePercentage`, cert-manager supports @@ -411,6 +412,80 @@ To disable automatic renewal for a certificate, set `spec.renewal.policy` to `Di > will still happen at the calculated `desiredRenewalTime` using the `spec.renewBefore`/ `spec.renewBeforePercentage` fields. > This behavior is intentional and is done to avoid certificates from expiring due to window misconfiguration. +#### Realistic scenarios + +**Regulated change-control windows.** Organizations subject to formal change management (for +example, financial services or healthcare) often require that any production change, including +certificate rotation, only happens inside a pre-approved maintenance window, so that on-call +staff are available if something goes wrong and so the change is auditable against a change +ticket. A weekly Sunday-morning window keeps renewal off the calculated `renewBefore` time and +onto a predictable, approved schedule instead: + +```yaml +spec: + duration: 2160h # 90d + renewBefore: 360h # 15d + renewal: + policy: RenewBefore + windows: + - cron: "0 3 * * 0" # every Sunday at 03:00 + timezone: America/New_York + windowDuration: 2h +``` + +**Coordinating rotation with a paired system.** Some certificates are consumed by more than one +independently-managed system that must pick up a new certificate together — for example, an +mTLS certificate shared with an external partner, or a certificate whose private key is mirrored +into a hardware security module (HSM) by a separate process. Renewing on an unpredictable +schedule risks one side rotating before the other is ready. Restricting renewal to a known +window (agreed with the partner team, or aligned with the HSM sync job's own schedule) means +downstream automation can reliably run immediately afterwards: + +```yaml +spec: + duration: 8760h # 365d + renewBefore: 720h # 30d + renewal: + policy: RenewBefore + windows: + - cron: "0 1 1 * *" # 01:00 on the first of each month + timezone: UTC + windowDuration: 4h +``` + +**Avoiding renewal during a traffic freeze.** A retailer running a change freeze during a +high-traffic sales event (for example, Black Friday week) wants to guarantee that no certificate +rotation happens during that period, even if the calculated `renewBefore` time falls inside it. +Configuring windows that only open outside the freeze period defers renewal until the next +matching window after the freeze ends, provided one still exists before the certificate expires: + +```yaml +spec: + duration: 2160h # 90d + renewBefore: 720h # 30d + renewal: + policy: RenewBefore + windows: + - cron: "0 4 * * 2" # Tuesdays at 04:00, well outside the freeze + timezone: America/Chicago + windowDuration: 3h +``` + +**Manually-managed root and intermediate CAs.** A root or long-lived intermediate CA certificate +is sometimes deliberately excluded from automated rotation because reissuing it requires an +offline key ceremony, updating distributed trust bundles across many clusters, or other manual +coordination that cert-manager cannot perform on its own. Setting `policy: Disabled` documents +that intent directly on the resource and prevents cert-manager from ever attempting an +unattended rotation of it: + +```yaml +spec: + isCA: true + duration: 87600h # 10y + renewal: + policy: Disabled +``` + ### Reissuance triggered by user actions From 8f82fd2af71df95d8685fe7996e7929c0069ef8b Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Tue, 28 Jul 2026 08:36:33 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Hemant Joshi Signed-off-by: Richard Wall --- content/docs/usage/certificate.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index 221efb210dc..4ef7e9a15b6 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -433,13 +433,13 @@ spec: windowDuration: 2h ``` -**Coordinating rotation with a paired system.** Some certificates are consumed by more than one +**Coordinating rotation with a paired system:** Some certificates are consumed by more than one independently-managed system that must pick up a new certificate together — for example, an mTLS certificate shared with an external partner, or a certificate whose private key is mirrored into a hardware security module (HSM) by a separate process. Renewing on an unpredictable schedule risks one side rotating before the other is ready. Restricting renewal to a known window (agreed with the partner team, or aligned with the HSM sync job's own schedule) means -downstream automation can reliably run immediately afterwards: +downstream automation can reliably run immediately afterwards. ```yaml spec: @@ -453,11 +453,11 @@ spec: windowDuration: 4h ``` -**Avoiding renewal during a traffic freeze.** A retailer running a change freeze during a +**Avoiding renewal during a traffic freeze:** A retailer running a change freeze during a high-traffic sales event (for example, Black Friday week) wants to guarantee that no certificate rotation happens during that period, even if the calculated `renewBefore` time falls inside it. Configuring windows that only open outside the freeze period defers renewal until the next -matching window after the freeze ends, provided one still exists before the certificate expires: +matching window after the freeze ends, provided one still exists before the certificate expires. ```yaml spec: @@ -471,12 +471,12 @@ spec: windowDuration: 3h ``` -**Manually-managed root and intermediate CAs.** A root or long-lived intermediate CA certificate +**Manually-managed root and intermediate CAs:** A root or long-lived intermediate CA certificate is sometimes deliberately excluded from automated rotation because reissuing it requires an offline key ceremony, updating distributed trust bundles across many clusters, or other manual coordination that cert-manager cannot perform on its own. Setting `policy: Disabled` documents that intent directly on the resource and prevents cert-manager from ever attempting an -unattended rotation of it: +unattended rotation of it. ```yaml spec: