Merge pull request #1681 from wallrj/release-note-private-key-rotation-always

[release-1.18] [VC-39805] Document the change of PrivateKeyRotationPolicy to Always

Author: cert-manager-prow[bot]

.spelling

@@ -543,6 +543,7 @@ ulrichgi
 uncomment
 unencrypted
 uninstallation
+unintuitive
 unredacted
 unschedule
 untrusted

content/docs/contributing/api-compatibility.md

@@ -11,7 +11,8 @@ after an upgrade or downgrade of cert-manager.
 In some cases, we may need to require users to take actions before upgrading or may need to diverge from the API compatibility promise but we'll treat this as an absolute
 last resort. In general the main criteria by which we'd determine whether a change is acceptable would be user value.
 
-For example in the event of a truly critical bug, a fix that breaks the API compatibility promise by changing the default behavior of an API field _might_ be acceptable. As of yet, though, there has never been a need for such a change.
+Here are the breaking changes we have made to the `v1` API:
+* [cert-manger 1.18](../releases/release-notes/release-notes-1.18.md): The default value of `Certificate.Spec.PrivateKey.RotationPolicy` changed from `Never` to `Always`.
 
 ## Alpha / Beta API Versions
 

content/docs/releases/release-notes/release-notes-1.18.md

@@ -9,6 +9,47 @@ cert-manager v1.18 includes:
 
 ## Major Themes
 
