weiguoqiang/cert-manager
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Updates documentation to remove outdated information and removes

Browse Source 
validation=false on the cert-manager namespace

Signed-off-by: JoshVanL <vleeuwenjoshua@gmail.com>
This commit is contained in:
JoshVanL 2019-10-01 16:10:06 +01:00
parent eb61adf0fc
commit ddd6e17f70
9 changed files with 16 additions and 258 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
deploy/charts/cert-manager/README.md
View File

@ -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
deploy/manifests/01-namespace.yaml
View File

@ -2,7 +2,5 @@ apiVersion: v1
kind: Namespace
metadata:
name: cert-manager
labels:
cert-manager.io/disable-validation: "true"
---

5
docs/devel/develop-with-minikube.rst
View File

@ -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
docs/getting-started/index.rst
View File

@ -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

25
docs/getting-started/install/kubernetes.rst
View File

@ -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

22
docs/getting-started/install/openshift.rst
View File

@ -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:

119
docs/getting-started/troubleshooting.rst
View 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

80
docs/getting-started/webhook.rst
View File

@ -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.

10
docs/tasks/upgrading/index.rst
View File

@ -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