cert-manager has the concept of ‘Certificates’ that define a desired X.509 certificate. A Certificate is a namespaced resource that references an Issuer or ClusterIssuer for information on how to obtain the certificate.
A simple Certificate could be defined as:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
apiVersion: certmanager.k8s.io/v1alpha1 kind: Certificate metadata: name: acme-crt spec: secretName: acme-crt-secret dnsNames: - foo.example.com - bar.example.com acme: config: - ingressClass: nginx domains: - foo.example.com - bar.example.com issuerRef: name: letsencrypt-prod # We can reference ClusterIssuers by changing the kind here. # The default value is Issuer (i.e. a locally namespaced Issuer) kind: Issuer
This Certificate will tell cert-manager to attempt to use the Issuer
letsencrypt-prod to obtain a certificate key pair for the
bar.example.com domains. If successful, the
resulting key and certificate will be stored in a secret named
acme-crt-secret with keys of
This secret will live in the same namespace as the
dnsNames field specifies a list of Subject Alternative Names to be
associated with the certificate. If the
commonName field is omitted, the
first element in the list will be the common name.
The referenced Issuer must exist in the same namespace as the Certificate. A Certificate can alternatively reference a ClusterIssuer which is non-namespaced.
Certificate Duration and Renewal Window¶
cert-manager Certificate resources also support custom validity durations and renewal windows.
Important: The backend service implementation can choose to generate a certificate with a different validity period than what is requested in the issuer.
Although the duration and renewal periods are specified on the Certificate resources, the corresponding Issuer or ClusterIssuer must support this.
The table below shows the support state of the different backend services used by issuer types:
|ACME||Only ‘renewBefore’ supported|
|Vault||Fully supported (although the requested duration must be lower than the configured Vault role’s TTL)|
|Self Signed||Fully supported|
The default duration for all certificates is 90 days and the default renewal windows is 30 days. This means that certificates are considered valid for 3 months and renewal will be attempted within 1 month of expiration.
The duration and renewBefore parameters must be given in the golang parseDuration string format.
Here an example of an issuer specifying the duration and renewal window.
The certificate from the previous section is extended with a validity period of 24 hours and to begin trying to renew 12 hours before the certificate expiration.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 apiVersion: certmanager.k8s.io/v1alpha1 kind: Certificate metadata: name: example spec: secretName: example-tls duration: 24h renewBefore: 12h dnsNames: - foo.example.com - bar.example.com issuerRef: name: my-internal-ca kind: Issuer