Convert h1 to h2 (2.5)

2026-05-19 11:25:15 +00:00 · 2022-10-28 17:08:01 -07:00
parent 15a1e067a6
commit bb76e99d20
87 changed files with 319 additions and 336 deletions
@@ -33,7 +33,7 @@ sudo iptables --list

 This section describes how to use `firewalld` to apply the [firewall port rules](../../installation-requirements/port-requirements.md) for nodes in a high-availability Rancher server cluster.

-# Prerequisite
+## Prerequisite

 Install v7.x or later ofv`firewalld`:

@@ -43,7 +43,7 @@ systemctl start firewalld
 systemctl enable firewalld
 ```

-# Applying Firewall Port Rules
+## Applying Firewall Port Rules

 In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node:

@@ -13,7 +13,7 @@ Environment Variable Key | Default Value | Status | Available as of
 `istio-virtual-service-ui` |`false` |  Experimental | v2.3.0
 `istio-virtual-service-ui` | `true` | GA                    | v2.3.2

-# About this Feature
+## About this Feature

 A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing.

@@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem';

 > These instructions assume you have already followed the instructions for a Kubernetes upgrade on [this page,](upgrades.md) including the prerequisites, up until step 3. Upgrade Rancher.

-### Rancher Helm Template Options
+## Rancher Helm Template Options

 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.

@@ -20,7 +20,6 @@ Placeholder | Description
 `<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

 <Tabs>
@@ -112,8 +111,7 @@ helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
 </TabItem>
 </Tabs>

-
-### Apply the Rendered Templates
+## Apply the Rendered Templates

 Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.

@@ -123,7 +121,7 @@ Use `kubectl` to apply the rendered manifests.
 kubectl -n cattle-system apply -R -f ./rancher
 ```

-# Verify the Upgrade
+## Verify the Upgrade

 Log into Rancher to confirm that the upgrade succeeded.

@@ -131,6 +129,6 @@ Log into Rancher to confirm that the upgrade succeeded.
 >
 > See [Restoring Cluster Networking](../../../../version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md).

-# Known Upgrade Issues
+## Known Upgrade Issues

 A 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)
@@ -8,7 +8,7 @@ The guide uses command line tools to provision an AKS cluster with an ingress. I

 If you already have an AKS Kubernetes cluster, skip to the step about [installing an ingress.](#5-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart)

-# Prerequisites
+## Prerequisites

 >**Note**
 >Deploying to Microsoft Azure will incur charges.
@@ -19,7 +19,7 @@ If you already have an AKS Kubernetes cluster, skip to the step about [installin
 - Your subscription has sufficient quota for at least 2 vCPUs. For details on Rancher server resource requirements, refer to [this section](../../../pages-for-subheaders/installation-requirements.md#rke-and-hosted-kubernetes)
 - When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations).

-# 1. Prepare your Workstation
+## 1. Prepare your Workstation

 Install the following command line tools on your workstation:

@@ -27,7 +27,7 @@ Install the following command line tools on your workstation:
 - **kubectl:** For help, refer to these [installation steps.](https://kubernetes.io/docs/tasks/tools/#kubectl)
 - **helm:** For help, refer to these [installation steps.](https://helm.sh/docs/intro/install/)

-# 2. Create a Resource Group
+## 2. Create a Resource Group

 After installing the CLI, you will need to log in with your Azure account.

@@ -41,7 +41,7 @@ Create a [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-
 az group create --name rancher-rg --location eastus
 ```

-# 3. Create the AKS Cluster
+## 3. Create the AKS Cluster

 To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to [this article](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes) for available sizes and options. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.

@@ -56,7 +56,7 @@ az aks create \

 The cluster will take some time to be deployed.

-# 4. Get Access Credentials
+## 4. Get Access Credentials

 After the cluster is deployed, get the access credentials.

