Kubernetes

cert-manager runs within your Kubernetes cluster as a series of deployment resources. It utilizes CustomResourceDefinitions to configure Certificate Authorities and request certificates.

It is deployed using regular YAML manifests, like any other application on Kubernetes.

Once cert-manager has been deployed, you must configure Issuer or ClusterIssuer resources which represent certificate authorities. More information on configuring different Issuer types can be found in the respective configuration guides.

Note: From cert-manager v0.14.0 onward, the minimum supported version of Kubernetes is v1.11.0. Users still running Kubernetes v1.10 or below should upgrade to a supported version before installing cert-manager.

Warning: You should not install multiple instances of cert-manager on a single cluster. This will lead to undefined behavior and you may be banned from providers such as Let’s Encrypt.

Installing with regular manifests

All resources (the CustomResourceDefinitions, cert-manager, namespace, and the webhook component) are included in a single YAML manifest file:

Install the CustomResourceDefinitions and cert-manager itself

# Kubernetes 1.15+
$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.3/cert-manager.yaml

# Kubernetes <1.15
$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.3/cert-manager-legacy.yaml

Note: If you’re using a Kubernetes version below v1.15 you will need to install the legacy version of the manifests. This version does not have API version conversion and only supports cert-manager.io/v1alpha2 API resources.

Note: If you are running Kubernetes v1.15.4 or below, you will need to add the --validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

Note: When running on GKE (Google Kubernetes Engine), you may encounter a ‘permission denied’ error when creating some of these resources. This is a nuance of the way GKE handles RBAC and IAM permissions, and as such you should ‘elevate’ your own privileges to that of a ‘cluster-admin’ before running the above command. If you have already run the above command, you should run them again after elevating your permissions:

Note: By default, cert-manager will be installed into the cert-manager namespace. It is possible to run cert-manager in a different namespace, although you will need to make modifications to the deployment manifests.

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole=cluster-admin \
  --user=$(gcloud config get-value core/account)

Once you have deployed cert-manager, you can verify the installation here.

Installing with Helm

As an alternative to the YAML manifests referenced above, we also provide an official Helm chart for installing cert-manager.

Prerequisites

Helm v2 or v3 installed

Note: Helm v2

Before deploying cert-manager with Helm v2, you must ensure Tiller is up and running in your cluster. Tiller is the server side component to Helm.

Your cluster administrator may have already setup and configured Helm for you, in which case you can skip this step.

Full documentation on installing Helm can be found in the installing helm docs.

If your cluster has RBAC (Role Based Access Control) enabled (default in GKE v1.7+), you will need to take special care when deploying Tiller, to ensure Tiller has permission to create resources as a cluster administrator. More information on deploying Helm with RBAC can be found in the Helm RBAC docs.

Steps

In order to install the Helm chart, you must follow these steps.

Install the CustomResourceDefinition resources separately.

# Kubernetes 1.15+
$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.3/cert-manager.crds.yaml

# Kubernetes <1.15
$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.3/cert-manager-legacy.crds.yaml

Note: If you’re using a Kubernetes version below v1.15 you will need to install the legacy version of the CRDs. This version does not have API version conversion and only supports cert-manager.io/v1alpha2 API resources.

Create the namespace for cert-manager.

$ kubectl create namespace cert-manager

Add the Jetstack Helm repository.

Warning: It is important that this repository is used to install cert-manager. The version residing in the helm stable repository is deprecated and should not be used.

$ helm repo add jetstack https://charts.jetstack.io

Update your local Helm chart repository cache.

$ helm repo update

Install the cert-manager Helm chart.

# Helm v3+
$ helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v0.14.3

# Helm v2
$ helm install \
  --name cert-manager \
  --namespace cert-manager \
  --version v0.14.3 \
  jetstack/cert-manager

The default cert-manager configuration is good for the majority of users, but a full list of the available options can be found in the Helm chart README.

Verifying the installation

Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:

$ kubectl get pods --namespace cert-manager

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

You should see the cert-manager, cert-manager-cainjector, and cert-manager-webhook pod in a Running state. It may take a minute or so for the TLS assets required for the webhook to function to be provisioned. This may cause the webhook to take a while longer to start for the first time than other pods. If you experience problems, please check the FAQ guide.

The following steps will confirm that cert-manager is set up correctly and able to issue basic certificate types.

Create an Issuer to test the webhook works okay.

$ cat <<EOF > test-resources.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: cert-manager-test
---
apiVersion: cert-manager.io/v1alpha2
kind: Issuer
metadata:
  name: test-selfsigned
  namespace: cert-manager-test
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
  name: selfsigned-cert
  namespace: cert-manager-test
spec:
  dnsNames:
    - example.com
  secretName: selfsigned-cert-tls
  issuerRef:
    name: test-selfsigned
EOF

Create the test resources.

$ kubectl apply -f test-resources.yaml

Check the status of the newly created certificate. You may need to wait a few seconds before cert-manager processes the certificate request.

$ kubectl describe certificate -n cert-manager-test

...
Spec:
  Common Name:  example.com
  Issuer Ref:
    Name:       test-selfsigned
  Secret Name:  selfsigned-cert-tls
Status:
  Conditions:
    Last Transition Time:  2019-01-29T17:34:30Z
    Message:               Certificate is up to date and has not expired
    Reason:                Ready
    Status:                True
    Type:                  Ready
  Not After:               2019-04-29T17:34:29Z
Events:
  Type    Reason      Age   From          Message
  ----    ------      ----  ----          -------
  Normal  CertIssued  4s    cert-manager  Certificate issued successfully

Clean up the test resources.

$ kubectl delete -f test-resources.yaml

If all the above steps have completed without error, you are good to go!

If you experience problems, please check the FAQ.

Configuring your first Issuer

Before you can begin issuing certificates, you must configure at least one Issuer or ClusterIssuer resource in your cluster.

You should read the configuration guide to learn how to configure cert-manager to issue certificates from one of the supported backends.

Alternative installation methods

kubeprod

Bitnami Kubernetes Production Runtime (BKPR, kubeprod) is a curated collection of the services you would need to deploy on top of your Kubernetes cluster to enable logging, monitoring, certificate management, automatic discovery of Kubernetes resources via public DNS servers and other common infrastructure needs.

It depends on cert-manager for certificate management, and it is regularly tested so the components are known to work together for GKE and AKS clusters (EKS to be added soon). For its ingress stack it creates a DNS entry in the configured DNS zone and requests a TLS certificate from the Let’s Encrypt staging server.

BKPR can be deployed using the kubeprod install command, which will deploy cert-manager as part of it. Details available in the BKPR installation guide.

Debugging installation issues

If you have any issues with your installation, please refer to the FAQ.

Last modified January 1, 0001