weiguoqiang/cert-manager
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Add doc on ingress-shim

Browse Source
This commit is contained in:
James Munnelly 2018-01-18 12:29:42 +00:00
parent c7900efc8a
commit 98b09b76fa
1 changed files with 66 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
docs/user-guides/ingress-shim.md Normal file
View File

@ -0,0 +1,66 @@
# Automatically provisioning 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](https://github.com/jetstack/cert-manager/tree/master/cmd/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.
As of the time of writing, it **will not** update Certificate resources if your
Ingress resource changes. It is up to yourself to ensure the corresponding
Certificate resource is as required.
## 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](https://github.com/jetstack/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.extraArgs='{--default-issuer-name=letsencrypt-prod,--default-issuer-kind=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](deploying.md).
## Usage
Since cert-manager v0.2.2, ingress-shim is deployed automatically as part of a
Helm chart installation. This allows your users to specify the following
annotations in ingresses in order to trigger certificates to be automatically
created:
* `certmanager.k8s.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.
* `certmanager.k8s.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.
* `certmanager.k8s.io/acme-challenge-type` - by default, if the Issuer
specified is an ACME issuer (either through ingress-shim's defaults, or with
one of the above annotations), the ingress-shim will set the ACME challenge
mechanism on the Certificate resource it creates to 'http01'. This annotation
can be used to alter this behaviour. Must be one of 'http01' or 'dns01'.
* `certmanager.k8s.io/acme-dns01-provider` - if the ACME challenge type has
been set to dns01, this annotation **must** be specified to instruct
cert-manager which DNS provider (as configured on the specified Issuer resource)
should be used. This field is required if the challenge type is set to DNS01.
* `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.