@@ -66,7 +66,7 @@ az aks get-credentials --resource-group rancher-rg --name rancher-server

 This command merges your cluster's credentials into the existing kubeconfig and allows `kubectl` to interact with the cluster.

-# 5. Install an Ingress
+## 5. Install an Ingress

 The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription.

@@ -83,7 +83,7 @@ helm upgrade --install \
  --create-namespace
 ```

-# 6. Get Load Balancer IP
+## 6. Get Load Balancer IP

 To get the address of the load balancer, run:

@@ -102,7 +102,7 @@ ingress-nginx-controller   LoadBalancer   10.0.116.18    40.31.180.83   80:31229

 Save the `EXTERNAL-IP`.

-# 7. Set up DNS
+## 7. Set up DNS

 External traffic to the Rancher server will need to be directed at the load balancer you created.

@@ -110,7 +110,7 @@ Set up a DNS to point at the `EXTERNAL-IP` that you saved. This DNS will be used

 There are many valid ways to set up the DNS. For help, refer to the [Azure DNS documentation](https://docs.microsoft.com/en-us/azure/dns/)

-# 8. Install the Rancher Helm Chart
+## 8. Install the Rancher Helm Chart

 Next, install the Rancher Helm chart by following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

@@ -13,7 +13,7 @@ If you already have an EKS Kubernetes cluster, skip to the step about [installin
 - [Automated Quickstart using AWS Best Practices](#automated-quickstart-using-aws-best-practices)
 - [Creating an EKS Cluster for the Rancher Server](#creating-an-eks-cluster-for-the-rancher-server)

-# Automated Quickstart using AWS Best Practices
+## Automated Quickstart using AWS Best Practices

 Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS cluster following AWS best practices. The deployment guide is [here.](https://aws-quickstart.github.io/quickstart-eks-rancher/)

@@ -39,7 +39,7 @@ Deploying this Quick Start for a new virtual private cloud (VPC) and new Amazon

 \* The CloudFormation template that deploys the Quick Start into an existing Amazon EKS cluster skips the components marked by asterisks and prompts you for your existing VPC configuration.

-# Creating an EKS Cluster for the Rancher Server
+## Creating an EKS Cluster for the Rancher Server

 In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.

@@ -9,13 +9,13 @@ In this section, you'll learn how to install Rancher using Google Kubernetes Eng

 If you already have a GKE Kubernetes cluster, skip to the step about [installing an ingress.](#7-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart)

-# Prerequisites
+## Prerequisites

 - You will need a Google account.
 - You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit [General guide to the console.](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599)
 - You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to [this section.](../../../pages-for-subheaders/installation-requirements.md#rke-and-hosted-kubernetes)

-# 1. Enable the Kubernetes Engine API
+## 1. Enable the Kubernetes Engine API

 Take the following steps to enable the Kubernetes Engine API:

@@ -24,7 +24,7 @@ Take the following steps to enable the Kubernetes Engine API:
 1. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes.
 1. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the [Google Cloud documentation.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)

-# 2. Open the Cloud Shell
+## 2. Open the Cloud Shell

 Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the `gcloud` command-line tool and kubectl command-line tool. The `gcloud` tool provides the primary command-line interface for Google Cloud, and `kubectl` provides the primary command-line interface for running commands against Kubernetes clusters.

@@ -63,7 +63,7 @@ To install `gcloud` and `kubectl`, perform the following steps:



-# 3. Configure the gcloud CLI
+## 3. Configure the gcloud CLI

 Set up default gcloud settings using one of the following methods:

@@ -91,7 +91,7 @@ To install `gcloud` and `kubectl`, perform the following steps:
 </TabItem>
 </Tabs>

-# 4. Confirm that gcloud is configured correctly
+## 4. Confirm that gcloud is configured correctly

 Run:

@@ -113,7 +113,7 @@ project = <Your project ID>
 Your active configuration is: [default]
 ```

-# 5. Create a GKE Cluster
+## 5. Create a GKE Cluster

 The following command creates a three-node cluster.