+### The default value of `Certificate.Spec.PrivateKey.RotationPolicy` is now `Always`
+
+> ⚠️ Breaking change
+
+We have changed the default value of `Certificate.Spec.PrivateKey.RotationPolicy` from `Never` to `Always`.
+
+Why? Because the old default was unintuitive and insecure.
+For example, if a private key is exposed, users may (reasonably) assume that
+re-issuing a certificate (e.g. using `cmctl renew`) will generate a new private
+key, but it won't unless the user has explicitly set `rotationPolicy: Always` on the Certificate resource.
+
+This change is feature gated and is enabled by default, because it has been fast-tracked to beta status.
+
+Users who want to preserve the old default have two options:
+1. Explicitly set `rotationPolicy: Never` on your Certificate resources.
+2. Turn off the feature gate in this release and explicitly set
+   `rotationPolicy: Never` on your Certificates before release 1.19.
+   In release 1.19, the feature will be marked as GA and it will no longer be
+   possible to turn off the feature.
+
+The following Helm chart values can be used to turn off the feature gate:
+
+```yaml
+# values.yaml
+config:
+  featureGates:
+    DefaultPrivateKeyRotationPolicyAlways: false
+```
+
+> ℹ️ The old default value `Never` was always intended to be changed before API `v1`, as can be seen in the description of the [original PR](https://github.com/cert-manager/cert-manager/pull/2814):
+> > For backward compatibility, the empty value is treated as 'Never' which matches the behavior we have today.
+> > In a future API version, we can flip this default to be Always.
+>
+> 📖 See [Issue: 7601: Change `PrivateKey.RotationPolicy` to default to Always](https://github.com/cert-manager/cert-manager/issues/7601) to read the proposal for this change and the discussion around it.
+>
+> 📖 Read [cert-manager component configuration](../../installation/configuring-components.md) to learn more about feature gates.
+>
+> 📖 Read our updated [API compatibility statement](../../contributing/api-compatibility.md) which now reflects our new, more flexible, approach to changing API defaults, with a view to introducing other "sane" default API values in future releases.
+>
+> 📖 Read [Issuance behavior: Rotation of the private key](../../usage/certificate.md#issuance-behavior-rotation-of-the-private-key) to learn more about private key rotation in cert-manager.
+
 ### Copy annotations from Ingress or Gateway to the Certificate
 
 We've added a new configuration option to the cert-manager controller: `--extra-certificate-annotations`, which allows you to specify annotation keys to be copied from an Ingress or Gateway resource to the resulting Certificate object.

content/docs/releases/upgrading/upgrading-1.17-1.18.md

@@ -5,7 +5,9 @@ description: 'cert-manager installation: Upgrading v1.17 to v1.18'
 
 Before upgrading cert-manager from 1.17 to 1.18, please read the following important notes about breaking changes in 1.18:
 
-1. TODO
+1. We have changed the default value of `Certificate.Spec.PrivateKey.RotationPolicy` from `Never` to `Always`.
+
+   > 📖 Read [Release 1.18 notes](../release-notes/release-notes-1.18.md) for more information..
 
 ## Next Steps
 

content/docs/tutorials/certificate-defaults/README.md

@@ -159,6 +159,7 @@ These rules will:
 
 - Set a default value of: `revisionHistoryLimit: 2`.
 - Set a [default value of `Always` under `spec.privateKey.rotationPolicy`](../../usage/certificate.md#the-rotationpolicy-setting).
+  > ℹ️ This is not necessary if you use cert-manager `>=v1.18.0`, because the default value was changed from `Never` to `Always`.
 - Set defaults for all `spec.privateKey` fields.
 
 > ℹ️ Note how these rules tackle the first two of our [uses cases](#use-cases).

content/docs/usage/certificate.md

@@ -377,8 +377,15 @@ Adding the following annotation on an ingress will automatically set "issue-temp
 <a id="rotation-private-key"></a>
 ## Issuance behavior: Rotation of the private key
 
-By default, the private key won't be rotated automatically. Using the setting
-`rotationPolicy: Always`, the private key Secret associated with a Certificate
+> ⚠️ In cert-manager v1.18.0, the default `rotationPolicy` was changed.
+>
+> In cert-manager `>= v1.18.0` the default is `rotationPolicy: Always`;
+> the private key **is** rotated automatically.
+>
+> In cert-manager `< v1.18.0` the default is `rotationPolicy: Never`;
+> the private key **is not** rotated automatically.
+
+With the setting `rotationPolicy: Always`, the private key Secret associated with a Certificate
 object can be configured to be rotated as soon as an the Certificate is reissued (see
 [Issuance triggers](#issuance-triggers)).
 

content/docs/usage/gateway.md

@@ -436,7 +436,7 @@ Certificate resources:
 
 - `cert-manager.io/private-key-rotation-policy`: (optional) this annotation allows you to
   configure `spec.privateKey.rotationPolicy` field to set the rotation policy of the private key for a Certificate.
-  Valid values are `Never` and `Always`. If unset a rotation policy `Never` will be used.
+  Valid values are `Never` and `Always`. If unset a rotation policy `Always` will be used.
 
 ## Copy annotations to the Certificate
 

content/docs/usage/ingress.md

@@ -175,7 +175,7 @@ trigger Certificate resources to be automatically created:
 
 - `cert-manager.io/private-key-rotation-policy`: (optional) this annotation allows you to
   configure `spec.privateKey.rotationPolicy` field to set the rotation policy of the private key for a Certificate.
-  Valid values are `Never` and `Always`. If unset a rotation policy `Never` will be used.
+  Valid values are `Never` and `Always`. If unset a rotation policy `Always` will be used.
 
 ## Copying annotations to the Certificate
 

public/docs/tutorials/certificate-defaults/cpol-mutate-certificates-0.yaml

@@ -18,6 +18,7 @@ spec:
           # +(...) This is the clever syntax for if not already set
           +(revisionHistoryLimit): 2
   # Set rotation to always if not already set
+  # ℹ️ This is not necessary if you use cert-manager `>=v1.18.0`, because the default value was changed from `Never` to `Always`.
   - name: set-privateKey-rotationPolicy
     match:
       any:

public/docs/tutorials/certificate-defaults/cpol-mutate-certificates-1.yaml

@@ -18,6 +18,7 @@ spec:
           # +(...) This is the clever syntax for if not already set
           +(revisionHistoryLimit): 2
   # Set rotation to always if not already set
+  # ℹ️ This is not necessary if you use cert-manager `>=v1.18.0`, because the default value was changed from `Never` to `Always`.
   - name: set-privateKey-rotationPolicy
     match:
       any: