From e20f18402371af9a13b0ab1ba93631c790382e00 Mon Sep 17 00:00:00 2001
From: Luke Addison <lukeaddison785@gmail.com>
Date: Fri, 20 Oct 2017 14:54:21 +0100
Subject: [PATCH] Add user-guide for creating cluster wide issuers

---
 docs/README.md                      |  2 +-
 docs/user-guides/README.md          |  4 +-
 docs/user-guides/cluster-issuers.md | 64 +++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 3 deletions(-)
 create mode 100644 docs/user-guides/cluster-issuers.md

diff --git a/docs/README.md b/docs/README.md
index e84d56e97..d9f3a60b4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,7 +13,7 @@ It is split into these three sections for easier navigation.
 ## User guides
 
 * [Creating a simple CA based issuer](user-guides/ca-based-issuer.md)
-* Creating cluster wide issuers
+* [Creating cluster wide issuers](user-guides/cluster-issuers.md)
 * [Issuing an ACME certificate using HTTP validation](user-guides/acme-http-validation.md)
 * [Issuing an ACME certificate using DNS validation](user-guides/acme-dns-validation.md)
 
diff --git a/docs/user-guides/README.md b/docs/user-guides/README.md
index 0364c0f9c..e44711cb2 100644
--- a/docs/user-guides/README.md
+++ b/docs/user-guides/README.md
@@ -1,8 +1,8 @@
 # User guides
 
-This section of the documentation contains a list of use-case focused user guides on using `cert-manager`
+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).
 
 * [Creating a simple CA based issuer](ca-based-issuer.md)
-* Creating cluster wide issuers
+* [Creating cluster wide issuers](cluster-issuers.md)
 * [Issuing an ACME certificate using HTTP validation](acme-http-validation.md)
 * [Issuing an ACME certificate using DNS validation](acme-dns-validation.md)
\ No newline at end of file
diff --git a/docs/user-guides/cluster-issuers.md b/docs/user-guides/cluster-issuers.md
new file mode 100644
index 000000000..549fd63d3
--- /dev/null
+++ b/docs/user-guides/cluster-issuers.md
@@ -0,0 +1,64 @@
+# Creating cluster wide Issuers
+
+cert-manager has the concept of `ClusterIssuers`. These are a non-namespaced and cluster-scoped version of an `Issuer`. The specification of a `ClusterIssuer` is exactly the same as that of an `Issuer`, but there are a couple of nuances you need to be aware of.
+
+```yaml
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: ClusterIssuer
+metadata:
+  name: ca-cluster-issuer
+spec:
+  ca:
+    secretName: ca-key-pair
+```
+
+```yaml
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-staging-cluster-issuer
+spec:
+  acme:
+    server: https://acme-staging.api.letsencrypt.org/directory
+    email: user@example.com
+    privateKeySecretRef:
+      name: letsencrypt-staging
+    http01: {}
+```
+
+The two manifests above define two `ClusterIssuers`. As `ClusterIssuer` resources do not specify a namespace, we must configure a namespace that cert-manager will use to store supporting resources required for each `ClusterIssuer`. We do this by specifying the `--cluster-resource-namespace` flag on the cert-manager controller. By default, this flag will be set to `kube-system`.
+
+In order to reference a `ClusterIssuer` in a `Certificate` you must specify the `kind` in the `issuerRef` stanza. The following are two examples of `Certificates` that reference our `ClusterIssuers` above.
+
+```yaml
+kind: Certificate
+metadata:
+  name: ca-crt
+  namespace: default
+spec:
+  secretName: ca-crt-secret
+  issuerRef:
+    name: ca-cluster-issuer
+    kind: ClusterIssuer
+  dnsNames:
+  - cert-manager.k8s.io
+```
+
+```yaml
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Certificate
+metadata:
+  name: nginx-k8s-io
+  namespace: default
+spec:
+  secretName: nginx-k8s-io-tls
+  issuerRef:
+    name: letsencrypt-staging-cluster-issuer
+    kind: ClusterIssuer
+  commonName: nginx.k8s.io
+  acme:
+    config:
+    - http01: {}
+      domains:
+      - nginx.k8s.io
+```