diff --git a/docs/admin/upgrading/index.rst b/docs/admin/upgrading/index.rst index 0d1c70b36..18e24d7b8 100644 --- a/docs/admin/upgrading/index.rst +++ b/docs/admin/upgrading/index.rst @@ -16,20 +16,28 @@ CLI. 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``): +Once you have read the relevant upgrading 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``) and replacing ```` with the +version number you want to install: .. code:: shell + # Install the cert-manager CustomResourceDefinition resources before + # upgrading the Helm chart + $ kubectl apply \ + -f https://raw.githubusercontent.com/jetstack/cert-manager//deploy/manifests/00-crds.yaml + + # Ensure the local Helm chart repository cache is up to date $ helm repo update - $ kubectl apply \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/${VERSION}/deploy/manifests/00-crds.yaml - + # 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 certmanager.k8s.io/disable-validation=true - $ helm upgrade --version ${VERSION} stable/cert-manager + $ helm upgrade --version stable/cert-manager This will upgrade you to the latest version of cert-manager, as listed in the `official Helm charts repository`_. @@ -48,19 +56,26 @@ can upgrade them in a similar way to how you first installed them. 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}`` with the +can begin the upgrade process like so - replacing ```` with the version number you want to install: .. code:: shell - $ kubectl apply \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/${VERSION}/deploy/manifests/00-crds.yaml - - # Ensure resource validation is disabled on the cert-manager namespace + # 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 certmanager.k8s.io/disable-validation=true $ kubectl apply \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/${VERSION}/deploy/manifests/cert-manager.yaml + -f https://raw.githubusercontent.com/jetstack/cert-manager//deploy/manifests/cert-manager.yaml + +.. note:: + If you are running kubectl v1.12 or below, you will need to add the + ``--validate=false`` flag to your ``kubectl apply`` command above else you + will receive a validation error relating to the ``caBundle`` field of the + ``ValidatingWebhookConfiguration`` resource. + This issue is resolved in Kubernetes 1.13 onwards. More details can be found + in `kubernetes/kubernetes#69590`_. .. toctree:: :maxdepth: 1 @@ -72,3 +87,4 @@ version number you want to install: .. _`official Helm charts repository`: https://github.com/helm/charts .. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/master/contrib/manifests/cert-manager +.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 diff --git a/docs/admin/upgrading/upgrading-0.5-0.6.rst b/docs/admin/upgrading/upgrading-0.5-0.6.rst index 578419ea9..010f54bcf 100644 --- a/docs/admin/upgrading/upgrading-0.5-0.6.rst +++ b/docs/admin/upgrading/upgrading-0.5-0.6.rst @@ -2,8 +2,107 @@ Upgrading from v0.5 to v0.6 =========================== -.. todo:: - Describe additional ``kubectl apply`` step +.. warning:: + If you are upgrading from a release older than v0.5, please read the + `Upgrading from older versions using Helm`_ note at the bottom of this + document! -.. todo:: - Adding additional notes about upgrading from v0.4 +The upgrade process from v0.5 to v0.6 should be fairly seamless for most users. +As part of the new release, we have changed how we ship the +CustomResourceDefinition resources that cert-manager needs in order to operate +(as well as introducing two **new** CRD types). + +Depending on the way you have installed cert-manager in the past, your upgrade +process will slightly vary: + +Upgrading with the Helm chart +============================= + +If you have previously deployed cert-manager v0.5 using the Helm installation +method, you will now need to perform one extra step before upgrading. + +Due to issues with the way Helm handles CRD resources in Helm charts, we have +now moved the installation of these resources into a separate YAML manifest +that must be installed with ``kubectl apply`` before upgrading the chart. + +You can follow the :doc:`regular upgrade guide ` as +usual in order to upgrade from v0.5 to v0.6. + +Upgrading with static manifests +=============================== + +The static manifests have moved into the ``deploy/manifests`` directory for +this release. + +We now also no longer ship different manifests for different configurations, in +favour of a single ``cert-manager.yaml`` file which should work for all +Kubernetes clusters from Kubernetes v1.9 onwards. + +You can follow the :doc:`regular upgrade guide ` as +usual in order to upgrade from v0.5 to v0.6. + +Upgrading from older versions using Helm +======================================== + +If you are upgrading from a version **older than v0.5** and +**have installed with Helm**, you will need to perform a fresh installation of +cert-manager due to issues with Helm. This will involve the +**removal of all cert-manager custom resources**. This **will not** delete the +Secret resources being used to serve your websites with. + +Before upgrading you will need to: + +1. Backup all Certificate, Issuer and ClusterIssuer resources: + +.. code-block:: shell + + $ kubectl get certificate,issuer,clusterissuer -o yaml --all-namespaces > cert-manager-backup.yaml + +2. Delete the existing cert-manager Helm release (replacing 'cert-manager' with + the name of your Helm release): + +.. code-block:: shell + + # Uninstall the Helm chart + $ helm delete --purge cert-manager + + # Ensure the cert-manager CustomResourceDefinition resources do not exist: + $ kubectl delete crd \ + certificates.certmanager.k8s.io \ + issuers.certmanager.k8s.io \ + clusterissuers.certmanager.k8s.io + +3. Perform a fresh install (as per the + :doc:`installation guide `): + +.. code-block:: shell + + # Install the cert-manager CRDs + $ kubectl apply \ + -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.6/deploy/manifests/00-crds.yaml + + # Update helm repository cache + $ helm repo update + + # Install cert-manager + $ helm install \ + --name cert-manager \ + --namespace cert-manager \ + --version v0.6.0 \ + stable/cert-manager + +4. Restore the previously backed up cert-manager resources: + +.. code-block:: shell + + $ kubectl apply -f cert-manager-backup.yaml + +5. Verify that your Issuers and Certificate resources are 'Ready': + +.. code-block:: shell + + $ kubectl get clusterissuer,issuer,certificates --all-namespaces + NAMESPACE NAME READY SECRET AGE + cert-manager cert-manager-webhook-ca True cert-manager-webhook-ca 1m + cert-manager cert-manager-webhook-webhook-tls True cert-manager-webhook-webhook-tls 1m + example-com example-com-tls True example-com-tls 11s diff --git a/docs/getting-started/2-installing.rst b/docs/getting-started/2-installing.rst index 35ee5133d..e3f0b2e4a 100644 --- a/docs/getting-started/2-installing.rst +++ b/docs/getting-started/2-installing.rst @@ -59,6 +59,15 @@ To install cert-manager using the static manifests, you should run: $ kubectl apply \ -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.6/deploy/manifests/cert-manager.yaml +.. note:: + If you are running kubectl v1.12 or below, you will need to add the + ``--validate=false`` flag to your ``kubectl apply`` command above else you + will receive a validation error relating to the ``caBundle`` field of the + ``ValidatingWebhookConfiguration`` resource. + This issue is resolved in Kubernetes 1.13 onwards. More details can be found + in `kubernetes/kubernetes#69590`_. + .. _`charts repository`: https://github.com/kubernetes/charts .. _`Helm chart README`: https://github.com/kubernetes/charts/blob/master/stable/cert-manager/README.md .. _`deploy directory`: https://github.com/jetstack/cert-manager/blob/master/contrib/manifests/cert-manager +.. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590