================================= 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. .. code-block:: shell # 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 :doc:`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 :doc:`ClusterIssuer `, a cluster-scoped version of an Issuer. For more information on ClusterIssuers, read the :doc:`ClusterIssuer reference documentation `. The following command will create a Secret containing a signing key pair in the default namespace: .. code-block:: shell 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: .. code-block:: yaml :linenos: :emphasize-lines: 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 :doc:`the reference docs `. .. code-block:: yaml :linenos: :emphasize-lines: 9, 10, 11, 12 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 organization: - Example CA 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 :doc:`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: .. code-block:: shell $ 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. .. _openssl: https://github.com/openssl/openssl .. _cfssl: https://github.com/cloudflare/cfssl .. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name