Creating a simple CA based issuer¶
cert-manager can be used to obtain certificates using an arbitrary signing key pair stored in a Kubernetes Secret resource.
This guide will show you how to configure and create a CA based issuer, backed by a signing key pair stored in a Secret resource.
1. (Optional) Generate a signing key pair¶
The CA Issuer does not automatically create and manage a signing key pair for you. As a result, you will need to either supply your own or generate a self signed CA using a tool such as openssl or cfssl.
This guide will explain how to generate a new signing key pair, however you can
substitute it for your own so long as it has the CA
flag set.
# Generate a CA private key
$ openssl genrsa -out ca.key 2048
# Create a self signed Certificate, valid for 10yrs with the 'signing' option set
$ openssl req -x509 -new -nodes -key ca.key -subj "/CN=${COMMON_NAME}" -days 3650 -reqexts v3_req -extensions v3_ca -out ca.crt
The output of these commands will be two files, ca.key
and ca.crt
, the
key and certificate for your signing key pair. If you already have your own key
pair, you should name the private key and certificate ca.key
and ca.crt
respectively.
2. Save the signing key pair as a Secret¶
We are going to create an Issuer that will use this key pair to generate signed certificates. You can read more about the Issuer resource in the Issuer reference docs. To allow the Issuer to reference our key pair we will store it in a Kubernetes Secret resource.
Issuers are namespaced resources and so they can only reference Secrets in their own namespace. We will therefore put the key pair into the same namespace as the Issuer. We could alternatively create a ClusterIssuer, a cluster-scoped version of an Issuer. For more information on ClusterIssuers, read the ClusterIssuer reference documentation.
The following command will create a Secret containing a signing key pair in the default namespace:
kubectl create secret tls ca-key-pair \
--cert=ca.crt \
--key=ca.key \
--namespace=default
3. Creating an Issuer referencing the Secret¶
We can now create an Issuer referencing the Secret resource we just created:
1 2 3 4 5 6 7 8 | apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
name: ca-issuer
namespace: default
spec:
ca:
secretName: ca-key-pair
|
We are now ready to obtain certificates!
4. Obtain a signed Certificate¶
We can now create the following Certificate resource which specifies the desired certificate. You can read more about the Certificate resource in the reference docs.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
name: example-com
namespace: default
spec:
secretName: example-com-tls
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
commonName: example.com
dnsNames:
- example.com
- www.example.com
|
In order to use the Issuer to obtain a Certificate, we must create a Certificate resource in the same namespace as the Issuer, as an Issuer is a namespaced resource. We could alternatively create a ClusterIssuer if we wanted to reuse the signing key pair across multiple namespaces.
Once we have created the Certificate resource, cert-manager will attempt to use
the Issuer ca-issuer
to obtain a certificate. If successful, the
certificate will be stored in a Secret resource named example-com-tls
in
the same namespace as the Certificate resource (default
).
Note that since we have specified the commonName
field, example.com
will be the common name for our certificate and both the common name and all
the elements of the dnsNames
array will be Subject Alternative Names
(SANs).
If we had not specified the common name then the first element of the
dnsNames
list would be used as the common name and all elements of the
dnsNames
list would also be SANs.
After creating the above Certificate, we can check whether it has been obtained successfully like so:
$ kubectl describe certificate example-com
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ErrorCheckCertificate 26s cert-manager-controller Error checking existing TLS certificate: secret "example-com-tls" not found
Normal PrepareCertificate 26s cert-manager-controller Preparing certificate with issuer
Normal IssueCertificate 26s cert-manager-controller Issuing certificate...
Normal CertificateIssued 25s cert-manager-controller Certificate issued successfully
You can also check whether issuance was successful with
kubectl get secret example-com-tls -o yaml
. You should see a base64 encoded
signed TLS key pair.
Once the certificate has been obtained, cert-manager will keep checking its validity and attempt to renew it if it gets close to expiry. cert-manager considers certificates to be close to expiry when the ‘Not After’ field on the certificate is less than the current time plus 30 days. For CA based Issuers, cert-manager will issue certificates with the ‘Not After’ field set to the current time plus 365 days.