From 337e4f090ede5867cdc1d422b701c7118d8d64aa Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Tue, 29 Jan 2019 23:24:11 +0000 Subject: [PATCH] Rearrange documentation and add new content Signed-off-by: James Munnelly --- docs/admin/index.rst | 14 - docs/admin/resource-validation-webhook.rst | 249 ----------------- docs/getting-started/1-configuring-helm.rst | 20 -- docs/getting-started/2-installing.rst | 150 ---------- .../3-configuring-first-issuer.rst | 26 -- docs/getting-started/index.rst | 20 +- docs/getting-started/install.rst | 263 ++++++++++++++++++ docs/getting-started/troubleshooting.rst | 42 +++ docs/getting-started/webhook.rst | 186 +++++++++++++ docs/index.rst | 4 +- docs/reference/certificates.rst | 6 - .../issuer-specific-config/acme.rst | 15 - docs/reference/issuers.rst | 38 +-- docs/reference/issuers/acme/index.rst | 14 - docs/reference/issuers/ca/index.rst | 15 - docs/reference/issuers/vault/index.rst | 15 - .../acme/configuring-dns01}/acme-dns.rst | 0 .../acme/configuring-dns01}/akamai.rst | 0 .../acme/configuring-dns01}/azuredns.rst | 0 .../acme/configuring-dns01}/cloudflare.rst | 0 .../acme/configuring-dns01}/digitalocean.rst | 0 .../acme/configuring-dns01}/google.rst | 0 .../acme/configuring-dns01}/index.rst | 0 .../acme/configuring-dns01}/route53.rst | 0 .../acme/configuring-http01.rst} | 36 ++- docs/tasks/acme/debugging-failing-orders.rst | 3 + docs/tasks/acme/index.rst | 16 ++ docs/tasks/acme/issuing-certificates.rst | 16 ++ docs/tasks/index.rst | 15 + .../issuers/vault => tasks/issuers}/OWNERS | 0 docs/tasks/issuers/index.rst | 74 +++++ docs/tasks/issuers/setup-acme.rst | 3 + .../issuers/setup-ca.rst} | 7 +- .../issuers/setup-selfsigned.rst} | 16 +- .../issuers/setup-vault.rst} | 5 +- docs/tasks/issuing-certificates.rst | 15 + docs/{admin => tasks}/upgrading/index.rst | 14 +- .../upgrading/upgrading-0.2-0.3.rst | 0 .../upgrading/upgrading-0.3-0.4.rst | 0 .../upgrading/upgrading-0.4-0.5.rst | 0 .../upgrading/upgrading-0.5-0.6.rst | 6 +- docs/tutorials/acme/dns-validation.rst | 2 +- docs/tutorials/acme/http-validation.rst | 6 +- docs/tutorials/acme/index.rst | 9 +- .../quick-start/example/deployment.yaml | 0 .../example/ingress-tls-final.yaml | 0 .../quick-start/example/ingress-tls.yaml | 0 .../quick-start/example/ingress.yaml | 0 .../example/production-issuer.yaml | 0 .../quick-start/example/service.yaml | 0 .../quick-start/example/staging-issuer.yaml | 0 .../{ => acme}/quick-start/index.rst | 16 +- ...ecuring-nginx-ingress-with-letsencrypt.rst | 22 -- docs/tutorials/ca/index.rst | 12 - docs/tutorials/index.rst | 10 +- docs/tutorials/vault/OWNERS | 5 - docs/tutorials/vault/index.rst | 12 - 57 files changed, 729 insertions(+), 668 deletions(-) delete mode 100644 docs/admin/index.rst delete mode 100644 docs/admin/resource-validation-webhook.rst delete mode 100644 docs/getting-started/1-configuring-helm.rst delete mode 100644 docs/getting-started/2-installing.rst delete mode 100644 docs/getting-started/3-configuring-first-issuer.rst create mode 100644 docs/getting-started/install.rst create mode 100644 docs/getting-started/troubleshooting.rst create mode 100644 docs/getting-started/webhook.rst delete mode 100644 docs/reference/certificates/issuer-specific-config/acme.rst delete mode 100644 docs/reference/issuers/acme/index.rst delete mode 100644 docs/reference/issuers/ca/index.rst delete mode 100644 docs/reference/issuers/vault/index.rst rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/acme-dns.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/akamai.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/azuredns.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/cloudflare.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/digitalocean.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/google.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/index.rst (100%) rename docs/{reference/issuers/acme/dns01 => tasks/acme/configuring-dns01}/route53.rst (100%) rename docs/{reference/issuers/acme/http01.rst => tasks/acme/configuring-http01.rst} (64%) create mode 100644 docs/tasks/acme/debugging-failing-orders.rst create mode 100644 docs/tasks/acme/index.rst create mode 100644 docs/tasks/acme/issuing-certificates.rst create mode 100644 docs/tasks/index.rst rename docs/{reference/issuers/vault => tasks/issuers}/OWNERS (100%) create mode 100644 docs/tasks/issuers/index.rst create mode 100644 docs/tasks/issuers/setup-acme.rst rename docs/{tutorials/ca/creating-ca-issuer.rst => tasks/issuers/setup-ca.rst} (98%) rename docs/{reference/issuers/selfsigned/index.rst => tasks/issuers/setup-selfsigned.rst} (73%) rename docs/{tutorials/vault/creating-vault-issuers.rst => tasks/issuers/setup-vault.rst} (98%) create mode 100644 docs/tasks/issuing-certificates.rst rename docs/{admin => tasks}/upgrading/index.rst (89%) rename docs/{admin => tasks}/upgrading/upgrading-0.2-0.3.rst (100%) rename docs/{admin => tasks}/upgrading/upgrading-0.3-0.4.rst (100%) rename docs/{admin => tasks}/upgrading/upgrading-0.4-0.5.rst (100%) rename docs/{admin => tasks}/upgrading/upgrading-0.5-0.6.rst (94%) rename docs/tutorials/{ => acme}/quick-start/example/deployment.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/example/ingress-tls-final.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/example/ingress-tls.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/example/ingress.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/example/production-issuer.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/example/service.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/example/staging-issuer.yaml (100%) rename docs/tutorials/{ => acme}/quick-start/index.rst (98%) delete mode 100644 docs/tutorials/acme/securing-nginx-ingress-with-letsencrypt.rst delete mode 100644 docs/tutorials/ca/index.rst delete mode 100644 docs/tutorials/vault/OWNERS delete mode 100644 docs/tutorials/vault/index.rst diff --git a/docs/admin/index.rst b/docs/admin/index.rst deleted file mode 100644 index 063376dc1..000000000 --- a/docs/admin/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -==================== -Administrative tasks -==================== - -This section contains documentation about common administrative tasks for cert-manager. - -Explore the sections listed below to find more information on how to run and -manage a cert-manager deployment as an administrator. - -.. toctree:: - :maxdepth: 1 - - resource-validation-webhook - upgrading/index diff --git a/docs/admin/resource-validation-webhook.rst b/docs/admin/resource-validation-webhook.rst deleted file mode 100644 index 90eb76a8c..000000000 --- a/docs/admin/resource-validation-webhook.rst +++ /dev/null @@ -1,249 +0,0 @@ -=========================== -Resource Validation Webhook -=========================== - -In order to provide advanced resource validation, cert-manager includes a -ValidatingWebhookConfiguration which is deployed into the cluster as its own -pod. - -This feature requires Kubernetes 1.9 or greater. If you disable the webhook -component, cert-manager will still perform the same resource validation however -will not reject 'create' events when submitting resources to the API server. - -The webhook component is disabled by default, and must be enabled when -installing with the helm chart, or installed as an additional component -if using the static manifests. - -Enabling the webhook component -============================== - -With Helm ---------- - -To enable the component when using Helm, you must first ensure the namespace -that you deploy cert-manager into has the label -``certmanager.k8s.io/disable-validation: "true"``. - -You can add this label like so: - -.. code:: - - $ kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - -.. note:: - New installations of cert-manager with Helm v2.10 and later will not require - this additional step - -You can then proceed to upgrade your Helm deployment as usual, adding one -additional flag: - -.. code:: - - $ helm upgrade cert-manager stable/cert-manager \ - --reuse-values \ - --set webhook.enabled=true - -With static manifests ---------------------- - -When installing using the static manifests, the webhook component is installed -as a separate set of manifests. - -You can find the manifests for the webhook in the `deploy directory`_. - -FAQ -=== - -TLS Configuration ------------------ - -The ValidatingWebhookConfiguration resource requires that the webhook server -uses TLS. - -cert-manager uses a commbination of the SelfSigned and CA Issuer types to -provision the resources required to do this. - -In order to do this, when installing with the Helm chart or static deployment -manifests, resource validation is **disabled** on the nammespace cert-manager -is deployed into. - -.. note:: - If you have manually created the namespace that cert-manager is deployed into, - you must ensure your namespace has the ``certmanager.k8s.io/disable-validation: "true"`` - Label set on the Namespace resource. - This is handled automatically when performing a ``helm install`` for the first - time by use of an additional selector in the ValidatingWebhookConfiguration - -1) First, a self-signed Issuer is created in order to issue self-signed -certificates. -You can see this named ``cm-cert-manager-selfsign`` in the output below. - -2) Then, a Certificate resource referencing the self-signed Issuer is created. -This certificate has ``spec.isCA: true`` set. It will be used as our root CA. -You can see this named ``cm-cert-manager-webhook-ca`` in the output below. - -3) Then another Issuer resource is created, this time a **CA** Issuer. -This Issuer will issue certificates signed by the self-signed root CA created -in (2). -You can see this named ``cm-cert-manager-webhook-ca`` in the output below. - -4) Finally, a second Certificate resource is created. This one will be used by -the webhook to secure communication between the apiserver and the webhook! -You can see this named ``cm-cert-manager-webhook-tls`` in the output below. - -You can see the status of the certificates and issuers used for the webhook in -your own cluster by running: - -.. code:: shell - - $ kubectl describe certificate --namespace cert-manager - Name: cm-cert-manager-webhook-ca - Namespace: cert-manager - Labels: - Annotations: - API Version: certmanager.k8s.io/v1alpha1 - Kind: Certificate - Metadata: - Cluster Name: - Creation Timestamp: 2018-08-07T23:18:53Z - Generation: 0 - Resource Version: 722 - Self Link: /apis/certmanager.k8s.io/v1alpha1/namespaces/cert-manager/certificates/cm-cert-manager-webhook-ca - UID: 402722a2-9a98-11e8-bf3f-525400856e41 - Spec: - Common Name: ca.webhook.cert-manager - Is CA: true - Issuer Ref: - Name: cm-cert-manager-selfsign - Secret Name: cm-cert-manager-webhook-ca - Status: - Conditions: - Last Transition Time: 2018-08-07T23:18:57Z - Message: Certificate issued successfully - Reason: CertIssued - Status: True - Type: Ready - Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal IssueCert 9m cert-manager Issuing certificate... - Normal CertIssued 9m cert-manager Certificate issued successfully - - - Name: cm-cert-manager-webhook-tls - Namespace: cert-manager - Labels: - Annotations: - API Version: certmanager.k8s.io/v1alpha1 - Kind: Certificate - Metadata: - Cluster Name: - Creation Timestamp: 2018-08-07T23:18:53Z - Generation: 0 - Resource Version: 738 - Self Link: /apis/certmanager.k8s.io/v1alpha1/namespaces/cert-manager/certificates/cm-cert-manager-webhook-tls - UID: 4021e81e-9a98-11e8-bf3f-525400856e41 - Spec: - Dns Names: - cm-cert-manager-webhook - cm-cert-manager-webhook.cert-manager - cm-cert-manager-webhook.cert-manager.svc - Is CA: false - Issuer Ref: - Name: cm-cert-manager-webhook - Secret Name: cm-cert-manager-webhook-tls - Status: - Conditions: - Last Transition Time: 2018-08-07T23:19:01Z - Message: Certificate issued successfully - Reason: CertIssued - Status: True - Type: Ready - Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Warning IssuerNotReady 9m cert-manager Issuer cm-cert-manager-webhook not ready - Normal IssueCert 9m cert-manager Issuing certificate... - Normal CertIssued 9m cert-manager Certificate issued successfully - - - $ kubectl describe issuer --namespace cert-manager - Name: cm-cert-manager-selfsign - Namespace: cert-manager - Labels: - Annotations: - API Version: certmanager.k8s.io/v1alpha1 - Kind: Issuer - Metadata: - Cluster Name: - Creation Timestamp: 2018-08-07T23:18:53Z - Generation: 0 - Resource Version: 696 - Self Link: /apis/certmanager.k8s.io/v1alpha1/namespaces/cert-manager/issuers/cm-cert-manager-selfsign - UID: 402a07c1-9a98-11e8-bf3f-525400856e41 - Spec: - Self Signed: - Status: - Conditions: - Last Transition Time: 2018-08-07T23:18:55Z - Message: - Reason: IsReady - Status: True - Type: Ready - Events: - - - Name: cm-cert-manager-webhook-ca - Namespace: cert-manager - Labels: - Annotations: - API Version: certmanager.k8s.io/v1alpha1 - Kind: Issuer - Metadata: - Cluster Name: - Creation Timestamp: 2018-08-07T23:18:53Z - Generation: 0 - Resource Version: 726 - Self Link: /apis/certmanager.k8s.io/v1alpha1/namespaces/cert-manager/issuers/cm-cert-manager-webhook-ca - UID: 402ea69e-9a98-11e8-bf3f-525400856e41 - Spec: - Ca: - Secret Name: cm-cert-manager-webhook-ca - Status: - Conditions: - Last Transition Time: 2018-08-07T23:18:58Z - Message: Signing CA verified - Reason: KeyPairVerified - Status: True - Type: Ready - Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Warning ErrGetKeyPair 9m cert-manager Error getting keypair for CA issuer: secret "cm-cert-manager-webhook-ca" not found - Warning ErrInitIssuer 9m cert-manager Error initializing issuer: secret "cm-cert-manager-webhook-ca" not found - Warning ErrGetKeyPair 9m (x6 over 9m) cert-manager Error getting keypair for CA issuer: secret "cm-cert-manager-webhook-ca" not found - Warning ErrInitIssuer 9m (x6 over 9m) cert-manager Error initializing issuer: secret "cm-cert-manager-webhook-ca" not found - Normal KeyPairVerified 9m (x2 over 9m) cert-manager Signing CA verified - -Keeping Kubernetes PKI resources up to date -------------------------------------------- - -Once the root CA certificate has been provisioned, cert-manager also needs to -update the Kubernetes API Server to give it a copy of the root CA in order to -verify connections to the webhook component. - -To do this, the ``spec.caBundle`` field on the ``APIService`` resource named -``v1beta1.admission.certmanager.k8s.io`` must be set to the root CA generated -above, and the ValidatingWebhookConfiguration named ``cert-manager-webhook`` -must have its own ``caBundle`` fields set to that of your Kubernetes API -Server. - -The cert-manager deployment manifests do this automatically by installing a -Kubernetes CronJob resource. -This CronJob will run every 24 hours and ensures that these resources are up to -date. - -The code for this component can be found at `munnerz/apiextensions-ca-helper`_ - -.. _`munnerz/apiextensions-ca-helper`: https://github.com/munnerz/apiextensions-ca-helper -.. _`deploy directory`: https://github.com/jetstack/cert-manager/blob/release-0.5/contrib/manifests/cert-manager diff --git a/docs/getting-started/1-configuring-helm.rst b/docs/getting-started/1-configuring-helm.rst deleted file mode 100644 index e47078d18..000000000 --- a/docs/getting-started/1-configuring-helm.rst +++ /dev/null @@ -1,20 +0,0 @@ -============================== -1. Configuring Helm and Tiller -============================== - -Before deploying cert-manager, you must ensure Tiller_ 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 in the `Installing helm docs`_. - -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 in the `Helm RBAC docs`_. - -.. _`helm RBAC docs`: https://github.com/kubernetes/helm/blob/master/docs/rbac.md -.. _`installing helm docs`: https://github.com/kubernetes/helm/blob/master/docs/install.md -.. _Tiller: https://github.com/kubernetes/helm diff --git a/docs/getting-started/2-installing.rst b/docs/getting-started/2-installing.rst deleted file mode 100644 index 0861e4713..000000000 --- a/docs/getting-started/2-installing.rst +++ /dev/null @@ -1,150 +0,0 @@ -========================== -2. Installing cert-manager -========================== - -With Helm -========== - -Using Helm is the recommended way to deploy cert-manager. We publish a stable -version of the chart to the public `charts repository`_. - -Before installing the cert-manager Helm chart, you will need to install the -CustomResourceDefinition resources that it uses. - -You can perform these two steps with the following commands: - -.. code-block:: shell - - # Install the cert-manager CRDs - $ kubectl apply \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.6/deploy/manifests/00-crds.yaml - - # Update helm repository cache - $ helm repo update - - # Install cert-manager - $ helm install \ - --name cert-manager \ - --namespace cert-manager \ - --version v0.6.0 \ - stable/cert-manager - -Each time you upgrade, you will need to re-apply the ``00-crds.yaml`` manifest -above (updating the version number, in this case ``v0.6.0``, accordingly). - -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. - -.. note:: - If you are upgrading from a previous release, please check the :doc:`upgrading guide ` - for special considerations. - -With static manifests -===================== - -As some users may not want to use Helm, or would prefer to use a more -traditional deployment management mechanism, we also provide 'static manifests' -which can be installed with ``kubectl apply -f``. - -To install cert-manager using the static manifests, you should run: - -.. code-block:: shell - - # Install cert-manager - $ kubectl apply \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.6/deploy/manifests/cert-manager.yaml - -.. note:: - If you are running kubectl v1.12 or below, you will need to add the - ``--validate=false`` flag to your ``kubectl apply`` command above else you - will receive a validation error relating to the ``caBundle`` field of the - ``ValidatingWebhookConfiguration`` resource. - This issue is resolved in Kubernetes 1.13 onwards. More details can be found - in `kubernetes/kubernetes#69590`_. - -Verifying your installation -=========================== - -During installation, a number of operations including a Kubernetes 'Job' will -be created. -These resources **must** complete successfully in order for cert-manager to -run. - -To verify your installation has completed, you should check the Status of all -pods in your cert-manager namespace: - -.. code-block:: shell - - # Get all pods, including Completed and Errored pods - $ kubectl get pods --show-all --namespace cert-manager - NAME READY STATUS RESTARTS AGE - cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m - cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m - cert-manager-webhook-ca-sync-1547942400-g6985 0/1 Completed 0 3m - -If the 'ca-sync' pod above does not show Completed, you may need to re-start -the Job using the ``kubectl create job`` command: - -.. code-block:: shell - - # Find the name of the CronJob resource - $ kubectl get cronjob --namespace cert-manager - NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE - cert-manager-webhook-ca-sync @weekly False 0 3m - - # Trigger the CronJob to run immediately - $ kubectl create job \ - --namespace cert-manager \ - --from cronjob/cert-manager-webhook-ca-sync \ - ca-sync-manually-triggered - -This will trigger the cert-manager job to run again. - -.. note:: - If the job continues to fail, please read the - :doc:`Resource Validating Webhook ` docs - for additional information. - -Once all the pods are 'Ready', you should be good to go. To confirm, attempt -to create a basic 'selfsigned' ClusterIssuer. If you do not receive any errors -when creating the resource, the deployment should be good to go! - -.. code-block:: shell - - # Create a ClusterIssuer to test the webhook works okay - $ cat < test-clusterissuer.yaml - apiVersion: certmanager.k8s.io/v1alpha1 - kind: ClusterIssuer - metadata: - name: test-selfsigned - spec: - selfSigned: {} - EOF - - # Create the new ClusterIssuer (if this step fails, please read the resource - # validation webhook doc linked in the note above) - $ kubectl apply -f test-clusterissuer.yaml - - # Delete the newly created test ClusterIssuer - $ kubectl delete -f test-clusterissuer.yaml - -If all the above steps have completed with error, you are good to go! - -Next steps -========== - -You'll need to set yourself at least one Issuer or ClusterIssuer resource in -order to begin issuing certificates. Take a look at the next page, -:doc:`Configuring your first Issuer or ClusterIssuer -` -for more information. - -.. _`charts repository`: https://github.com/kubernetes/charts -.. _`Helm chart README`: https://github.com/kubernetes/charts/blob/master/stable/cert-manager/README.md -.. _`deploy directory`: https://github.com/jetstack/cert-manager/blob/master/contrib/manifests/cert-manager -.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 diff --git a/docs/getting-started/3-configuring-first-issuer.rst b/docs/getting-started/3-configuring-first-issuer.rst deleted file mode 100644 index 253bd4a51..000000000 --- a/docs/getting-started/3-configuring-first-issuer.rst +++ /dev/null @@ -1,26 +0,0 @@ -================================================= -3. Configuring your first Issuer or ClusterIssuer -================================================= - -Before you can issue any Certificates, you will need to configure an -:doc:`Issuer ` or -:doc:`ClusterIssuer ` resource. - -These represent a certificate authority from which signed x509 certificates can -be obtained, such as Let's Encrypt, or your own signing key pair stored in a -Kubernetes Secret resource. - -An :doc:`Issuer ` is scoped to a single namespace, and can -only fulfill :doc:`Certificate ` resources within its -own namespace. This is useful in a multi-tenant environment where multiple -teams or independent parties operate within a single cluster. - -On the other hand, a :doc:`ClusterIssuer ` is a -cluster wide version of an :doc:`Issuer `. It is able to be -referenced by :doc:`Certificate ` resources in any -namespace. Users often create ``letsencrypt-staging`` and ``letsencrypt-prod`` -:doc:`ClusterIssuers ` if they operate a -single-tenant environment and want to expose a cluster-wide mechanism for -obtaining TLS certificates from `Let's Encrypt`_. - -.. _`Let's Encrypt`: https://letsencrypt.org diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index 0d206074c..b505cf3e3 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -1,16 +1,16 @@ -=============== -Getting started -=============== +=========== +Get started +=========== -This contains information on getting started with cert-manager and deployment -information. +The guides in this section will explain how to install and set up cert-manager. -New users should start here before proceeding to the :doc:`/tutorials/index` section, -as the steps in this section are a prerequisite for all tutorials. +If you run into issues deploying, upgrading or running cert-manager please +check the :doc:`troubleshooting <./troubleshooting>` document. .. toctree:: :maxdepth: 2 + :caption: Contents: - 1-configuring-helm - 2-installing - 3-configuring-first-issuer + install + webhook + troubleshooting diff --git a/docs/getting-started/install.rst b/docs/getting-started/install.rst new file mode 100644 index 000000000..8803f0d01 --- /dev/null +++ b/docs/getting-started/install.rst @@ -0,0 +1,263 @@ +======================= +Installing cert-manager +======================= + +cert-manager runs within your Kubernetes cluster as a series of deployment +resources. It utilises `CustomResourceDefinitions`_ to configure Certificate +Authorities and request certificates. + +It is deployed using regular YAML manifests, like any other applications on +Kubernetes. + +Once cert-manager has been deployed, you must configure Issuer or ClusterIssuer +resources which represent certificate authorities. +More information on configuring different Issuer types can be found in the +:doc:`respective setup guides `. + + +Installing with regular manifests +================================= + +In order to install cert-manager, we must first create a namespace to run it +within. This guide will install cert-manager into the ``cert-manager`` +namespace. It is possible to run cert-manager in a different namespace, +although you will need to make modifications to the deployment manifests. + +.. code-block:: shell + + # Create a namespace to run cert-manager in + kubectl create namespace cert-manager + +As part of the installation, cert-manager also deploys a +`ValidatingWebhookConfiguration`_ resource in order to validate that the +Issuer, ClusterIssuer and Certificate resources we will create after +installation are valid. + +In order to deploy the ValidatingWebhookConfiguration, cert-manager creates +a number of 'internal' Issuer and Certificate resources in its own namespace. + +This creates a chicken-and-egg problem, where cert-manager requires the +webhook in order to create the resources, and the webhook requires cert-manager +in order to run. + +We avoid this problem by disabling resource validation on the namespace that +cert-manager runs in: + +.. code-block:: shell + + # Disable resource validation on the cert-manager namespace + kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true + +We can now go ahead and install cert-manager. This is a two-stage process where +we first install the CustomResourceDefinition resources, and then afterwards +install cert-manager along with the webhook component: + +.. code-block:: shell + + # Install the CustomResourceDefinition resources + kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/v0.6.0/deploy/manifests/00-crds.yaml + + # Install cert-manager itself + kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/v0.6.0/deploy/manifests/cert-manager.yaml + +.. note:: + If you are running kubectl v1.12 or below, you will need to add the + ``--validate=false`` flag to your ``kubectl apply`` command above else you + will receive a validation error relating to the ``caBundle`` field of the + ``ValidatingWebhookConfiguration`` resource. + This issue is resolved in Kubernetes 1.13 onwards. More details can be found + in `kubernetes/kubernetes#69590`_. + +.. note:: + When running on GKE (Google Kubernetes Engine), you may encounter a + 'permission denied' error when creating some of these resources. This is a + nuance of the way GKE handles RBAC and IAM permissions, and as such you + should 'elevate' your own privileges to that of a 'cluster-admin' **before** + running the above commands. If you have already run the above commands, you + should run them again after elevating your permissions: + +.. code-block:: shell + + kubectl create clusterrolebinding cluster-admin-binding \ + --clusterrole=cluster-admin \ + --user=$(gcloud config get-value core/account) + +Installing with Helm +==================== + +As an alternative to the YAML manifests referenced above, we also provide an +official Helm chart for installing cert-manager. + +Pre-requisites +-------------- + +* Helm_ and Tiller installed +* `cluster-admin privileges bound to the Tiller pod`_ + +Foreword +-------- + +Before deploying cert-manager with Helm, you must ensure Tiller_ 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 in the `Installing helm docs`_. + +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 in the `Helm RBAC docs`_. + +Steps +----- + +In order to install the Helm chart, you must run: + +.. code-block:: shell + + # Install the CustomResourceDefinition resources separately + kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/v0.6.0/deploy/manifests/00-crds.yaml + + # Create the namespace for cert-manager + kubectl create namespace cert-manager + + # Label the cert-manager namespace to disable resource validation + kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true + + # Update your local Helm chart repository cache + helm repo update + + # Install the cert-manager Helm chart + helm install \ + --name cert-manager \ + --namespace cert-manager \ + --version v0.6.0 \ + stable/cert-manager + +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`_. + +Verifying the installation +========================== + +Once you've installed cert-manager, you can verify it is deployed correctly by +checking the ``cert-manager`` namespace for running pods: + +.. code-block:: shell + + kubectl get pods --namespace cert-manager + + NAME READY STATUS RESTARTS AGE + cert-manager-5c6866597-zw7kh 1/1 Running 0 2m + webhook-78fb756679-9bsmf 1/1 Running 0 2m + webhook-ca-sync-1543708620-n82gj 0/1 Completed 0 1m + +You should see both the ``cert-manager`` and ``webhook`` component in a Running +state, and the ``ca-sync`` pod is Completed. If the webhook has not Completed +but the ``cert-manager`` pod has recently started, wait a few minutes for the +``ca-sync`` pod to be retried. +If you experience problems, please check the +:doc:`troubleshooting guide <./troubleshooting>`. + +The following steps will confirm that cert-manager is set up and correctly and +able to issue basic certificate types: + +.. code-block:: shell + + # Create a ClusterIssuer to test the webhook works okay + cat < test-resources.yaml + apiVersion: v1 + kind: Namespace + metadata: + name: cert-manager-test + --- + apiVersion: certmanager.k8s.io/v1alpha1 + kind: Issuer + metadata: + name: test-selfsigned + namespace: cert-manager-test + spec: + selfSigned: {} + --- + apiVersion: certmanager.k8s.io/v1alpha1 + kind: Certificate + metadata: + name: selfsigned-cert + namespace: cert-manager-test + spec: + commonName: example.com + secretName: selfsigned-cert-tls + issuerRef: + name: test-selfsigned + EOF + + # Create the test resources + kubectl apply -f test-resources.yaml + + # Check the status of the newly created certificate + # You may need to wait a few seconds before cert-manager processes the + # certificate request + kubectl describe certificate -n cert-manager-test + ... + Spec: + Common Name: example.com + Issuer Ref: + Name: test-selfsigned + Secret Name: selfsigned-cert-tls + Status: + Conditions: + Last Transition Time: 2019-01-29T17:34:30Z + Message: Certificate is up to date and has not expired + Reason: Ready + Status: True + Type: Ready + Not After: 2019-04-29T17:34:29Z + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal CertIssued 4s cert-manager Certificate issued successfully + + # Clean up the test resources + kubectl delete -f test-resources.yaml + +If all the above steps have completed with error, you are good to go! + +If you experience problems, please check the +:doc:`troubleshooting guide <./troubleshooting>`. + +Configuring your first Issuer +============================= + +Before you can begin issuing certificates, you must configure at least one +Issuer or ClusterIssuer resource in your cluster. + +These represent a certificate authority from which signed x509 certificates can +be obtained, such as Let's Encrypt, or your own signing key pair stored in a +Kubernetes Secret resource. They are referenced by Certificate resources in +order to request certificates from them. + +For example, users often create ``letsencrypt-staging`` and +``letsencrypt-prod`` ClusterIssuers if they operate a single-tenant environment +and want to expose a cluster-wide mechanism for obtaining TLS certificates +from `Let's Encrypt`_. + +More information on configuring different Issuer types can be found in the +:doc:`tasks section `. + +Debugging installation issues +============================= + +If you have any issues with your installation, please refer to the +:doc:`troubleshooting guide <./troubleshooting>`. + +.. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ +.. _`Helm chart README`: https://github.com/helm/charts/blob/master/stable/cert-manager/README.md +.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 +.. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/ +.. _`Helm`: https://helm.sh/ +.. _`cluster-admin privileges bound to the Tiller pod`: https://github.com/helm/helm/blob/240e539cec44e2b746b3541529d41f4ba01e77df/docs/rbac.md#Example-Service-account-with-cluster-admin-role +.. _`helm RBAC docs`: https://github.com/helm/helm/blob/master/docs/rbac.md +.. _`installing helm docs`: https://github.com/kubernetes/helm/blob/master/docs/install.md +.. _Tiller: https://github.com/helm/helm diff --git a/docs/getting-started/troubleshooting.rst b/docs/getting-started/troubleshooting.rst new file mode 100644 index 000000000..4e20019cf --- /dev/null +++ b/docs/getting-started/troubleshooting.rst @@ -0,0 +1,42 @@ +============================ +Troubleshooting installation +============================ + +During installation, a number of operations including a Kubernetes 'Job' will +be created. +These resources **must** complete successfully in order for cert-manager to +run. + +To verify your installation has completed, you should check the Status of all +pods in your cert-manager namespace: + +.. code-block:: shell + + # Get all pods, including Completed and Errored pods + kubectl get pods --show-all --namespace cert-manager + NAME READY STATUS RESTARTS AGE + cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m + cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m + cert-manager-webhook-ca-sync-1547942400-g6985 0/1 Completed 0 3m + +If the 'ca-sync' pod above does not show Completed, you may need to re-start +the Job using the ``kubectl create job`` command: + +.. code-block:: shell + + # Find the name of the CronJob resource + kubectl get cronjob --namespace cert-manager + NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE + cert-manager-webhook-ca-sync @weekly False 0 3m + + # Trigger the CronJob to run immediately + kubectl create job \ + --namespace cert-manager \ + --from cronjob/cert-manager-webhook-ca-sync \ + ca-sync-manually-triggered + +This will trigger the cert-manager job to run again. + +.. note:: + If the job continues to fail, please read the :doc:`Webhook <./webhook>` + docs for additional information. diff --git a/docs/getting-started/webhook.rst b/docs/getting-started/webhook.rst new file mode 100644 index 000000000..f72bf72c5 --- /dev/null +++ b/docs/getting-started/webhook.rst @@ -0,0 +1,186 @@ +================= +Webhook component +================= + +In order to provide advanced resource validation, cert-manager includes a +ValidatingWebhookConfiguration which is deployed into the cluster as its own +pod. + +This feature requires Kubernetes v1.9 or greater. If you disable the webhook +component, cert-manager will still perform the same resource validation however +will not reject 'create' events when submitting resources to the API server. +This can still cause issues if invalid resources are submitted however, so it +is advised to keep the webhook enabled. + +The webhook component is enabled by default, but can be disabled. + +How it works +============ + +This sections walks through how the resource validation webhook is configured +and explains the process required for it to provision. + +The webhook is a ValidatingWebhookConfiguration_ resource combined with an +extra pod that is deployed alongside the cert-manager-controller. + +The ValidatingWebhookConfiguration instructs the Kubernetes apiserver to +POST the contents of any Create or Update operations performed on cert-manager +resource types in order to validate that they are setting valid configurations. + +This allows us to ensure mis-configurations are caught early on and communicated +to you. + +In order for this to work, the webhook requires a TLS certificate that the +apiserver is configured to trust. + +The cert-manager deployment manifests define two Issuer resources, and two +Certificate resources: + +* issuer/cert-manager-webhook-selfsign - A self signing Issuer that is used + to issue a self signed root CA certificate. +* certificate/cert-manager-webhook-ca - A self-signed root CA certificate + which is used to sign certificates for the webhook pod. +* issue/cert-manager-webhook-ca - A CA Issuer that is used to issue + certificates used by the webhook pod to serve with. +* certificate/cert-manager-webhook-webhook-tls - A TLS certificate issued by the + root CA above, served by the webhook. + +You can check the status of these resources to ensure they're functioning +correctly by running: + +.. code-block:: shell + + kubectl get issuer --namespace cert-manager + NAME AGE + cert-manager-webhook-ca 10m + cert-manager-webhook-selfsign 10m + + kubectl get certificate -o wide --namespace cert-manager + NAME READY SECRET ISSUER STATUS AGE + cert-manager-webhook-ca True cert-manager-webhook-ca cert-manager-webhook-selfsign Certificate is up to date and has not expired 10m + cert-manager-webhook-webhook-tls True cert-manager-webhook-webhook-tls cert-manager-webhook-ca Certificate is up to date and has not expired 10m + +If the certificates or issuer are not Ready or you cannot see them, you should +check the :doc:`troubleshooting <./troubleshooting>` guide for help. + +.. note:: + If you are running Kubernetes v1.10 or earlier, you may need to run + ``kubectl describe`` instead of ``kubectl get`` as the + 'additionalPrinterColumns' functionality only moved to beta in v1.11. + +ca-sync CronJob +--------------- + +In order to configure the Kubernetes apiserver with the generated root CA that +the webhook uses, we also deploy a CronJob resource: + +.. code-block:: shell + + kubectl get cronjob + NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE + cert-manager-webhook-ca-sync @weekly False 0 2d21h 20d + +As you can see, this job runs weekly. + +It copies across the CA defined in the 'cert-manager-webhook-ca' secret +generated above to the ``spec.caBundle`` field on the +``v1beta1.admission.certmanager.k8s.io`` APIService resource. +It also sets the ``webhooks.clientConfig.caBundle`` field on the +``cert-manager-webhook`` ValidatingWebhookConfiguration resource to that of +your Kubernetes API server. + +If the ca-sync job fails more than 20 times, it will not be retried until the +next time the CronJob is scheduled. This may occur when you first setup +cert-manager if you have run into issues during installation. + +You can manually trigger the ca-sync CronJob to run immediately using: + +.. code-block:: shell + + kubectl create job ca-sync-manually-triggered --from cronjob/cert-manager-webhook-ca-sync + +If you have run the ``create job`` command above multiple times, you will need +to choose a new name or delete the old job resource else you will receive an +'AlreadyExists' error. + +.. note:: + + The --from flag was only introduced in kubectl v1.11 + +The code for this component can be found at `munnerz/apiextensions-ca-helper`_ + +Known issues +------------ + +This section contains known issues with the webhook component. + +If you're having problems, or receiving errors when creating cert-manager +resources, please read through this section for help. + +Disabling validation on the cert-manager namespace +-------------------------------------------------- + +If you've installed cert-manager with custom manifests, or have performed an +upgrade from an earlier version, it's important to make sure that the namespace +that the webhook is running in has an additional label applied to it in order +to disable resource validation on the namespace that the webhook runs in. + +If this step is not completed, cert-manager will not be able to provision +certificates for the webhook correctly, causing a chicken-egg situation. + +To apply the label, run: + +.. code-block:: shell + + kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true + +You may need to wait a little while before cert-manager retries issuing the +certificates if they have been failing for a while due to cert-manager's built +in back-offs. + +Running on Amazon EKS +--------------------- + +Unfortunately, Amazon EKS does not configure the options needed on the +Kubernetes apiserver that are required for ValidatingWebhookConfiguration +resources to work. + +This means there is currently no option other than disabling the webhook until +this issue is resolved by Amazon. + +You can read how to `disable the webhook component`_ below. + +Running on private GKE clusters +------------------------------- + +When Google configure the control plane for private clusters, they +automatically configure VPC peering between your Kubernetes cluster's network +and a separate Google managed project. + +In order to restrict what Google are able to access within your cluster, the +firewall rules configured restrict access to your Kubernetes pods. + +This means that in order to use the webhook component with a GKE private +cluster, you must configure an additional firewall rule to allow the GKE +control plane access to your webhook pod. + +You can read more information on how to add firewall rules for the GKE control +plane nodes in the `GKE docs`_. + +Alternatively, you can read how to `disable the webhook component`_ below. + +.. todo:: add an example command for how to do this here & explain any security + implications + +Disable the webhook component +============================== + +With Helm +--------- + +With static manifests +--------------------- + +.. _`munnerz/apiextensions-ca-helper`: https://github.com/munnerz/apiextensions-ca-helper +.. _`deploy directory`: https://github.com/jetstack/cert-manager/blob/release-0.5/contrib/manifests/cert-manager +.. _`GKE docs`: https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules diff --git a/docs/index.rst b/docs/index.rst index f302d9eec..b5bc63ce1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,13 +24,13 @@ This is the full technical documentation for the project, and should be used as a source of references when seeking help with the project. .. toctree:: - :maxdepth: 5 + :maxdepth: 2 :titlesonly: :caption: Contents: getting-started/index + tasks/index tutorials/index - admin/index reference/index devel/index diff --git a/docs/reference/certificates.rst b/docs/reference/certificates.rst index 0e5f4974f..fddcf3591 100644 --- a/docs/reference/certificates.rst +++ b/docs/reference/certificates.rst @@ -50,12 +50,6 @@ non-namespaced. .. _`Subject Alternative Names`: https://en.wikipedia.org/wiki/Subject_Alternative_Name -.. toctree:: - :maxdepth: 1 - :hidden: - - certificates/issuer-specific-config/acme - *************************************** Certificate Duration and Renewal Window *************************************** diff --git a/docs/reference/certificates/issuer-specific-config/acme.rst b/docs/reference/certificates/issuer-specific-config/acme.rst deleted file mode 100644 index 012200a2d..000000000 --- a/docs/reference/certificates/issuer-specific-config/acme.rst +++ /dev/null @@ -1,15 +0,0 @@ -================================ -ACME Specific Certificate Config -================================ - -When creating Certificate resources that reference an ACME Issuer, there are -a number of extra configuration parameters that can be specified to influence -how the Certificate will be obtained (notably, configuring the ACME challenge -type). - -.. todo:: - Extend this document with information on configuring the ACME stanza on - Certificate resources. - -.. todo:: - Make this document more prominent diff --git a/docs/reference/issuers.rst b/docs/reference/issuers.rst index 63208f457..90eeddb4a 100644 --- a/docs/reference/issuers.rst +++ b/docs/reference/issuers.rst @@ -34,8 +34,8 @@ An example of an Issuer type is ACME. A simple ACME issuer could be defined as: This is the simplest of ACME issuers - it specifies no DNS-01 challenge providers. HTTP-01 validation can be performed through using Ingress resources by enabling the HTTP-01 challenge mechanism (with the ``http01: {}`` -field). More information on configuring ACME Issuers can be found :doc:`here `. - +field). +More information on configuring ACME Issuers can be found :doc:`here `. *********** Namespacing @@ -117,31 +117,23 @@ Supported Issuer types cert-manager has been designed to support pluggable Issuer backends. The currently supported Issuer types are: -+-----------------------------------------------+----------------------------------------------------------------------+ -| Name | Description | -+===============================================+======================================================================+ -| :doc:`ACME ` | Supports obtaining certificates from an ACME server, validating with | -| | HTTP01 or DNS01 | -+-----------------------------------------------+----------------------------------------------------------------------+ -| :doc:`CA ` | Supports issuing certificates using a simple signing keypair, stored | -| | in a Secret in the Kubernetes API server | -+-----------------------------------------------+----------------------------------------------------------------------+ -| :doc:`Vault ` | Supports issuing certificates using HashiCorp Vault. | -+-----------------------------------------------+----------------------------------------------------------------------+ -| :doc:`Self signed ` | Supports issuing self signed certificates | -+-----------------------------------------------+----------------------------------------------------------------------+ - ++-----------------------------------------------------+----------------------------------------------------------------------+ +| Name | Description | ++=====================================================+======================================================================+ +| :doc:`ACME ` | Supports obtaining certificates from an ACME server, validating with | +| | HTTP01 or DNS01 | ++-----------------------------------------------------+----------------------------------------------------------------------+ +| :doc:`CA ` | Supports issuing certificates using a simple signing keypair, stored | +| | in a Secret in the Kubernetes API server | ++-----------------------------------------------------+----------------------------------------------------------------------+ +| :doc:`Vault ` | Supports issuing certificates using HashiCorp Vault. | ++-----------------------------------------------------+----------------------------------------------------------------------+ +| :doc:`Self signed ` | Supports issuing self signed certificates | ++-----------------------------------------------------+----------------------------------------------------------------------+ Each Issuer resource is of one, and only one type. The type of an Issuer is inferred by which field it specifies in its spec, such as ``spec.acme`` for the ACME issuer, or ``spec.ca`` for the CA based issuer. -.. toctree:: - - issuers/acme/index - issuers/ca/index - issuers/vault/index - issuers/selfsigned/index - .. _`Let's Encrypt`: https://letsencrypt.org .. _kube2iam: https://github.com/jtblin/kube2iam diff --git a/docs/reference/issuers/acme/index.rst b/docs/reference/issuers/acme/index.rst deleted file mode 100644 index 290e491ed..000000000 --- a/docs/reference/issuers/acme/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -================== -ACME Configuration -================== - -In order to use the ACME provider, there are a number of required fields. -For your ACME issuer to support the various ACME challenge mechanisms, you may -need to provide some additional configuration on your resource, such as -configuring credentials for a DNS provider. - -.. toctree:: - :maxdepth: 1 - - http01 - dns01/index diff --git a/docs/reference/issuers/ca/index.rst b/docs/reference/issuers/ca/index.rst deleted file mode 100644 index caec8bc54..000000000 --- a/docs/reference/issuers/ca/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -================ -CA Configuration -================ - -.. toctree:: - :maxdepth: 1 - -CA Issuers issue certificates signed from a X509 signing keypair, stored in a -secret in the Kubernetes API server. - -You can find user guides on using the CA Issuer in the :doc:`CA Issuer tutorials -section `. - -.. todo:: - Expand out CA Issuer reference documentation \ No newline at end of file diff --git a/docs/reference/issuers/vault/index.rst b/docs/reference/issuers/vault/index.rst deleted file mode 100644 index c4291b241..000000000 --- a/docs/reference/issuers/vault/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -=================== -Vault Configuration -=================== - -.. toctree:: - :maxdepth: 1 - -Vault Issuers issue certificates from `Hashicorp's -Vault `__. - -You can find user guides on using the Vault Issuer in the :doc:`Vault Issuer tutorials -section `. - -.. todo:: - Expand out Vault Issuer reference documentation diff --git a/docs/reference/issuers/acme/dns01/acme-dns.rst b/docs/tasks/acme/configuring-dns01/acme-dns.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/acme-dns.rst rename to docs/tasks/acme/configuring-dns01/acme-dns.rst diff --git a/docs/reference/issuers/acme/dns01/akamai.rst b/docs/tasks/acme/configuring-dns01/akamai.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/akamai.rst rename to docs/tasks/acme/configuring-dns01/akamai.rst diff --git a/docs/reference/issuers/acme/dns01/azuredns.rst b/docs/tasks/acme/configuring-dns01/azuredns.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/azuredns.rst rename to docs/tasks/acme/configuring-dns01/azuredns.rst diff --git a/docs/reference/issuers/acme/dns01/cloudflare.rst b/docs/tasks/acme/configuring-dns01/cloudflare.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/cloudflare.rst rename to docs/tasks/acme/configuring-dns01/cloudflare.rst diff --git a/docs/reference/issuers/acme/dns01/digitalocean.rst b/docs/tasks/acme/configuring-dns01/digitalocean.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/digitalocean.rst rename to docs/tasks/acme/configuring-dns01/digitalocean.rst diff --git a/docs/reference/issuers/acme/dns01/google.rst b/docs/tasks/acme/configuring-dns01/google.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/google.rst rename to docs/tasks/acme/configuring-dns01/google.rst diff --git a/docs/reference/issuers/acme/dns01/index.rst b/docs/tasks/acme/configuring-dns01/index.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/index.rst rename to docs/tasks/acme/configuring-dns01/index.rst diff --git a/docs/reference/issuers/acme/dns01/route53.rst b/docs/tasks/acme/configuring-dns01/route53.rst similarity index 100% rename from docs/reference/issuers/acme/dns01/route53.rst rename to docs/tasks/acme/configuring-dns01/route53.rst diff --git a/docs/reference/issuers/acme/http01.rst b/docs/tasks/acme/configuring-http01.rst similarity index 64% rename from docs/reference/issuers/acme/http01.rst rename to docs/tasks/acme/configuring-http01.rst index 93eece47f..7624fd678 100644 --- a/docs/reference/issuers/acme/http01.rst +++ b/docs/tasks/acme/configuring-http01.rst @@ -25,8 +25,32 @@ using Ingress resources name: example-issuer-account-key http01: {} +.. note:: + Let's Encrypt does not support issuing wildcard certificates with HTTP-01 challenges. + To issue wildcard certificates, you must use the DNS-01 challenge. -In rare cases it might be not possible/desired to use NodePort as type for the http01 challenge response service, e.g. because of Kubernetes limit restrictions. To define which Kubernetes service type to use during challenge response specify the following http01 config +How HTTP01 validations work +=========================== + +.. todo:: + Write a full description of how HTTP01 challenge validation works + +Extra options +============= + +The HTTP01 Issuer supports a number of additional options. +For full details on the range of options available, read the +`reference documentation`_. + +.. _`reference documentation`: https://cert-manager.readthedocs.io/en/latest/reference/api-docs/index.html#acmeissuerhttp01config-v1alpha1 + +servicePort +----------- + +In rare cases it might be not possible/desired to use NodePort as type for the +http01 challenge response service, e.g. because of Kubernetes limit +restrictions. To define which Kubernetes service type to use during challenge +response specify the following http01 config: .. code-block:: yaml @@ -34,11 +58,5 @@ In rare cases it might be not possible/desired to use NodePort as type for the h # Valid values are ClusterIP and NodePort serviceType: ClusterIP -By default type NodePort will be used when you don't set http01 or when you set serviceType to an empty string. Normally there's no need to change this. - -.. note:: - Let's Encrypt does not support issuing wildcard certificates with HTTP-01 challenges. - To issue wildcard certificates, you must use the DNS-01 challenge. - -.. todo:: - Write a full description of how HTTP01 challenge validation works +By default type NodePort will be used when you don't set http01 or when you set +serviceType to an empty string. Normally there's no need to change this. diff --git a/docs/tasks/acme/debugging-failing-orders.rst b/docs/tasks/acme/debugging-failing-orders.rst new file mode 100644 index 000000000..3b41a1338 --- /dev/null +++ b/docs/tasks/acme/debugging-failing-orders.rst @@ -0,0 +1,3 @@ +======================== +Debugging failing Orders +======================== diff --git a/docs/tasks/acme/index.rst b/docs/tasks/acme/index.rst new file mode 100644 index 000000000..8d8e4ed6e --- /dev/null +++ b/docs/tasks/acme/index.rst @@ -0,0 +1,16 @@ +=================== +ACME specific tasks +=================== + +In order to use the ACME provider, there are a number of required fields. +For your ACME issuer to support the various ACME challenge mechanisms, you may +need to provide some additional configuration on your resource, such as +configuring credentials for a DNS provider or enabling HTTP01 validation. + +.. toctree:: + :maxdepth: 2 + + issuing-certificates + configuring-dns01/index + configuring-http01 + debugging-failing-orders diff --git a/docs/tasks/acme/issuing-certificates.rst b/docs/tasks/acme/issuing-certificates.rst new file mode 100644 index 000000000..127199052 --- /dev/null +++ b/docs/tasks/acme/issuing-certificates.rst @@ -0,0 +1,16 @@ +=============================== +Issuing Certificates using ACME +=============================== + +ACME certificates currently require additional configuration on the Certificate +resource that you create in order to determine how to solve the +`ACME challenges`_ that the ACME protocol requires. + +In future releases of cert-manager, this configuration is likely to move off of +the Certificate resource and onto the Issuer resource in order to create a +better separation of concerns. More info can be found on issue `#XXX`_. + +.. todo:: write guide explaining how to configure certificate.spec.acme + +.. _`ACME challenges`: +.. _`#XXX`: diff --git a/docs/tasks/index.rst b/docs/tasks/index.rst new file mode 100644 index 000000000..877dd9d5c --- /dev/null +++ b/docs/tasks/index.rst @@ -0,0 +1,15 @@ +===== +Tasks +===== + +This section contains guides on using specific features of cert-manager, such +as configuring different Issuer types and any special settings that you may +want to configure. + +.. toctree:: + :maxdepth: 2 + + issuing-certificates + issuers/index + acme/index + upgrading/index diff --git a/docs/reference/issuers/vault/OWNERS b/docs/tasks/issuers/OWNERS similarity index 100% rename from docs/reference/issuers/vault/OWNERS rename to docs/tasks/issuers/OWNERS diff --git a/docs/tasks/issuers/index.rst b/docs/tasks/issuers/index.rst new file mode 100644 index 000000000..fd9c66c33 --- /dev/null +++ b/docs/tasks/issuers/index.rst @@ -0,0 +1,74 @@ +================== +Setting up Issuers +================== + +Before you can begin issuing certificates, you must configure at least one +Issuer or ClusterIssuer resource in your cluster. + +These represent a certificate authority from which signed x509 certificates can +be obtained, such as Let's Encrypt, or your own signing key pair stored in a +Kubernetes Secret resource. They are referenced by Certificate resources in +order to request certificates from them. + +An :doc:`Issuer ` is scoped to a single namespace, and can +only fulfill :doc:`Certificate ` resources within its +own namespace. This is useful in a multi-tenant environment where multiple +teams or independent parties operate within a single cluster. + +On the other hand, a :doc:`ClusterIssuer ` is a +cluster wide version of an :doc:`Issuer `. It is able to be +referenced by :doc:`Certificate ` resources in any +namespace. + +Users often create ``letsencrypt-staging`` and ``letsencrypt-prod`` +:doc:`ClusterIssuers ` if they operate a +single-tenant environment and want to expose a cluster-wide mechanism for +obtaining TLS certificates from `Let's Encrypt`_. + +Supported issuer types +====================== + +cert-manager supports a number of different issuer backends, each with their +own different types of configuration. + +Please follow one of the below linked guides for to learn how to set up +the issuer types you require: + +* :doc:`CA <./setup-ca>` - issue certificates signed by a X509 signing keypair, + stored in a Secret in the Kubernetes API server. +* :doc:`Self signed <./setup-selfsigned>` - +* :doc:`ACME <./setup-acme>` - +* :doc:`Vault <./setup-vault>`- + +Additional information +====================== + +There are a few key things to know about Issuers, but for full information +you can refer to the :doc:`Issuer reference docs `. + +Difference between Issuers and ClusterIssuers +--------------------------------------------- + +ClusterIssuers are a resource type similar to :doc:`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. + +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 resource spec is identical, and you should set the +``certificate.spec.issuerRef.kind`` field to ClusterIssuer when creating your +Certificate resources. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + setup-acme + setup-ca + setup-selfsigned + setup-vault + +.. _`Let's Encrypt`: https://letsencrypt.org diff --git a/docs/tasks/issuers/setup-acme.rst b/docs/tasks/issuers/setup-acme.rst new file mode 100644 index 000000000..eda3651eb --- /dev/null +++ b/docs/tasks/issuers/setup-acme.rst @@ -0,0 +1,3 @@ +======================= +Setting up ACME Issuers +======================= diff --git a/docs/tutorials/ca/creating-ca-issuer.rst b/docs/tasks/issuers/setup-ca.rst similarity index 98% rename from docs/tutorials/ca/creating-ca-issuer.rst rename to docs/tasks/issuers/setup-ca.rst index 37486c523..32a70d77f 100644 --- a/docs/tutorials/ca/creating-ca-issuer.rst +++ b/docs/tasks/issuers/setup-ca.rst @@ -1,6 +1,7 @@ -================================= -Creating a simple CA based issuer -================================= +===================== +Setting up CA Issuers +===================== + cert-manager can be used to obtain certificates using an arbitrary signing key pair stored in a Kubernetes Secret resource. diff --git a/docs/reference/issuers/selfsigned/index.rst b/docs/tasks/issuers/setup-selfsigned.rst similarity index 73% rename from docs/reference/issuers/selfsigned/index.rst rename to docs/tasks/issuers/setup-selfsigned.rst index 2bc8e9a46..8c9400dcb 100644 --- a/docs/reference/issuers/selfsigned/index.rst +++ b/docs/tasks/issuers/setup-selfsigned.rst @@ -1,6 +1,6 @@ -========================= -Self-signed Configuration -========================= +=============================== +Setting up self signing Issuers +=============================== .. toctree:: :maxdepth: 1 @@ -8,9 +8,7 @@ Self-signed Configuration Self signed Issuers will issue self signed certificates. This is useful when building PKI within Kubernetes, or as a means to generate a -root CA for use with the :doc:`CA Issuer ` once -cert-manager supports setting the ``isCA`` flag on Certificate resources -(`#85`_). +root CA for use with the :doc:`CA Issuer <./setup-ca>`. A self-signed Issuer contains no additional configuration fields, and can be created with a resource like so: @@ -39,10 +37,8 @@ referencing the newly created Issuer in your ``issuerRef``: name: example-crt spec: secretName: my-selfsigned-cert - dnsNames: - - example.com + commonName: "my-selfsigned-root-ca" + isCA: true issuerRef: name: selfsigning-issuer kind: ClusterIssuer - -.. _`#85`: https://github.com/jetstack/cert-manager/issues/85 \ No newline at end of file diff --git a/docs/tutorials/vault/creating-vault-issuers.rst b/docs/tasks/issuers/setup-vault.rst similarity index 98% rename from docs/tutorials/vault/creating-vault-issuers.rst rename to docs/tasks/issuers/setup-vault.rst index a88d874c3..614b879af 100644 --- a/docs/tutorials/vault/creating-vault-issuers.rst +++ b/docs/tasks/issuers/setup-vault.rst @@ -1,5 +1,6 @@ -Vault Installation -================== +======================== +Setting up Vault Issuers +======================== Installing Vault ---------------- diff --git a/docs/tasks/issuing-certificates.rst b/docs/tasks/issuing-certificates.rst new file mode 100644 index 000000000..7a640b445 --- /dev/null +++ b/docs/tasks/issuing-certificates.rst @@ -0,0 +1,15 @@ +==================== +Issuing Certificates +==================== + +The Certificate resource type is used to request certificates from different +Issuers. + +In order to issue any certificates, you'll need to configure an Issuer resource +first. + +If you have not configured any issuers yet, you should read the +:doc:`Setting up Issuers <./issuers/index>` guide. + +.. todo:: write a general purpose guide on issuing certificates +.. todo:: link to the extra config required on ACME certificates diff --git a/docs/admin/upgrading/index.rst b/docs/tasks/upgrading/index.rst similarity index 89% rename from docs/admin/upgrading/index.rst rename to docs/tasks/upgrading/index.rst index 18e24d7b8..a7ddf1faf 100644 --- a/docs/admin/upgrading/index.rst +++ b/docs/tasks/upgrading/index.rst @@ -26,18 +26,18 @@ version number you want to install: # Install the cert-manager CustomResourceDefinition resources before # upgrading the Helm chart - $ kubectl apply \ + kubectl apply \ -f https://raw.githubusercontent.com/jetstack/cert-manager//deploy/manifests/00-crds.yaml # Ensure the local Helm chart repository cache is up to date - $ helm repo update + helm repo update # If you are upgrading from v0.5 or below, you should manually add this # label to your cert-manager namespace to ensure the `webhook component`_ # can provision correctly. - $ kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true + kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - $ helm upgrade --version stable/cert-manager + helm upgrade --version stable/cert-manager This will upgrade you to the latest version of cert-manager, as listed in the `official Helm charts repository`_. @@ -64,9 +64,9 @@ version number you want to install: # If you are upgrading from v0.5 or below, you should manually add this # label to your cert-manager namespace to ensure the `webhook component`_ # can provision correctly. - $ kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true + kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - $ kubectl apply \ + kubectl apply \ -f https://raw.githubusercontent.com/jetstack/cert-manager//deploy/manifests/cert-manager.yaml .. note:: @@ -86,5 +86,5 @@ version number you want to install: upgrading-0.5-0.6 .. _`official Helm charts repository`: https://github.com/helm/charts -.. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/master/contrib/manifests/cert-manager +.. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/release-0.6/deploy/manifests .. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 diff --git a/docs/admin/upgrading/upgrading-0.2-0.3.rst b/docs/tasks/upgrading/upgrading-0.2-0.3.rst similarity index 100% rename from docs/admin/upgrading/upgrading-0.2-0.3.rst rename to docs/tasks/upgrading/upgrading-0.2-0.3.rst diff --git a/docs/admin/upgrading/upgrading-0.3-0.4.rst b/docs/tasks/upgrading/upgrading-0.3-0.4.rst similarity index 100% rename from docs/admin/upgrading/upgrading-0.3-0.4.rst rename to docs/tasks/upgrading/upgrading-0.3-0.4.rst diff --git a/docs/admin/upgrading/upgrading-0.4-0.5.rst b/docs/tasks/upgrading/upgrading-0.4-0.5.rst similarity index 100% rename from docs/admin/upgrading/upgrading-0.4-0.5.rst rename to docs/tasks/upgrading/upgrading-0.4-0.5.rst diff --git a/docs/admin/upgrading/upgrading-0.5-0.6.rst b/docs/tasks/upgrading/upgrading-0.5-0.6.rst similarity index 94% rename from docs/admin/upgrading/upgrading-0.5-0.6.rst rename to docs/tasks/upgrading/upgrading-0.5-0.6.rst index 010f54bcf..ec1ed2625 100644 --- a/docs/admin/upgrading/upgrading-0.5-0.6.rst +++ b/docs/tasks/upgrading/upgrading-0.5-0.6.rst @@ -25,7 +25,7 @@ Due to issues with the way Helm handles CRD resources in Helm charts, we have now moved the installation of these resources into a separate YAML manifest that must be installed with ``kubectl apply`` before upgrading the chart. -You can follow the :doc:`regular upgrade guide ` as +You can follow the :doc:`regular upgrade guide <./index>` as usual in order to upgrade from v0.5 to v0.6. Upgrading with static manifests @@ -38,7 +38,7 @@ We now also no longer ship different manifests for different configurations, in favour of a single ``cert-manager.yaml`` file which should work for all Kubernetes clusters from Kubernetes v1.9 onwards. -You can follow the :doc:`regular upgrade guide ` as +You can follow the :doc:`regular upgrade guide <./index>` as usual in order to upgrade from v0.5 to v0.6. Upgrading from older versions using Helm @@ -73,7 +73,7 @@ Before upgrading you will need to: clusterissuers.certmanager.k8s.io 3. Perform a fresh install (as per the - :doc:`installation guide `): + :doc:`installation guide `): .. code-block:: shell diff --git a/docs/tutorials/acme/dns-validation.rst b/docs/tutorials/acme/dns-validation.rst index e903514a7..23ff6863c 100644 --- a/docs/tutorials/acme/dns-validation.rst +++ b/docs/tutorials/acme/dns-validation.rst @@ -146,7 +146,7 @@ be cleaned up. .. note:: It is your responsibility to ensure the selected provider is authoritative for - your domain. + your domain. After creating the above Certificate, we can check whether it has been obtained successfully using ``kubectl describe``: diff --git a/docs/tutorials/acme/http-validation.rst b/docs/tutorials/acme/http-validation.rst index e026ec1c1..4ce738f44 100644 --- a/docs/tutorials/acme/http-validation.rst +++ b/docs/tutorials/acme/http-validation.rst @@ -2,10 +2,6 @@ Issuing an ACME certificate using HTTP validation ================================================= -.. todo:: - This guide needs rewriting to be clearer, splitting into sections and - potentially rewriting altogether. - cert-manager can be used to obtain certificates from a CA using the ACME_ protocol. The ACME protocol supports various challenge mechanisms which are used to prove ownership of a domain so that a valid certificate can be issued for that domain. @@ -163,7 +159,7 @@ You should see a base64 encoded signed TLS key pair. Once our certificate has been obtained, cert-manager will periodically check its validity and attempt to renew it if it gets close to expiry. cert-manager considers certificates to be close to expiry when the 'Not After' -field on the certificate is less than the current time plus 30 days. +field on the certificate is less than the current time plus 30 days. .. _ACME: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment .. _`staging environment`: https://letsencrypt.org/docs/staging-environment/ diff --git a/docs/tutorials/acme/index.rst b/docs/tutorials/acme/index.rst index eb44f80a3..caaaa84d1 100644 --- a/docs/tutorials/acme/index.rst +++ b/docs/tutorials/acme/index.rst @@ -2,14 +2,13 @@ ACME Issuer Tutorials ===================== -This section contains tutorials that specifically utilise the ACME Issuer. They -are designed to help teach the underlying concepts of cert-manager whilst also -helping 'quickstart' common use-cases for the project. +This sections contains tutorials relating to the ACME issuer. + .. toctree:: :maxdepth: 1 - migrating-from-kube-lego - securing-nginx-ingress-with-letsencrypt + quick-start/index dns-validation http-validation + migrating-from-kube-lego diff --git a/docs/tutorials/quick-start/example/deployment.yaml b/docs/tutorials/acme/quick-start/example/deployment.yaml similarity index 100% rename from docs/tutorials/quick-start/example/deployment.yaml rename to docs/tutorials/acme/quick-start/example/deployment.yaml diff --git a/docs/tutorials/quick-start/example/ingress-tls-final.yaml b/docs/tutorials/acme/quick-start/example/ingress-tls-final.yaml similarity index 100% rename from docs/tutorials/quick-start/example/ingress-tls-final.yaml rename to docs/tutorials/acme/quick-start/example/ingress-tls-final.yaml diff --git a/docs/tutorials/quick-start/example/ingress-tls.yaml b/docs/tutorials/acme/quick-start/example/ingress-tls.yaml similarity index 100% rename from docs/tutorials/quick-start/example/ingress-tls.yaml rename to docs/tutorials/acme/quick-start/example/ingress-tls.yaml diff --git a/docs/tutorials/quick-start/example/ingress.yaml b/docs/tutorials/acme/quick-start/example/ingress.yaml similarity index 100% rename from docs/tutorials/quick-start/example/ingress.yaml rename to docs/tutorials/acme/quick-start/example/ingress.yaml diff --git a/docs/tutorials/quick-start/example/production-issuer.yaml b/docs/tutorials/acme/quick-start/example/production-issuer.yaml similarity index 100% rename from docs/tutorials/quick-start/example/production-issuer.yaml rename to docs/tutorials/acme/quick-start/example/production-issuer.yaml diff --git a/docs/tutorials/quick-start/example/service.yaml b/docs/tutorials/acme/quick-start/example/service.yaml similarity index 100% rename from docs/tutorials/quick-start/example/service.yaml rename to docs/tutorials/acme/quick-start/example/service.yaml diff --git a/docs/tutorials/quick-start/example/staging-issuer.yaml b/docs/tutorials/acme/quick-start/example/staging-issuer.yaml similarity index 100% rename from docs/tutorials/quick-start/example/staging-issuer.yaml rename to docs/tutorials/acme/quick-start/example/staging-issuer.yaml diff --git a/docs/tutorials/quick-start/index.rst b/docs/tutorials/acme/quick-start/index.rst similarity index 98% rename from docs/tutorials/quick-start/index.rst rename to docs/tutorials/acme/quick-start/index.rst index ea2580c56..546ab7f5f 100644 --- a/docs/tutorials/quick-start/index.rst +++ b/docs/tutorials/acme/quick-start/index.rst @@ -20,7 +20,7 @@ For example, on macOS: $ brew install kubernetes-helm .. _`Helm`: https://helm.sh -.. _`Helm installation instructions`: https://github.com/kubernetes/helm/blob/master/docs/install.md +.. _`Helm installation instructions`: https://github.com/helm/helm/blob/master/docs/install.md Step 1 - Installer Tiller ========================= @@ -236,8 +236,8 @@ sample deployment and an associated service: .. literalinclude:: example/service.yaml :language: yaml -.. _`deployment.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/quick-start/example/deployment.yaml -.. _`service.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/quick-start/example/service.yaml +.. _`deployment.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/acme/quick-start/example/deployment.yaml +.. _`service.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/acme/quick-start/example/service.yaml .. _`kuard`: https://github.com/kubernetes-up-and-running/kuard You can create download and reference these files locally, or you can @@ -247,10 +247,10 @@ you may use the commands: .. code-block:: shell - $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/quick-start/example/deployment.yaml + $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/acme/quick-start/example/deployment.yaml deployment.extensions "kuard" created - $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/quick-start/example/service.yaml + $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/acme/quick-start/example/service.yaml service "kuard" created An `ingress resource`_ is what Kubernetes uses to expose this example service @@ -265,14 +265,14 @@ A sample ingress you can start with is: .. literalinclude:: example/ingress.yaml :language: yaml -.. _`ingress.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/quick-start/example/ingress.yaml +.. _`ingress.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/acme/quick-start/example/ingress.yaml .. _`ingress resource`: https://kubernetes.io/docs/concepts/services-networking/ingress/ You can download the sample manifest from github, edit it, and submit the manifest to Kubernetes with the command: .. code-block:: shell - $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/quick-start/example/ingress.yaml + $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/master/docs/tutorials/acme/quick-start/example/ingress.yaml # edit the file in your editor, and once it is saved: ingress.extensions "kuard" created @@ -511,7 +511,7 @@ will need to update this example and add in your own email address. issuer.certmanager.k8s.io "letsencrypt-prod" created Both of these issuers are configured to use the -:doc:`HTTP01 ` challenge provider. +:doc:`HTTP01 ` challenge provider. Check on the status of the issuer after you create it: diff --git a/docs/tutorials/acme/securing-nginx-ingress-with-letsencrypt.rst b/docs/tutorials/acme/securing-nginx-ingress-with-letsencrypt.rst deleted file mode 100644 index 7ec455690..000000000 --- a/docs/tutorials/acme/securing-nginx-ingress-with-letsencrypt.rst +++ /dev/null @@ -1,22 +0,0 @@ -========================================= -Securing nginx-ingress with Let's Encrypt -========================================= - -This guide talks you through securing a website exposed with `nginx-ingress`_ -using a Certificate issued by `Let's Encrypt`_. - -Prerequisites -============= - -First, you should make sure you have properly configured and deployed -`nginx-ingress`_ and at least one service is available **publicly** via the -ingress controllers external IP address. - -There's official deployment documentation in the `official repository`__, or you -can alternatively use Helm_ to deploy and manage your nginx-ingress_ -installation. - -.. __: -.. _nginx-ingress: https://github.com/kubernetes/ingress-nginx -.. _`Let's Encrypt`: https://letsencrypt.org -.. _Helm: https://helm.sh diff --git a/docs/tutorials/ca/index.rst b/docs/tutorials/ca/index.rst deleted file mode 100644 index fae7f12cc..000000000 --- a/docs/tutorials/ca/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -=================== -CA Issuer Tutorials -=================== - -This section contains tutorials that specifically utilise the CA Issuer. They -are designed to help teach the underlying concepts of cert-manager whilst also -helping 'quickstart' common use-cases for the project. - -.. toctree:: - :maxdepth: 1 - - creating-ca-issuer diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index ef3b6d07b..1b5a0cac6 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -2,13 +2,13 @@ Tutorials ========= -This section contains numerous tutorials that cover basic use cases of -cert-manager. +This section contains guides that help you get started using cert-manager for +more specific use cases. + +For more information on performing individual tasks, read the +:doc:`tasks section `. .. toctree:: :maxdepth: 2 - quick-start/index acme/index - ca/index - vault/index diff --git a/docs/tutorials/vault/OWNERS b/docs/tutorials/vault/OWNERS deleted file mode 100644 index 1fb493914..000000000 --- a/docs/tutorials/vault/OWNERS +++ /dev/null @@ -1,5 +0,0 @@ -approvers: -- munnerz -reviewers: -- munnerz -- vdesjardins diff --git a/docs/tutorials/vault/index.rst b/docs/tutorials/vault/index.rst deleted file mode 100644 index b3a76e26f..000000000 --- a/docs/tutorials/vault/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -====================== -Vault Issuer Tutorials -====================== - -This section contains tutorials that specifically utilise the Vault Issuer. They -are designed to help teach the underlying concepts of cert-manager whilst also -helping 'quickstart' common use-cases for the project. - -.. toctree:: - :maxdepth: 1 - - creating-vault-issuers