From 093aa6844ca04e179dd19dbbd72e996a9d9da1fe Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 27 Sep 2019 11:22:44 +0100 Subject: [PATCH 1/2] 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 From 3de186305f5abab9b0b8bfd0b112496874612031 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 27 Sep 2019 11:22:58 +0100 Subject: [PATCH 2/2] Bump version strings for v0.11.0-alpha.0 Signed-off-by: James Munnelly --- deploy/charts/cert-manager/README.md | 10 ++++---- docs/getting-started/install/kubernetes.rst | 8 +++--- docs/getting-started/install/openshift.rst | 2 +- docs/getting-started/webhook.rst | 8 +++--- docs/tasks/issuing-certificates/index.rst | 2 +- docs/tasks/upgrading/index.rst | 2 +- docs/tutorials/acme/quick-start/index.rst | 28 ++++++++++----------- 7 files changed, 30 insertions(+), 30 deletions(-) diff --git a/deploy/charts/cert-manager/README.md b/deploy/charts/cert-manager/README.md index 95f6d3a81..153b84b82 100644 --- a/deploy/charts/cert-manager/README.md +++ b/deploy/charts/cert-manager/README.md @@ -21,11 +21,11 @@ To install the chart with the release name `my-release`: ## IMPORTANT: you MUST install the cert-manager CRDs **before** installing the ## cert-manager Helm chart $ kubectl apply \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/deploy/manifests/00-crds.yaml + -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/deploy/manifests/00-crds.yaml ## If you are installing on openshift : $ oc create \ - -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/deploy/manifests/00-crds.yaml + -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 @@ -83,7 +83,7 @@ The following table lists the configurable parameters of the cert-manager chart | `global.imagePullSecrets` | Reference to one or more secrets to be used when pulling images | `[]` | | `global.rbac.create` | If `true`, create and use RBAC resources (includes sub-charts) | `true` | | `image.repository` | Image repository | `quay.io/jetstack/cert-manager-controller` | -| `image.tag` | Image tag | `v0.10.0` | +| `image.tag` | Image tag | `v0.11.0-alpha.0` | | `image.pullPolicy` | Image pull policy | `IfNotPresent` | | `replicaCount` | Number of cert-manager replicas | `1` | | `clusterResourceNamespace` | Override the namespace used to store DNS provider credentials etc. for ClusterIssuer resources | Same namespace as cert-manager pod @@ -128,7 +128,7 @@ The following table lists the configurable parameters of the cert-manager chart | `webhook.resources` | CPU/memory resource requests/limits for the webhook pods | | | `webhook.nodeSelector` | Node labels for webhook pod assignment | `{}` | | `webhook.image.repository` | Webhook image repository | `quay.io/jetstack/cert-manager-webhook` | -| `webhook.image.tag` | Webhook image tag | `v0.10.0` | +| `webhook.image.tag` | Webhook image tag | `v0.11.0-alpha.0` | | `webhook.image.pullPolicy` | Webhook image pull policy | `IfNotPresent` | | `webhook.injectAPIServerCA` | if true, the apiserver's CABundle will be automatically injected into the ValidatingWebhookConfiguration resource | `true` | | `cainjector.enabled` | Toggles whether the cainjector component should be installed (required for the webhook component to work) | `true` | @@ -138,7 +138,7 @@ The following table lists the configurable parameters of the cert-manager chart | `cainjector.resources` | CPU/memory resource requests/limits for the cainjector pods | | | `cainjector.nodeSelector` | Node labels for cainjector pod assignment | `{}` | | `cainjector.image.repository` | cainjector image repository | `quay.io/jetstack/cert-manager-cainjector` | -| `cainjector.image.tag` | cainjector image tag | `v0.10.0` | +| `cainjector.image.tag` | cainjector image tag | `v0.11.0-alpha.0` | | `cainjector.image.pullPolicy` | cainjector image pull policy | `IfNotPresent` | Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. diff --git a/docs/getting-started/install/kubernetes.rst b/docs/getting-started/install/kubernetes.rst index dd4ee1e8b..a153c403f 100644 --- a/docs/getting-started/install/kubernetes.rst +++ b/docs/getting-started/install/kubernetes.rst @@ -62,7 +62,7 @@ are included in a single YAML manifest file: .. code-block:: shell # Install the CustomResourceDefinitions and cert-manager itself - kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v0.10.0/cert-manager.yaml + kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0-alpha.0/cert-manager.yaml .. note:: If you are running kubectl v1.12 or below, you will need to add the @@ -120,7 +120,7 @@ In order to install the Helm chart, you must run: .. code-block:: shell # Install the CustomResourceDefinition resources separately - kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/deploy/manifests/00-crds.yaml + kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/deploy/manifests/00-crds.yaml # Create the namespace for cert-manager kubectl create namespace cert-manager @@ -138,7 +138,7 @@ In order to install the Helm chart, you must run: helm install \ --name cert-manager \ --namespace cert-manager \ - --version v0.10.0 \ + --version v0.11.0-alpha.0 \ jetstack/cert-manager The default cert-manager configuration is good for the majority of users, but a @@ -289,7 +289,7 @@ If you have any issues with your installation, please refer to the :doc:`troubleshooting guide <../troubleshooting>`. .. _`CustomResourceDefinitions`: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ -.. _`Helm chart README`: https://github.com/jetstack/cert-manager/blob/release-0.10/deploy/charts/cert-manager/README.md +.. _`Helm chart README`: https://github.com/jetstack/cert-manager/blob/release-0.11/deploy/charts/cert-manager/README.md .. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 .. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/ .. _`Helm`: https://helm.sh/ diff --git a/docs/getting-started/install/openshift.rst b/docs/getting-started/install/openshift.rst index 9aa37136a..cc8b4b874 100644 --- a/docs/getting-started/install/openshift.rst +++ b/docs/getting-started/install/openshift.rst @@ -75,7 +75,7 @@ are included in a single YAML manifest file: .. code-block:: shell # Install the CustomResourceDefinitions and cert-manager itself - oc apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.10.0/cert-manager-openshift.yaml + oc apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0-alpha.0/cert-manager-openshift.yaml .. note:: The ``--validate=false`` flag is added to the ``oc apply`` command above diff --git a/docs/getting-started/webhook.rst b/docs/getting-started/webhook.rst index 429278cf7..1321a7e9f 100644 --- a/docs/getting-started/webhook.rst +++ b/docs/getting-started/webhook.rst @@ -193,14 +193,14 @@ To re-install cert-manager without the webhook, run: .. code-block:: shell - kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/v0.10.0/cert-manager.yaml + kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0-alpha.0/cert-manager.yaml - kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v0.10.0/cert-manager-no-webhook.yaml + kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v0.11.0-alpha.0/cert-manager-no-webhook.yaml Once you have re-installed cert-manager, you should then :doc:`restore your configuration `. -.. _`cert-manager.yaml`: https://github.com/jetstack/cert-manager/releases/download/v0.10.0/cert-manager.yaml -.. _`cert-manager-no-webhook.yaml`: https://github.com/jetstack/cert-manager/releases/download/v0.10.0/cert-manager-no-webhook.yaml +.. _`cert-manager.yaml`: https://github.com/jetstack/cert-manager/releases/download/v0.11.0-alpha.0/cert-manager.yaml +.. _`cert-manager-no-webhook.yaml`: https://github.com/jetstack/cert-manager/releases/download/v0.11.0-alpha.0/cert-manager-no-webhook.yaml .. _`GKE docs`: https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules .. _`ValidatingWebhookConfiguration`: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/ diff --git a/docs/tasks/issuing-certificates/index.rst b/docs/tasks/issuing-certificates/index.rst index b016e73d1..2f8b594c2 100644 --- a/docs/tasks/issuing-certificates/index.rst +++ b/docs/tasks/issuing-certificates/index.rst @@ -82,7 +82,7 @@ A full list of the fields supported on the Certificate resource can be found in the `API reference documentation`_. .. _`#1269`: https://github.com/jetstack/cert-manager/issues/1269 -.. _`API reference documentation`: https://docs.cert-manager.io/en/release-0.10/reference/api-docs/index.html#certificatespec-v1alpha2 +.. _`API reference documentation`: https://docs.cert-manager.io/en/release-0.11/reference/api-docs/index.html#certificatespec-v1alpha2 Temporary certificates whilst issuing ===================================== diff --git a/docs/tasks/upgrading/index.rst b/docs/tasks/upgrading/index.rst index d0ac2a6f1..7d78aa504 100644 --- a/docs/tasks/upgrading/index.rst +++ b/docs/tasks/upgrading/index.rst @@ -101,5 +101,5 @@ version number you want to install: 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 +.. _`static deployment manifests`: https://github.com/jetstack/cert-manager/blob/release-0.11/deploy/manifests .. _`kubernetes/kubernetes#69590`: https://github.com/kubernetes/kubernetes/issues/69590 diff --git a/docs/tutorials/acme/quick-start/index.rst b/docs/tutorials/acme/quick-start/index.rst index 924f440a7..5e22483b1 100644 --- a/docs/tutorials/acme/quick-start/index.rst +++ b/docs/tutorials/acme/quick-start/index.rst @@ -236,8 +236,8 @@ sample deployment and an associated service: .. literalinclude:: example/service.yaml :language: yaml -.. _`deployment.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/deployment.yaml -.. _`service.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/service.yaml +.. _`deployment.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/deployment.yaml +.. _`service.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/service.yaml .. _`kuard`: https://github.com/kubernetes-up-and-running/kuard You can create download and reference these files locally, or you can @@ -247,10 +247,10 @@ you may use the commands: .. code-block:: shell - $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/deployment.yaml + $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/deployment.yaml deployment.extensions "kuard" created - $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/service.yaml + $ kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/service.yaml service "kuard" created An `ingress resource`_ is what Kubernetes uses to expose this example service @@ -265,14 +265,14 @@ A sample ingress you can start with is: .. literalinclude:: example/ingress.yaml :language: yaml -.. _`ingress.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/ingress.yaml +.. _`ingress.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/ingress.yaml .. _`ingress resource`: https://kubernetes.io/docs/concepts/services-networking/ingress/ You can download the sample manifest from github, edit it, and submit the manifest to Kubernetes with the command: .. code-block:: shell - $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/ingress.yaml + $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/ingress.yaml # edit the file in your editor, and once it is saved: ingress.extensions "kuard" created @@ -403,13 +403,13 @@ expirations and updates. .. literalinclude:: example/staging-issuer.yaml :language: yaml -.. _`staging-issuer.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/staging-issuer.yaml +.. _`staging-issuer.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/staging-issuer.yaml Once edited, apply the custom resource: .. code-block:: shell - $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/staging-issuer.yaml + $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/staging-issuer.yaml issuer.cert-manager.io "letsencrypt-staging" created Also create a production issuer and deploy it. As with the staging issuer, you @@ -421,11 +421,11 @@ will need to update this example and add in your own email address. :language: yaml :emphasize-lines: 10 -.. _`production-issuer.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/production-issuer.yaml +.. _`production-issuer.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/production-issuer.yaml .. code-block:: shell - $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/production-issuer.yaml + $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/production-issuer.yaml issuer.cert-manager.io "letsencrypt-prod" created Both of these issuers are configured to use the @@ -506,13 +506,13 @@ example: :language: yaml :emphasize-lines: 6-8 -.. _`ingress-tls.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/ingress-tls.yaml +.. _`ingress-tls.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/ingress-tls.yaml and apply it: .. code-block:: shell - $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/ingress-tls.yaml + $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/ingress-tls.yaml ingress.extensions "kuard" configured Cert-manager will read these annotations and use them to create a certificate, @@ -615,11 +615,11 @@ can update the annotations in the ingress to specify the production issuer: .. literalinclude:: example/ingress-tls-final.yaml :language: yaml -.. _`ingress-tls-final.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/ingress-tls-final.yaml +.. _`ingress-tls-final.yaml`: https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/ingress-tls-final.yaml .. code-block:: shell - $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.10/docs/tutorials/acme/quick-start/example/ingress-tls-final.yaml + $ kubectl create --edit -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/docs/tutorials/acme/quick-start/example/ingress-tls-final.yaml ingress.extensions "kuard" configured