diff --git a/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md index acf713331b1..bdc57d9a70c 100644 --- a/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md +++ b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md @@ -3,11 +3,11 @@ title: Upgrading Cert-Manager weight: 2040 --- -Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, two important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher: +Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher: 1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) 1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). This change has no exact deadline. -2. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/) +1. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/) To address these changes, this guide will do two things: @@ -25,48 +25,56 @@ In order to upgrade cert-manager, follow these instructions: {{% accordion id="normal" label="Upgrading cert-manager with Internet access" %}} 1. [Back up existing resources](https://cert-manager.io/docs/tutorials/backup/) as a precaution + ```plain kubectl get -o yaml --all-namespaces \ issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml ``` -> **Important:** -> If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. [Additional annotation changes](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + > **Important:** + > If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. [Additional annotation changes](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) 1. [Uninstall existing deployment](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm) + ```plain helm delete --purge cert-manager ``` Delete the CustomResourceDefinition using the link to the version vX.Y you installed + ```plain kubectl delete -f https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml ``` 1. Install the CustomResourceDefinition resources separately + ```plain kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml ``` -> **Important:** -> If you are running Kubernetes v1.15 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 x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + > **Important:** + > If you are running Kubernetes v1.15 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 x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. 1. Create the namespace for cert-manager if needed + ```plain kubectl create namespace cert-manager ``` 1. Add the Jetstack Helm repository + ```plain helm repo add jetstack https://charts.jetstack.io ``` 1. Update your local Helm chart repository cache + ```plain helm repo update ``` 1. Install the new version of cert-manager + ```plain helm install \ cert-manager jetstack/cert-manager \ @@ -75,6 +83,7 @@ In order to upgrade cert-manager, follow these instructions: ``` 1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + ```plain kubectl apply -f cert-manager-backup.yaml ``` @@ -127,8 +136,8 @@ Before you can perform the upgrade, you must prepare your air gapped environment issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml ``` -> **Important:** -> If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. [Additional annotation changes](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + > **Important:** + > If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. [Additional annotation changes](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) 1. Delete the existing cert-manager installation @@ -139,6 +148,7 @@ Before you can perform the upgrade, you must prepare your air gapped environment ``` Delete the CustomResourceDefinition using the link to the version vX.Y you installed + ```plain kubectl delete -f cert-manager/cert-manager-crd-old.yaml ``` @@ -149,8 +159,8 @@ Before you can perform the upgrade, you must prepare your air gapped environment kubectl apply -f cert-manager/cert-manager-crd.yaml ``` -> **Important:** -> If you are running Kubernetes v1.15 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 x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + > **Important:** + > If you are running Kubernetes v1.15 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 x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. 1. Create the namespace for cert-manager @@ -165,6 +175,7 @@ Before you can perform the upgrade, you must prepare your air gapped environment ``` 1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + ```plain kubectl apply -f cert-manager-backup.yaml ``` diff --git a/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions/_index.md b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions/_index.md index a3c256bf437..850d25ecaa7 100644 --- a/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions/_index.md +++ b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions/_index.md @@ -3,10 +3,11 @@ title: Upgrading Cert-Manager with Helm 2 weight: 2040 --- -Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, two important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher: +Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher: 1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) 1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.7-0.8.html#upgrading-from-v0-7-to-v0-8). This change has no exact deadline. +1. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/) To address these changes, this guide will do two things: @@ -15,42 +16,50 @@ To address these changes, this guide will do two things: ## Performing the upgrade ->**Note:** The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues. + +The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues. In order to upgrade cert-manager, follow these instructions: {{% accordion id="normal" label="Upgrading cert-manager with Internet access" %}} 1. Back up existing resources as a precaution + ```plain kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml ``` 1. Delete the existing deployment + ```plain helm delete --purge cert-manager ``` 1. Install the CustomResourceDefinition resources separately + ```plain kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml ``` 1. Label the kube-system namespace to disable resource validation + ```plain kubectl label namespace kube-system certmanager.k8s.io/disable-validation=true ``` 1. Add the Jetstack Helm repository + ```plain helm repo add jetstack https://charts.jetstack.io ``` 1. Update your local Helm chart repository cache + ```plain helm repo update ``` 1. Install the new version of cert-manager + ```plain helm install --version 0.9.1 --name cert-manager --namespace kube-system jetstack/cert-manager ``` @@ -150,4 +159,12 @@ Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format. -Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.7-0.8.html). +Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). + +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 configuration 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 [upgrading to v0.8 guide](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). + +Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/). + +More info about [cert-manager upgrade information](https://cert-manager.io/docs/installation/upgrading/). \ No newline at end of file diff --git a/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md index b3e15eefaad..b0fc9382a9d 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md @@ -90,7 +90,11 @@ This section describes how to upgrade normal (Internet-connected) or air gap ins > **Note:** There will be more values that are listed with this command. This is just an example of one of the values. -2. Upgrade Rancher to the latest version with all your settings. +> **Note:** If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, please follow Option B: Reinstalling Rancher, otherwise follow Option A: Upgrading Rancher + +{{% accordion id="secret" label="Option A: Upgrading Rancher" %}} + +1. Upgrade Rancher to the latest version with all your settings. - Take all the values from the previous step and append them to the command using `--set key=value`. @@ -99,6 +103,27 @@ This section describes how to upgrade normal (Internet-connected) or air gap ins --set hostname=rancher.my.org # Note: There will be many more options from the previous step that need to be appended. ``` +{{% /accordion %}} + +{{% accordion id="secret" label="Option B: Reinstalling Rancher chart" %}} + +1. Uninstall Rancher + + ``` + helm delete rancher -n cattle-system + ``` + +2. Reinstall Rancher to the latest version with all your settings. + + - Take all the values from the previous step and append them to the command using `--set key=value`. + + ``` + helm install rancher rancher-/rancher \ + --set hostname=rancher.my.org # Note: There will be many more options from the previous step that need to be appended. + ``` + +{{% /accordion %}} + {{% /tab %}} {{% tab "HA Air Gap Upgrade" %}}