Updates documentation to remove outdated information and removes
validation=false on the cert-manager namespace Signed-off-by: JoshVanL <vleeuwenjoshua@gmail.com>
This commit is contained in:
JoshVanL
parent
eb61adf0fc
commit
ddd6e17f70
@ -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
|
||||
|
||||
|
||||
@ -2,7 +2,5 @@ apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: cert-manager
|
||||
labels:
|
||||
cert-manager.io/disable-validation: "true"
|
||||
|
||||
---
|
||||
|
||||
@ -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 <deployment-namespace> cert-manager.io/disable-validation="true"
|
||||
|
||||
# Install our freshly built cert-manager image
|
||||
$ helm install \
|
||||
--set image.tag=canary \
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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: <none>
|
||||
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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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 <version> <release_name> 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/<version>/cert-manager.yaml
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user