Securing Ingress Resources
A common use-case for cert-manager is requesting TLS signed certificates to
secure your ingress resources. This can be done by simply adding annotations to
Ingress resources and cert-manager will facilitate creating the
Certificate resource for you. A small sub-component of cert-manager,
ingress-shim, is responsible for this.
How It Works
The sub-component ingress-shim watches
Ingress resources across your cluster.
If it observes an
Ingress with annotations described in the Supported
Annotations section, it will ensure a
resource with the name provided in the
tls.secretName field and configured as
described on the
Ingress exists. For example:
apiVersion: extensions/v1beta1kind: Ingressmetadata:annotations:# add an annotation indicating the issuer to use.cert-manager.io/cluster-issuer: nameOfClusterIssuername: myIngressnamespace: myIngressspec:rules:- host: example.comhttp:paths:- backend:serviceName: myserviceservicePort: 80path: /tls: # < placing a host in the TLS config will indicate a certificate should be created- hosts:- example.comsecretName: myingress-cert # < cert-manager will store the created certificate in this secret.
You can specify the following annotations on
Ingress resources in order to
Certificate resources to be automatically created:
cert-manager.io/issuer: the name of an
Issuerto acquire the certificate required for this
Ingress. The Issuer must be in the same namespace as the
cert-manager.io/cluster-issuer: the name of a
ClusterIssuerto acquire the certificate required for this
Ingress. It does not matter which namespace your
ClusterIssuersare non-namespaced resources.
cert-manager.io/issuer-kind: the name of an external
CustomResourceDefinition(only necessary for out-of-tree
cert-manager.io/issuer-group: the name of the API group of external
Issuercontroller (only necessary for out-of-tree
kubernetes.io/tls-acme: "true": this annotation requires additional configuration of the ingress-shim see below. Namely, a default
Issuermust be specified as arguments to the ingress-shim container.
acme.cert-manager.io/http01-ingress-class: this annotation allows you to configure the ingress class that will be used to solve challenges for this ingress. Customizing this is useful when you are trying to secure internal services, and need to solve challenges using a different ingress class to that of the ingress. If not specified and the
acme-http01-edit-in-placeannotation is not set, this defaults to the ingress class defined in the Issuer resource.
acme.cert-manager.io/http01-edit-in-place: "true": this controls whether the ingress is modified 'in-place', or a new one is 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". This annotation will also add the annotation
"cert-manager.io/issue-temporary-certificate": "true"onto created certificates which will cause a temporary certificate to be set on the resulting
Secretuntil the final signed certificate has been returned. This is useful for keeping compatibility with the
The ingress-shim sub-component is deployed automatically as part of installation.
If you would like to use the old
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 \--set ingressShim.defaultIssuerGroup=cert-manager.io
Or by adding the following arguments to the cert-manager deployment
podTemplate container arguments.
- --default-issuer-name=letsencrypt-prod- --default-issuer-kind=ClusterIssuer- --default-issuer-group=cert-manager.io
In the above example, cert-manager will create
Certificate resources that
letsencrypt-prod for all Ingresses that have a
kubernetes.io/tls-acme: "true" annotation.
For more information on deploying cert-manager, read the installation guide.
If you do not see a
Certificate resource being created after applying the ingress-shim annotations check that at least
cert-manager.io/cluster-issuer is set. If you want to use
kubernetes.io/tls-acme: "true" make sure to have checked all steps above and you might want to look for errors in the cert-manager pod logs if not resolved.