Merge pull request #4119 from jtravee/updating-private-ca-cert

Updating Private CA cert to Non-Private cert directions
2026-09-25 04:28:15 +00:00 · 2022-05-31 16:52:17 -07:00
parent 7b728dbc95 2d3072b79d
commit 50ee406a79
6 changed files with 305 additions and 22 deletions
@@ -35,4 +35,4 @@ kubectl -n cattle-system create secret generic tls-ca \

 # Updating a Private CA Certificate

-Follow the steps on [this page]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/resources/update-ca-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
+Follow the steps on [this page]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
@@ -1,8 +1,10 @@
 ---
-title: Updating a Private CA Certificate
+title: Updating the Rancher Certificate
 weight: 10
 ---

+# Updating a Private CA Certificate
+
 Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.

 A summary of the steps is as follows:
@@ -14,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`.

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

@@ -54,9 +56,9 @@ $ 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.
+> Before proceeding, [generate an API token in the Rancher UI]({{<baseurl>}}/rancher/v2.0-v2.4/en/user-settings/api-keys/#creating-an-api-key) (<b>User > API & Keys</b>).

 This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`).

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

@@ -142,4 +144,91 @@ With this method you are recreating the Rancher agents by running a set of comma
 First, generate the agent definitions as described here: https://gist.github.com/superseb/076f20146e012f1d4e289f5bd1bd4971

 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
+https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b
+
+# 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
+
+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`.
+
+If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the `tls-rancher-ingress` secret resource in your Rancher HA cluster:
+
+```
+$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
+  --cert=tls.crt \
+  --key=tls.key
+```
+
+Alternatively, to update an existing certificate secret:
+
+```
+$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
+  --cert=tls.crt \
+  --key=tls.key \
+  --dry-run --save-config -o yaml | kubectl apply -f -
+```
+
+## 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.
+
+To save the existing secret:
+
+```
+kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml
+```
+
+To delete the existing `tls-ca` secret:
+
+```
+kubectl -n cattle-system delete secret tls-ca
+```
+
+## 3. Reconfigure the Rancher deployment
+
+> Before proceeding, [generate an API token in the Rancher UI](https://rancher.com/docs/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (<b>User > API & Keys</b>) and save the Bearer Token which you might need in step 4.
+
+This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`).
+
+It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.
+
+To update the Helm deployment you will need to use the same (`--set`) options that were used during initial installation. Check with:
+
+```
+$ helm get values rancher -n cattle-system
+```
+
+Also get the version string of the currently deployed Rancher chart:
+
+```
+$ helm ls -A
+```
+
+Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.    
+
+Also make sure to read the documentation describing the initial installation using custom certificates.
+
+```
+helm upgrade rancher rancher-stable/rancher \
+  --namespace cattle-system \
+  --version <DEPLOYED_CHART_VERSION> \
+  --set hostname=rancher.my.org \
+  --set ...
+```
+
+On upgrade, you can either 
+
+- remove `--set ingress.tls.source=secret \` from the Helm upgrade command, as shown above, or 
+
+- remove the `privateCA` parameter or set it to `false` because the CA is valid:
+
+```
+set privateCA=false
+```
+
+## 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).
@@ -38,4 +38,4 @@ kubectl -n cattle-system create secret generic tls-ca \

 # Updating a Private CA Certificate

-Follow the steps on [this page]({{<baseurl>}}/rancher/v2.5/en/installation/resources/update-ca-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.5/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
+Follow the steps on [this page]({{<baseurl>}}/rancher/v2.5/en/installation/resources/update-rancher-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.5/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
@@ -1,10 +1,12 @@
 ---
-title: Updating a Private CA Certificate
+title: Updating the Rancher Certificate
 weight: 10
 aliases:
  - /rancher/v2.x/en/installation/resources/update-ca-cert/
 ---

+# Updating a Private CA Certificate
+
 Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.5/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.

 A summary of the steps is as follows:
@@ -17,7 +19,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`.

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

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

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