@@ -125,7 +125,7 @@ When choosing a Kubernetes version, be sure to first consult the [support matrix
 gcloud container clusters create cluster-name --num-nodes=3 --cluster-version=1.20.10-gke.301
 ```

-# 6. Get Authentication Credentials
+## 6. Get Authentication Credentials

 After creating your cluster, you need to get authentication credentials to interact with the cluster:

@@ -135,7 +135,7 @@ gcloud container clusters get-credentials cluster-name

 This command configures `kubectl` to use the cluster you created.

-# 7. Install an Ingress
+## 7. Install an Ingress

 The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.

@@ -152,7 +152,7 @@ helm upgrade --install \
  --create-namespace
 ```

-# 8. Get the Load Balancer IP
+## 8. Get the Load Balancer IP

 To get the address of the load balancer, run:

@@ -169,7 +169,7 @@ ingress-nginx-controller   LoadBalancer   10.3.244.156   35.233.206.34   80:3187

 Save the `EXTERNAL-IP`.

-# 9. Set up DNS
+## 9. Set up DNS

 External traffic to the Rancher server will need to be directed at the load balancer you created.

@@ -177,7 +177,7 @@ Set up a DNS to point at the external IP that you saved. This DNS will be used a

 There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about [managing DNS records.](https://cloud.google.com/dns/docs/records)

-# 10. Install the Rancher Helm chart
+## 10. Install the Rancher Helm chart

 Next, install the Rancher Helm chart by following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

@@ -6,7 +6,7 @@ title: Rollbacks
 - [Rolling Back to Rancher v2.2-v2.4+](#rolling-back-to-rancher-v2-2-v2-4)
 - [Rolling Back to Rancher v2.0-v2.1](#rolling-back-to-rancher-v2-0-v2-1)

-# Rolling Back to Rancher v2.5.0+
+## Rolling Back to Rancher v2.5.0+

 To roll back to Rancher v2.5.0+, use the **Rancher Backups** application and restore Rancher from backup.

@@ -90,7 +90,7 @@ When the target revision is determined, perform the rollback. This example will
 helm rollback rancher 3 -n cattle-system
 ```

-# Rolling Back to Rancher v2.2-v2.4+
+## Rolling Back to Rancher v2.2-v2.4+

 To roll back to Rancher before v2.5, follow the procedure detailed here: [Restoring Backups — Kubernetes installs](../../../../version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Restoring a snapshot of the Rancher server cluster will revert Rancher to the version and state at the time of the snapshot.

@@ -98,6 +98,6 @@ For information on how to roll back Rancher installed with Docker, refer to [thi

 > Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.

-# Rolling Back to Rancher v2.0-v2.1
+## Rolling Back to Rancher v2.0-v2.1

 Rolling back to Rancher v2.0-v2.1 is no longer supported. The instructions for rolling back to these versions are preserved [here](../../../../version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) and are intended to be used only in cases where upgrading to Rancher v2.2+ is not feasible.
@@ -15,7 +15,7 @@ To upgrade the components in your Kubernetes cluster, or the definition of the [
 - [Known Upgrade Issues](#known-upgrade-issues)
 - [RKE Add-on Installs](#rke-add-on-installs)

-# Prerequisites
+## Prerequisites

 ### Access to kubeconfig

@@ -49,7 +49,7 @@ If you are upgrading to Rancher v2.5 from a Rancher server that was started with

 [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
+## Upgrade Outline

 Follow the steps to upgrade Rancher server:

@@ -58,13 +58,13 @@ Follow the steps to upgrade Rancher server:
 - [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
+## 1. Back up Your Kubernetes Cluster that is Running Rancher Server

 Use the [backup application](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) to back up Rancher.

 You'll use the backup as a restoration point if something goes wrong during upgrade.

-# 2. Update the Helm chart repository
+## 2. Update the Helm chart repository

 1. Update your local helm repo cache.

@@ -114,7 +114,7 @@ You'll use the backup as a restoration point if something goes wrong during upgr
    helm fetch rancher-<CHART_REPO>/rancher --version=2.5.16
    ```

-# 3. Upgrade Rancher
+## 3. Upgrade Rancher

 This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.

@@ -180,7 +180,7 @@ If you are currently running the cert-manager whose version is older than v0.11,
    --set hostname=rancher.my.org
    ```

-# 4. Verify the Upgrade
+## 4. Verify the Upgrade

 Log into Rancher to confirm that the upgrade succeeded.

@@ -188,6 +188,6 @@ Log into Rancher to confirm that the upgrade succeeded.
 >
 > See [Restoring Cluster Networking](../../../../version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md).

-# Known Upgrade Issues
+## Known Upgrade Issues

 A 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)
@@ -11,7 +11,7 @@ import PortsImportedHosted from '@site/src/components/PortsImportedHosted'

 To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes.

-# Rancher Nodes
+## Rancher Nodes

 The following table lists the ports that need to be open to and from nodes that are running the Rancher server.

@@ -163,7 +163,7 @@ The following tables break down the port requirements for Rancher nodes, for inb

 </details>

-# Downstream Kubernetes Cluster Nodes
+## Downstream Kubernetes Cluster Nodes

 Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.

@@ -229,7 +229,7 @@ The following table depicts the port requirements for [registered clusters](../.
 </details>


-# Other Port Considerations
+## Other Port Considerations

 ### Commonly Used Ports

@@ -11,11 +11,11 @@ This section is about how to deploy Rancher for your air gapped environment in a

 When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the `--privileged` option.

-# Docker Instructions
+## Docker Instructions

 If you want to continue the air gapped installation using Docker commands, skip the rest of this page and follow the instructions on [this page.](docker-install-commands.md)

-# Kubernetes Instructions
+## Kubernetes Instructions

 Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.

@@ -26,7 +26,7 @@ This section describes installing Rancher:
 - [3. Render the Rancher Helm Template](#3-render-the-rancher-helm-template)
 - [4. Install Rancher](#4-install-rancher)

-# 1. Add the Helm Chart Repository
+## 1. Add the Helm Chart Repository

 From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.

@@ -57,7 +57,7 @@ From a system that has access to the internet, fetch the latest Helm chart and c
    helm fetch rancher-stable/rancher --version=v2.4.8
    ```

-# 2. Choose your SSL Configuration
+## 2. Choose your SSL Configuration

 Rancher Server is designed to be secure by default and requires SSL/TLS configuration.

@@ -70,7 +70,7 @@ When Rancher is installed on an air gapped Kubernetes cluster, there are two rec
 | Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)<br/> This is the **default** and does not need to be added when rendering the Helm template. | yes                   |
 | Certificates from Files                    | `ingress.tls.source=secret`  | Use your own certificate files by creating Kubernetes Secret(s). <br/> This option must be passed when rendering the Rancher Helm template.                  | no                    |

-# Helm Chart Options for Air Gap Installations
+## Helm Chart Options for Air Gap Installations

 When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.

@@ -80,11 +80,11 @@ When setting up the Rancher Helm template, there are several options in the Helm
 | `systemDefaultRegistry` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | 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. |

-# 3. Render the Rancher Helm Template
+## 3. Render the Rancher Helm Template

 Based on the choice your made in [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration), complete one of the procedures below.

-# Option A: Default Self-Signed Certificate
+## Option A: Default Self-Signed Certificate


 By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.
@@ -177,7 +177,7 @@ helm template rancher ./rancher-<VERSION>.tgz --output-dir . \



-# Option B: Certificates From Files using Kubernetes Secrets
+## Option B: Certificates From Files using Kubernetes Secrets


 ### 1. Create secrets
@@ -262,7 +262,7 @@ Then refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md/) to publi



-# 4. Install Rancher
+## 4. Install Rancher

 Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.

@@ -307,7 +307,7 @@ The installation is complete.

 > **Note:** If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

-# Additional Resources
+## Additional Resources

 These resources could be helpful when installing Rancher:

@@ -110,7 +110,7 @@ The `rancher-images.txt` is expected to be on the workstation in the same direct

 For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests.

-# Windows Steps
+## Windows Steps

 The Windows images need to be collected and pushed from a Windows server workstation.

@@ -189,7 +189,7 @@ The `rancher-windows-images.txt` is expected to be on the workstation in the sam
   ./rancher-load-images.ps1 --registry <REGISTRY.YOURDOMAIN.COM:PORT>
   ```

-# Linux Steps
+## Linux Steps

 The Linux images need to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images.

@@ -7,12 +7,12 @@ import TabItem from '@theme/TabItem';

 The following instructions will guide you through upgrading a Rancher server that was installed with Docker.

-# Prerequisites
+## Prerequisites

 - **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#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](../../../../reference-guides/installation-references/helm-chart-options.md#helm-chart-repositories/) aren’t supported.
 - **For [air gap installs only,](../../../../pages-for-subheaders/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry](../air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.

-# Placeholder Review
+## Placeholder Review

 During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`).

@@ -24,7 +24,7 @@ docker stop <RANCHER_CONTAINER_NAME>

 In this command, `<RANCHER_CONTAINER_NAME>` is the name of your Rancher container.

-# Get Data for Upgrade Commands
+## Get Data for Upgrade Commands

 To obtain the data to replace the placeholders, run:

@@ -48,7 +48,7 @@ Write down or copy this information before starting the upgrade.

 You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by logging into your Rancher server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups.

-# Upgrade Outline
+## Upgrade Outline

 During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. Follow the steps to upgrade Rancher server:

@@ -59,7 +59,7 @@ During upgrade, you create a copy of the data from your current Rancher containe
 - [5. Verify the Upgrade](#5-verify-the-upgrade)
 - [6. Clean up your old Rancher server container](#6-clean-up-your-old-rancher-server-container)

-# 1. Create a copy of the data from your Rancher server container
+## 1. Create a copy of the data from your Rancher server container

 1. Using a remote Terminal connection, log into the node running your Rancher server.

@@ -75,7 +75,7 @@ During upgrade, you create a copy of the data from your current Rancher containe
    docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>
    ```

-# 2. Create a backup tarball
+## 2. Create a backup tarball

 1. <a id="tarball"></a>From the data container that you just created (<code>rancher-data</code>), create a backup tarball (<code>rancher-data-backup-&lt;RANCHER_VERSION&gt;-&lt;DATE&gt;.tar.gz</code>).

@@ -97,7 +97,7 @@ During upgrade, you create a copy of the data from your current Rancher containe

 1. Move your backup tarball to a safe location external from your Rancher server.

-# 3. Pull the New Docker Image
+## 3. Pull the New Docker Image

 Pull the image of the Rancher version that you want to upgrade to.

@@ -109,7 +109,7 @@ Placeholder | Description
 docker pull rancher/rancher:<RANCHER_VERSION_TAG>
 ```

-# 4. Start the New Rancher Server Container
+## 4. Start the New Rancher Server Container

 Start a new Rancher server container using the data from the `rancher-data` container. Remember to pass in all the environment variables that you had used when you started the original container.

@@ -351,7 +351,7 @@ As of Rancher v2.5, privileged access is [required.](../../../../pages-for-subhe

 **Result:** You have upgraded Rancher. Data from your upgraded server is now saved to the `rancher-data` container for use in future upgrades.

-# 5. Verify the Upgrade
+## 5. Verify the Upgrade

 Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window.

@@ -360,10 +360,10 @@ Log into Rancher. Confirm that the upgrade succeeded by checking the version dis
 > See [Restoring Cluster Networking](../../../../../version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md).


-# 6. Clean up Your Old Rancher Server Container
+## 6. Clean up Your Old Rancher Server Container

 Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot.

-# Rolling Back
+## Rolling Back

 If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see [Docker Rollback](roll-back-docker-installed-rancher.md).
@@ -19,7 +19,7 @@ kubectl -n cattle-system create secret tls tls-rancher-ingress \

 > **Note:** If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.

-# Using a Private CA Signed Certificate
+## Using a Private CA Signed Certificate

 If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server.

@@ -32,6 +32,6 @@ kubectl -n cattle-system create secret generic tls-ca \

 > **Note:** The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started.

-# Updating a Private CA Certificate
+## Updating a Private CA Certificate

 Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.
@@ -6,9 +6,8 @@ The [System Charts](https://github.com/rancher/system-charts) repository contain

 In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag.

-# Using Local System Charts
+## Using Local System Charts

 A local copy of `system-charts` has been packaged into the `rancher/rancher` container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, `CATTLE_SYSTEM_CATALOG=bundled`, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub.

 Example commands for a Rancher installation with a bundled `system-charts` are included in the [air gap Docker installation](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md) instructions and the [air gap Kubernetes installation](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md) instructions.
-
@@ -2,7 +2,7 @@
 title: Updating the Rancher Certificate
 ---

-# Updating a Private CA Certificate
+## Updating a Private CA Certificate

 Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate.

@@ -16,7 +16,7 @@ A summary of the steps is as follows:

 The details of these instructions are below.

-## 1. Create/update the certificate secret resource
+### 1. Create/update the certificate secret resource

 First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`.

@@ -37,7 +37,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --dry-run --save-config -o yaml | kubectl apply -f -
 ```

-## 2. Create/update the CA certificate secret resource
+### 2. Create/update the CA certificate secret resource

 If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named `cacerts.pem` and create or update the `tls-ca secret` in the `cattle-system` namespace. If the certificate was signed by an intermediate CA, then the `cacerts.pem` must contain both the intermediate and root CA certificates (in this order).

@@ -56,7 +56,7 @@ $ kubectl -n cattle-system create secret generic tls-ca \
  --dry-run --save-config -o yaml | kubectl apply -f -
 ```

-## 3. Reconfigure the Rancher deployment
+### 3. Reconfigure the Rancher deployment

 > Before proceeding, generate an API token in the Rancher UI (<b>User > API & Keys</b>) and save the Bearer Token which you might need in step 4.

@@ -91,18 +91,18 @@ helm upgrade rancher rancher-stable/rancher \

 When the upgrade is completed, navigate to `https://<Rancher_SERVER>/v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier.

-## 4. Reconfigure Rancher agents to trust the private CA
+### 4. Reconfigure Rancher agents to trust the private CA

 This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true:

 - Rancher was initially configured to use the Rancher self-signed certificate (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`)
 - The root CA certificate for the new custom certificate has changed

-### Why is this step required?
+#### Why is this step required?

 When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the `CATTLE_CA_CHECKSUM` environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable `CATTLE_CA_CHECKSUM` must be updated accordingly.

-### Which method should I choose?
+#### Which method should I choose?

 Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3).

@@ -110,7 +110,7 @@ If the clusters have lost connection to Rancher but you have [Authorized Cluster

 Method 3 can be used as a fallback if method 1 and 2 are unfeasible.

-### Method 1: Kubectl command
+#### Method 1: Kubectl command

 For each cluster under Rancher management (except the `local` Rancher management cluster) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S).

@@ -120,8 +120,7 @@ kubectl patch clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> -p '{"statu

 This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate.

-
-### Method 2: Manually update checksum
+#### Method 2: Manually update checksum

 Manually patch the agent Kubernetes resources by updating the `CATTLE_CA_CHECKSUM` environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so:

@@ -137,7 +136,7 @@ $ kubectl edit -n cattle-system ds/cattle-node-agent
 $ kubectl edit -n cattle-system deployment/cattle-cluster-agent
 ```

-### Method 3: Recreate Rancher agents
+#### Method 3: Recreate Rancher agents

 With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster.

@@ -147,7 +146,7 @@ Then, connect to a controlplane node of the downstream cluster via SSH, create a
 https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b


-## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher
+### 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher

 Select 'Force Update' for the clusters within the [Continuous Delivery](../../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md#accessing-fleet-in-the-rancher-ui) view under Cluster Explorer in the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.

@@ -155,11 +154,11 @@ Select 'Force Update' for the clusters within the [Continuous Delivery](../../..

 Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher.

-# Updating from a Private CA Certificate to a Common Certificate
+## Updating from a Private CA Certificate to a Common Certificate

 >It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below.

-## 1. Create/update the certificate secret resource
+### 1. Create/update the certificate secret resource

 First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`.

@@ -180,7 +179,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --dry-run --save-config -o yaml | kubectl apply -f -
 ```

-## 2. Delete the CA certificate secret resource
+### 2. Delete the CA certificate secret resource

 You will delete the `tls-ca secret` in the `cattle-system` namespace as it is no longer needed. You may also optionally save a copy of the `tls-ca secret` if desired.

@@ -196,7 +195,7 @@ To delete the existing `tls-ca` secret:
 kubectl -n cattle-system delete secret tls-ca
 ```

-## 3. Reconfigure the Rancher deployment
+### 3. Reconfigure the Rancher deployment

 > Before proceeding, [generate an API token in the Rancher UI](../../../reference-guides/user-settings/api-keys.md#creating-an-api-key) (<b>User > API & Keys</b>).

@@ -238,14 +237,14 @@ On upgrade, you can either
 set privateCA=false
 ```

-## 4. Reconfigure Rancher agents for the non-private/common certificate
+### 4. Reconfigure Rancher agents for the non-private/common certificate

 `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string).

-## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher
+### 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher

 Select 'Force Update' for the clusters within the [Continuous Delivery](../../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md#accessing-fleet-in-the-rancher-ui) view under Cluster Explorer in the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.

-### Why is this step required?
+#### Why is this step required?

 Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher.
@@ -24,7 +24,7 @@ To address these changes, this guide will do two things:

 > For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../install-upgrade-on-a-kubernetes-cluster/upgrades.md) under the upgrade Rancher section.

-# Upgrade Cert-Manager
+## Upgrade Cert-Manager

 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.

@@ -239,4 +239,3 @@ We have also removed support for the old configuration format that was deprecate
 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/).
-
@@ -45,7 +45,7 @@ The restore operation will work on a cluster that is not in a healthy or active

 **Result:** Kubernetes begins upgrading for the cluster.

-# Rolling Back
+## Rolling Back

 A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections:

@@ -4,11 +4,11 @@ title: Overview

 Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams.

-# Run Kubernetes Everywhere
+## Run Kubernetes Everywhere

 Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer.

-# Meet IT requirements
+## Meet IT requirements

 Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can:

@@ -16,7 +16,7 @@ Rancher supports centralized authentication, access control, and monitoring for
 - Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds.
 - View the health and capacity of your Kubernetes clusters from a single-pane-of-glass.

-# Empower DevOps Teams
+## Empower DevOps Teams

 Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers.

@@ -24,7 +24,7 @@ The following figure illustrates the role Rancher plays in IT and DevOps organiz

 ![Platform](/img/platform.png)

-# Features of the Rancher API Server
+## Features of the Rancher API Server

 The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:

@@ -52,7 +52,7 @@ The Rancher API server is built on top of an embedded Kubernetes API server and
 - **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.
 - **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned.

-# Editing Downstream Clusters with Rancher
+## Editing Downstream Clusters with Rancher

 The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) have **Cluster Options** available for editing.