Merge pull request #2017 from sunilarjun/update-cve-sept25

Updating CVEs for September maintenance
Merge pull request #2016 from rancher/v2.12.2
2026-09-29 14:38:50 +00:00 · 2025-09-25 13:14:13 -07:00 · 2025-09-25 13:12:11 -07:00 · 2025-09-25 13:11:53 -07:00 · 2025-09-25 13:11:40 -07:00 · 2025-09-25 13:11:15 -07:00
6443 changed files with 379831 additions and 202909 deletions
@@ -0,0 +1,18 @@
+---
+name: Release Maintenance Task Checklist
+about: Track tasks that need to be done every release.
+title: '<VERSION> - Rancher Manager Release Maintenance Task Checklist'
+---
+
+This issue is to track tasks that need to be done every release regardless of whether the release has new feature content or not.
+
+- [ ] Create a new branch for the release. Release-specific updates should use this branch as its base
+- [ ] Update the [versions table](https://ranchermanager.docs.rancher.com/versions)
+- [ ] Update the [Rancher:webhook version mapping table](https://ranchermanager.docs.rancher.com/reference-guides/rancher-webhook)
+- [ ] Update the [CNI popularity table](https://ranchermanager.docs.rancher.com/faq/container-network-interface-providers#cni-community-popularity)
+- [ ] Update the [CSP adapter compatibility matrix](https://ranchermanager.docs.rancher.com/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter#rancher-vs-adapter-compatibility-matrix)
+- [ ] Update the [deprecated features table](https://ranchermanager.docs.rancher.com/faq/deprecated-features)
+- [ ] Update the swagger-<VERSION>.json file
+- [ ] Create a PR merging the release branch back into the main branch
+- [ ] Create a new [release](https://github.com/rancher/rancher-docs/releases)
+- [ ] Update Algolia search index
@@ -1,9 +1,6 @@
 ---
 name: Request a New Feature
 about: For requesting new feature(s) to be added to the docs.
-title: ''
-labels: ''
-assignees: ''
 ---

 ## Related Issues
@@ -1,9 +1,6 @@
 ---
 name: Request an Update
 about: For fixing docs errors/typos, adding needed/missing information, updating verbiage, deleting outdated info, etc.
-title: ''
-labels: ''
-assignees: ''
 ---

 ## Related Issues
@@ -0,0 +1 @@
+f288d286db3b7c65e02cb6635d0c048f0f7a88fa
@@ -0,0 +1,29 @@
+name: Create issue to track porting between Community and Product docs
+
+on:
+  pull_request_target:
+    types:
+      - closed
+    paths-ignore:
+      - '**/README.md'
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  create_issue:
+    if: github.event.pull_request.merged == true && contains( github.event.pull_request.labels.*.name, 'port/community-product')
+    runs-on: ubuntu-latest
+    steps:
+    - name: Create issue
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO_TYPE: ${{ contains( github.repository, 'product-docs') && 'Product' || 'Community' }}
+        PR_TITLE: ${{ github.event.pull_request.title }}
+      run: |
+        gh issue create \
+          --repo ${{ github.repository }} \
+          --title "Port $REPO_TYPE docs PR #${{ github.event.pull_request.number }}: $PR_TITLE" \
+          --body "Reference: https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}" \
+          --label port/community-product
@@ -6,6 +6,7 @@ on:
      - main
    paths-ignore:
      - '**/README.md'
+      - '**/.github/ISSUE_TEMPLATE/**'

 jobs:
  build:
@@ -24,7 +25,7 @@ jobs:
        run: yarn install --frozen-lockfile
      - name: Build website
        env:
-          NODE_OPTIONS: "--max_old_space_size=7168"
+          NODE_OPTIONS: "--max_old_space_size=8192"
        run: yarn build --no-minify

      - name: Upload Build Artifact
@@ -4,6 +4,7 @@ on:
  pull_request:
    paths-ignore:
      - '**/README.md'
+      - '**/.github/ISSUE_TEMPLATE/**'

 jobs:
  test-deploy:
@@ -1 +1 @@
-* @btat @LucasSaintarbor @martyav @sunilarjun
+* @btat @LucasSaintarbor @pmkovar @sunilarjun
@@ -15,7 +15,7 @@ To get started, [fork](https://github.com/rancher/rancher-docs/fork) and clone t

 Our repository doesn't allow you to make changes directly to the `main` branch. Create a working branch and make pull requests from your fork to [rancher/rancher-docs](https://github.com/rancher/rancher-docs).

-For most updates, you'll need to edit a file in the `/docs` directory, which represents the ["Latest"](https://ranchermanager.docs.rancher.com/) version of our published documentation. The "Latest" version is a mirror of the most recently released version of Rancher. As of August 2024, the most recently released version of Rancher is 2.9.
+For most updates, you'll need to edit a file in the `/docs` directory, which represents the ["Latest"](https://ranchermanager.docs.rancher.com/) version of our published documentation. The "Latest" version is a mirror of the most recently released version of Rancher. As of July 2025, the most recently released version of Rancher is 2.12.

 Whenever an update is made to `/docs`, you should apply the same change to the corresponding file in `/versioned_docs/version-2.9`. If a change only affects older versions, you don't need to mirror it to the `/docs` directory.

@@ -93,7 +93,7 @@ Subsequent executions will check for updated dependencies, if there are none, it

 License
 =======
-Copyright (c) 2014-2024 [Rancher Labs, Inc.](https://rancher.com)
+Copyright (c) 2014-2025 [SUSE, LLC.](https://www.suse.com/)

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -52,7 +52,7 @@ As an [administrator](../../../how-to-guides/advanced-user-guides/authentication
 > | 10252 | Controlplane | Kube controller manager |
 > | 2379 | Etcd | Etcd server |

-> Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to [migrate to Monitoring V2.](/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5%2B-monitoring.md)
+> Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to [migrate to Monitoring V2.](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5%2B-monitoring.md)

 1. From the **Global** view, navigate to the cluster that you want to configure cluster monitoring.

@@ -0,0 +1,105 @@
+---
+title: Prometheus Configuration
+---
+
+_Available as of v2.2.0_
+
+While configuring monitoring at either the [cluster level](cluster-monitoring.md) or [project level](./project-monitoring.md), there are multiple options that can be configured.
+
+- [Basic Configuration](#basic-configuration)
+- [Advanced Options](#advanced-options)
+- [Node Exporter](#node-exporter)
+- [Persistent Storage](#persistent-storage)
+- [Remote Storage](#remote-storage)
+
+## Basic Configuration
+
+Option | Description
+-------|-------------
+Data Retention | How long your Prometheus instance retains monitoring data scraped from Rancher objects before it's purged.
+[Enable Node Exporter](#node-exporter) | Whether or not to deploy the node exporter.
+Node Exporter Host Port | The host port on which data is exposed, i.e. data that Prometheus collects from your node hardware. Required if you have enabled the node exporter.
+[Enable Persistent Storage](#persistent-storage) for Prometheus | Whether or not to configure storage for Prometheus so that metrics can be retained even if the Prometheus pod fails.
+[Enable Persistent Storage](#persistent-storage) for Grafana | Whether or not to configure storage for Grafana so that the Grafana dashboards and configuration  can be retained even if the Grafana pod fails.
+Prometheus [CPU Limit](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu) |  CPU resource limit for the Prometheus pod.
+Prometheus [CPU Reservation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu) | CPU reservation for the Prometheus pod.
+Prometheus [Memory Limit](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) | Memory resource limit for the Prometheus pod.
+Prometheus [Memory Reservation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) | Memory resource requests for the Prometheus pod.
+Selector | Ability to select the nodes in which Prometheus and Grafana pods are deployed to. To use this option, the nodes must have labels.
+
+## Advanced Options
+
+Since monitoring is an [application](https://github.com/rancher/system-charts/tree/dev/charts/rancher-monitoring) from the [Rancher catalog](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), it can be configured like any other catalog application, by passing in values to Helm.
+
+> **Warning:** Any modification to the application without understanding the entire application can lead to catastrophic errors.
+
+### Prometheus RemoteRead and RemoteWrite
+
+_Available as of v2.4.0_
+
+Prometheus RemoteRead and RemoteWrite can be configured as custom answers in the **Advanced Options** section.
+
+For more information on remote endpoints and storage, refer to the [Prometheus documentation.](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage)
+
+The Prometheus operator documentation contains the full [RemoteReadSpec](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#remotereadspec) and [RemoteWriteSpec.](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#remotewritespec)
+
+An example configuration would be:
+
+| Variable | Value |
+|--------------|------------|
+|  `prometheus.remoteWrite[0].url` | `http://mytarget.com` |
+
+### LivenessProbe and ReadinessProbe
+
+_Available as of v2.4.0_
+
+Prometheus LivenessProbe and ReadinessProbe can be configured as custom answers in the **Advanced Options** section.
+
+The Kubernetes probe spec is [here.](https://v1-17.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#probe-v1-core)
+
+Some example key-value pairs are:
+
+| Variable | Value |
+|--------------|------------|
+| `prometheus.livenessProbe.timeoutSeconds` | 60 |
+| `prometheus.readinessProbe.timeoutSeconds` | 60 |
+
+## Node Exporter
+
+The [node exporter](https://github.com/prometheus/node_exporter/blob/master/README.md) is a popular open source exporter, which exposes the metrics for hardware and \*NIX kernels OS. It is designed to monitor the host system. However, there are still issues with namespaces when running it in a container, mostly around filesystem mount spaces. In order to monitor actual network metrics for the container network, the node exporter must be deployed with the `hostNetwork` mode.
+
+When configuring Prometheus and enabling the node exporter, enter a host port in the **Node Exporter Host Port** that will not produce port conflicts with existing applications. The host port chosen must be open to allow internal traffic between Prometheus and the Node Exporter.
+
+>**Warning:** In order for Prometheus to collect the metrics of the node exporter, after enabling cluster monitoring, you must open the <b>Node Exporter Host Port</b> in the host firewall rules to allow intranet access. By default, `9796` is used as that host port.
+
+## Persistent Storage
+
+>**Prerequisite:** Configure one or more StorageClasses to use as [persistent storage](../../../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) for your Prometheus or Grafana pod.
+
+By default, when you enable Prometheus for either a cluster or project, all monitoring data that Prometheus collects is stored on its own pod. With local storage, if the Prometheus or Grafana pods fail, all the data is lost. Rancher recommends configuring an external persistent storage to the cluster. With the external persistent storage, if the Prometheus or Grafana pods fail, the new pods can recover using data from the persistent storage.
+
+When enabling persistent storage for Prometheus or Grafana, specify the size of the persistent volume and select the StorageClass.
+
+## Remote Storage
+
+>**Prerequisite:** Need a remote storage endpoint to be available. The possible list of integrations is available [here](https://prometheus.io/docs/operating/integrations/)
+
+Using advanced options, remote storage integration for the Prometheus installation can be configured as follows:
+
+```
+prometheus.remoteWrite[0].url = http://remote1/push
+prometheus.remoteWrite[0].remoteTimeout = 33s
+
+prometheus.remoteWrite[1].url = http://remote2/push
+
+
+prometheus.remoteRead[0].url = http://remote1/read
+prometheus.remoteRead[0].proxyUrl = http://proxy.url
+prometheus.remoteRead[0].bearerToken = token-value
+
+prometheus.remoteRead[1].url = http://remote2/read
+prometheus.remoteRead[1].remoteTimeout = 33s
+prometheus.remoteRead[1].readRecent = true
+```
+
+Additional fields can be set up based on the [ReadSpec](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#remotereadspec) and [RemoteWriteSpec](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#remotewritespec)
@@ -155,15 +155,32 @@ You may terminate the SSL/TLS on a L7 load balancer external to the Rancher clus

 Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

-#### Configuring Ingress for External TLS when Using NGINX v0.25
+### Configuring Ingress for External TLS when Using NGINX v0.22

-In NGINX v0.25, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/main/Changelog.md#0220) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the `cluster.yml` to enable the `use-forwarded-headers` option for ingress:
+In NGINX v0.22, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/06efac9f0b6f8f84b553f58ccecf79dc42c75cc6/Changelog.md) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.22, you must enable the `use-forwarded-headers` option for ingress:

+For RKE installations, edit the `cluster.yml` to add the following settings.
 ```yaml
 ingress:
  provider: nginx
  options:
-    use-forwarded-headers: "true"
+    use-forwarded-headers: 'true'
+```
+
+For RKE2 installations, you can create a custom `rke2-ingress-nginx-config.yaml` file at `/var/lib/rancher/rke2/server/manifests/rke2-ingress-nginx-config.yaml` containing this required setting to enable using forwarded headers with external TLS termination. Without this required setting applied, the external LB will continuously respond with redirect loops it receives from the ingress controller. (This can be created before or after rancher is installed, rke2 server agent will notice this addition and automatically apply it.)
+
+```yaml
+---
+apiVersion: helm.cattle.io/v1
+kind: HelmChartConfig
+metadata:
+  name: rke2-ingress-nginx
+  namespace: kube-system
+spec:
+  valuesContent: |-
+    controller:
+      config:
+        use-forwarded-headers: "true"
 ```

 #### Required Headers
@@ -121,7 +121,7 @@ To test the overlay network, you can launch the following `DaemonSet` definition
          - image: alpine
            imagePullPolicy: Always
            name: alpine
-            command: ["sh", "-c", "tail -f /dev/null"]
+            command: ["sleep", "infinity"]
            terminationMessagePath: /dev/termination-log
    ```

@@ -0,0 +1,283 @@
+---
+title: Upgrades
+---
+
+<head>
+  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades"/>
+</head>
+
+The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.
+
+For the instructions to upgrade Rancher installed with Docker, refer to [this page.](../../other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md)
+
+To upgrade the components in your Kubernetes cluster, or the definition of the [Kubernetes services](https://rancher.com/docs/rke/latest/en/config-options/services/) or [add-ons](https://rancher.com/docs/rke/latest/en/config-options/add-ons/), refer to the [upgrade documentation for RKE](https://rancher.com/docs/rke/latest/en/upgrades/), the Rancher Kubernetes Engine.
+
+If you installed Rancher using the RKE Add-on yaml, follow the directions to [migrate or upgrade](migrating-from-rke-add-on.md).
+
+- [Prerequisites](#prerequisites)
+- [Upgrade Outline](#upgrade-outline)
+- [Known Upgrade Issues](#known-upgrade-issues)
+- [RKE Add-on Installs](#rke-add-on-installs)
+
+## Prerequisites
+
+### Access to kubeconfig
+
+Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.
+
+If you installed Kubernetes with RKE, the config will have been created in the directory you ran `rke up` in.
+
+The kubeconfig can also be manually targeted for the intended cluster with the `--kubeconfig` tag (see: https://helm.sh/docs/helm/helm/)
+
+### Review Known Issues
+
+Review the [known upgrade issues](#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.
+
+A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
+
+Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren't supported.
+
+### Helm Version
+
+The upgrade instructions assume you are using Helm 3.
+
+For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here](helm2.md) provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
+
+### For air gap installs: Populate private registry
+
+-For [air gap installs only,](../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
+
+### For upgrades from v2.0-v2.2 with external TLS termination
+
+If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.](../../../../reference-guides/installation-references/helm-chart-options.md#configuring-ingress-for-external-tls-when-using-nginx-v025)
+
+### For upgrades with cert-manager older than 0.8.0
+
+[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) Upgrade cert-manager to the latest version by following [these instructions.](../../resources/upgrade-cert-manager.md)
+
+## Upgrade Outline
+
+Follow the steps to upgrade Rancher server:
+
+- [1. Back up your Kubernetes cluster that is running Rancher server](#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server)
+- [2. Update the Helm chart repository](#2-update-the-helm-chart-repository)
+- [3. Upgrade Rancher](#3-upgrade-rancher)
+- [4. Verify the Upgrade](#4-verify-the-upgrade)
+
+## 1. Back up Your Kubernetes Cluster that is Running Rancher Server
+
+
+[Take a one-time snapshot](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#option-b-one-time-snapshots)
+of your Kubernetes cluster running Rancher server.
+
+You'll use the backup as a restoration point if something goes wrong during upgrade.
+
+## 2. Update the Helm chart repository
+
+1. Update your local Helm repo cache:
+
+    ```
+    helm repo update
+    ```
+
+1. Get the repository name that you used to install Rancher.
+
+    For information about the repos and their differences, see [Helm Chart Repositories](../../resources/choose-a-rancher-version.md#helm-chart-repositories).
+
+    - Latest: Recommended for trying out the newest features
+        ```
+        helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
+        ```
+    - Stable: Recommended for production environments
+        ```
+        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
+        ```
+    - Alpha: Experimental preview of upcoming releases.
+        ```
+        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
+        ```
+        Note: Upgrades are not supported to, from, or between Alphas.
+
+    ```
+    helm repo list
+
+    NAME          	       URL
+    stable        	       https://charts.helm.sh/stable
+    rancher-<CHART_REPO>	 https://releases.rancher.com/server-charts/<CHART_REPO>
+    ```
+
+    > **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories](../../resources/choose-a-rancher-version.md#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.
+
+1. Fetch the latest chart to install Rancher from the Helm chart repository.
+
+    This command will pull down the latest charts and save it in the current directory as a `.tgz` file.
+
+    ```plain
+    helm fetch rancher-<CHART_REPO>/rancher
+    ```
+    You can fetch the chart for the specific version you are upgrading to by adding in the `--version=` tag.  For example:
+
+    ```plain
+    helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11
+    ```
+
+## 3. Upgrade Rancher
+
+This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
+
+<Tabs>
+<TabItem value="Kubernetes Upgrade">
+
+Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.
+
+```
+helm get values rancher -n cattle-system
+
+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 and cert-manager.](#option-b-reinstalling-rancher-and-cert-manager)
+
+Otherwise, follow [Option A: Upgrading Rancher.](#option-a-upgrading-rancher)
+
+### Option A: Upgrading Rancher
+
+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`:
+
+```
+helm upgrade rancher rancher-<CHART_REPO>/rancher \
+  --namespace cattle-system \
+  --set hostname=rancher.my.org
+```
+
+> **Note:** The above is an example, there may be more values from the previous step that need to be appended.
+
+Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
+
+```
+helm get values rancher -n cattle-system -o yaml > values.yaml
+
+helm upgrade rancher rancher-<CHART_REPO>/rancher \
+  --namespace cattle-system \
+  -f values.yaml \
+  --version=2.4.5
+```
+
+### 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.
+
+1. Uninstall Rancher
+
+    ```
+    helm delete rancher -n cattle-system
+    ```
+
+2. Uninstall and reinstall `cert-manager` according to the instructions on the [Upgrading Cert-Manager](../../resources/upgrade-cert-manager-helm-2.md) page.
+
+3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using `--set key=value`. Note: There will be many more options from the step 1 that need to be appended.
+
+    ```
+    helm install rancher rancher-<CHART_REPO>/rancher \
+    --namespace cattle-system \
+    --set hostname=rancher.my.org
+    ```
+
+</TabItem>
+<TabItem value="Kubernetes Air Gap Upgrade">
+
+Render the Rancher template using the same chosen options that were used when installing Rancher. 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.
+
+Based on the choice you made during installation, complete one of the procedures below.
+
+Placeholder | Description
+------------|-------------
+`<VERSION>` | The version number of the output tarball.
+`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
+`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
+`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
+
+### Option A: Default Self-signed Certificate
+
+ ```plain
+helm template ./rancher-<VERSION>.tgz --output-dir . \
+ --name rancher \
+ --namespace cattle-system \
+ --set hostname=<RANCHER.YOURDOMAIN.COM> \
+ --set certmanager.version=<CERTMANAGER_VERSION> \
+ --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
+ --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # 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
+```
+
+### Option B: Certificates from Files using Kubernetes Secrets
+
+```plain
+helm template ./rancher-<VERSION>.tgz --output-dir . \
+--name rancher \
+--namespace cattle-system \
+--set hostname=<RANCHER.YOURDOMAIN.COM> \
+--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
+--set ingress.tls.source=secret \
+--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # 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
+```
+
+If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
+
+```plain
+helm template ./rancher-<VERSION>.tgz --output-dir . \
+--name rancher \
+--namespace cattle-system \
+--set hostname=<RANCHER.YOURDOMAIN.COM> \
+--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
+--set ingress.tls.source=secret \
+--set privateCA=true \
+--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # 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
+```
+
+### Apply the Rendered Templates
+
+Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.
+
+Use `kubectl` to apply the rendered manifests.
+
+```plain
+kubectl -n cattle-system apply -R -f ./rancher
+```
+
+</TabItem>
+</Tabs>
+
+## 4. Verify the Upgrade
+
+Log into Rancher to confirm that the upgrade succeeded.
+
+>**Having network issues following upgrade?**
+>
+> See [Restoring Cluster Networking](namespace-migration.md#restoring-cluster-networking).
+
+## Known Upgrade Issues
+
+The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
+
+Upgrade Scenario | Issue
+---|---
+Upgrading to v2.4.6 or v2.4.7 | These Rancher versions had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.
+Upgrading to v2.3.0+ | Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.
+Upgrading to v2.2.0-v2.2.x | Rancher introduced the [system charts](https://github.com/rancher/system-charts) repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the `system-charts` repository locally and configure Rancher to use that repository. Please follow the instructions to [configure Rancher system charts](../../resources/local-system-charts.md).
+Upgrading from v2.0.13 or earlier  | If your cluster's certificates have expired, you will need to perform [additional steps](../../../../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
+Upgrading from v2.0.7 or earlier | Rancher introduced the `system` project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to [prevent cluster networking issues.](namespace-migration.md)
+
+## RKE Add-on Installs
+
+**Important: RKE add-on install is only supported up to Rancher v2.0.8**
+
+Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../install-upgrade-on-a-kubernetes-cluster.md).
+
+If you are currently using the RKE add-on install method, see [Migrating from a RKE add-on install](migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
--- a/Show More
+++ b/Show More