Certificate Resources
In cert-manager, the Certificate
resource
represents a human readable definition of a certificate request that is to be
honored by an issuer which is to be kept up-to-date. This is the usual way that
you will interact with cert-manager to request signed certificates.
In order to issue any certificates, you'll need to configure an
Issuer
resource first.
Creating Certificate Resources
A Certificate
resource specifies fields that are used to generate certificate
signing requests which are then fulfilled by the issuer type you have
referenced. Certificates
specify which issuer they want to obtain the
certificate 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 contains
an exhaustive list of all options a Certificate
resource may have however only
a subset of fields are required as labelled.
apiVersion: cert-manager.io/v1kind: Certificatemetadata:name: example-comnamespace: sandboxspec:# Secret names are always required.secretName: example-com-tlsduration: 2160h # 90drenewBefore: 360h # 15dsubject:organizations:- jetstack# The use of the common name field has been deprecated since 2000 and is# discouraged from being used.commonName: example.comisCA: falseprivateKey:algorithm: RSAencoding: PKCS1size: 2048usages:- server auth- client auth# At least one of a DNS Name, URI, or IP address is required.dnsNames:- example.com- www.example.comuris:- spiffe://cluster.local/ns/sandbox/sa/exampleipAddresses:- 192.168.0.5# 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 named
example-com-tls
in the same namespace as the Certificate
once the issuer has
successfully issued the requested certificate.
The Certificate
will be issued using the issuer named ca-issuer
in the
sandbox
namespace (the same namespace as the Certificate
resource).
Note: If you want to create an
Issuer
that can be referenced byCertificate
resources in all namespaces, you should create aClusterIssuer
resource and set thecertificate.spec.issuerRef.kind
field toClusterIssuer
.
Note: The
renewBefore
andduration
fields must be specified using a Gotime.Duration
string format, which does not allow thed
(days) suffix. You must specify these values usings
,m
, andh
suffixes instead. Failing to do so without installing thewebhook component
can prevent cert-manager from functioning correctly#1269
.
Note: Take care when setting the
renewBefore
field to be very close to theduration
as this can lead to a renewal loop, where theCertificate
is always in the renewal period. SomeIssuers
set thenotBefore
field on their issued 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 full duration of the certificate. For example, Let's Encrypt sets it to be one hour before issue time, so the actual working duration of the certificate is 89 days, 23 hours (the full duration remains 90 days).
A full list of the fields supported on the Certificate resource can be found in the API reference documentation.
X.509 key usages and extended key usages
cert-manager supports requesting certificates that have a number of custom key
usages and extended key
usages. Although
cert-manager will attempt to honor this request, some issuers will remove, add
defaults, 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 default
requested usages of digital signature
, key encipherment
, and server auth
.
cert-manager will not attempt to request a new certificate if the current
certificate does not match the current key usage set.
An exhaustive list of supported key usages can be found in the API reference documentation.
Temporary Certificates while Issuing
On old GKE versions (1.10.7-gke.1
and below), when requesting certificates
using the ingress-shim alongside the
ingress-gce
ingress controller, ingress-gce
required a temporary
certificate must be present while waiting for the issuance of a signed
certificate. Note that this issue was
solved
in 1.10.7-gke.2
.
# Required for GKE 1.10.7-gke.1 and below.cert-manager.io/issue-temporary-certificate": "true"
That made sure that a temporary self-signed certificate was present in the
Secret
. The self-signed certificate was replaced with the signed certificate
later on.
Rotation of the private key
By default, the private key won't be rotated automatically. Using the setting
rotationPolicy: Always
, the private key Secret associated with a Certificate
object can be configured to be rotated as soon as an action triggers the
reissuance of the Certificate object (see
Actions that will trigger a rotation of the private key below).
With rotationPolicy: Always
, cert-manager waits until the Certificate
object is correctly signed before overwriting the tls.key
file in the
Secret.
With this setting, you can expect no downtime if your application can detect
changes to the mounted tls.crt
and tls.key
and reload them gracefully or
automatically restart.
If your application only loads the private key and signed certificate once
at start up, the new certificate won't immediately be served by your
application, and you will want to either manually restart your pod with
kubectl rollout restart
, or automate the action by running
wave. Wave is a Secret controller that
makes sure deployments get restarted whenever a mounted Secret changes.
Re-use of private keys
Some issuers, like the built-in Venafi
issuer, 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 with
rotationPolicy: Always
:
apiVersion: cert-manager.io/v1kind: Certificatespec:secretName: my-cert-tlsprivateKey:rotationPolicy: Always # 🔰 Here.
Actions that will trigger a rotation of the private key
Setting the rotationPolicy: Always
won't rotate the private key immediately.
In order to rotate the private key, the certificate objects must be reissued. A
certificate object is reissued under the following circumstances:
- when the X.509 certificate is nearing expiry, which is when the Certificate's
status.renewalTime
is reached; - when a change is made to one of the following fields on the Certificate's
spec:
commonName
,dnsNames
,ipAddresses
,uris
,emailAddresses
,subject
,isCA
,usages
,duration
orissuerRef
; - when a reissuance is manually triggered with the following:
Note that the above command requires the kubectl cert-manager plugin.kubectl cert-manager renew cert-1
❌ Deleting the Secret resource associated with a Certificate resource is
not a recommended solution for manually rotating the private key. The
recommended way to manually rotate the private key is to trigger the reissuance
of the Certificate resource with the following command (requires the kubectl cert-manager
plugin):
kubectl cert-manager renew cert-1
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 not
already exist in the target Secret resource (using the tls.key
key). All
further issuances will re-use this private key. This is the default in order to
maintain compatibility with previous releases.
With rotationPolicy: Always
, a new private key will be generated each time an
action triggers the reissuance of the certificate object (see Actions that will
trigger a rotation of the private key
above). Note that if the private key secret already exists when creating the
certificate object, the existing private key will not be used, since the
rotation mechanism also includes the initial issuance.
👉 We recommend that you configure rotationPolicy: Always
on your Certificate
resources. Rotating both the certificate and the private key simultaneously
prevents the risk of issuing a certificate with an exposed private key. Another
benefit to renewing the private key regularly is to let you be confident that
the private key rotation can be done in case of emergency. More generally, it is
a good practice to be rotating the keys as often as possible, reducing the risk
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.
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.
Renewal
cert-manager will automatically renew Certificate
s. 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.