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 21
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: - http01: 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
Certificate Key Encoding¶
cert-manager Certificate resources support two types of key encodings for its private key known as the private key cryptography standards (PKCS). The two key encodings are PKCS#1 and PKCS#8.
The default encoding is PKCS#1, if the keyEncoding field of the Certificate spec is left empty.
A limitation exists where once a Certificate resource is generated with a specific key encoding, it cannot be generated with a different key encoding.
Here is an example of a Certificate specifying the use of PKCS#8 encoding on its private key.
1 2 3 4 5 6 7 8 9 10 11 12 13 apiVersion: certmanager.k8s.io/v1alpha1 kind: Certificate metadata: name: example-pkcs8-cert spec: secretName: example-pkcs8-secret keyEncoding: pkcs8 dnsNames: - foo.example.com - bar.example.com issuerRef: name: my-internal-ca kind: Issuer