Expand deployment docs, including docs on ingress-shim

docs/README.md

@@ -12,7 +12,8 @@ It is split into these three sections for easier navigation.
 
 ## User guides
 
-* [Deploying cert-manager using Helm](user-guides/helm.md)
+* [Deploying cert-manager using Helm](user-guides/deploying.md)
+* [ingress-shim configuration and usage](user-guides/ingress-shim.md)
 * [Creating a simple CA based issuer](user-guides/ca-based-issuer.md)
 * [Creating cluster wide issuers](user-guides/cluster-issuers.md)
 * [Issuing an ACME certificate using HTTP validation](user-guides/acme-http-validation.md)

docs/user-guides/README.md

@@ -2,7 +2,8 @@
 
 This section of the documentation contains user guides for cert-manager. Full specifications of the different options in cert-manager can be found in [`docs/api-types`](../api-types).
 
-* [Deploying cert-manager using Helm](helm.md)
+* [Deploying cert-manager using Helm](deploying.md)
+* [ingress-shim configuration and usage](ingress-shim.md)
 * [Creating a simple CA based issuer](ca-based-issuer.md)
 * [Creating cluster wide issuers](cluster-issuers.md)
 * [Issuing an ACME certificate using HTTP validation](acme-http-validation.md)

docs/user-guides/deploying.md

@@ -0,0 +1,72 @@
+# Deploying cert-manager using Helm
+
+The recommended deployment tool for cert-manager is Helm. We ship a Helm chart
+with each release that is end-to-end tested in an RBAC enabled environment.
+
+## Deploying with Helm
+
+### Step 0 - setting up and configuring Helm/Tiller
+
+Before deploying cert-manager, you must ensure [Tiller](https://github.com/kubernetes/helm)
+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 [here](https://github.com/kubernetes/helm/blob/master/docs/install.md).
+
+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 [here](https://github.com/kubernetes/helm/blob/master/docs/rbac.md).
+
+### Step 1 - deploying cert-manager
+
+To deploy the latest version of cert-manager using Helm you will first need to
+clone this repository:
+
+```bash
+$ git clone https://github.com/jetstack/cert-manager
+$ cd cert-manager
+# check out the latest release tag to ensure we use a supported version of cert-manager
+$ git checkout v0.2.3
+```
+
+We can then go ahead and install the bundled chart:
+
+```bash
+$ helm install \
+    --name cert-manager \
+    --namespace kube-system \
+    contrib/charts/cert-manager
+```
+
+> **NOTE**: if your cluster does not use RBAC (Role Based Access Control), you should add `--set rbac.create=false` when running your `helm install` command.
+
+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](https://github.com/jetstack/cert-manager/blob/master/contrib/charts/cert-manager/README.md).
+
+Next, you will need to configure cert-manager with Issuers and ClusterIssuers.
+These represent a 'source' for x509 certificates and will be used later on to
+issue certificates.
+
+## Addendum
+
+* If your cluster does not use RBAC, you should add `--set rbac.create=false` to
+your `helm install` command. All RBAC related resources will not be created in
+this instance.
+
+* To add support for automatically creating Certificates for Ingress resources
+with the `kubernetes.io/tls-acme` annotation (similar to [kube-lego](https://github.com/jetstack/kube-lego)),
+you should deploy cert-manager with additional flags in order to specify the
+Issuer (or ClusterIssuer) responsible for acquiring these certificates. This
+can be done by adding the following additional `--set` command when running
+`helm install` (replacing the values accordingly):
+
+```
+--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.
+
+You can find more information on the ingress-shim (the component responsible
+for this) [here](ingress-shim.md).

docs/user-guides/ingress-shim.md

@@ -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.