From 093aa6844ca04e179dd19dbbd72e996a9d9da1fe Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 27 Sep 2019 11:22:44 +0100 Subject: [PATCH] Add provisional upgrade notes for v0.11 Signed-off-by: James Munnelly --- docs/tasks/upgrading/index.rst | 1 + docs/tasks/upgrading/upgrading-0.10-0.11.rst | 50 ++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 docs/tasks/upgrading/upgrading-0.10-0.11.rst diff --git a/docs/tasks/upgrading/index.rst b/docs/tasks/upgrading/index.rst index 14234cbea..d0ac2a6f1 100644 --- a/docs/tasks/upgrading/index.rst +++ b/docs/tasks/upgrading/index.rst @@ -98,6 +98,7 @@ version number you want to install: upgrading-0.7-0.8 upgrading-0.8-0.9 upgrading-0.9-0.10 + upgrading-0.10-0.11 .. _`official Helm charts repository`: https://hub.helm.sh/charts/jetstack .. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/release-0.10/deploy/manifests diff --git a/docs/tasks/upgrading/upgrading-0.10-0.11.rst b/docs/tasks/upgrading/upgrading-0.10-0.11.rst new file mode 100644 index 000000000..5145645f4 --- /dev/null +++ b/docs/tasks/upgrading/upgrading-0.10-0.11.rst @@ -0,0 +1,50 @@ +============================= +Upgrading from v0.10 to v0.11 +============================= + +** NOTE: THIS UPGRADE GUIDE IS PROVISIONAL AND MAY NOT BE COMPLETE WHILST THE v0.11 RELEASE SERIES IS IN ALPHA** + +The v0.11 release marks the removal of the v1alpha1 API that was used in +previous versions of cert-manager, as well as our API group changing to be +``cert-manager.io`` instead of ``certmanager.k8s.io``. + +We have also removed support for the **old style config format** that was +deprecated in the v0.8 release. This means you **must** transition to using the +new ``solvers`` style configuration format for your ACME issuers **before** +upgrading to v0.11. For more information, see the +:doc:`upgrading to v0.8 ` guide. + +This makes for a fairly significant breaking change for users, as **all** +cert-manager resources, or even Ingresses that reference cert-manager +resources, will need to be updated to reflect these changes. + +This upgrade should be performed in a few steps: + +1) Back up existing cert-manager resources, as per the + :doc:`backup and restore guide <../backup-restore-crds>`. + +2) Uninstall cert-manager (by running ``kubectl delete -f`` or ``helm delete --purge``) + +3) Ensure the old cert-manager CRD resources have also been deleted: ``kubectl get crd | grep certmanager.k8s.io`` + +4) Update the apiVersion on all your backed up resources from + ``certmanager.k8s.io/v1alpha1`` to ``cert-manager.io/v1alpha2``. + +5) Re-install cert-manager from scratch according to the :doc:`getting started guide `. + +You must be sure to properly **backup**, **uninstall**, **re-install** and +**restore** your installation in order to ensure the upgrade is successful. + +Additional annotation changes +============================= + +As well as changing the API group used by our CRDs, we have also changed the +annotation-based configuration key to **also** reflect the new API group. + +This means that if you use any cert-manager annotations on any of your other +resources (such as Ingresses, {Validating,Mutating}WebhookConfiguration, etc) +you will need to update them to reflect the new API group. + +A full table of annotations, including the old and new equivalents: + +.. TODO: create a table mapping old annotations to new