cert-manager has the concept of
Certificates that define a desired X.509
certificate which will be renewed and kept up to date. A
Certificate is a
namespaced resource that references an
determine what will be honoring the certificate request.
Certificate is created, a corresponding
is created by cert-manager containing the encoded X.509 certificate request,
Issuer reference, and other options based upon the specification of the
Here is one such example of a
apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: acme-crt spec: secretName: acme-crt-secret dnsNames: - example.com - foo.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 group: cert-manager.io
Certificate will tell cert-manager to attempt to use the
letsencrypt-prod to obtain a certificate key pair for the
foo.example.com domains. If successful, the resulting TLS key and certificate
will be stored in a secret named
acme-crt-secret, with keys of
tls.crt respectively. This secret will live in the same namespace as the
When a certificate is issued by an intermediate CA and the
Issuer can provide
the issued certificate’s chain, the contents of
tls.crt will be the requested
certificate followed by the certificate chain.
Additionally, if the Certificate Authority is known, the corresponding CA
certificate will be stored in the secret with key
ca.crt. For example, with
the ACME issuer, the CA is not known and
ca.crt will not exist in
cert-manager intentionally avoids adding root certificates to
tls.crt, because they
are useless in a situation where TLS is being done securely. For more information,
see RFC 5246 section 7.4.2
which contains the following explanation:
Because certificate validation requires that root keys be distributed independently, the self-signed certificate that specifies the root certificate authority MAY be omitted from the chain, under the assumption that the remote end must already possess it in order to validate it in any case.
Use ca.crt with caution
When configuring a client to connect to a TLS server with a serving certificate that is signed by a private CA,
you will need to provide the client with the CA certificate in order for it to verify the server.
ca.crt will likely contain the certificate you need to trust,
but do not mount the same
Secret as the server to access
This is because:
Secretalso contains the private key of the server, which should only be accessible to the server. You should use RBAC to ensure that the
Secretcontaining the serving certificate and private key are only accessible to Pods that need it.
- Rotating CA certificates safely relies on being able to have both the old and new CA certificates trusted at the same time. By consuming the CA directly from the source, this isn’t possible; you’ll be forced to have some down-time in order to rotate certificates.
When configuring the client you should independently choose and fetch the CA certificates that you want to trust.
Download the CA out of band and store it in a
ConfigMap separate from the
Secret containing the server’s private key and certificate.
This ensures that if the material in the
Secret containing the server key and certificate is tampered with,
the client will fail to connect to the compromised server.
The same concept also applies when configuring a server for mutually-authenticated TLS; don’t give the server access to Secret containing the client certificate and private key.
dnsNames field specifies a list of
Subject Alternative Names to be associated
with the certificate.
Issuer must exist in the same namespace as the
Certificate can alternatively reference a
ClusterIssuer which is
non-namespaced and so can be referenced from any namespace.
You can read more on how to configure your
This diagram shows the lifecycle of a Certificate named
cert-1 using an
ACME / Let’s Encrypt issuer. You don’t need to understand all of these steps
to use cert-manager; this is more of an explanation of the logic which happens
under the hood for those curious about the process.