Add renewal policy scenarios and link release notes to docs

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))

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.
 
+<a id="renewal-policies-and-windows"></a>
 ### 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
+```
+
 <a id="non-renewal-reissuance"></a>
 <a id="actions-triggering-private-key-rotation"></a>
 ### Reissuance triggered by user actions