From 0bb9a2c0a8335e16ddb83142a4c103b612c6a716 Mon Sep 17 00:00:00 2001 From: JoshVanL Date: Wed, 2 Oct 2019 18:21:56 +0100 Subject: [PATCH] Re-introduce wehbook documentation in areas Signed-off-by: JoshVanL --- docs/getting-started/install/kubernetes.rst | 15 +++++++++++++++ docs/getting-started/install/openshift.rst | 15 +++++++++++++++ docs/getting-started/webhook.rst | 14 +++++++++++--- 3 files changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/install/kubernetes.rst b/docs/getting-started/install/kubernetes.rst index e2b3c821a..21ba5d6ef 100644 --- a/docs/getting-started/install/kubernetes.rst +++ b/docs/getting-started/install/kubernetes.rst @@ -33,6 +33,20 @@ 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 webhook deployment as +an `APIService`_. This can cause issues when uninstalling cert-manager if the +API service still exists but the webhook is no longer running as the API server +is unable to reach the validating webhook. Ensure to follow the documentation +when uninstalling cert-manager. TODO (@joshvanl): add uninstalling documentation +link when this has been created. + +The webhook enables cert-manager to implement validation and mutating webhooks +on cert-manager resources. A `ValidatingWebhookConfiguration`_ resource is +deployed to validate cert-manager resources we will create after installation. +No mutating webhooks are currently implemented. + +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: @@ -267,6 +281,7 @@ If you have any issues with your installation, please refer to the .. _`Helm chart README`: https://github.com/jetstack/cert-manager/blob/release-0.11/deploy/charts/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/ +.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server .. _`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 diff --git a/docs/getting-started/install/openshift.rst b/docs/getting-started/install/openshift.rst index 2d9964409..d9cc5a428 100644 --- a/docs/getting-started/install/openshift.rst +++ b/docs/getting-started/install/openshift.rst @@ -46,6 +46,20 @@ 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 webhook deployment as +an `APIService`_. This can cause issues when uninstalling cert-manager if the +API service still exists but the webhook is no longer running as the API server +is unable to reach the validating webhook. Ensure to follow the documentation +when uninstalling cert-manager. TODO (@joshvanl): add uninstalling documentation +link when this has been created. + +The webhook enables cert-manager to implement validation and mutating webhooks +on cert-manager resources. A `ValidatingWebhookConfiguration`_ resource is +deployed to validate cert-manager resources we will create after installation. +No mutating webhooks are currently implemented. + +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: @@ -78,5 +92,6 @@ 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/ +.. _`APIService`: https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server .. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 .. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/ diff --git a/docs/getting-started/webhook.rst b/docs/getting-started/webhook.rst index 8b1caa655..729bee597 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, Certificate, -and CertificateRequest 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 cert-manager API 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 @@ -44,6 +44,14 @@ implemented by the following two Secrets: * secret/cert-manager-webhook-tls - A TLS certificate issued by the root CA above, served by the webhook. +The webhook's 'webhookbootstrap' controller is responsible for creating these +secrets with no manual intervention needed. + +If errors occur around the webhook but the webhook is running then the webhook +is most likely not reachable from the API server. In this case, ensure that the +API server can communicate with the webhook by following the GKE private cluster +explanation below. + cainjector ----------