From ddd6e17f706bf3b416fb71aa568986b2eb0d9993 Mon Sep 17 00:00:00 2001 From: JoshVanL Date: Tue, 1 Oct 2019 16:10:06 +0100 Subject: [PATCH] Updates documentation to remove outdated information and removes validation=false on the cert-manager namespace Signed-off-by: JoshVanL --- deploy/charts/cert-manager/README.md | 7 -- deploy/manifests/01-namespace.yaml | 2 - docs/devel/develop-with-minikube.rst | 5 - docs/getting-started/index.rst | 4 - docs/getting-started/install/kubernetes.rst | 25 ---- docs/getting-started/install/openshift.rst | 22 ---- docs/getting-started/troubleshooting.rst | 119 -------------------- docs/getting-started/webhook.rst | 80 +++---------- docs/tasks/upgrading/index.rst | 10 -- 9 files changed, 16 insertions(+), 258 deletions(-) delete mode 100644 docs/getting-started/troubleshooting.rst diff --git a/deploy/charts/cert-manager/README.md b/deploy/charts/cert-manager/README.md index 153b84b82..720272b23 100644 --- a/deploy/charts/cert-manager/README.md +++ b/deploy/charts/cert-manager/README.md @@ -27,13 +27,6 @@ $ kubectl apply \ $ oc create \ -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/deploy/manifests/00-crds.yaml -## IMPORTANT: if the cert-manager namespace **already exists**, you MUST ensure -## it has an additional label on it in order for the deployment to succeed -$ kubectl label namespace cert-manager cert-manager.io/disable-validation="true" - -## For openshift: -$ oc label namespace cert-manager cert-manager.io/disable-validation=true - ## Add the Jetstack Helm repository $ helm repo add jetstack https://charts.jetstack.io diff --git a/deploy/manifests/01-namespace.yaml b/deploy/manifests/01-namespace.yaml index 4d738beb8..7caa1f30b 100644 --- a/deploy/manifests/01-namespace.yaml +++ b/deploy/manifests/01-namespace.yaml @@ -2,7 +2,5 @@ apiVersion: v1 kind: Namespace metadata: name: cert-manager - labels: - cert-manager.io/disable-validation: "true" --- diff --git a/docs/devel/develop-with-minikube.rst b/docs/devel/develop-with-minikube.rst index fb9d41d2a..bd896dff9 100644 --- a/docs/devel/develop-with-minikube.rst +++ b/docs/devel/develop-with-minikube.rst @@ -73,11 +73,6 @@ Deploy that version with helm # Install custom resources before running helm $ kubectl apply -f deploy/manifests/00-crds.yaml - # IMPORTANT: if you are deploying into a namespace that **already exists**, - # you MUST ensure the namespace has an additional label on it in order for - # the deployment to succeed - $ kubectl label namespace cert-manager.io/disable-validation="true" - # Install our freshly built cert-manager image $ helm install \ --set image.tag=canary \ diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index 975db5ed4..e8e35796a 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -4,13 +4,9 @@ Get started The guides in this section will explain how to install and set up cert-manager. -If you run into issues deploying, upgrading or running cert-manager please -check the :doc:`troubleshooting <./troubleshooting>` document. - .. toctree:: :maxdepth: 2 :caption: Contents: install/index webhook - troubleshooting diff --git a/docs/getting-started/install/kubernetes.rst b/docs/getting-started/install/kubernetes.rst index a153c403f..e2b3c821a 100644 --- a/docs/getting-started/install/kubernetes.rst +++ b/docs/getting-started/install/kubernetes.rst @@ -33,28 +33,6 @@ although you will need to make modifications to the deployment manifests. # 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 cert-manager.io/disable-validation=true - -You can read more about the webhook on the :doc:`webhook document <../webhook>`. - We can now go ahead and install cert-manager. All resources (the CustomResourceDefinitions, cert-manager, and the webhook component) are included in a single YAML manifest file: @@ -125,9 +103,6 @@ In order to install the Helm chart, you must run: # 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 cert-manager.io/disable-validation=true - # Add the Jetstack Helm repository helm repo add jetstack https://charts.jetstack.io diff --git a/docs/getting-started/install/openshift.rst b/docs/getting-started/install/openshift.rst index cc8b4b874..2d9964409 100644 --- a/docs/getting-started/install/openshift.rst +++ b/docs/getting-started/install/openshift.rst @@ -46,28 +46,6 @@ although you will need to make modifications to the deployment manifests. # Create a namespace to run cert-manager in oc 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 - oc label namespace cert-manager cert-manager.io/disable-validation=true - -You can read more about the webhook on the :doc:`webhook document <../webhook>`. - We can now go ahead and install cert-manager. All resources (the CustomResourceDefinitions, cert-manager, and the webhook component) are included in a single YAML manifest file: diff --git a/docs/getting-started/troubleshooting.rst b/docs/getting-started/troubleshooting.rst deleted file mode 100644 index fa9d0e64b..000000000 --- a/docs/getting-started/troubleshooting.rst +++ /dev/null @@ -1,119 +0,0 @@ -============================ -Troubleshooting installation -============================ - -Internal error occurred: failed calling admission webhook ... the server is currently unable to handle the request -================================================================================================================== - -When installing or upgrading cert-manager, you may run into issues when going -through the Validation Steps in the install guide which relate to the admission -webhook. - -If you see an error like the above, this guide will talk you through a few -checks that can pick up common installation problems. - -1. Check the namespace cert-manager is running in -------------------------------------------------- - -As described in the :doc:`webhook` documentation, the webhook component -requires TLS certificates in order to start and communicate securely with the -Kubernetes API server. - -In order for cert-manager to be able to issue certificates for the webhook -before it has started, we must **disable** resource validation on the namespace -that cert-manager is running in. - -Assuming you have deployed into the ``cert-manager`` namespace, run the -following command to verify that your cert-manager namespace has the necessary -label: - -.. code-block:: shell - - kubectl describe namespace cert-manager - - Name: cert-manager - Labels: cert-manager.io/disable-validation=true - Annotations: - Status: Active - ... - -If you cannot see the ``cert-manager.io/disable-validation=true`` label on -your namespace, you should add it with: - -.. code-block:: shell - - kubectl label namespace cert-manager cert-manager.io/disable-validation=true - -Please continue reading this guide once you have added the label. - -2. Verify that the webhook Issuer and Certificate resources exist ------------------------------------------------------------------ - -If you had any issues upgrading, especially if you install cert-manager using -Helm, you may run into an issue where either: - -* the CustomResourceDefinition resources do not exist -* the webhook's Issuer and Certificate resources do not exist - -We can first check for the existence of the CustomResourceDefinition resources: - -.. code-block:: shell - - kubectl get crd | grep certmanager - - NAME CREATED AT - certificates.cert-manager.io 2018-08-17T20:12:26Z - challenges.cert-manager.io 2018-08-02T15:33:02Z - clusterissuers.cert-manager.io 2018-08-17T20:12:26Z - issuers.cert-manager.io 2018-08-17T20:12:26Z - orders.cert-manager.io 2018-08-02T14:40:11Z - -We should then also check for that the webhook's Issuer and Certificate -resources exist and have been issued correctly: - -.. code-block:: shell - - kubectl get issuer,certificate --namespace cert-manager - - NAME AGE - issuer.cert-manager.io/cert-manager-webhook-ca 22d - issuer.cert-manager.io/cert-manager-webhook-selfsign 22d - - NAME READY SECRET AGE - certificate.cert-manager.io/cert-manager-webhook-ca True cert-manager-webhook-ca 22d - certificate.cert-manager.io/cert-manager-webhook-webhook-tls True cert-manager-webhook-webhook-tls 22d - -If you do not see the CustomResourceDefinitions installed, or cannot see the -webhook's Issuer and Certificate resources, please go back to the install guide -and ensure you've followed every step closely. - -Take particular care to install the CRD manifest **before** installing -cert-manager itself. - -3. Verify all cert-manager pods are running successfully --------------------------------------------------------- - -You can verify that cert-manager has managed to start successfully by checking -the state of the pods that have been deployed: - -.. code-block:: shell - - kubectl get pods --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-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m - -If the 'webhook' pod (2nd line) is in a ContainerCreating state, it may still -be waiting for the Secret in step 2 to be mounted into the pod. - -Provided the Secret resource **does** now exist, Waiting a few minutes, or -deleting the pod and allowing it to be recreated should get things moving -again. - -.. note:: - Check if the Secret exists by running:: - - kubectl --namespace cert-manager get secret cert-manager-webhook-webhook-tls - diff --git a/docs/getting-started/webhook.rst b/docs/getting-started/webhook.rst index 1321a7e9f..8b1caa655 100644 --- a/docs/getting-started/webhook.rst +++ b/docs/getting-started/webhook.rst @@ -5,9 +5,9 @@ Webhook component In order to provide advanced resource validation, cert-manager includes a ValidatingWebhookConfiguration_ resource which is deployed into the cluster. -This allows cert-manager to validate that Issuer, ClusterIssuer and Certificate -resources that are submitted to the apiserver are syntactically valid, and -catch issues with your resources early on. +This allows cert-manager to validate that Issuer, ClusterIssuer, Certificate, +and CertificateRequest resources that are submitted to the apiserver are +syntactically valid, and catch issues with your resources early on. If you disable the webhook component, cert-manager will still perform the same resource validation however it will not reject 'create' events when the @@ -32,47 +32,18 @@ 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. +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. +apiserver is configured to trust. This is created by the webhook itself and is +implemented by the following two Secrets: -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 +* secret/cert-manager-webhook-ca - A self-signed root CA certificate which is used to sign certificates for the webhook pod. -* issuer/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 +* secret/cert-manager-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. - cainjector ---------- @@ -100,28 +71,6 @@ 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 cert-manager.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 private GKE clusters ------------------------------- @@ -130,9 +79,12 @@ 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. +firewall rules configured restrict access to your Kubernetes pods. This will +mean that you will experience the webhook to not work and expierence errors such +as `Internal error occurred: failed calling admission webhook ... the server is +currently unable to handle the request`. -This means that in order to use the webhook component with a GKE private +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. @@ -151,8 +103,8 @@ If you are having issues with the webhook and cannot use it at this time, you can optionally disable the webhook altogether. Doing this may expose your cluster to mis-configuration problems that in some -cases could cause cert-manager to stop working altogether (i.e. if invalid -types are set for fields on cert-manager resources). +cases could cause cert-manager to stop working altogether (i.e. if invalid types +are set for fields on cert-manager resources). How you disable the webhook depends on your deployment method. diff --git a/docs/tasks/upgrading/index.rst b/docs/tasks/upgrading/index.rst index 7d78aa504..f267ec341 100644 --- a/docs/tasks/upgrading/index.rst +++ b/docs/tasks/upgrading/index.rst @@ -41,11 +41,6 @@ version number you want to install: # Ensure the local Helm chart repository cache is up to date 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 cert-manager.io/disable-validation=true - helm upgrade --version jetstack/cert-manager This will upgrade you to the latest version of cert-manager, as listed in the @@ -71,11 +66,6 @@ version number you want to install: .. code:: shell - # 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 cert-manager.io/disable-validation=true - kubectl apply \ -f https://github.com/jetstack/cert-manager/releases/download//cert-manager.yaml