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

Update upgrading docs

Browse Source 
Update docs

Signed-off-by: James Munnelly <james.munnelly@jetstack.io>
This commit is contained in:
James Munnelly 2018-08-17 13:16:16 +01:00
parent 122a9e3b65
commit e77eacdcec
6 changed files with 338 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/admin/index.rst
View File

@ -10,4 +10,5 @@ manage a cert-manager deployment as an administrator.
.. toctree::
:maxdepth: 1
resource-validation-webhook
upgrading/index

249
docs/admin/resource-validation-webhook.rst Normal file
View File

@ -0,0 +1,249 @@
===========================
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: <none>
Annotations: <none>
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: <none>
Annotations: <none>
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: <none>
Annotations: <none>
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: <none>
Name: cm-cert-manager-webhook-ca
Namespace: cert-manager
Labels: <none>
Annotations: <none>
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

59
docs/admin/upgrading/index.rst
View File

@ -3,10 +3,65 @@ Upgrading cert-manager
======================
This section contains information on upgrading cert-manager.
It also contains documents detailing breaking changes between cert-manager versions,
and information on things to look out for when upgrading.
It also contains documents detailing breaking changes between cert-manager
versions, and information on things to look out for when upgrading.
Upgrading with Helm
===================
If you installed cert-manager using Helm, you can easily upgrade using the Helm
CLI.
.. note::
Before upgrading, please read the relevant instructions at the links below
for your from and to version.
Once you have read the relevant notes and taken any appropriate actions, you
can begin the upgrade process like so - replacing ``<release_name>`` with the
name of your Helm release for cert-manager (usually this is ``cert-manager``):
.. code:: shell
$ helm repo update
$ helm upgrade <release_name> stable/cert-manager
This will upgrade you to the latest version of cert-manager, as listed in the
`official Helm charts repository`_.
.. note::
You can find out your release name using ``helm list | grep cert-manager``.
Upgrading using static manifests
================================
If you installed cert-manager using the `static deployment manifests`_, you
can upgrade them in a similar way to how you first installed them.
.. note::
Before upgrading, please read the relevant instructions at the links below
for your from and to version.
Once you have read the relevant notes and taken any appropriate actions, you
can begin the upgrade process like so - replacing ``<version_number>`` and
``<namespace>`` with the version number you want to install, and the namespace
that cert-manager is deployed into respectively:
.. code:: shell
$ kubectl apply --namespace <namespace> -f \
https://github.com/jetstack/cert-manager/blob/<version_number>/contrib/manifests/cert-manager/with-rbac.yaml
.. note::
Please be sure to choose the correct variant of the static manifests, i.e.
one of the ``with-rbac`` or ``without-rbac`` files, depending on your cluster
configuration.
.. toctree::
:maxdepth: 1
upgrading-0.2-0.3
upgrading-0.3-0.4
upgrading-0.4-0.5
.. _`official Helm charts repository`: https://github.com/helm/charts
.. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/master/contrib/manifests/cert-manager

5
docs/admin/upgrading/upgrading-0.3-0.4.rst Normal file
View File

@ -0,0 +1,5 @@
===========================
Upgrading from v0.3 to v0.4
===========================
There are no special notes or considerations when upgrading from v0.3 to v0.4.

21
docs/admin/upgrading/upgrading-0.4-0.5.rst Normal file
View File

@ -0,0 +1,21 @@
===========================
Upgrading from v0.4 to v0.5
===========================
Version 0.5 of cert-manager introduces a new 'webhook' component, which is used
by the Kubernetes apiserver to validate our CRD resource types.
This should help in future to reduce errors caused by misconfigured Certificate
and Issuer resources.
When upgrading from a previous release using Helm, it is **essential** that
you perform one extra step before upgrading.
Disabling resource validation on the cert-manager namespace
===========================================================
Before upgrading, you should add the ``certmanager.k8s.io/disable-validation: "true"``
annotation to the ``cert-manager`` namespace.
This will allow the system resources that cert-manager requires to bootstrap
TLS to be created in its own namespace.

6
docs/getting-started/2-installing.rst
View File

@ -10,7 +10,7 @@ version of the chart to the public `charts repository`_.
You can install the chart with the following command:
.. code-block:: none
.. code-block:: shell
$ helm install \
--name cert-manager \
@ -25,6 +25,10 @@ full list of the available options can be found in the `Helm chart README`_.
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 </admin/upgrading>`
for special considerations.
With static manifests
=====================