@@ -148,10 +150,105 @@ 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]({{<baseurl>}}/rancher/v2.5/en/deploy-across-clusters/fleet/#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?

 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
+
+>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
+
+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`.
+
+If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the `tls-rancher-ingress` secret resource in your Rancher HA cluster:
+
+```
+$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
+  --cert=tls.crt \
+  --key=tls.key
+```
+
+Alternatively, to update an existing certificate secret:
+
+```
+$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
+  --cert=tls.crt \
+  --key=tls.key \
+  --dry-run --save-config -o yaml | kubectl apply -f -
+```
+
+## 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.
+
+To save the existing secret:
+
+```
+kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml
+```
+
+To delete the existing `tls-ca` secret:
+
+```
+kubectl -n cattle-system delete secret tls-ca
+```
+
+## 3. Reconfigure the Rancher deployment
+
+> Before proceeding, [generate an API token in the Rancher UI]({{<baseurl>}}/rancher/v2.5/en/user-settings/api-keys/#creating-an-api-key) (<b>User > API & Keys</b>).
+
+This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`).
+
+It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.
+
+To update the Helm deployment you will need to use the same (`--set`) options that were used during initial installation. Check with:
+
+```
+$ helm get values rancher -n cattle-system
+```
+
+Also get the version string of the currently deployed Rancher chart:
+
+```
+$ helm ls -A
+```
+
+Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.    
+
+Also make sure to read the documentation describing the initial installation using custom certificates.
+
+```
+helm upgrade rancher rancher-stable/rancher \
+  --namespace cattle-system \
+  --version <DEPLOYED_CHART_VERSION> \
+  --set hostname=rancher.my.org \
+  --set ...
+```
+
+On upgrade, you can either 
+
+- remove `--set ingress.tls.source=secret \` from the Helm upgrade command, as shown above, or 
+
+- remove the `privateCA` parameter or set it to `false` because the CA is valid:
+
+```
+set privateCA=false
+```
+
+## 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
+
+Select 'Force Update' for the clusters within the [Continuous Delivery]({{<baseurl>}}/rancher/v2.5/en/deploy-across-clusters/fleet/#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?
+
+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.
@@ -35,4 +35,4 @@ kubectl -n cattle-system create secret generic tls-ca \

 # Updating a Private CA Certificate

-Follow the steps on [this page]({{<baseurl>}}/rancher/v2.6/en/installation/resources/update-ca-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
+Follow the steps on [this page]({{<baseurl>}}/rancher/v2.6/en/installation/resources/update-rancher-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
@@ -1,8 +1,10 @@
 ---
-title: Updating a Private CA Certificate
+title: Updating the Rancher Certificate
 weight: 10
 ---

+# Updating a Private CA Certificate
+
 Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.

 A summary of the steps is as follows:
@@ -15,7 +17,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`.

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

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

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

@@ -145,7 +147,102 @@ 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]({{<baseurl>}}/rancher/v2.6/en/deploy-across-clusters/fleet/#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?
+
+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
+
+>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
+
+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`.
+
+If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the `tls-rancher-ingress` secret resource in your Rancher HA cluster:
+
+```
+$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
+  --cert=tls.crt \
+  --key=tls.key
+```
+
+Alternatively, to update an existing certificate secret:
+
+```
+$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
+  --cert=tls.crt \
+  --key=tls.key \
+  --dry-run --save-config -o yaml | kubectl apply -f -
+```
+
+## 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.
+
+To save the existing secret:
+
+```
+kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml
+```
+
+To delete the existing `tls-ca` secret:
+
+```
+kubectl -n cattle-system delete secret tls-ca
+```
+
+## 3. Reconfigure the Rancher deployment
+
+> Before proceeding, [generate an API token in the Rancher UI]({{<baseurl>}}/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (<b>User > API & Keys</b>).
+
+This step is required if Rancher was initially installed with self-signed certificates (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`).
+
+It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.
+
+To update the Helm deployment you will need to use the same (`--set`) options that were used during initial installation. Check with:
+
+```
+$ helm get values rancher -n cattle-system
+```
+
+Also get the version string of the currently deployed Rancher chart:
+
+```
+$ helm ls -A
+```
+
+Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.    
+
+Also make sure to read the documentation describing the initial installation using custom certificates.
+
+```
+helm upgrade rancher rancher-stable/rancher \
+  --namespace cattle-system \
+  --version <DEPLOYED_CHART_VERSION> \
+  --set hostname=rancher.my.org \
+  --set ...
+```
+
+On upgrade, you can either 
+
+- remove `--set ingress.tls.source=secret \` from the Helm upgrade command, as shown above, or 
+
+- remove the `privateCA` parameter or set it to `false` because the CA is valid:
+
+```
+set privateCA=false
+```
+
+## 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

 Select 'Force Update' for the clusters within the [Continuous Delivery]({{<baseurl>}}/rancher/v2.6/en/deploy-across-clusters/fleet/#accessing-fleet-in-the-rancher-ui) view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.