Updated by Linode Contributed by Linode
What is cert manager
Cert-manager is a Kubernetes add-on designed to assist with the creation and management of TLS certificates. Similar to Certbot, cert-manager can automate the process of creating and renewing self-signed and signed certificates for a large number of use cases, with a specific focus on container orchestration tools like Kubernetes.
In This Guide
In this guide, you will learn about how cert-manager works to create certificates, the options available for creating certificates, and then use cert-manager to create two public signed certificates using only Kubernetes and cert-manager tooling.
Before you Begin
- Follow our guide to Deploying an Ingress. The final example of this guide uses the same configuration, cluster, and domains.
- You should have a working knowledge of Kubernetes’ key concepts, including master and worker nodes, Pods, Deployments, and Services. For more information on Kubernetes, see our Beginner’s Guide to Kubernetes series.
Understanding Cert Manager Concepts
Cert-Manager is divided into a number of components and microservices that are each designed to perform specific tasks necessary for the certificate lifecycle.
Issuers and ClusterIssuers
Certificate creation begins with
ClusterIssuers, resources that represent certificate authorities and are able to generate signed certificates using a specific issuer
type. An issuer
type represents the method used to create your certificate, such as
SelfSigned for a Self-Signed Certificate and
ACME for requests for certificates from ACME servers, typically used by tools like Let’s Encrypt. All supported issuer types are listed in Cert-Manager’s Documentation.
Issuers resources are only able to create certificates in the namespace they were created in,
ClusterIssuers can create certificates for all namespaces. This guide provides an example that demonstrates how
ClusterIssuers creates certificates for all namespaces in the cluster.
Certificates and CertificateRequests
Although Issuers are responsible for defining the method used to create a certificate, a
Certificate resource must also be created to define how a certificate is renewed and kept up to date.
Certificate resource is created, changed, or a certificate referenced needs renewal, cert-manager creates a corresponding
CertificateRequest resource, which contains the base64 encoded string of an
x509 certificate request (CSR). Additionally, if successful, it contains the signed certificate where one is successfully returned and updates the
Ready condition status to
CertificateRequestresource is not designed to interact with a user directly, and instead is utilized through controllers or similar methods where needed.
ACME Orders and Challenges
For external certificates from ACME servers, cert-manager must be able to solve ACME challenges in order to prove ownership of DNS names and addresses being requested.
Order resource represents and encapsulates the multiple ACME challenges the certificate request requires for domain validation. The
Order resource is created automatically when a
CertificateRequest referencing an ACME
Issuer or has been created.
Challenge resources represent all of the steps in an ACME challenge that must be completed for domain validation. Although defined by the
Order, a separate
Challenge resource is created for each DNS name that is being validated, and each are scheduled separately.
Challenge resources are only created for
ClusterIssuers with a
challengeresource is never manually created directly by a user and are instead defined through
CertificateRequestresources and the
Issuerstype. After it is issued,
challengeresources cannot be changed.
This feature includes the ability to request certificates through Let’s Encrypt.
Cert-Manager can be easily installed through a single command as follows:
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.15.0/cert-manager.yaml
As the installation completes, you should see a number of required resources created, including a
cert-manager namespace, RBAC rules, CRD’s, and a webhook component. To confirm that the installation was a success, enter the following:
kubectl get pods --namespace cert-manager
The output is similar to the following:
NAME READY STATUS RESTARTS AGE cert-manager-766d5c494b-l9sdb 1/1 Running 0 19m cert-manager-cainjector-6649bbb695-bz999 1/1 Running 0 19m cert-manager-webhook-68d464c8b-86tqw 1/1 Running 0 19m
Using Cert-Manager to Create Certificates
The following example creates an ACME certificate signed using Let’s Encrypt.
To begin, define a ClusterIssuer resource manually, replacing
[email protected] with your own personal email address which is used for ACME registration:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
apiVersion: cert-manager.io/v1alpha2 kind: ClusterIssuer metadata: name: letsencrypt-certmanager spec: acme: # Replace this e-mail with your own to be used for ACME registration email: [email protected] server: https://acme-v02.api.letsencrypt.org/directory privateKeySecretRef: name: letsencrypt-private-key # Add a single challenge solver, HTTP01 using nginx solvers: - http01: ingress: class: nginx
In the above example, note that
privateKeySecretRef attribute creates a secret resource using the specified name for storing the private key of the account.
Then enter the following to create the resource:
kubectl create -f my-new-issuer.yaml
You should see a confirmation message that the resource was successfully created.
Finally, edit your Ingress to include the annotation for the cert-manager resource, add the
tls block to define the domains that need certificates, and the name of the
privateKeySecretRef in the
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
metadata: name: my-new-ingress annotations: kubernetes.io/ingress.class: nginx cert-manager.io/cluster-issuer: letsencrypt-certmanager spec: tls: - hosts: - shop.example.com - blog.example.com secretName: letsencrypt-private-key rules: - host: shop.example.com http: paths: - backend: serviceName: hello-one servicePort: 80 - host: blog.example.com http: paths: - backend: serviceName: hello-two servicePort: 80
After you have completed the configuration, apply it with the following:
kubectl apply -f my-new-ingress.yaml
http01stanza specifies that the ACME challenge is performed through the HTTP-01 challenge type. For more information on how this works, see Let’s Encrypt’s documentation
Now that the resource has been applied, you may now navigate to your subdomains
https://shop.example.com to see them resolve using SSL/TLS encryption.
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This guide is published under a CC BY-ND 4.0 license.