From 3be66c4ab49cb9dafa96d2d644421883d5b34123 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 16:48:51 -0400 Subject: [PATCH 01/11] Added new section for common cert, updated link to page in 2.0-2.4 --- .../resources/tls-secrets/_index.md | 2 +- .../_index.md | 43 ++++++++++++++++--- 2 files changed, 38 insertions(+), 7 deletions(-) rename content/rancher/v2.0-v2.4/en/installation/resources/{update-ca-cert => update-rancher-cert}/_index.md (83%) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/tls-secrets/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/tls-secrets/_index.md index 3c32084c5e6..351dc19b5ae 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/tls-secrets/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/tls-secrets/_index.md @@ -35,4 +35,4 @@ kubectl -n cattle-system create secret generic tls-ca \ # Updating a Private CA Certificate -Follow the steps on [this page]({{}}/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]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file +Follow the steps on [this page]({{}}/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]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-ca-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md similarity index 83% rename from content/rancher/v2.0-v2.4/en/installation/resources/update-ca-cert/_index.md rename to content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 9ad73812a47..48c0aa9ec42 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-ca-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -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]({{}}/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,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 (User > API & Keys) and save the Bearer Token which you might need in step 4. @@ -89,7 +91,7 @@ helm upgrade rancher rancher-stable/rancher \ When the upgrade is completed, navigate to `https:///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,33 @@ 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 \ No newline at end of file +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 very similar to the above, with some exceptions. + +The steps needed to accomplish this are as follows: + +1. Perform [Step 1 above](#1-create-update-the-certificate-secret-resource). +1. Delete the `tls-ca` secret as it is no longer needed. + + >**Note:** You may optionally save a copy of the `tls-ca` secret if desired. + + **To save:** + ``` + kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml + ``` + + **To delete:** + ``` + kubectl -n cattle-system delete secret tls-ca + ``` + +1. On Rancher upgrade, the `privateCA` parameter **must** be either removed or set to `false` because the CA is valid: + + ``` + set privateCA=false + ``` + +1. `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file From 6d1541ab7a014df55c4ee191d48c43398817a955 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 17:24:41 -0400 Subject: [PATCH 02/11] Updated steps --- .../resources/update-rancher-cert/_index.md | 176 ++++++++++++++++-- 1 file changed, 157 insertions(+), 19 deletions(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 48c0aa9ec42..4147cdd5aa2 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -148,29 +148,167 @@ 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 very similar to the above, with some exceptions. +>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 very similar to the above, with some exceptions. The changes to these steps are shown at the bottom of each step below as they apply. -The steps needed to accomplish this are as follows: +Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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. Perform [Step 1 above](#1-create-update-the-certificate-secret-resource). -1. Delete the `tls-ca` secret as it is no longer needed. - - >**Note:** You may optionally save a copy of the `tls-ca` secret if desired. +A summary of the steps is as follows: - **To save:** - ``` - kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml - ``` +1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. +2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). +3. Update the Rancher installation using the Helm CLI. +4. Reconfigure the Rancher agents to trust the new CA certificate. - **To delete:** - ``` - kubectl -n cattle-system delete secret tls-ca - ``` +The details of these instructions are below. -1. On Rancher upgrade, the `privateCA` parameter **must** be either removed or set to `false` because the CA is valid: +## 1. Create/update the certificate secret resource - ``` - set privateCA=false - ``` +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`. -1. `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file +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 - +``` + +>**NOTE:** No changes in this step. + +## 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). + +To create the initial secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +To update an existing `tls-ca` secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +>**CHANGE:** Delete the `tls-ca` secret as it is no longer needed. Note that you may optionally save a copy of the `tls-ca` secret if desired. +> +**To save:** + ``` + kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml + ``` +> +**To delete:** + ``` + kubectl -n cattle-system delete secret tls-ca + ``` + +## 3. Reconfigure the Rancher deployment + +> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. + +If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. + +``` +helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + --version \ + --set hostname=rancher.my.org \ + --set ingress.tls.source=secret \ + --set ... +``` + +When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. + +>**CHANGE:** On Rancher upgrade, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: +> + ``` + set privateCA=false + ``` + +## 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 + +>**CHANGE:** `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). + +### 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? + +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). + +If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.0-v2.4/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. + +Method 3 can be used as a fallback if method 1 and 2 are unfeasible. + +### Method 1: Kubectl command + +For each cluster under Rancher management (including `local`) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S). + +``` +kubectl patch clusters -p '{"status":{"agentImage":"dummy"}}' --type merge +``` + +This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. + + +### 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: + +``` +$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp +$ sha256sum cacert.tmp | awk '{print $1}' +``` + +Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. + +``` +$ kubectl edit -n cattle-system ds/cattle-node-agent +$ kubectl edit -n cattle-system deployment/cluster-agent +``` + +### 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. + +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 \ No newline at end of file From 71a6fe4223062e738c22cbe465f30aaf50ed6bef Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 17:43:30 -0400 Subject: [PATCH 03/11] Updated spacing on a step --- .../installation/resources/update-rancher-cert/_index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 4147cdd5aa2..0781b1454eb 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -263,8 +263,6 @@ This section covers three methods to reconfigure Rancher agents to trust the pri - 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 ->**CHANGE:** `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). - ### 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. @@ -311,4 +309,8 @@ 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 \ No newline at end of file +https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b + +>**CHANGE:** +> +>`CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file From 0249ba2556a882dea123ee887fc8cc0f22312f4f Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 17:43:49 -0400 Subject: [PATCH 04/11] Added new section, updated links for 2.5 --- .../resources/tls-secrets/_index.md | 2 +- .../resources/update-ca-cert/_index.md | 157 -------- .../resources/update-rancher-cert/_index.md | 337 ++++++++++++++++++ 3 files changed, 338 insertions(+), 158 deletions(-) delete mode 100644 content/rancher/v2.5/en/installation/resources/update-ca-cert/_index.md create mode 100644 content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md diff --git a/content/rancher/v2.5/en/installation/resources/tls-secrets/_index.md b/content/rancher/v2.5/en/installation/resources/tls-secrets/_index.md index 9878109b8b6..ab2b18cec4c 100644 --- a/content/rancher/v2.5/en/installation/resources/tls-secrets/_index.md +++ b/content/rancher/v2.5/en/installation/resources/tls-secrets/_index.md @@ -38,4 +38,4 @@ kubectl -n cattle-system create secret generic tls-ca \ # Updating a Private CA Certificate -Follow the steps on [this page]({{}}/rancher/v2.5/en/installation/resources/update-ca-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file +Follow the steps on [this page]({{}}/rancher/v2.5/en/installation/resources/update-rancher-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file diff --git a/content/rancher/v2.5/en/installation/resources/update-ca-cert/_index.md b/content/rancher/v2.5/en/installation/resources/update-ca-cert/_index.md deleted file mode 100644 index 751feae2d8c..00000000000 --- a/content/rancher/v2.5/en/installation/resources/update-ca-cert/_index.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Updating a Private CA Certificate -weight: 10 -aliases: - - /rancher/v2.x/en/installation/resources/update-ca-cert/ ---- - -Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: - -1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. -2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). -3. Update the Rancher installation using the Helm CLI. -4. Reconfigure the Rancher agents to trust the new CA certificate. -5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. - -The details of these instructions are 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. 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). - -To create the initial secret: - -``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem -``` - -To update an existing `tls-ca` secret: - -``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem \ - --dry-run --save-config -o yaml | kubectl apply -f - -``` - -# 3. Reconfigure the Rancher deployment - -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. - -If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. - -``` -helm upgrade rancher rancher-stable/rancher \ - --namespace cattle-system \ - --version \ - --set hostname=rancher.my.org \ - --set ingress.tls.source=secret \ - --set ... -``` - -When the upgrade is completed, navigate to `https:///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 - -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? - -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? - -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). - -If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.5/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. - -Method 3 can be used as a fallback if method 1 and 2 are unfeasible. - -### 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). - -``` -kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge -``` - -This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. - - -### 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: - -``` -$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp -$ sha256sum cacert.tmp | awk '{print $1}' -``` - -Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. - -``` -$ kubectl edit -n cattle-system ds/cattle-node-agent -$ kubectl edit -n cattle-system deployment/cattle-cluster-agent -``` - -### 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. - -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 - - -# 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher - -Select 'Force Update' for the clusters within the [Continuous Delivery]({{}}/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. diff --git a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md new file mode 100644 index 00000000000..67b6772215e --- /dev/null +++ b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md @@ -0,0 +1,337 @@ +--- +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]({{}}/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: + +1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. +2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). +3. Update the Rancher installation using the Helm CLI. +4. Reconfigure the Rancher agents to trust the new CA certificate. +5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. + +The details of these instructions are 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. 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). + +To create the initial secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +To update an existing `tls-ca` secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +## 3. Reconfigure the Rancher deployment + +> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. + +If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. + +``` +helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + --version \ + --set hostname=rancher.my.org \ + --set ingress.tls.source=secret \ + --set ... +``` + +When the upgrade is completed, navigate to `https:///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 + +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? + +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? + +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). + +If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.5/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. + +Method 3 can be used as a fallback if method 1 and 2 are unfeasible. + +### 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). + +``` +kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge +``` + +This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. + + +### 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: + +``` +$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp +$ sha256sum cacert.tmp | awk '{print $1}' +``` + +Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. + +``` +$ kubectl edit -n cattle-system ds/cattle-node-agent +$ kubectl edit -n cattle-system deployment/cattle-cluster-agent +``` + +### 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. + +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 + + +## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher + +Select 'Force Update' for the clusters within the [Continuous Delivery]({{}}/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 very similar to the above, with some exceptions. The changes to these steps are shown at the bottom of each step below as they apply. + +Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: + +1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. +2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). +3. Update the Rancher installation using the Helm CLI. +4. Reconfigure the Rancher agents to trust the new CA certificate. +5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. + +The details of these instructions are 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 - +``` + +>**NOTE:** No changes in this step. + +## 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). + +To create the initial secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +To update an existing `tls-ca` secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +>**CHANGE:** Delete the `tls-ca` secret as it is no longer needed. Note that you may optionally save a copy of the `tls-ca` secret if desired. +> +**To save:** + ``` + kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml + ``` +> +**To delete:** + ``` + kubectl -n cattle-system delete secret tls-ca + ``` + +## 3. Reconfigure the Rancher deployment + +> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. + +If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. + +``` +helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + --version \ + --set hostname=rancher.my.org \ + --set ingress.tls.source=secret \ + --set ... +``` + +When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. + +>**CHANGE:** On Rancher upgrade, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: +> + ``` + set privateCA=false + ``` + +## 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? + +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? + +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). + +If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.5/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. + +Method 3 can be used as a fallback if method 1 and 2 are unfeasible. + +### 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). + +``` +kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge +``` + +This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. + + +### 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: + +``` +$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp +$ sha256sum cacert.tmp | awk '{print $1}' +``` + +Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. + +``` +$ kubectl edit -n cattle-system ds/cattle-node-agent +$ kubectl edit -n cattle-system deployment/cattle-cluster-agent +``` + +### 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. + +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 + +>**CHANGE:** +> +>`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]({{}}/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. \ No newline at end of file From 9514e6b30f8c6a819f589ce2604a58243c98435b Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 17:51:16 -0400 Subject: [PATCH 05/11] Updated spacing --- .../en/installation/resources/update-rancher-cert/_index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 0781b1454eb..6b2b4eaee09 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -311,6 +311,4 @@ 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 ->**CHANGE:** -> ->`CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file +>**CHANGE:** `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file From f0158e234d83696de373495878d21ae918672b4f Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 17:51:31 -0400 Subject: [PATCH 06/11] Updated spacing --- .../en/installation/resources/update-rancher-cert/_index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md index 67b6772215e..f8ba73d1747 100644 --- a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md @@ -324,9 +324,7 @@ 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 ->**CHANGE:** -> ->`CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). +>**CHANGE:** `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 From 35f5da1a8b06740c41806d0b380892d4ef42518e Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 24 May 2022 17:51:46 -0400 Subject: [PATCH 07/11] Added section, updated link --- .../resources/tls-secrets/_index.md | 2 +- .../resources/update-ca-cert/_index.md | 154 -------- .../resources/update-rancher-cert/_index.md | 332 ++++++++++++++++++ 3 files changed, 333 insertions(+), 155 deletions(-) delete mode 100644 content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md create mode 100644 content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md diff --git a/content/rancher/v2.6/en/installation/resources/tls-secrets/_index.md b/content/rancher/v2.6/en/installation/resources/tls-secrets/_index.md index cd11f1e9684..c5b79f9b37d 100644 --- a/content/rancher/v2.6/en/installation/resources/tls-secrets/_index.md +++ b/content/rancher/v2.6/en/installation/resources/tls-secrets/_index.md @@ -35,4 +35,4 @@ kubectl -n cattle-system create secret generic tls-ca \ # Updating a Private CA Certificate -Follow the steps on [this page]({{}}/rancher/v2.6/en/installation/resources/update-ca-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file +Follow the steps on [this page]({{}}/rancher/v2.6/en/installation/resources/update-rancher-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file diff --git a/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md b/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md deleted file mode 100644 index 057ca0f8c77..00000000000 --- a/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Updating a Private CA Certificate -weight: 10 ---- - -Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: - -1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. -2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). -3. Update the Rancher installation using the Helm CLI. -4. Reconfigure the Rancher agents to trust the new CA certificate. -5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. - -The details of these instructions are 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. 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). - -To create the initial secret: - -``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem -``` - -To update an existing `tls-ca` secret: - -``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem \ - --dry-run --save-config -o yaml | kubectl apply -f - -``` - -# 3. Reconfigure the Rancher deployment - -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. - -If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. - -``` -helm upgrade rancher rancher-stable/rancher \ - --namespace cattle-system \ - --version \ - --set hostname=rancher.my.org \ - --set ingress.tls.source=secret \ - --set ... -``` - -When the upgrade is completed, navigate to `https:///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 - -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? - -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? - -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). - -If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.6/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. - -Method 3 can be used as a fallback if method 1 and 2 are unfeasible. - -### 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). - -``` -kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge -``` - -This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. - - -### 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: - -``` -$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp -$ sha256sum cacert.tmp | awk '{print $1}' -``` - -Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. - -``` -$ kubectl edit -n cattle-system ds/cattle-node-agent -$ kubectl edit -n cattle-system deployment/cattle-cluster-agent -``` - -### 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. - -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 - -# 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher - -Select 'Force Update' for the clusters within the [Continuous Delivery]({{}}/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. diff --git a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md new file mode 100644 index 00000000000..71834965eaa --- /dev/null +++ b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md @@ -0,0 +1,332 @@ +--- +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]({{}}/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: + +1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. +2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). +3. Update the Rancher installation using the Helm CLI. +4. Reconfigure the Rancher agents to trust the new CA certificate. +5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. + +The details of these instructions are 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. 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). + +To create the initial secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +To update an existing `tls-ca` secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +## 3. Reconfigure the Rancher deployment + +> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. + +If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. + +``` +helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + --version \ + --set hostname=rancher.my.org \ + --set ingress.tls.source=secret \ + --set ... +``` + +When the upgrade is completed, navigate to `https:///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 + +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? + +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? + +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). + +If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.6/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. + +Method 3 can be used as a fallback if method 1 and 2 are unfeasible. + +### 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). + +``` +kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge +``` + +This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. + + +### 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: + +``` +$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp +$ sha256sum cacert.tmp | awk '{print $1}' +``` + +Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. + +``` +$ kubectl edit -n cattle-system ds/cattle-node-agent +$ kubectl edit -n cattle-system deployment/cattle-cluster-agent +``` + +### 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. + +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 + +## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher + +Select 'Force Update' for the clusters within the [Continuous Delivery]({{}}/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 very similar to the above, with some exceptions. The changes to these steps are shown at the bottom of each step below as they apply. + +Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: + +1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. +2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). +3. Update the Rancher installation using the Helm CLI. +4. Reconfigure the Rancher agents to trust the new CA certificate. +5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. + +The details of these instructions are 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 - +``` + +>**NOTE:** No changes in this step. + +## 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). + +To create the initial secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +To update an existing `tls-ca` secret: + +``` +$ kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +>**CHANGE:** Delete the `tls-ca` secret as it is no longer needed. Note that you may optionally save a copy of the `tls-ca` secret if desired. +> +**To save:** + ``` + kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml + ``` +> +**To delete:** + ``` + kubectl -n cattle-system delete secret tls-ca + ``` + +## 3. Reconfigure the Rancher deployment + +> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. + +If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. + +``` +helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + --version \ + --set hostname=rancher.my.org \ + --set ingress.tls.source=secret \ + --set ... +``` + +When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. + +>**CHANGE:** On Rancher upgrade, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: +> + ``` + set privateCA=false + ``` + +## 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? + +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? + +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). + +If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.6/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. + +Method 3 can be used as a fallback if method 1 and 2 are unfeasible. + +### 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). + +``` +kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge +``` + +This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. + + +### 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: + +``` +$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp +$ sha256sum cacert.tmp | awk '{print $1}' +``` + +Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. + +``` +$ kubectl edit -n cattle-system ds/cattle-node-agent +$ kubectl edit -n cattle-system deployment/cattle-cluster-agent +``` + +### 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. + +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 + +>**CHANGE:** `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]({{}}/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. From 4bd712bb9b3c6224de4a5fc7ff0673014c684697 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 26 May 2022 09:46:27 -0400 Subject: [PATCH 08/11] Updating pages per feedback --- .../resources/update-rancher-cert/_index.md | 110 ++--------------- .../resources/update-rancher-cert/_index.md | 111 ++---------------- .../resources/update-rancher-cert/_index.md | 111 ++---------------- 3 files changed, 39 insertions(+), 293 deletions(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 6b2b4eaee09..2e77d4bf12d 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -148,18 +148,7 @@ 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 very similar to the above, with some exceptions. The changes to these steps are shown at the bottom of each step below as they apply. - -Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: - -1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. -2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). -3. Update the Rancher installation using the Helm CLI. -4. Reconfigure the Rancher agents to trust the new CA certificate. - -The details of these instructions are below. +>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 very similar to the above, with some exceptions. ## 1. Create/update the certificate secret resource @@ -182,39 +171,22 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` ->**NOTE:** No changes in this step. +## 2. Delete the CA certificate secret resource -## 2. Create/update 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. -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). - -To create the initial secret: +To save the existing secret: ``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem +kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml ``` -To update an existing `tls-ca` secret: +To delete the existing `tls-ca` secret: ``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem \ - --dry-run --save-config -o yaml | kubectl apply -f - +kubectl -n cattle-system delete secret tls-ca ``` ->**CHANGE:** Delete the `tls-ca` secret as it is no longer needed. Note that you may optionally save a copy of the `tls-ca` secret if desired. -> -**To save:** - ``` - kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml - ``` -> -**To delete:** - ``` - kubectl -n cattle-system delete secret tls-ca - ``` - ## 3. Reconfigure the Rancher deployment > Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. @@ -235,80 +207,24 @@ 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. +Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade. -If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. +Also make sure to read the documentation describing the initial installation using custom certificates. ``` helm upgrade rancher rancher-stable/rancher \ --namespace cattle-system \ --version \ --set hostname=rancher.my.org \ - --set ingress.tls.source=secret \ --set ... ``` -When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. - ->**CHANGE:** On Rancher upgrade, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: -> - ``` - set privateCA=false - ``` - -## 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? - -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? - -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). - -If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.0-v2.4/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. - -Method 3 can be used as a fallback if method 1 and 2 are unfeasible. - -### Method 1: Kubectl command - -For each cluster under Rancher management (including `local`) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S). +After upgrade is completed, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: ``` -kubectl patch clusters -p '{"status":{"agentImage":"dummy"}}' --type merge +set privateCA=false ``` -This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. +## 4. Reconfigure Rancher agents for the non-private/common certificate - -### 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: - -``` -$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp -$ sha256sum cacert.tmp | awk '{print $1}' -``` - -Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. - -``` -$ kubectl edit -n cattle-system ds/cattle-node-agent -$ kubectl edit -n cattle-system deployment/cluster-agent -``` - -### 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. - -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 - ->**CHANGE:** `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file +`CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file diff --git a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md index f8ba73d1747..09485cf47dd 100644 --- a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md @@ -160,19 +160,7 @@ Fleet agents in Rancher managed clusters store kubeconfig that is used to connec # 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 very similar to the above, with some exceptions. The changes to these steps are shown at the bottom of each step below as they apply. - -Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: - -1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. -2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). -3. Update the Rancher installation using the Helm CLI. -4. Reconfigure the Rancher agents to trust the new CA certificate. -5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. - -The details of these instructions are below. +>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 @@ -195,39 +183,22 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` ->**NOTE:** No changes in this step. +## 2. Delete the CA certificate secret resource -## 2. Create/update 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. -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). - -To create the initial secret: +To save the existing secret: ``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem +kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml ``` -To update an existing `tls-ca` secret: +To delete the existing `tls-ca` secret: ``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem \ - --dry-run --save-config -o yaml | kubectl apply -f - +kubectl -n cattle-system delete secret tls-ca ``` ->**CHANGE:** Delete the `tls-ca` secret as it is no longer needed. Note that you may optionally save a copy of the `tls-ca` secret if desired. -> -**To save:** - ``` - kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml - ``` -> -**To delete:** - ``` - kubectl -n cattle-system delete secret tls-ca - ``` - ## 3. Reconfigure the Rancher deployment > Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. @@ -248,83 +219,27 @@ 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. +Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade. -If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. +Also make sure to read the documentation describing the initial installation using custom certificates. ``` helm upgrade rancher rancher-stable/rancher \ --namespace cattle-system \ --version \ --set hostname=rancher.my.org \ - --set ingress.tls.source=secret \ --set ... ``` -When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. - ->**CHANGE:** On Rancher upgrade, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: -> - ``` - set privateCA=false - ``` - -## 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? - -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? - -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). - -If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.5/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. - -Method 3 can be used as a fallback if method 1 and 2 are unfeasible. - -### 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). +After upgrade is completed, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: ``` -kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge +set privateCA=false ``` -This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. +## 4. Reconfigure Rancher agents for the non-private/common certificate - -### 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: - -``` -$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp -$ sha256sum cacert.tmp | awk '{print $1}' -``` - -Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. - -``` -$ kubectl edit -n cattle-system ds/cattle-node-agent -$ kubectl edit -n cattle-system deployment/cattle-cluster-agent -``` - -### 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. - -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 - ->**CHANGE:** `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). +`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 diff --git a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md index 71834965eaa..c9bdf724e3a 100644 --- a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md @@ -157,19 +157,7 @@ Fleet agents in Rancher managed clusters store kubeconfig that is used to connec # 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 very similar to the above, with some exceptions. The changes to these steps are shown at the bottom of each step below as they apply. - -Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{}}/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: - -1. Create or update the `tls-rancher-ingress` Kubernetes secret resource with the new certificate and private key. -2. Create or update the `tls-ca` Kubernetes secret resource with the root CA certificate (only required when using a private CA). -3. Update the Rancher installation using the Helm CLI. -4. Reconfigure the Rancher agents to trust the new CA certificate. -5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. - -The details of these instructions are below. +>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 @@ -192,39 +180,22 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` ->**NOTE:** No changes in this step. +## 2. Delete the CA certificate secret resource -## 2. Create/update 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. -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). - -To create the initial secret: +To save the existing secret: ``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem +kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml ``` -To update an existing `tls-ca` secret: +To delete the existing `tls-ca` secret: ``` -$ kubectl -n cattle-system create secret generic tls-ca \ - --from-file=cacerts.pem \ - --dry-run --save-config -o yaml | kubectl apply -f - +kubectl -n cattle-system delete secret tls-ca ``` ->**CHANGE:** Delete the `tls-ca` secret as it is no longer needed. Note that you may optionally save a copy of the `tls-ca` secret if desired. -> -**To save:** - ``` - kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml - ``` -> -**To delete:** - ``` - kubectl -n cattle-system delete secret tls-ca - ``` - ## 3. Reconfigure the Rancher deployment > Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. @@ -245,83 +216,27 @@ 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 `ingress.tls.source=secret` as well as the current chart version to prevent an application upgrade. +Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade. -If the certificate was signed by a private CA, add the `set privateCA=true` argument as well. Also make sure to read the documentation describing the initial installation using custom certificates. +Also make sure to read the documentation describing the initial installation using custom certificates. ``` helm upgrade rancher rancher-stable/rancher \ --namespace cattle-system \ --version \ --set hostname=rancher.my.org \ - --set ingress.tls.source=secret \ --set ... ``` -When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. - ->**CHANGE:** On Rancher upgrade, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: -> - ``` - set privateCA=false - ``` - -## 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? - -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? - -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). - -If the clusters have lost connection to Rancher but you have [Authorized Cluster Endpoints](https://rancher.com/docs/rancher/v2.6/en/cluster-admin/cluster-access/ace/) enabled, then go with method 2. - -Method 3 can be used as a fallback if method 1 and 2 are unfeasible. - -### 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). +After upgrade is completed, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: ``` -kubectl patch clusters.management.cattle.io -p '{"status":{"agentImage":"dummy"}}' --type merge +set privateCA=false ``` -This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. +## 4. Reconfigure Rancher agents for the non-private/common certificate - -### 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: - -``` -$ curl -k -s -fL /v3/settings/cacerts | jq -r .value > cacert.tmp -$ sha256sum cacert.tmp | awk '{print $1}' -``` - -Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. - -``` -$ kubectl edit -n cattle-system ds/cattle-node-agent -$ kubectl edit -n cattle-system deployment/cattle-cluster-agent -``` - -### 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. - -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 - ->**CHANGE:** `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). +`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 From 3e89075184dce68b9a96540be0641c71330342ab Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 26 May 2022 09:52:30 -0400 Subject: [PATCH 09/11] Updated 2.0-2.4 --- .../en/installation/resources/update-rancher-cert/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 2e77d4bf12d..76865145076 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -148,7 +148,7 @@ 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 very similar to the above, with some exceptions. +>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 From 7ca9ebe3d00cebd861c27feed3a8849c799b9f2a Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 31 May 2022 17:27:29 -0400 Subject: [PATCH 10/11] Updating verbiage on commands --- .../en/installation/resources/update-rancher-cert/_index.md | 6 +++++- .../en/installation/resources/update-rancher-cert/_index.md | 6 +++++- .../en/installation/resources/update-rancher-cert/_index.md | 6 +++++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 76865145076..526155b9ee7 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -219,7 +219,11 @@ helm upgrade rancher rancher-stable/rancher \ --set ... ``` -After upgrade is completed, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: +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 diff --git a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md index 09485cf47dd..9af5b7bf3db 100644 --- a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md @@ -231,7 +231,11 @@ helm upgrade rancher rancher-stable/rancher \ --set ... ``` -After upgrade is completed, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: +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 diff --git a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md index c9bdf724e3a..35ef121f40c 100644 --- a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md @@ -228,7 +228,11 @@ helm upgrade rancher rancher-stable/rancher \ --set ... ``` -After upgrade is completed, the `privateCA` parameter must be either removed or set to `false` because the CA is valid: +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 From 2d3072b79ddfd44a236b0cc8cbe78ff9afdd7a1e Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Tue, 31 May 2022 17:51:10 -0400 Subject: [PATCH 11/11] Added link to API key page --- .../en/installation/resources/update-rancher-cert/_index.md | 4 ++-- .../en/installation/resources/update-rancher-cert/_index.md | 2 +- .../en/installation/resources/update-rancher-cert/_index.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md index 526155b9ee7..f27a09a8825 100644 --- a/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/resources/update-rancher-cert/_index.md @@ -58,7 +58,7 @@ $ kubectl -n cattle-system create secret generic tls-ca \ ## 3. Reconfigure the Rancher deployment -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. +> Before proceeding, [generate an API token in the Rancher UI]({{}}/rancher/v2.0-v2.4/en/user-settings/api-keys/#creating-an-api-key) (User > API & Keys). 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`). @@ -189,7 +189,7 @@ kubectl -n cattle-system delete secret tls-ca ## 3. Reconfigure the Rancher deployment -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. +> 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) (User > API & Keys) 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`). diff --git a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md index 9af5b7bf3db..75ea85f862b 100644 --- a/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.5/en/installation/resources/update-rancher-cert/_index.md @@ -201,7 +201,7 @@ kubectl -n cattle-system delete secret tls-ca ## 3. Reconfigure the Rancher deployment -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. +> Before proceeding, [generate an API token in the Rancher UI]({{}}/rancher/v2.5/en/user-settings/api-keys/#creating-an-api-key) (User > API & Keys). 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`). diff --git a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md index 35ef121f40c..afb49caa9df 100644 --- a/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md +++ b/content/rancher/v2.6/en/installation/resources/update-rancher-cert/_index.md @@ -198,7 +198,7 @@ kubectl -n cattle-system delete secret tls-ca ## 3. Reconfigure the Rancher deployment -> Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. +> Before proceeding, [generate an API token in the Rancher UI]({{}}/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (User > API & Keys). 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`).