Automatically creating Certificates for Ingress resources

cert-manager can be configured to automatically provision TLS certificates for Ingress resources via annotations on your Ingresses.

A small sub-component of cert-manager, ingress-shim, is responsible for this.

How it works

ingress-shim watches Ingress resources across your cluster. If it observes an Ingress with any of the annotations described in the ‘Usage’ section, it will ensure a Certificate resource with the same name as the Ingress, and configured as described on the Ingress exists. For example:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    # add an annotation indicating the issuer to use.
    cert-manager.io/cluster-issuer: nameOfClusterIssuer
  name: myIngress
  namespace: myIngress
spec:
  rules:
  - host: myingress.com
    http:
      paths:
      - backend:
          serviceName: myservice
          servicePort: 80
        path: /
  tls: # < placing a host in the TLS config will indicate a cert should be created
  - hosts:
    - myingress.com
    secretName: myingress-cert # < cert-manager will store the created certificate in this secret.

Configuration

Since cert-manager v0.2.2, ingress-shim is deployed automatically as part of a Helm chart installation.

If you would also like to use the old kube-lego kubernetes.io/tls-acme: "true" annotation for fully automated TLS, you will need to configure a default Issuer when deploying cert-manager. This can be done by adding the following --set when deploying using Helm:

--set ingressShim.defaultIssuerName=letsencrypt-prod \
--set ingressShim.defaultIssuerKind=ClusterIssuer

In the above example, cert-manager will create Certificate resources that reference the ClusterIssuer letsencrypt-prod for all Ingresses that have a kubernetes.io/tls-acme: "true" annotation.

For more information on deploying cert-manager, read the deployment guide.

Supported annotations

You can specify the following annotations on ingresses in order to trigger Certificate resources to be automatically created:

  • cert-manager.io/issuer - the name of an Issuer to acquire the certificate required for this ingress from. The Issuer must be in the same namespace as the Ingress resource.
  • cert-manager.io/cluster-issuer - the name of a ClusterIssuer to acquire the certificate required for this ingress from. It does not matter which namespace your Ingress resides, as ClusterIssuers are non-namespaced resources.
  • kubernetes.io/tls-acme: "true" - this annotation requires additional configuration of the ingress-shim (see above). Namely, a default issuer must be specified as arguments to the ingress-shim container.
  • acme.cert-manager.io/http01-ingress-class - this annotation allows you to configure ingress class that will be used to solve challenges for this ingress. Customising this is useful when you are trying to secure internal services, and need to solve challenges using different ingress class to that of the ingress. If not specified and the ‘acme-http01-edit-in-place’ annotation is not set, this defaults to the ingress class of the ingress resource.
  • acme.cert-manager.io/http01-edit-in-place: "true" - this controls whether the ingress is modified ‘in-place’, or a new one created specifically for the http01 challenge. If present, and set to “true” the existing ingress will be modified. Any other value, or the absence of the annotation assumes “false”.