Cert-Manager is a very popular open source
certificate management tool, specifically designed to work with
Kubernetes. It can handle all the required operations for obtaining, renewing and using
SSL/TLS certificates. Cert-Manager is able to talk with various certificate authorities (or CAs), like: Let’s Encrypt, HashiCorp Vault, and Venafi, and issue valid certificates for you automatically. On top of that, it can also take care of automatic certificate renewal before expiration.
Why do you need
SSL/TLS certificates ?
First, and the most important aspect is verifying the
identity of a host or site. You need to make sure that the person or company holding a website is to be trusted. This is a very important aspect, because you do not want to give your personal data (or even credit card details) to anyone.
Second important aspect deals with
sensitive data which must be
encrypted. The communication channel should never use a simple
HTTP scheme, which is basically a
plain-text protocol under the hood. In other words, data must travel encrypted between the two parties (meaning you, and the website).
Where does all this fit?
Cert-Manager goes hand in hand with your
Ingress Controller resource. An
Ingress Controller is the main entrypoint of your
Kubernetes cluster, and sits in front of your
backend services. So, by securing your ingress resources (e.g.
Nginx), sensitive data never goes in or out un-encrypted. On top of that, you provide identity information to users, by presenting them a valid SSL/TLS certificate whenever they visit your website(s). Self-signed certificates are not to be trusted, and should never be used in production systems.
Please make sure to visit the Cert-Manager official documentation page to study more.
DigitalOcean is using
Helm v3 to deploy
Cert-Manager to your
Click the Deploy to DigitalOcean button to install a Kubernetes 1-Click Application. If you aren’t logged in, this link will prompt you to log in with your DigitalOcean account.
In addition to creating Cert-Manager using the control panel, you can also use the DigitalOcean API. As an example, to create a 3 node DigitalOcean Kubernetes cluster made up of Basic Droplets in the SFO2 region, you can use the following
doctl command. You need to authenticate with
doctl with your API access token) and replace the
$CLUSTER_NAME variable with the chosen name for your cluster in the command below.
doctl kubernetes clusters create --size s-4vcpu-8gb $CLUSTER_NAME --1-clicks cert-manager
First, check if the Helm installation was successful, by running below command:
helm ls -n cert-manager
The output looks similar to (the
STATUS column value should be
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION cert-manager cert-manager 1 2022-02-21 18:49:08.264191 +0200 EET deployed cert-manager-v1.8.0 v1.8.0
Next, verify if the Cert-Manager Pods are up and running:
kubectl get pods -n cert-manager
The output looks similar to (all Pods should be in a
READY state, and
STATUS should be
NAME READY STATUS RESTARTS AGE cert-manager-57d89b9548-94r5z 1/1 Running 0 3m24s cert-manager-cainjector-5bcf77b697-hkv2k 1/1 Running 0 3m24s cert-manager-webhook-9cb88bd6d-mxhgh 1/1 Running 0 3m24s
cert-manager stack provides some custom values to start with. Please have a look at the values file from the main GitHub repository (explanations are provided inside, where necessary).
You can always inspect all the available options, as well as the default values for the
cert-manager Helm chart by running below command:
helm show values jetstack/cert-manager --version 1.8.0
After tweaking the Helm values file (
values.yml) according to your needs, you can always apply the changes via
helm upgrade command, as shown below:
helm upgrade cert-manager jetstack/cert-manager --version 1.8.0 \ --namespace cert-manager \ --values values.yml
Cert-Manager expects some typical CRDs to be created in order to operate. You start by creating a certificate Issuer CRD. Next, the
Issuer CRD will try to fetch a valid TLS certificate for your Ingress Controller (e.g. Nginx) from a known authority, such as Let’s Encrypt. To accomplish this task, the
Issuer is using the
HTTP-01 challenge (it also knows how to perform
DNS-01 challenges as well, for wildcard certificates).
Next, a Certificate CRD is needed to store the actual certificate. The
Certificate CRD doesn’t work alone, and needs a reference to an
Issuer CRD to be able to fetch the real certificate from the
CA (Certificate Authority).
Issuer manifest looks like below (explanations for each relevant field is provided inline):
apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: letsencrypt-nginx namespace: backend spec: # ACME issuer configuration # `email` - the email address to be associated with the ACME account (make sure it's a valid one) # `server` - the URL used to access the ACME server’s directory endpoint # `privateKeySecretRef` - Kubernetes Secret to store the automatically generated ACME account private key acme: email: <YOUR_VALID_EMAIL_ADDRESS_HERE> server: https://acme-v02.api.letsencrypt.org/directory privateKeySecretRef: name: letsencrypt-nginx-private-key solvers: # Use the HTTP-01 challenge provider - http01: ingress: class: nginx
Next, you need to configure each Nginx ingress resource to use TLS termination. Typical manifest looks like below:
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: ingress-echo namespace: backend annotations: cert-manager.io/issuer: letsencrypt-nginx spec: tls: - hosts: - echo.my-domain.org secretName: letsencrypt-nginx rules: - host: echo.my-domain.org ...
Explanation for the above configuration:
cert-manager.io/issuer: Annotation that takes advantage of cert-manager ingress-shim to create the certificate resource on your behalf.
spec.tls.hosts: List of hosts included in the TLS certificate.
spec.tls.secretName: Name of the secret used to terminate TLS traffic on port 443.
Notice that the
Nginx Ingress Controller is able to generate the
Certificate CRD automatically via a special annotation:
cert-manager.io/issuer. This saves work and time, because you don’t have to create and maintain a separate manifest for certificates as well (only the
Issuer manifest is required). For other ingresses you may need to provide the
Certificate CRD as well.
You can check what versions are available to upgrade, by navigating to the cert-manager official releases page from GitHub. Alternatively, you can also use ArtifactHUB, which provides a more rich and user friendly interface.
Then, to upgrade the stack to a newer version, please run the following command (make sure to replace the
&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt; placeholders first):
helm upgrade cert-manager jetstack/cert-manager \ --version <CERT_MANAGER_NEW_VERSION> \ --namespace cert-manager \ --values <YOUR_HELM_VALUES_FILE>
See helm upgrade for command documentation.
Also, please make sure to check the official recommendations for various upgrade paths, from an existing release to a new major version of cert-manager.
To delete your installation of
cert-manager, please run the following
helm uninstall cert-manager -n cert-manager
Above command will delete all the associated
Kubernetes resources installed by the
cert-manager Helm chart, except the namespace itself. To delete the
cert-manager namespace as well, please run below command:
kubectl delete ns cert-manager
You can visit the Starter Kit set of guides provided by DigitalOcean for further study. Specifically for
Cert-Manager, you can access the following content:
To further enrich your experience, you can also browse the list of available tutorials from the official
Cert-Manager documentation site.