From 4cfc34d76c9290d42e0da4c0ff1ad2332389ec59 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 23 Dec 2019 18:00:43 -0700 Subject: [PATCH 1/8] Cert-manager upgrade docs for both Helm 2 and Helm 3 --- .../options/upgrading-cert-manager/_index.md | 5 +- .../helm-2-instructions/_index.md | 153 ++++++++++++++++++ 2 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 content/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions/_index.md 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 622eea8c319..de4ff24d360 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 @@ -15,7 +15,10 @@ 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. + +> These instructions have been updated for Helm 3. If you are still using Helm 2, refer to [these instructions.]({{}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions) In order to upgrade cert-manager, follow these instructions: 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 new file mode 100644 index 00000000000..a3c256bf437 --- /dev/null +++ b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions/_index.md @@ -0,0 +1,153 @@ +--- +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: + +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. + +To address these changes, this guide will do two things: + +1. Document the procedure for upgrading cert-manager +1. Explain the cert-manager API changes and link to cert-manager's offficial documentation for migrating your data + + +## 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. + +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 + ``` +{{% /accordion %}} + +{{% accordion id="airgap" label="Upgrading cert-manager in an airgapped environment" %}} +### Prerequisites + +Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files. + +1. Follow the guide to [Prepare your Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/) with the images needed for the upgrade. + +1. From a system connected to the internet, add the cert-manager repo to Helm + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + ``` + +1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). + + ```plain + helm fetch jetstack/cert-manager --version v0.9.1 + ``` + +1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. + + ```plain + helm template ./cert-manager-v0.9.1.tgz --output-dir . \ + --name cert-manager --namespace kube-system \ + --set image.repository=/quay.io/jetstack/cert-manager-controller + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector + ``` + +1. Download the required CRD file for cert-manager + + ```plain + curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + ``` + +### Install cert-manager + +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 cert-manager installation + + ```plain + kubectl -n kube-system delete deployment,sa,clusterrole,clusterrolebinding -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + ``` + +1. Install the CustomResourceDefinition resources separately + + ```plain + kubectl apply -f cert-manager/cert-manager-crd.yaml + ``` + +1. Label the kube-system namespace to disable resource validation + + ```plain + kubectl label namespace kube-system certmanager.k8s.io/disable-validation=true + ``` + +1. Install cert-manager + + ```plain + kubectl -n kube-system apply -R -f ./cert-manager + ``` +{{% /accordion %}} + + +Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods: + +``` +kubectl get pods --namespace kube-system + +NAME READY STATUS RESTARTS AGE +cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m +cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m +cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m +``` + +If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check cert-manager's [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide. + +> **Note:** The above instructions ask you to add the disable-validation label to the kube-system namespace. Here are additional resources that explain why this is necessary: +> +> - [Information on the disable-validation label](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.4-0.5.html?highlight=certmanager.k8s.io%2Fdisable-validation#disabling-resource-validation-on-the-cert-manager-namespace) +> - [Information on webhook validation for certificates](https://docs.cert-manager.io/en/latest/getting-started/webhook.html) + +## Cert-Manager API change and data migration + +Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field and will drop support for it completely in an upcoming release. + +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). From d0e685aec647501c29177fce65437d63f0423471 Mon Sep 17 00:00:00 2001 From: Denise Date: Fri, 3 Jan 2020 12:34:21 -0800 Subject: [PATCH 2/8] Revert "Revert "Updated cert-manager installation/upgrade docs"" This reverts commit c561b648a689c2282e7a301e4123f593253acbc5. --- .../en/installation/ha/helm-rancher/_index.md | 23 ++-- .../options/chart-options/_index.md | 2 + .../options/upgrading-cert-manager/_index.md | 109 +++++++++++++----- .../air-gap/install-rancher/_index.md | 37 +++++- .../v2.x/en/upgrades/upgrades/ha/_index.md | 2 + 5 files changed, 124 insertions(+), 49 deletions(-) diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index a7d25919080..c808a7eb502 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -63,20 +63,20 @@ Rancher relies on [cert-manager](https://github.com/jetstack/cert-manager) to is > **Important:** > Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher. -> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.9.1, please see our [upgrade documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). +> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). -These instructions are adapted from the [official cert-manager documentation](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#installing-with-helm). +These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm). ``` # Install the CustomResourceDefinition resources separately -kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml +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. # Create the namespace for cert-manager kubectl create namespace cert-manager -# Label the cert-manager namespace to disable resource validation -kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - # Add the Jetstack Helm repository helm repo add jetstack https://charts.jetstack.io @@ -87,7 +87,7 @@ helm repo update helm install \ cert-manager jetstack/cert-manager \ --namespace cert-manager \ - --version v0.9.1 + --version v0.12.0 ``` Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods: @@ -95,13 +95,12 @@ Once you’ve installed cert-manager, you can verify it is deployed correctly by ``` kubectl get pods --namespace cert-manager -NAME READY STATUS RESTARTS AGE -cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m -cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m -cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m ``` -If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check the [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide. {{% /accordion %}} ### Install Rancher with Helm and Your Chosen Certificate Option diff --git a/content/rancher/v2.x/en/installation/options/chart-options/_index.md b/content/rancher/v2.x/en/installation/options/chart-options/_index.md index 3e3e477a56e..b9869077a2e 100644 --- a/content/rancher/v2.x/en/installation/options/chart-options/_index.md +++ b/content/rancher/v2.x/en/installation/options/chart-options/_index.md @@ -32,6 +32,8 @@ aliases: | `auditLog.maxSize` | 100 | `int` - maximum size in megabytes of the audit log file before it gets rotated (only applies when `auditLog.destination` is set to `hostPath`) | | `busyboxImage` | "busybox" | `string` - Image location for busybox image used to collect audit logs _Note: Available as of v2.2.0_ | | `debug` | false | `bool` - set debug flag on rancher server | +| `certmanager.version` | "" | `string` - set cert-manager compatibility + | | `extraEnv` | [] | `list` - set additional environment variables for Rancher _Note: Available as of v2.2.0_ | | `imagePullSecrets` | [] | `list` - list of names of Secret resource containing private registry credentials | | `ingress.extraAnnotations` | {} | `map` - additional annotations to customize the ingress | 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 de4ff24d360..acf713331b1 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 @@ -6,7 +6,8 @@ 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: 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 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/) To address these changes, this guide will do two things: @@ -23,24 +24,36 @@ The namespace used in these instructions depends on the namespace cert-manager i 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 +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 > cert-manager-backup.yaml + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml ``` -1. Delete the existing deployment +> **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 ``` -1. Install the CustomResourceDefinition resources separately + Delete the CustomResourceDefinition using the link to the version vX.Y you installed ```plain - kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + kubectl delete -f https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml ``` -1. Label the kube-system namespace to disable resource validation +1. Install the CustomResourceDefinition resources separately ```plain - kubectl label namespace kube-system certmanager.k8s.io/disable-validation=true + 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. + +1. Create the namespace for cert-manager if needed + ```plain + kubectl create namespace cert-manager ``` 1. Add the Jetstack Helm repository @@ -55,8 +68,17 @@ In order to upgrade cert-manager, follow these instructions: 1. Install the new version of cert-manager ```plain - helm install --version 0.9.1 --name cert-manager --namespace kube-system jetstack/cert-manager + helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --version v0.12.0 ``` + +1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + {{% /accordion %}} {{% accordion id="airgap" label="Upgrading cert-manager in an airgapped environment" %}} @@ -76,23 +98,24 @@ Before you can perform the upgrade, you must prepare your air gapped environment 1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). ```plain - helm fetch jetstack/cert-manager --version v0.9.1 + helm fetch jetstack/cert-manager --version v0.12.0 ``` 1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. ```plain - helm template ./cert-manager-v0.9.1.tgz --output-dir . \ - --name cert-manager --namespace kube-system \ + helm template ./cert-manager-v0.12.0.tgz --output-dir . \ + --name cert-manager --namespace cert-manager \ --set image.repository=/quay.io/jetstack/cert-manager-controller --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector ``` -1. Download the required CRD file for cert-manager +1. Download the required CRD file for cert-manager (old and new) ```plain - curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml ``` ### Install cert-manager @@ -100,13 +123,24 @@ Before you can perform the upgrade, you must prepare your air gapped environment 1. Back up existing resources as a precaution ```plain - kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml + 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) + 1. Delete the existing cert-manager installation ```plain - kubectl -n kube-system delete deployment,sa,clusterrole,clusterrolebinding -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + kubectl -n cert-manager \ + delete deployment,sa,clusterrole,clusterrolebinding \ + -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + ``` + + Delete the CustomResourceDefinition using the link to the version vX.Y you installed + ```plain + kubectl delete -f cert-manager/cert-manager-crd-old.yaml ``` 1. Install the CustomResourceDefinition resources separately @@ -115,42 +149,53 @@ Before you can perform the upgrade, you must prepare your air gapped environment kubectl apply -f cert-manager/cert-manager-crd.yaml ``` -1. Label the kube-system namespace to disable 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 ```plain - kubectl label namespace kube-system certmanager.k8s.io/disable-validation=true + kubectl create namespace cert-manager ``` 1. Install cert-manager ```plain - kubectl -n kube-system apply -R -f ./cert-manager + kubectl -n cert-manager apply -R -f ./cert-manager ``` + +1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + {{% /accordion %}} Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods: ``` -kubectl get pods --namespace kube-system +kubectl get pods --namespace cert-manager -NAME READY STATUS RESTARTS AGE -cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m -cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m -cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m ``` -If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check cert-manager's [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide. - -> **Note:** The above instructions ask you to add the disable-validation label to the kube-system namespace. Here are additional resources that explain why this is necessary: -> -> - [Information on the disable-validation label](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.4-0.5.html?highlight=certmanager.k8s.io%2Fdisable-validation#disabling-resource-validation-on-the-cert-manager-namespace) -> - [Information on webhook validation for certificates](https://docs.cert-manager.io/en/latest/getting-started/webhook.html) - ## Cert-Manager API change and data migration Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field and will drop support for it completely in an upcoming release. 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/). + diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md index e0becd6511d..33c3ea95253 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md @@ -66,8 +66,9 @@ For HA air gap configurations, there are two recommended options for the source When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations. | Chart Option | Chart Value | Description | -| ----------------------- | -------------------------------- | ------- | -| `systemDefaultRegistry` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | +| ----------------------- | -------------------------------- | ---- | +| `certmanager.version` | "" | Configure proper Rancher TLS issuer depending of running cert-manager version. | +| `systemDefaultRegistry` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | | `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. _Available as of v2.3.0_ | Based on the choice your made in [B. Choose your SSL Configuration](#b-choose-your-ssl-configuration), complete one of the procedures below. @@ -77,7 +78,7 @@ Based on the choice your made in [B. Choose your SSL Configuration](#b-choose-yo By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface. > **Note:** -> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.9.1, please see our [upgrade cert-manager documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). +> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). 1. From a system connected to the internet, add the cert-manager repo to Helm. ```plain @@ -86,13 +87,20 @@ By default, Rancher generates a CA and uses cert-manager to issue the certificat ``` 1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). +<<<<<<< HEAD ```plain helm fetch jetstack/cert-manager --version v0.9.1 ``` +======= + + ```plain + helm fetch jetstack/cert-manager --version v0.12.0 + ``` +>>>>>>> Revert "Revert "Updated cert-manager installation/upgrade docs"" 1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. ```plain - helm template ./cert-manager-v0.9.1.tgz --output-dir . \ + helm template ./cert-manager-v0.12.0.tgz --output-dir . \ --name cert-manager --namespace cert-manager \ --set image.repository=/quay.io/jetstack/cert-manager-controller --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook @@ -101,20 +109,33 @@ By default, Rancher generates a CA and uses cert-manager to issue the certificat 1. Download the required CRD file for cert-manager ```plain - curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml ``` 1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. +<<<<<<< HEAD Placeholder | Description ------------|------------- `` | The version number of the output tarball. `` | The DNS name you pointed at your load balancer. `` | The DNS name for your private registry. ```plain +======= + + Placeholder | Description + ------------|------------- + `` | The version number of the output tarball. + `` | The DNS name you pointed at your load balancer. + `` | The DNS name for your private registry. + `` | Cert-manager version running on k8s cluster. + + ```plain +>>>>>>> Revert "Revert "Updated cert-manager installation/upgrade docs"" helm template ./rancher-.tgz --output-dir . \ --name rancher \ --namespace cattle-system \ --set hostname= \ + --set certmanager.version= \ --set rancherImage=/rancher/rancher \ --set systemDefaultRegistry= \ # Available as of v2.2.0, set a default private registry to be used in Rancher --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts @@ -167,16 +188,22 @@ If you are using self-signed certificates, install cert-manager: kubectl create namespace cert-manager ``` +<<<<<<< HEAD 1. Label the cert-manager namespace to disable resource validation. ```plain kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true ``` +======= +>>>>>>> Revert "Revert "Updated cert-manager installation/upgrade docs"" 1. Create the cert-manager CustomResourceDefinitions (CRDs). ```plain 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. + 1. Launch cert-manager. ```plain kubectl apply -R -f ./cert-manager 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 793140b6b8d..b3e15eefaad 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md @@ -112,6 +112,7 @@ This section describes how to upgrade normal (Internet-connected) or air gap ins `` | The version number of the output tarball. `` | The DNS name you pointed at your load balancer. `` | The DNS name for your private registry. + `` | Cert-manager version running on k8s cluster. {{% accordion id="self-signed" label="Option A-Default Self-Signed Certificate" %}} @@ -120,6 +121,7 @@ helm template ./rancher-.tgz --output-dir . \ --name rancher \ --namespace cattle-system \ --set hostname= \ + --set certmanager.version= \ --set rancherImage=/rancher/rancher \ --set systemDefaultRegistry= \ # Available as of v2.2.0, set a default private registry to be used in Rancher --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts From 584fda65f4336af28fb37f895a8ee792f6f6a770 Mon Sep 17 00:00:00 2001 From: rawmind0 Date: Wed, 8 Jan 2020 23:56:06 +0100 Subject: [PATCH 3/8] upgrade path for upgrading Rancher and cert-manger v0.12 --- .../options/upgrading-cert-manager/_index.md | 31 +++++++++++++------ .../helm-2-instructions/_index.md | 23 ++++++++++++-- .../v2.x/en/upgrades/upgrades/ha/_index.md | 27 +++++++++++++++- 3 files changed, 67 insertions(+), 14 deletions(-) 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" %}} From f24eb74568aba38a9f2cee6f1a37a8662d3a5dbf Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 9 Jan 2020 22:57:02 -0700 Subject: [PATCH 4/8] Minor edits to cert-manager doc --- .../options/upgrading-cert-manager/_index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) 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 bdc57d9a70c..5d3a2302032 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 @@ -32,7 +32,7 @@ In order to upgrade cert-manager, follow these instructions: ``` > **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) + > 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`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [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) @@ -52,8 +52,8 @@ In order to upgrade cert-manager, follow these instructions: 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. + > **Note:** + > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, 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 @@ -137,7 +137,7 @@ Before you can perform the upgrade, you must prepare your air gapped environment ``` > **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) + > 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`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [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 @@ -159,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. + > **Note:** + > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, 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 From 931a03932110e42ee866c73311fb9baa5a817004 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 9 Jan 2020 23:27:56 -0700 Subject: [PATCH 5/8] Minor edit to cert-manager doc --- .../upgrading-cert-manager/helm-2-instructions/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 850d25ecaa7..1948dfb7102 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 @@ -161,10 +161,10 @@ Per the cert-manager documentation, a new format for configuring ACME certificat 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. +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 +For information on upgrading from all other versions of cert-manager, refer to the [official documentation](https://cert-manager.io/docs/installation/upgrading/). From 51ee2183da1f940fda8dbf8aebb1ae895584072b Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 9 Jan 2020 23:49:03 -0700 Subject: [PATCH 6/8] Formatting changes to cert-manager doc --- .../v2.x/en/upgrades/upgrades/ha/_index.md | 34 +++++++++---------- 1 file changed, 16 insertions(+), 18 deletions(-) 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 b0fc9382a9d..84940d394ba 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md @@ -80,32 +80,32 @@ This section describes how to upgrade normal (Internet-connected) or air gap ins {{% tabs %}} {{% tab "HA Upgrade" %}} -1. Get the values, that were passed with `--set`, from the current Rancher helm chart installed. +Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed. - ``` - helm get values rancher +``` +helm get values rancher - hostname: rancher.my.org - ``` +hostname: rancher.my.org +``` - > **Note:** There will be more values that are listed with this command. This is just an example of one of the values. +> **Note:** There will be more values that are listed with this command. This is just an example of one of the values. -> **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 +If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow Option B: Reinstalling Rancher. Otherwise, follow Option A: Upgrading Rancher. -{{% accordion id="secret" label="Option A: Upgrading Rancher" %}} +{{% accordion label="Option A: Upgrading Rancher" %}} -1. Upgrade Rancher to the latest version with all your settings. +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`. +Take all the values from the previous step and append them to the command using `--set key=value`: - ``` - helm upgrade rancher rancher-/rancher \ - --set hostname=rancher.my.org # Note: There will be many more options from the previous step that need to be appended. - ``` +``` +helm upgrade 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 %}} -{{% accordion id="secret" label="Option B: Reinstalling Rancher chart" %}} +{{% accordion label="Option B: Reinstalling Rancher chart" %}} 1. Uninstall Rancher @@ -113,9 +113,7 @@ This section describes how to upgrade normal (Internet-connected) or air gap ins 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`. +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 \ From b6a8208c58d416939755ba25596d98ea14dfc199 Mon Sep 17 00:00:00 2001 From: Jiaqi Luo Date: Wed, 15 Jan 2020 11:02:11 -0700 Subject: [PATCH 7/8] add explaination and instructions for upgrading both rancher and cert-manager --- .../options/upgrading-cert-manager/_index.md | 13 ++++++++++++- .../helm-2-instructions/_index.md | 13 ++++++++++++- .../rancher/v2.x/en/upgrades/upgrades/ha/_index.md | 6 +++++- 3 files changed, 29 insertions(+), 3 deletions(-) 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 5d3a2302032..c5dcb1d7213 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 @@ -14,8 +14,19 @@ To address these changes, this guide will do two things: 1. Document the procedure for upgrading cert-manager 1. Explain the cert-manager API changes and link to cert-manager's official documentation for migrating your data +> **Important:** +> If you are currently running the cert-manger whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, you need to reinstall both of them: -## Performing the upgrade +> 1. Take a one-time snapshot of your Kubernetes cluster running Rancher server +> 2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager +> 3. Install the newer version of Rancher and cert-manager + +> The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected. + +## Upgrade Cert-Manager Only + +> **Note:** +> These instructions are applied if you have no plan to upgrade Rancher. 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. 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 1948dfb7102..f4f11131e75 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 @@ -14,8 +14,19 @@ To address these changes, this guide will do two things: 1. Document the procedure for upgrading cert-manager 1. Explain the cert-manager API changes and link to cert-manager's offficial documentation for migrating your data +> **Important:** +> If you are currently running the cert-manger whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, you need to reinstall both of them: -## Performing the upgrade +> 1. Take a one-time snapshot of your Kubernetes cluster running Rancher server +> 2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager +> 3. Install the newer version of Rancher and cert-manager + +> The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected. + +## Upgrade Cert-Manager Only + +> **Note:** +> These instructions are applied if you have no plan to upgrade Rancher. 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. 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 84940d394ba..7ca2f6abb5d 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,7 @@ hostname: rancher.my.org > **Note:** There will be more values that are listed with this command. This is just an example of one of the values. -If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow Option B: Reinstalling Rancher. Otherwise, follow Option A: Upgrading Rancher. +If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow `Option B: Reinstalling Rancher`. Otherwise, follow `Option A: Upgrading Rancher`. {{% accordion label="Option A: Upgrading Rancher" %}} @@ -107,6 +107,10 @@ helm upgrade rancher rancher-/rancher \ {{% accordion label="Option B: Reinstalling Rancher chart" %}} +If you are currently running the cert-manger whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manger due to the API change in cert-manger v0.11. + +Please refer the [Upgrading Cert-Manager]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager) page for more information. + 1. Uninstall Rancher ``` From 2367cda9724ccb1001cdf1850130f71a6e7b0e79 Mon Sep 17 00:00:00 2001 From: Jiaqi Luo Date: Wed, 15 Jan 2020 11:28:25 -0700 Subject: [PATCH 8/8] add reference to reinstalling Rancher in the upgrading cert-manager page. --- .../en/installation/options/upgrading-cert-manager/_index.md | 2 ++ .../upgrading-cert-manager/helm-2-instructions/_index.md | 2 ++ 2 files changed, 4 insertions(+) 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 c5dcb1d7213..8cddb785b06 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 @@ -23,6 +23,8 @@ To address these changes, this guide will do two things: > The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected. +> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart]({{}}/rancher/v2.x/en/upgrades/upgrades/ha/#c-upgrade-rancher) under the upgrade Rancher section. + ## Upgrade Cert-Manager Only > **Note:** 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 f4f11131e75..3ae463cf22d 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 @@ -23,6 +23,8 @@ To address these changes, this guide will do two things: > The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected. +> For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart]({{}}/rancher/v2.x/en/upgrades/upgrades/ha/#c-upgrade-rancher) under the upgrade Rancher section. + ## Upgrade Cert-Manager Only > **Note:**