Fix order of headings (#1465)

* Fix 'title out of sequence' errors fixed Dockershim.md * fixed deprecated-features.md * fixed install-and-configure-kubectl.md * fixed rancher-is-no-longer-needed.md * fixed security.md * fixed technical-items.md + spacing, duplicate section, admonitions * fixed telemetry.md * fixed upgrades.md * fixed upgrade-kubernetes-without-upgrading-rancher.md * fixed air-gapped-upgrades.md * fixed dockershim.md * fixed docker-install-commands.md * fixed install-kubernetes.md * fixed infrastructure-private-registry.md * fixed install-rancher-ha * fixed manage-namespaces and tune-etcd-for-large-installs.md * fixed cis-scans/configuration-reference.md * fixed custom-benchmark.md * fixed supportconfig.md * fixed harvester/overview.md * fixed logging-architecture.md * fixed logging-helm-chart-options.md + rm'd unnecessary annotation title * fixed taints-and-tolerances.md * fixed longhorn/overview.md * fixed neuvector/overview.md * fixed monitoring-and-alerting * fixed rancher-cli.md * fixed cluster-configuration.md * fixed monitoring-v2-configuration/examples.md * fixed servicemonitors-and-podmonitors.md * fixed other-troubleshooting-tips/dns.md
2026-05-21 20:35:27 +00:00 · 2024-09-18 14:02:55 -04:00
parent 9f8e1a7a53
commit c869ea69ac
191 changed files with 1059 additions and 1135 deletions
@@ -12,7 +12,7 @@ These instructions assume you have already followed the instructions for a Kuber

 :::

-### Rancher Helm Upgrade Options
+## Rancher Helm Upgrade Options

 To upgrade with Helm, apply the same options that you used when installing Rancher. Refer to 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.

@@ -12,7 +12,6 @@ For the instructions to upgrade Rancher installed with Docker, refer to [this pa

 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.

-
 ## Prerequisites

 ### Access to kubeconfig
@@ -119,7 +118,6 @@ If you are installing Rancher in an air-gapped environment, skip the rest of thi

 :::

-
 Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.

 ```
@@ -22,7 +22,7 @@ Starting with version 1.24, the above defaults to true.

 For users looking to use another container runtime, Rancher has the edge-focused K3s and datacenter-focused RKE2 Kubernetes distributions that use containerd as the default runtime. Imported RKE2 and K3s Kubernetes clusters can then be upgraded and managed through Rancher going forward.

-### FAQ
+## FAQ

 <br/>

@@ -28,7 +28,7 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher

 Choose from the following options:

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

 <details id="option-a">
  <summary>Click to expand</summary>
@@ -55,7 +55,7 @@ docker run -d --restart=unless-stopped \

 </details>

-### Option B: Bring Your Own Certificate: Self-Signed
+## Option B: Bring Your Own Certificate: Self-Signed

 <details id="option-b">
  <summary>Click to expand</summary>
@@ -98,7 +98,7 @@ docker run -d --restart=unless-stopped \

 </details>

-### Option C: Bring Your Own Certificate: Signed by Recognized CA
+## Option C: Bring Your Own Certificate: Signed by Recognized CA

 <details id="option-c">
  <summary>Click to expand</summary>
@@ -143,8 +143,6 @@ docker run -d --restart=unless-stopped \

 </details>

-
-
 :::note

 If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login.
@@ -25,7 +25,7 @@ We recommend setting up the following infrastructure for a high-availability ins
 - **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
 - **A private image registry** to distribute container images to your machines.

-### 1. Set up Linux Nodes
+## 1. Set up Linux Nodes

 These hosts will be disconnected from the internet, but require being able to connect with your private registry.

@@ -33,7 +33,7 @@ Make sure that your nodes fulfill the general installation requirements for [OS,

 For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.

-### 2. Set up External Datastore
+## 2. Set up External Datastore

 The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

@@ -49,7 +49,7 @@ For an example of one way to set up the database, refer to this [tutorial](../..

 For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/datastore/)

-### 3. Set up the Load Balancer
+## 3. Set up the Load Balancer

 You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

@@ -72,7 +72,7 @@ Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance

 :::

-### 4. Set up the DNS Record
+## 4. Set up the DNS Record

 Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

@@ -82,7 +82,7 @@ You will need to specify this hostname in a later step when you install Rancher,

 For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)

-### 5. Set up a Private Image Registry
+## 5. Set up a Private Image Registry

 Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing container images to your machines.

@@ -106,13 +106,13 @@ To install the Rancher management server on a high-availability RKE cluster, we

 These nodes must be in the same region/data center. You may place these servers in separate availability zones.

-### Why three nodes?
+## Why Three Nodes?

 In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

 The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

-### 1. Set up Linux Nodes
+## 1. Set up Linux Nodes

 These hosts will be disconnected from the internet, but require being able to connect with your private registry.

@@ -120,7 +120,7 @@ Make sure that your nodes fulfill the general installation requirements for [OS,

 For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.

-### 2. Set up the Load Balancer
+## 2. Set up the Load Balancer

 You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

@@ -143,7 +143,7 @@ Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance

 :::

-### 3. Set up the DNS Record
+## 3. Set up the DNS Record

 Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

@@ -153,7 +153,7 @@ You will need to specify this hostname in a later step when you install Rancher,

 For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)

-### 4. Set up a Private Image Registry
+## 4. Set up a Private Image Registry

 Rancher supports air gap installs using a secure private registry. You must have your own private registry or other means of distributing container images to your machines.

@@ -168,7 +168,7 @@ If you need to create a private registry, refer to the documentation pages for y
 </TabItem>
 <TabItem value="Docker">

-:::note Notes:
+:::note

 - The Docker installation is for Rancher users that are wanting to test out Rancher. Since there is only one node and a single Docker container, if the node goes down, you will lose all the data of your Rancher server.

@@ -176,7 +176,7 @@ If you need to create a private registry, refer to the documentation pages for y

 :::

-### 1. Set up a Linux Node
+## 1. Set up a Linux Node

 This host will be disconnected from the Internet, but needs to be able to connect to your private registry.

@@ -184,7 +184,7 @@ Make sure that your node fulfills the general installation requirements for [OS,

 For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.

-### 2. Set up a Private Docker Registry
+## 2. Set up a Private Docker Registry

 Rancher supports air gap installs using a private registry on your bastion server. You must have your own private registry or other means of distributing container images to your machines.

@@ -193,4 +193,4 @@ If you need help with creating a private registry, please refer to the [official
 </TabItem>
 </Tabs>

-### [Next: Collect and Publish Images to your Private Registry](publish-images.md)
+## [Next: Collect and Publish Images to your Private Registry](publish-images.md)
@@ -23,14 +23,15 @@ The steps to set up an air-gapped Kubernetes cluster on RKE, RKE2, or K3s are sh

 In this guide, we are assuming you have created your nodes in your air gapped environment and have a secure Docker private registry on your bastion server.

-### Installation Outline
+## Installation Outline

 1. [Prepare Images Directory](#1-prepare-images-directory)
 2. [Create Registry YAML](#2-create-registry-yaml)
 3. [Install K3s](#3-install-k3s)
 4. [Save and Start Using the kubeconfig File](#4-save-and-start-using-the-kubeconfig-file)

-### 1. Prepare Images Directory
+## 1. Prepare Images Directory
+
 Obtain the images tar file for your architecture from the [releases](https://github.com/k3s-io/k3s/releases) page for the version of K3s you will be running.

 Place the tar file in the `images` directory before starting K3s on each node, for example:
@@ -40,7 +41,8 @@ sudo mkdir -p /var/lib/rancher/k3s/agent/images/
 sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
 ```

-### 2. Create Registry YAML
+## 2. Create Registry YAML
+
 Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will tell K3s the necessary details to connect to your private registry.

 The registries.yaml file should look like this before plugging in the necessary information:
@@ -66,7 +68,7 @@ Note, at this time only secure registries are supported with K3s (SSL with custo

 For more information on private registries configuration file for K3s, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)

-### 3. Install K3s
+## 3. Install K3s

 Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/).

@@ -98,7 +100,7 @@ K3s additionally provides a `--resolv-conf` flag for kubelets, which may help wi

 :::

-### 4. Save and Start Using the kubeconfig File
+## 4. Save and Start Using the kubeconfig File

 When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

@@ -138,7 +140,7 @@ kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

 For more information about the `kubeconfig` file, refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files.

-### Note on Upgrading
+## Note on Upgrading

 Upgrading an air-gap environment can be accomplished in the following manner:

@@ -151,14 +153,15 @@ Upgrading an air-gap environment can be accomplished in the following manner:

 In this guide, we are assuming you have created your nodes in your air-gapped environment and have a secure Docker private registry on your bastion server.

-### Installation Outline
+## Installation Outline

 1. [Create RKE2 configuration](#1-create-rke2-configuration)
 2. [Create Registry YAML](#2-create-registry-yaml)
 3. [Install RKE2](#3-install-rke2)
 4. [Save and Start Using the kubeconfig File](#4-save-and-start-using-the-kubeconfig-file)

-### 1. Create RKE2 configuration
+## 1. Create RKE2 configuration
+
 Create the config.yaml file at `/etc/rancher/rke2/config.yaml`. This will contain all the configuration options necessary to create a highly available RKE2 cluster.

 On the first server the minimum config is:
@@ -186,7 +189,8 @@ RKE2 additionally provides a `resolv-conf` option for kubelets, which may help w

 :::

-### 2. Create Registry YAML
+## 2. Create Registry YAML
+
 Create the registries.yaml file at `/etc/rancher/rke2/registries.yaml`. This will tell RKE2 the necessary details to connect to your private registry.

 The registries.yaml file should look like this before plugging in the necessary information:
@@ -210,7 +214,7 @@ configs:

 For more information on private registries configuration file for RKE2, refer to the [RKE2 documentation.](https://docs.rke2.io/install/containerd_registry_configuration)

-### 3. Install RKE2
+## 3. Install RKE2

 Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)

@@ -239,7 +243,7 @@ systemctl start rke2-server.service

 For more information, refer to the [RKE2 documentation](https://docs.rke2.io/install/airgap).

-### 4. Save and Start Using the kubeconfig File
+## 4. Save and Start Using the kubeconfig File

 When you installed RKE2 on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/rke2/rke2.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

@@ -279,7 +283,7 @@ kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces

 For more information about the `kubeconfig` file, refer to the [RKE2 documentation](https://docs.rke2.io/cluster_access) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files.

-### Note on Upgrading
+## Note on Upgrading

 Upgrading an air-gap environment can be accomplished in the following manner:

@@ -291,7 +295,7 @@ Upgrading an air-gap environment can be accomplished in the following manner:
 <TabItem value="RKE">
 We will create a Kubernetes cluster using Rancher Kubernetes Engine (RKE). Before being able to start your Kubernetes cluster, you’ll need to install RKE and create a RKE config file.

-### 1. Install RKE
+## 1. Install RKE

 Install RKE by following the instructions in the [RKE documentation.](https://rancher.com/docs/rke/latest/en/installation/)

@@ -301,7 +305,7 @@ Certified version(s) of RKE based on the Rancher version can be found in the [Ra

 :::

-### 2. Create an RKE Config File
+## 2. Create an RKE Config File

 From a system that can access ports 22/TCP and 6443/TCP on the Linux host node(s) that you set up in a previous step, use the sample below to create a new file named `rancher-cluster.yml`.

@@ -352,7 +356,7 @@ private_registries:
    is_default: true
 ```

-### 3. Run RKE
+## 3. Run RKE

 After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:

@@ -360,7 +364,7 @@ After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:
 rke up --config ./rancher-cluster.yml
 ```

-### 4. Save Your Files
+## 4. Save Your Files

 :::note Important:

@@ -383,8 +387,8 @@ The "rancher-cluster" parts of the two latter file names are dependent on how yo

 :::

-### Issues or errors?
+## Issues or Errors?

 See the [Troubleshooting](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) page.

-### [Next: Install Rancher](install-rancher-ha.md)
+## [Next: Install Rancher](install-rancher-ha.md)
@@ -8,7 +8,7 @@ title: 4. Install Rancher

 This section is about how to deploy Rancher for your air gapped environment in a high-availability Kubernetes installation. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

-### Privileged Access for Rancher
+## Privileged Access for Rancher

 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.

@@ -78,7 +78,7 @@ 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. Fetch the Cert-Manager Chart
+### 3. Fetch the cert-manager Chart

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

@@ -109,7 +109,7 @@ Fetch the latest cert-manager chart available from the [Helm chart repository](h
 helm fetch jetstack/cert-manager --version v1.11.0
 ```

-##### 3. Retrieve the Cert-Manager CRDs
+##### 3. Retrieve the cert-manager CRDs

 Download the required CRD file for cert-manager:
   ```plain
@@ -120,7 +120,7 @@ Download the required CRD file for cert-manager:

 Copy the fetched charts to a system that has access to the Rancher server cluster to complete installation.

-##### 1. Install Cert-Manager
+#### 1. Install cert-manager

 Install cert-manager with the same options you would use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry.

@@ -160,7 +160,7 @@ If you are using self-signed certificates, install cert-manager:

 </details>

-##### 2. Install Rancher
+#### 2. Install Rancher
 First, refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.

 Then, create the namespace for Rancher using kubectl:
@@ -192,9 +192,9 @@ Placeholder | Description

 **Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.5.8`

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

-##### 1. Create secrets
+##### 1. Create Secrets

 Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher.

@@ -36,7 +36,7 @@ Administrators might configure the RKE metadata settings to do the following:
 - Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
 - Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher

-### Refresh Kubernetes Metadata
+## Refresh Kubernetes Metadata

 The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the **Manage Cluster Drivers** [global role.](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)

@@ -74,7 +74,7 @@ If you don't have an air gap setup, you don't need to specify the URL where Ranc

 However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.

-### Air Gap Setups
+## Air Gap Setups

 Rancher relies on a periodic refresh of the `rke-metadata-config` to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the [service terms section.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/)