apiVersion: cert-manager.io/v1
kind: Certificate
In cert-manager, the Certificate resource represents a human readable definitionof a certificate request. cert-manager uses this input to generate a private keyand CertificateRequest resource in order to obtaina signed certificate from an Issuer orClusterIssuer. The signed certificate and privatekey are then stored in the specified Secret resource. cert-manager will ensurethat the certificate is auto-renewed before it expires andre-issued if requested.
In order to issue any certificates, you'll need to configure anIssuer or ClusterIssuerresource first.
Creating Certificate Resources
A Certificate resource specifies fields that are used to generate certificatesigning requests which are then fulfilled by the issuer type you havereferenced. Certificates specify which issuer they want to obtain thecertificate from by specifying the certificate.spec.issuerRef field.
A Certificate resource, for the example.com and www.example.com DNS names,spiffe://cluster.local/ns/sandbox/sa/example URI Subject Alternative Name,that is valid for 90 days and renews 15 days before expiry is below. It containsan exhaustive list of all options a Certificate resource may have however onlya subset of fields are required as labelled.
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: example-com
namespace: sandbox
spec:
# Secret names are always required.
secretName: example-com-tls
# secretTemplate is optional. If set, these annotations and labels will be
# copied to the Secret named example-com-tls. These labels and annotations will
# be re-reconciled if the Certificate's secretTemplate changes. secretTemplate
# is also enforced, so relevant label and annotation changes on the Secret by a
# third party will be overwriten by cert-manager to match the secretTemplate.
secretTemplate:
annotations:
my-secret-annotation-1: "foo"
my-secret-annotation-2: "bar"
labels:
my-secret-label: foo
privateKey:
algorithm: RSA
encoding: PKCS1
size: 2048
# keystores allows adding additional output formats. This is an example for reference only.
keystores:
pkcs12:
create: true
passwordSecretRef:
name: example-com-tls-keystore
key: password
profile: Modern2023
duration: 2160h # 90d
renewBefore: 360h # 15d
isCA: false
usages:
- server auth
- client auth
subject:
organizations:
- cert-manager
# Avoid using commonName for DNS names in end-entity (leaf) certificates. Unless you have a specific
# need for it in your environment, use dnsNames exclusively to avoid issues with commonName.
# Usually, commonName is used to give human-readable names to CA certificates and can be avoided for
# other certificates.
commonName: example.com
See AlsoHow to Become a ManagerWhen Do You Need Certificate Management?Certified Manager Certification | Start Your Journey TodayCertificate Manager overview | Google Cloud# The literalSubject field is exclusive with subject and commonName. It allows
# specifying the subject directly as a string. This is useful for when the order
# of the subject fields is important or when the subject contains special types
# which can be specified by their OID.
#
# literalSubject: "O=jetstack, CN=example.com, 2.5.4.42=John, 2.5.4.4=Doe"
# At least one of commonName (possibly through literalSubject), dnsNames, uris, emailAddresses, ipAddresses or otherNames is required.
dnsNames:
- example.com
- www.example.com
uris:
- spiffe://cluster.local/ns/sandbox/sa/example
emailAddresses:
- john.doe@cert-manager.io
ipAddresses:
- 192.168.0.5
# Needs cert-manager 1.14+ and "OtherNames" feature flag
otherNames:
# Should only supply oid of ut8 valued types
- oid: 1.3.6.1.4.1.311.20.2.3 # User Principal Name "OID"
utf8Value: [email protected]
# Issuer references are always required.
issuerRef:
name: ca-issuer
# We can reference ClusterIssuers by changing the kind here.
# The default value is Issuer (i.e. a locally namespaced Issuer)
kind: Issuer
# This is optional since cert-manager will default to this value however
# if you are using an external issuer, change this to that issuer group.
group: cert-manager.io
The signed certificate will be stored in a Secret resource namedexample-com-tls in the same namespace as the Certificate once the issuer hassuccessfully issued the requested certificate.
If secretTemplate is present, annotations and labels set in this propertywill be copied over to example-com-tls secret. Both properties are optional.
The Certificate will be issued using the issuer named ca-issuer in thesandbox namespace (the same namespace as the Certificate resource).
Note: If you want to create an
Issuerthat can be referenced byCertificateresources in all namespaces, you should create aClusterIssuer resource and set thecertificate.spec.issuerRef.kindfield toClusterIssuer.
Note: The
renewBeforeanddurationfields must be specified using a Gotime.Durationstring format,which does not allow thed(days) suffix. You must specify these valuesusings,m, andhsuffixes instead. Failing to do so without installingthe webhook component can prevent cert-managerfrom functioning correctly#1269.
Note: Take care when setting the
renewBeforefield to be very close to thedurationas this can lead to a renewal loop, where theCertificateis alwaysin the renewal period. SomeIssuersset thenotBeforefield on theirissued X.509 certificates before the issue time to fix clock-skew issues,leading to the working duration of a certificate to be less than the fullduration of the certificate. For example, Let's Encrypt sets it to be one hourbefore issue time, so the actual working duration of the certificate is 89days, 23 hours (the full duration remains 90 days).
A full list of the fields supported on the Certificate resource can be found inthe API reference documentation.
Target Secret
When a certificate is issued by an intermediate CA and the Issuer can providethe issued certificate's chain, the contents of tls.crt will be the requestedcertificate followed by the certificate chain.
Additionally, if the Certificate Authority is known, the corresponding CAcertificate will be stored in the secret with key ca.crt. For example, withthe ACME issuer, the CA is not known and ca.crt will not exist in the Secret.The ca.crt value at the time of issuance can be copied to the trust store ofthe application that is using the certificate. However, DO NOT directly mountthe ca.crt value into the application's trust store, as it will be updatedwhen the certificate is renewed (see Trusting certificates for more details).
cert-manager intentionally avoids adding root certificates to tls.crt, because theyare useless in a situation where TLS is being done securely. For more information,see RFC 5246 section 7.4.2which contains the following explanation:
Because certificate validation requires that root keys be distributedindependently, the self-signed certificate that specifies the rootcertificate authority MAY be omitted from the chain, under theassumption that the remote end must already possess it in order tovalidate it in any case.
X.509 key usages and extended key usages
cert-manager supports requesting certificates that have a number of custom keyusages and extended keyusages. Althoughcert-manager will attempt to honor this request, some issuers will remove, adddefaults, or otherwise completely ignore the request.The CA and SelfSigned Issuer will always return certificates matching the usages you have requested.
Unless any number of usages has been set, cert-manager will set the defaultrequested usages of digital signature, key encipherment, and server auth.cert-manager will not attempt to request a new certificate if the currentcertificate does not match the current key usage set.
An exhaustive list of supported key usages can be found in the API referencedocumentation.
Additional Certificate Output Formats
additionalOutputFormats is a field on the Certificate spec that allowsspecifying additional supplementary formats of issued certificates and theirprivate key. There are currently two supported additional output formats:CombinedPEM and DER. Both output formats can be specified on the sameCertificate.
apiVersion: cert-manager.io/v1
kind: Certificate
spec:
...
secretName: my-cert-tls
additionalOutputFormats:
- type: CombinedPEM
- type: DER
# Results in:
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
ca.crt: <PEM CA certificate>
tls.key: <PEM private key>
tls.crt: <PEM signed certificate chain>
tls-combined.pem: <PEM private key + "\n" + PEM signed certificate chain>
key.der: <DER binary format of private key>
CombinedPEM
The CombinedPEM type will create a new key entry in the resultingCertificate's Secret tls-combined.pem. This entry will contain the PEM encodedprivate key, followed by at least one new line character, followed by the PEMencoded signed certificate chain-
<private key> + "\n" + <signed certificate chain>
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
tls-combined.pem: <PEM private key + "\n" + PEM signed certificate chain>
...
DER
The DER type will create a new key entry in the resulting Certificate's Secretkey.der. This entry will contain the DER binary format of the private key.
apiVersion: v1
kind: Secret
metadata:
name: my-cert-tls
type: kubernetes.io/tls
data:
key.der: <DER binary format of private key>
...
Creating Certificate With Name Constraints
Root or Intermediate CA certificates can have name constraints. Name constraints indicates a name space within which all subject names in subsequent certificates in a certification path MUST be located.Checkout https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.10 for more details on this.
⛔️ This feature is only enabled by adding it to the--feature-gates flag on the cert-manager controller and webhook components:
--feature-gates=NameConstraints=true
To create a CA Certificate with name constraints use the following configuration:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: ca-cert-example
spec:
secretName: example-ca-key-pair
isCA: true
issuerRef:
name: selfsigned
kind: ClusterIssuer
commonName: "example1.com"
dnsNames:
- example1.com
nameConstraints:
critical: true
permitted:
dnsDomains: ["example1.com", "example2.com"]
ipRanges: ["10.10.0.0/16"]
emailAddress: ["[email protected]"]
excluded:
ipRanges: ["10.10.0.0/24"]
Note that when used with cert-manager's built-in CA and SelfSigned Issuer, the SANs (DNS name, IP address, URI, and email address) are not checked with the certificate's own name constraints, and are not checked with any of name constraints contained in the chain of certificates the certificate belongs to.
The certificate may get issued successfully, but be rejected by clients during TLS handshakes.
Issuance triggers
Reissuance triggered by expiry (renewal)
cert-manager will automatically renew Certificates. It will calculate when to renew a Certificate based on the issued X.509 certificate's duration and a 'renewBefore' value which specifies how long before expiry a certificate should be renewed.
spec.duration and spec.renewBefore fields on a Certificate can be used to specify an X.509 certificate's duration and a 'renewBefore' value. Default value for spec.duration is 90 days. Some issuers might be configured to only issue certificates with a set duration, so the actual duration may be different.Minimum value for spec.duration is 1 hour and minimum value for spec.renewBefore is 5 minutes.It is also required that spec.duration > spec.renewBefore.
Once an X.509 certificate has been issued, cert-manager will calculate the renewal time for the Certificate. By default this will be 2/3 through the X.509 certificate's duration. If spec.renewBefore has been set, it will be spec.renewBefore amount of time before expiry. cert-manager will set Certificate's status.RenewalTime to the time when the renewal will be attempted.
Reissuance triggered by user actions
A certificate object is reissued under the following circ*mstances:
- when a change is made to one of the following fields on the Certificate'sspec:
commonName,dnsNames,ipAddresses,uris,emailAddresses,subject,isCA,usages,durationorissuerRef;A more detailed explanation can be found on the FAQ page. - when a reissuance is manually triggered with the following:Note that the above command requires cmctl.
cmctl renew cert-1
❌ Deleting the Secret resource associated with a Certificate resource isnot a recommended solution for manually rotating the private key. Therecommended way to manually rotate the private key is to trigger the reissuanceof the Certificate resource with the following command (requirescmctl):
cmctl renew cert-1
Issuance behavior: Temporary Certificates while Issuing
When requesting certificates using the ingress-shim, thecomponent ingress-gce, if used, requires that a temporary certificate ispresent while waiting for the issuance of a signed certificate when serving. Tofacilitate this, if the following annotation:
cert-manager.io/issue-temporary-certificate: "true"
is present on the certificate, a self-signed temporary certificate will bepresent on the Secret until it is overwritten once the signed certificate hasbeen issued.
Adding the following annotation on an ingress will automatically set "issue-temporary-certificate" on the certificate:
acme.cert-manager.io/http01-edit-in-place: "true"
Issuance behavior: Rotation of the private key
By default, the private key won't be rotated automatically. Using the settingrotationPolicy: Always, the private key Secret associated with a Certificateobject can be configured to be rotated as soon as an the Certificate is reissued (seeIssuance triggers).
With rotationPolicy: Always, cert-manager waits until the Certificateobject is correctly signed before overwriting the tls.key file in theSecret.
With this setting, you can expect no downtime if your application can detectchanges to the mounted tls.crt and tls.key and reload them gracefully orautomatically restart.
If your application only loads the private key and signed certificate onceat start up, the new certificate won't immediately be served by yourapplication, and you will want to either manually restart your pod withkubectl rollout restart, or automate the action by runningwave. Wave is a Secret controller thatmakes sure deployments get restarted whenever a mounted Secret changes.
Re-use of private keys
Some issuers, like the built-in Venafiissuer, may disallow re-using private keys.If this is the case, you must explicitly configure the rotationPolicy: Always setting for each of your Certificate objects accordingly.
In the following example, the certificate has been set withrotationPolicy: Always:
apiVersion: cert-manager.io/v1
kind: Certificate
spec:
secretName: my-cert-tls
privateKey:
rotationPolicy: Always # 🔰 Here.
The rotationPolicy setting
The possible values for rotationPolicy are:
| Value | Description |
|---|---|
Never (default) | cert-manager reuses the existing private key on each issuance |
Always (recommended) | cert-manager regenerates a new private key on each issuance |
With rotationPolicy: Never, a private key is only generated if one does notalready exist in the target Secret resource (using the tls.key key). Allfurther issuances will re-use this private key. This is the default in order tomaintain compatibility with previous releases.
With rotationPolicy: Always, a new private key will be generated each time anaction triggers the reissuance of the certificate object (see Actions that willtrigger a rotation of the private keyabove). Note that if the private key secret already exists when creating thecertificate object, the existing private key will not be used, since therotation mechanism also includes the initial issuance.
👉 We recommend that you configure rotationPolicy: Always on your Certificateresources. Rotating both the certificate and the private key simultaneouslyprevents the risk of issuing a certificate with an exposed private key. Anotherbenefit to renewing the private key regularly is to let you be confident thatthe private key rotation can be done in case of emergency. More generally, it isa good practice to be rotating the keys as often as possible, reducing the riskassociated 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.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.
Inner workings diagram for developers
[1] https://cert-manager.io/docs/usage/certificaterequest
