doc about new option default-cleanup-policy

content/docs/cli/controller.md

@@ -35,7 +35,8 @@ Flags:
       --dns01-check-retry-period duration                   The duration the controller should wait between a propagation check. Despite the name, this flag is used to configure the wait period for both DNS01 and HTTP01 challenge propagation checks. For DNS01 challenges the propagation check verifies that a TXT record with the challenge token has been created. For HTTP01 challenges the propagation check verifies that the challenge token is served at the challenge URL.This should be a valid duration string, for example 180s or 1h (default 10s)
       --dns01-recursive-nameservers strings                 A list of comma separated dns server endpoints used for DNS01 check requests. This should be a list containing host and port, for example 8.8.8.8:53,8.8.4.4:53
       --dns01-recursive-nameservers-only                    When true, cert-manager will only ever query the configured DNS resolvers to perform the ACME DNS01 self check. This is useful in DNS constrained environments, where access to authoritative nameservers is restricted. Enabling this option could cause the DNS01 self check to take longer due to caching performed by the recursive nameservers.
-      --enable-certificate-owner-ref                        Whether to set the certificate resource as an owner of secret where the tls certificate is stored. When this flag is enabled, the secret will be automatically removed when the certificate resource is deleted.
+      --enable-certificate-owner-ref                        Whether to set the certificate resource as an owner of secret where the tls certificate is stored. When this flag is enabled, the secret will be automatically removed when the certificate resource is deleted. This flag is deprecated, but takes precedence over --default-secret-cleanup-policy for backward compatibility. Use --default-secret-cleanup-policy instead of it.
+      --default-secret-cleanup-policy                       When this field is set to `OnDelete`, the owner reference is always created on the Secret resource and the secret will be automatically removed when the certificate resource is deleted. When this field is set to `Never`, the owner reference is never created on the Secret resource and the secret will not be automatically removed when the certificate resource is deleted.
       --enable-profiling                                    Enable profiling for controller.
       --feature-gates mapStringBool                         A set of key=value pairs that describe feature gates for alpha/experimental features. Options are:
                                                             AdditionalCertificateOutputFormats=true|false (ALPHA - default=false)

content/docs/usage/certificate.md

@@ -267,11 +267,53 @@ associated with compromised keys.
 
 ## Cleaning up Secrets when Certificates are deleted
 
-By default, cert-manager does not delete the `Secret` resource containing the signed certificate when the corresponding `Certificate` resource is deleted.
-This means that deleting a `Certificate` won't take down any services that are currently relying on that certificate, but the certificate will no longer be renewed.
+By default, cert-manager does not delete the `Secret` resource containing the
+signed certificate when the corresponding `Certificate` resource is deleted.
+This means that deleting a `Certificate` won't take down any services that are
+currently relying on that certificate, but the certificate will no longer be renewed.
 The `Secret` needs to be manually deleted if it is no longer needed.
 
-If you would prefer the `Secret` to be deleted automatically when the `Certificate` is deleted, you need to configure your installation to pass the `--enable-certificate-owner-ref` flag to the controller.
+If you would prefer the `Secret` to be deleted automatically when the `Certificate`
+is deleted, you will need to set `cleanupPolicy: OnDelete` on the Certificate resource. Alternatively, you can add the flag `--default-secret-cleanup-policy=OnDelete` to the cert-manager controller pod in case you want all Secret resources to be cleaned up by default.
+
+#### `cleanupPolicy`
+**FEATURE STATE**: This feature is available since cert-manager 1.12.
+
+`cleanupPolicy` is when this field is set to `OnDelete`, the owner reference
+is always created on the Secret resource and the secret will be automatically
+removed when the certificate resource is deleted. When this field is set to `Never`,
+the owner reference is never created on the Secret resource and the secret will not
+be automatically removed when the certificate resource is deleted.
+If the value of this field is unset this field "inherits" the value of
+the flag `--default-secret-cleanup-policy`.
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: my-cert
+spec:
+  ...
+  secretName: my-cert-tls
+  cleanupPolicy: OnDelete
+```
+
+Results in:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: my-cert-tls
+  ownerReferences:
+  - apiVersion: cert-manager.io/v1
+    blockOwnerDeletion: true
+    controller: true
+    kind: Certificate
+    name: my-cert
+    ...
+type: kubernetes.io/tls
+```
 
 ## Renewal