Merge pull request #1223 from munnerz/upgrade-notes
Add upgrade notes for v0.6
This commit is contained in:
jetstack-bot
GitHub
commit
9bec321c7d
@ -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 ``<release_name>`` 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
|
||||
``<release_name>`` with the name of your Helm release for cert-manager (usually
|
||||
this is ``cert-manager``) and replacing ``<version>`` 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/<version>/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} <release_name> stable/cert-manager
|
||||
$ helm upgrade --version <version> <release_name> 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 ``<version>`` 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/<version>/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
|
||||
|
||||
@ -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 </admin/upgrading/index>` 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 </admin/upgrading/index>` 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 </getting-started/2-installing>`):
|
||||
|
||||
.. 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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user