Merge pull request #3973 from jtravee/cert-manager-update

Updating cert-manager version for 2.6 docs
2026-09-26 04:58:07 +00:00 · 2022-03-29 18:18:51 -04:00
parent e2219de1b0 18326faba2
commit c6066f51f7
6 changed files with 33 additions and 10 deletions
@@ -104,6 +104,10 @@ There are three recommended options for the source of the certificate used for T

 ### 4. Install cert-manager

+**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
+
+> You should skip this step if you are bringing your own certificate files (option `ingress.tls.source=secret`), or if you use [TLS termination on an external load balancer]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination). 
+
 > You should skip this step if you are bringing your own certificate files (option `ingress.tls.source=secret`), or if you use [TLS termination on an external load balancer]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination).

 This step is only required to use certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) or to request Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`).
@@ -116,7 +120,7 @@ These instructions are adapted from the [official cert-manager documentation](ht

 ```
 # If you have installed the CRDs manually instead of with the `--set installCRDs=true` option added to your Helm install command, you should upgrade your CRD resources before upgrading the Helm chart:
-kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
+kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml

 # Add the Jetstack Helm repository
 helm repo add jetstack https://charts.jetstack.io
@@ -128,7 +132,7 @@ helm repo update
 helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
-  --version v1.5.1
+  --version v1.7.1
 ```

 Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
@@ -148,7 +148,13 @@ helm upgrade rancher rancher-<CHART_REPO>/rancher \

 ### Option B: Reinstalling Rancher and cert-manager

-If you are currently running the cert-manager 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-manager due to the API change in cert-manager v0.11. 
+If you are currently running the cert-manager whose version is 1.5 or below, and want to upgrade both Rancher and cert-manager to a new version (1.6+ in the case of cert-manager), then you need to re-install both Rancher and cert-manager due to the API change in cert-manager 1.6. This will also be necessary if you are upgrading from a version of cert manager below 0.11 to a version of cert-manager above 0.11.
+
+>**Important:** 
+>
+>- New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
+>
+>- Note that if you are below version 1.5 and want to go to 1.7, you should first upgrade to 1.6 as an intermediate step. Follow the cert-manager docs [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/) to do a 1.5 to 1.6 upgrade, and [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/) to then do a 1.6 to 1.7 upgrade. For more details on upgrading cert-manager, refer to our [documentation]({{<baseurl>}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager).

 1. Uninstall Rancher

@@ -94,8 +94,10 @@ helm repo update

 Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager).

+**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
+
 ```plain
-helm fetch jetstack/cert-manager --version v1.5.1
+helm fetch jetstack/cert-manager --version v1.7.1
 ```

 ### 3. Render the cert-manager template
@@ -103,7 +105,7 @@ helm fetch jetstack/cert-manager --version v1.5.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 ./cert-manager-v1.5.1.tgz --output-dir . \
+helm template cert-manager ./cert-manager-v1.7.1.tgz --output-dir . \
    --namespace cert-manager \
    --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
    --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
@@ -115,7 +117,7 @@ helm template cert-manager ./cert-manager-v1.5.1.tgz --output-dir . \

 Download the required CRD file for cert-manager:
   ```plain
-   curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
+   curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml
   ```

 ### 5. Render the Rancher template
@@ -51,6 +51,8 @@ If you will use ARM64 hosts, the registry must support manifests. As of April 20

 In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. 

+**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
+
 1.  Fetch the latest `cert-manager` Helm chart and parse the template for image details:

    > **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{<baseurl>}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/).
@@ -58,7 +60,7 @@ In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS
    ```plain
    helm repo add jetstack https://charts.jetstack.io
    helm repo update
-    helm fetch jetstack/cert-manager --version v1.5.1
+    helm fetch jetstack/cert-manager --version v1.7.1
    helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt
    ```

@@ -23,15 +23,17 @@ kubectl create namespace cert-manager

 Install the CustomResourceDefinitions of cert-manager:

+**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
+
 ```
-kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
+kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml
 ```

 And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:

 ```
 helm upgrade --install cert-manager jetstack/cert-manager \
-  --namespace cert-manager --version v1.5.1 \
+  --namespace cert-manager --version v1.7.1 \
  --set http_proxy=http://${proxy_host} \
  --set https_proxy=http://${proxy_host} \
  --set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local
@@ -15,7 +15,7 @@ To address these changes, this guide will do two things:
 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-manager 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:
+> If you are currently running the cert-manager whose version is 1.5 or below, and want to upgrade both Rancher and cert-manager to a new version (1.6+ in the case of cert-manager), then you need to re-install both Rancher and cert-manager due to the API change in cert-manager 1.6. This will also be necessary if you are upgrading from a version of cert manager below 0.11 to a version of cert-manager above 0.11. Follow the steps below:

 > 1. Take a one-time snapshot of your Kubernetes cluster running Rancher server
 > 2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager
@@ -220,6 +220,13 @@ cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

 ## Cert-Manager API change and data migration

+---
+_New in v2.6.4_
+
+Rancher now supports cert-manager versions 1.6.2 and 1.7.1. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. To read more, see the [cert-manager docs]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#4-install-cert-manager). For instructions on upgrading cert-manager from version 1.5 to 1.6, see the upstream cert-manager documentation [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/). For instructions on upgrading cert-manager from version 1.6 to 1.7, see the upstream cert-manager documentation [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/).
+
+---
+
 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.