Convert h1 to h2 (2.5)

2026-09-26 04:58:07 +00:00 · 2022-10-28 17:09:19 -07:00
parent 15a1e067a6
commit bb76e99d20
87 changed files with 319 additions and 336 deletions
@@ -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/).
-