From e77eacdcecbf62371a5f555b8d8652d4e82ce57a Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 17 Aug 2018 13:16:16 +0100 Subject: [PATCH] Update upgrading docs Update docs Signed-off-by: James Munnelly --- docs/admin/index.rst | 1 + docs/admin/resource-validation-webhook.rst | 249 +++++++++++++++++++++ docs/admin/upgrading/index.rst | 59 ++++- docs/admin/upgrading/upgrading-0.3-0.4.rst | 5 + docs/admin/upgrading/upgrading-0.4-0.5.rst | 21 ++ docs/getting-started/2-installing.rst | 6 +- 6 files changed, 338 insertions(+), 3 deletions(-) create mode 100644 docs/admin/resource-validation-webhook.rst create mode 100644 docs/admin/upgrading/upgrading-0.3-0.4.rst create mode 100644 docs/admin/upgrading/upgrading-0.4-0.5.rst diff --git a/docs/admin/index.rst b/docs/admin/index.rst index 9089b82f0..063376dc1 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -10,4 +10,5 @@ manage a cert-manager deployment as an administrator. .. toctree:: :maxdepth: 1 + resource-validation-webhook upgrading/index diff --git a/docs/admin/resource-validation-webhook.rst b/docs/admin/resource-validation-webhook.rst new file mode 100644 index 000000000..90eb76a8c --- /dev/null +++ b/docs/admin/resource-validation-webhook.rst @@ -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: + Annotations: + 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: + Annotations: + 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: + Annotations: + 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: + + + Name: cm-cert-manager-webhook-ca + Namespace: cert-manager + Labels: + Annotations: + 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 diff --git a/docs/admin/upgrading/index.rst b/docs/admin/upgrading/index.rst index f450245cd..1c9b5a0f8 100644 --- a/docs/admin/upgrading/index.rst +++ b/docs/admin/upgrading/index.rst @@ -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 ```` with the +name of your Helm release for cert-manager (usually this is ``cert-manager``): + +.. code:: shell + + $ helm repo update + $ helm upgrade 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 ```` and +```` with the version number you want to install, and the namespace +that cert-manager is deployed into respectively: + +.. code:: shell + + $ kubectl apply --namespace -f \ + https://github.com/jetstack/cert-manager/blob//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 diff --git a/docs/admin/upgrading/upgrading-0.3-0.4.rst b/docs/admin/upgrading/upgrading-0.3-0.4.rst new file mode 100644 index 000000000..c7411bdfa --- /dev/null +++ b/docs/admin/upgrading/upgrading-0.3-0.4.rst @@ -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. diff --git a/docs/admin/upgrading/upgrading-0.4-0.5.rst b/docs/admin/upgrading/upgrading-0.4-0.5.rst new file mode 100644 index 000000000..fb0fceed1 --- /dev/null +++ b/docs/admin/upgrading/upgrading-0.4-0.5.rst @@ -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. diff --git a/docs/getting-started/2-installing.rst b/docs/getting-started/2-installing.rst index 2bce9bc74..d3c0f2bf8 100644 --- a/docs/getting-started/2-installing.rst +++ b/docs/getting-started/2-installing.rst @@ -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 ` + for special considerations. + With static manifests =====================