Convert h1 to h2 (2.6)

2026-09-25 20:48:11 +00:00 · 2022-10-28 17:09:06 -07:00
parent 60cee22bf0
commit 15a1e067a6
70 changed files with 193 additions and 191 deletions
@@ -72,7 +72,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.

@@ -84,6 +84,6 @@ See [Restoring Cluster Networking](../../../../versioned_docs/version-2.0-2.4/ge

 :::

-# 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)
@@ -165,7 +165,7 @@ kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-

 For details on installing Rancher with a private registry, see the [air gap installation docs.](../../../pages-for-subheaders/air-gapped-helm-cli-install.md)

-# External TLS Termination
+## External TLS Termination

 We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

@@ -4,14 +4,14 @@ title: TLS Settings

 Changing the default TLS settings depends on the chosen installation method.

-# Running Rancher in a highly available Kubernetes cluster
+## Running Rancher in a highly available Kubernetes cluster

 When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller:

 * nginx-ingress-controller (default for RKE1 and RKE2): [Default TLS Version and Ciphers](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#default-tls-version-and-ciphers).
 * traefik (default for K3s): [TLS Options](https://doc.traefik.io/traefik/https/tls/#tls-options).

-# Running Rancher in a single Docker container
+## Running Rancher in a single Docker container

 The default TLS configuration only accepts TLS 1.2 and secure TLS cipher suites. You can change this by setting the following environment variables:

@@ -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.

@@ -174,7 +174,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.

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


-# Other Port Considerations
+## Other Port Considerations

 ### Commonly Used Ports

@@ -127,7 +127,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.

@@ -206,7 +206,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.

@@ -23,7 +23,7 @@ If you want to replace the certificate, you can delete the `tls-rancher-ingress`

 :::

-# 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.

@@ -40,6 +40,6 @@ The configured `tls-ca` secret is retrieved when Rancher starts. On a running Ra

 :::

-# 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,7 +6,7 @@ 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.

@@ -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

 :::note

@@ -95,18 +95,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).

@@ -114,7 +114,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).

@@ -125,7 +125,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:

@@ -141,7 +141,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.

@@ -150,15 +150,15 @@ First, generate the agent definitions as described here: https://gist.github.com
 Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions:
 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 of 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.

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

 :::note

@@ -166,7 +166,7 @@ It is possible to perform the opposite procedure as shown above: you may change

 :::

-## 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`.

@@ -187,7 +187,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.

@@ -203,7 +203,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

 :::note Important:

@@ -249,14 +249,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 of 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.
@@ -19,7 +19,7 @@ If you are upgrading cert-manager to the latest version from a version older tha

 :::

-# 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.

@@ -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.