Add user-guide for creating cluster wide issuers

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)
 

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)

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
+```