NEW: Get project updates onTwitterandMastodon

SelfSigned

⚠️ SelfSigned issuers are generally useful for bootstrapping a PKI locally, which is a complex topic for advanced users. To be used safely in production, running a PKI introduces complex planning requirements around rotation, trust store distribution and disaster recovery.

If you're not planning to run your own PKI, use a different issuer type.

The SelfSigned issuer doesn't represent a certificate authority as such, but instead denotes that certificates will "sign themselves" using a given private key. In other words, the private key of the certificate will be used to sign the certificate itself.

This Issuer type is useful for bootstrapping a root certificate for a custom PKI (Public Key Infrastructure), or for otherwise creating simple ad-hoc certificates for a quick test.

There are important caveats - including security issues - to consider with SelfSigned issuers; in general you'd likely want to use a CA issuer rather than a SelfSigned issuer. That said, SelfSigned issuers are really useful for initially bootstrapping a CA issuer.

Note: a CertificateRequest that references a self-signed certificate must also contain the cert-manager.io/private-key-secret-name annotation since the private key corresponding to the CertificateRequest is required to sign the certificate. This annotation is added automatically by the Certificate controller.

Deployment

Since the SelfSigned issuer has no dependency on any other resource, it is the simplest to configure. Only the SelfSigned stanza is required to be present in the issuer spec, with no other configuration required:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
 name: selfsigned-issuer
 namespace: sandbox
spec:
 selfSigned: {}
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: selfsigned-cluster-issuer
spec:
 selfSigned: {}

Once deployed, you should be able to see immediately that the issuer is ready for signing:

$ kubectl get issuers -n sandbox -o wide selfsigned-issuer
NAME READY STATUS AGE
selfsigned-issuer True 2m
 
$ kubectl get clusterissuers -o wide selfsigned-cluster-issuer
NAME READY STATUS AGE
selfsigned-cluster-issuer True 3m

Bootstrapping CA Issuers

One of the ideal use cases for SelfSigned issuers is to bootstrap a custom root certificate for a private PKI, including with the cert-manager CA issuer.

The YAML below will create a SelfSigned issuer, issue a root certificate and use that root as a CA issuer:

apiVersion: v1
kind: Namespace
metadata:
 name: sandbox
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: selfsigned-issuer
spec:
 selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: my-selfsigned-ca
 namespace: sandbox
spec:
 isCA: true
 commonName: my-selfsigned-ca
 secretName: root-secret
 privateKey:
 algorithm: ECDSA
 size: 256
 issuerRef:
 name: selfsigned-issuer
 kind: ClusterIssuer
 group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
 name: my-ca-issuer
 namespace: sandbox
spec:
 ca:
 secretName: root-secret

Alternatively, if you are looking to use ClusterIssuer for signing Certificates anywhere in your cluster with the SelfSigned Certificate CA, use the YAML below (slight modification):

# `sandbox` namespace is no longer needed.
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: selfsigned-issuer
spec:
 selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: my-selfsigned-ca
 # Create CA root secret in `cert-manager` namespace instead of `sandbox` namespace.
 namespace: cert-manager
spec:
 isCA: true
 commonName: my-selfsigned-ca
 secretName: root-secret
 privateKey:
 algorithm: ECDSA
 size: 256
 issuerRef:
 name: selfsigned-issuer
 kind: ClusterIssuer
 group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: my-ca-issuer
spec:
 ca:
 # `ClusterIssuer` resource is not namespaced, so `secretName` is assumed to reference secret in `cert-manager` namespace.
 secretName: root-secret

The "selfsigned-issuer" ClusterIssuer is used to issue the Root CA Certificate. Then, "my-ca-issuer" ClusterIssuer is used to issue but also sign certificates using the newly created Root CA Certificate, which is what you will use for future certificates cluster-wide.

CRL Distribution Points

You may also optionally specify CRL Distribution Points as an array of strings, each of which identifies the location of a CRL in which the revocation status of issued certificates can be checked:

...
spec:
 selfSigned:
 crlDistributionPoints:
 - "http://example.com"

Caveats

Trust

Clients consuming SelfSigned certificates have no way to trust them without already having the certificates beforehand, which can be hard to manage when the client is in a different namespace to the server.

This limitation can be tackled by using trust-manager to distribute ca.crt to other namespaces.

There is no secure alternative to solving the problem of distributing trust stores; it's possible to "TOFU" (trust-on-first-use) a certificate, but that approach is vulnerable to man-in-the-middle attacks.

Certificate Validity

One side-effect of a certificate being self-signed is that its Subject DN and its Issuer DN are identical. The X.509 RFC 5280, section 4.1.2.4 requires that:

The issuer field MUST contain a non-empty distinguished name (DN).

However, self-signed certs don't have a subject DN set by default. Unless you manually set a certificate's Subject DN, the Issuer DN will be empty and the certificate will technically be invalid.

Validation of this specific area of the spec is patchy and varies between TLS libraries, but there's always the risk that a library will improve its validation - entirely within spec - in the future and break your app if you're using a certificate with an empty Issuer DN.

To avoid this, be sure to set a Subject for SelfSigned certs. This can be done by setting the spec.subject on a cert-manager Certificate object which will be issued by a SelfSigned issuer.

Starting in version 1.3, cert-manager will emit a Kubernetes warning event of type BadConfig if it detects that a certificate is being created by a SelfSigned issuer which has an empty Issuer DN.