Update ClusterIssuers doc

docs/reference/clusterissuers.rst

@@ -2,7 +2,47 @@
 ClusterIssuers
 ==============
 
-ClusterIssuers work the same as Issuers, but with an important difference:
-they issue certificates across all namespaces.
+ClusterIssuers are a resource type similar to :doc:`Issuers </reference/issuers>`.
+They are specified in exactly the same way, but they do not belong to a single
+namespace and can be referenced by Certificate resources from multiple different
+namespaces.
 
-The docs for Issuer resources apply equally to ClusterIssuers, with the same supported providers.
+They are particularly useful when you want to provide the ability to obtain
+certificates from a central authority (e.g. Letsencrypt, or your internal CA)
+and you run single-tenant clusters.
+
+The docs for Issuer resources apply equally to ClusterIssuers.
+
+You can specify a ClusterIssuer resource by changing the ``kind`` attribute of
+an Issuer to ``ClusterIssuer``, and removing the ``metadata.namespace`` attribute:
+
+.. code-block:: yaml
+   :emphasize-lines: 2
+
+   apiVersion: certmanager.k8s.io/v1alpha1
+   kind: ClusterIssuer
+   metadata:
+     name: letsencrypt-prod
+   spec:
+   ...
+
+We can then reference a ClusterIssuer from a Certificate resource by setting
+the ``spec.issuerRef.kind`` field to ClusterIssuer:
+
+.. code-block:: yaml
+   :emphasize-lines: 10
+
+   apiVersion: certmanager.k8s.io/v1alpha1
+   kind: Certificate
+   metadata:
+     name: my-certificate
+     namespace: my-namespace
+   spec:
+     secretName: my-certificate-secret
+     issuerRef:
+       name: letsencrypt-prod
+       kind: ClusterIssuer
+     ...
+
+For more information on configuring Issuer resources, see the :doc:`Issuers </reference/issuers>`
+reference documentation.

docs/reference/issuers.rst

@@ -46,9 +46,9 @@ certificates from an Issuer in a different namespace. This means you will need
 to create an Issuer in each namespace you wish to obtain Certificates in.
 
 If you want to create a single issuer than can be consumed in multiple
-namespaces, you should consider creating a `ClusterIssuer` resource. This is
-almost identical to the `Issuer` resource, however is non-namespaced and so it
-can be used to issue Certificates across all namespaces.
+namespaces, you should consider creating a :doc:`ClusterIssuer <clusterissuers>`
+resource. This is almost identical to the Issuer resource, however is
+non-namespaced and so it can be used to issue Certificates across all namespaces.
 
 *******************
 Ambient Credentials

docs/tutorials/acme/migrating-from-kube-lego.rst

@@ -1,6 +1,6 @@
-************************
+========================
 Migrating from kube-lego
-************************
+========================
 
 kube-lego_ is an older Jetstack project for obtaining TLS certificates from
 Let's Encrypt (or another ACME server).