From 37812059b5c84f85d6bd4aa90f9ff47ed215e80b Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Wed, 11 Apr 2018 15:48:33 +0100 Subject: [PATCH] Add notes and todos, rephrase and tidy up --- docs/conf.py | 3 +++ docs/getting-started/2-installing.rst | 9 +++++---- docs/reference/certificates.rst | 1 - docs/reference/issuers/acme/http01.rst | 12 ++++++++---- docs/tutorials/acme/migrating-from-kube-lego.rst | 8 ++++++-- 5 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 22f65bc43..9f41948b6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,6 +38,7 @@ release = u'' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.todo', ] # Add any paths that contain templates here, relative to this directory. @@ -67,6 +68,8 @@ exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True # -- Options for HTML output ------------------------------------------------- diff --git a/docs/getting-started/2-installing.rst b/docs/getting-started/2-installing.rst index d7ddc2e49..2bce9bc74 100644 --- a/docs/getting-started/2-installing.rst +++ b/docs/getting-started/2-installing.rst @@ -17,13 +17,14 @@ You can install the chart with the following command: --namespace kube-system \ stable/cert-manager -**NOTE**: if your cluster does not use RBAC (Role Based Access Control), you -will need to disable creation of RBAC resources by adding -``--set rbac.create=false`` to your ``helm install`` command above. - 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`_. +.. note:: + If your cluster does not use RBAC (Role Based Access Control), you + will need to disable creation of RBAC resources by adding + ``--set rbac.create=false`` to your ``helm install`` command above. + With static manifests ===================== diff --git a/docs/reference/certificates.rst b/docs/reference/certificates.rst index f13e853ce..dcf688e4e 100644 --- a/docs/reference/certificates.rst +++ b/docs/reference/certificates.rst @@ -33,7 +33,6 @@ A simple Certificate could be defined as: # The default value is Issuer (i.e. a locally namespaced Issuer) kind: Issuer - This Certificate will tell cert-manager to attempt to use the Issuer named ``letsencrypt-prod`` to obtain a certificate key pair for the ``foo.example.com`` and ``bar.example.com`` domains. If successful, the resulting diff --git a/docs/reference/issuers/acme/http01.rst b/docs/reference/issuers/acme/http01.rst index 099c4994a..045207e2a 100644 --- a/docs/reference/issuers/acme/http01.rst +++ b/docs/reference/issuers/acme/http01.rst @@ -3,10 +3,11 @@ HTTP01 Challenge Provider ========================= In order to allow HTTP01 challenges to be solved, we must enable the HTTP01 -challenge provider on our Issuer resource. This can be done through setting the -``http01`` field on the ``issuer.spec.acme`` stanza. Cert-manager will then -create and manage Ingress rules in the Kubernetes API server in order to solve -HTTP-01 based challenges. +challenge provider on our Issuer resource. + +This is done through setting the ``http01`` field on the ``issuer.spec.acme`` +stanza. Cert-manager will then attempt to solve ACME HTTP-01 challenges by +using Ingress resources .. code-block:: yaml :linenos: @@ -23,3 +24,6 @@ HTTP-01 based challenges. privateKeySecretRef: name: example-issuer-account-key http01: {} + +.. todo:: + Write a full description of how HTTP01 challenge validation works diff --git a/docs/tutorials/acme/migrating-from-kube-lego.rst b/docs/tutorials/acme/migrating-from-kube-lego.rst index 61c4a826f..170edf29c 100644 --- a/docs/tutorials/acme/migrating-from-kube-lego.rst +++ b/docs/tutorials/acme/migrating-from-kube-lego.rst @@ -20,7 +20,8 @@ Distinct issuance sources per Certificate Not supported Ingress controller support (ACME) GCE, nginx All ========================================= ================================ ===================== -This guide will walk through how you can safely migrate your kube-lego installation to cert-manager, without service interruption. +This guide will walk through how you can safely migrate your kube-lego +installation to cert-manager, without service interruption. By the end of the guide, we should have: @@ -44,7 +45,10 @@ By the end of the guide, we should have: 1. Scale down kube-lego ======================= -Before we begin deploying cert-manager, it is best we scale our kube-lego deployment down to 0 replicas. This will prevent the two controllers potentially 'fighting' each other. If you deployed kube-lego using the official deployment YAMLs, a command like so should do: +Before we begin deploying cert-manager, it is best we scale our kube-lego +deployment down to 0 replicas. This will prevent the two controllers +potentially 'fighting' each other. If you deployed kube-lego using the official +deployment YAMLs, a command like so should do: .. code-block:: shell