diff --git a/content/docs/cli/controller.md b/content/docs/cli/controller.md index 768ffb05ccd..401f3e98d6c 100644 --- a/content/docs/cli/controller.md +++ b/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) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index d0bce92755a..0626f7e1fdf 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -267,11 +267,60 @@ 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. + +The field `cleanupPolicy` can be used on the Certificate resource to configure +whether cert-manager should remove the leftover Secret resource when the +Certificate is deleted. + +When this field is set to `OnDelete`, the Secret resource will automatically +be removed when the Certificate is deleted. That works by adding an owner +reference on the Secret resource. + +When this field is set to `Never`, the Secret resource is preserved when +the Certificate is deleted. + +When this field is unset, the value of the flag `--default-secret-cleanup-policy` +is used. + +```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