From 48e1114f4407a025849f6ba99b895aec9b6d4eb2 Mon Sep 17 00:00:00 2001 From: e-minguez Date: Wed, 28 Jan 2026 13:27:19 +0100 Subject: [PATCH] feat: Added a note for Let's Encrypt certs --- docs/certificate-authority.md | 24 ++++++++++--------- .../version-1.7/certificate-authority.md | 24 ++++++++++--------- .../version-1.8/certificate-authority.md | 24 ++++++++++--------- 3 files changed, 39 insertions(+), 33 deletions(-) diff --git a/docs/certificate-authority.md b/docs/certificate-authority.md index f04b115a4..06329ba46 100644 --- a/docs/certificate-authority.md +++ b/docs/certificate-authority.md @@ -1,6 +1,6 @@ --- sidebar_label: Certificate Authority Verification -title: '' +title: "" --- @@ -9,25 +9,27 @@ title: '' # Certificate Authority Verification -The `elemental-register` and `elemental-system-agent` rely on the [Rancher's Certificate Authority configuration](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/update-rancher-certificate) to verify the [MachineRegistration](https://elemental.docs.rancher.com/machineregistration-reference#configelementalregistration) URL, and to remotely watch plans. +The `elemental-register` and `elemental-system-agent` rely on the [Rancher's Certificate Authority configuration](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/update-rancher-certificate) to verify the [MachineRegistration](https://elemental.docs.rancher.com/machineregistration-reference#configelementalregistration) URL, and to remotely watch plans. -Depending on whether the Certificate Authority is private or public, you may want to instruct the agent to enforce `strict` CA verification, or to use the system trust store instead. +Depending on whether the Certificate Authority is private or public, you may want to instruct the agent to enforce `strict` CA verification, or to use the system trust store instead. From Rancher `2.9`, the [agent-tls-mode](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-references/tls-settings#agent-tls-enforcement) global setting will also apply to the installation of Elemental agents. -Note that if the `agent-tls-mode` setting changes, Elemental machines will need to be [reset](./reset.md) in order for the setting to apply. +Note that if the `agent-tls-mode` setting changes, Elemental machines will need to be [reset](./reset.md) in order for the setting to apply. + +:::info Let's Encrypt note +If using Let's Encrypt and `agent-tls-mode=strict` it is required for Rancher to have access to the CA which generated the certificate visible to the agents. This is not automatic, and extra configuration is needed. See the [Rancher installation guide](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster#3-choose-your-ssl-configuration) for more information on which scenarios require extra configuration. Another option is to set `agent-tls-mode=system-store` instead. When the value is set to system-store, Rancher's agents trust any certificate generated by a public Certificate Authority contained in the operating system's trust store including those signed by authorities such as Let's Encrypt. This can be a security risk, since any certificate generated by these external authorities, which are outside the user's control, are considered valid in this state. +::: ## Private CA certificate lifecycle When using a private CA, the recommendation is to always make sure that the same CA is also used for Rancher. -Elemental will make use of the `cacerts`, when including the CA cert to be trusted by agents. This is the same value as it appears on the `https://my.rancher.example/cacerts` URL. +Elemental will make use of the `cacerts`, when including the CA cert to be trusted by agents. This is the same value as it appears on the `https://my.rancher.example/cacerts` URL. Note however that it will not be possible to update this value after an Elemental machine has been installed. -Replacing the CA certificate on Rancher may lead to Elemental machines not being able to re-connect to Rancher and operating normally, when the `agent-tls-mode` is set to `strict`. - -For this reason the recommendation is to use the `agent-tls-mode: system-store` setting instead and manage the lifecycle of CA certs on Elemental machines directly, when a private Certificate Authority is in use. +Replacing the CA certificate on Rancher may lead to Elemental machines not being able to re-connect to Rancher and operating normally, when the `agent-tls-mode` is set to `strict`. The CA cert can be installed in [custom OS images](./custom-images.md) directly, or passed as a cloud-init configuration in Elemental resources. -For example the initial CA certificate can be included in the [MachineRegistration](./machineregistration-reference.md#configcloud-config) `cloud-config`: +For example the initial CA certificate can be included in the [MachineRegistration](./machineregistration-reference.md#configcloud-config) `cloud-config`: ```yaml apiVersion: elemental.cattle.io/v1beta1 @@ -66,7 +68,7 @@ spec: ``` Before the CA cert is replaced on Rancher, the new CA cert can be included on Elemental machines by upgrading them. -The **new** CA cert can be configured in the [ManagedOSImage](./managedosimage-reference.md#cloudconfig) `cloudConfig`: +The **new** CA cert can be configured in the [ManagedOSImage](./managedosimage-reference.md#cloudconfig) `cloudConfig`: ```yaml apiVersion: elemental.cattle.io/v1beta1 @@ -107,7 +109,7 @@ spec: - clusterName: volcano upgradeContainer: envs: - # Use FORCE to force an upgrade. + # Use FORCE to force an upgrade. # This is convenient when the `osImage` is the same, and only the `cloudConfig` changed. - name: FORCE value: "false" diff --git a/versioned_docs/version-1.7/certificate-authority.md b/versioned_docs/version-1.7/certificate-authority.md index f04b115a4..06329ba46 100644 --- a/versioned_docs/version-1.7/certificate-authority.md +++ b/versioned_docs/version-1.7/certificate-authority.md @@ -1,6 +1,6 @@ --- sidebar_label: Certificate Authority Verification -title: '' +title: "" --- @@ -9,25 +9,27 @@ title: '' # Certificate Authority Verification -The `elemental-register` and `elemental-system-agent` rely on the [Rancher's Certificate Authority configuration](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/update-rancher-certificate) to verify the [MachineRegistration](https://elemental.docs.rancher.com/machineregistration-reference#configelementalregistration) URL, and to remotely watch plans. +The `elemental-register` and `elemental-system-agent` rely on the [Rancher's Certificate Authority configuration](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/update-rancher-certificate) to verify the [MachineRegistration](https://elemental.docs.rancher.com/machineregistration-reference#configelementalregistration) URL, and to remotely watch plans. -Depending on whether the Certificate Authority is private or public, you may want to instruct the agent to enforce `strict` CA verification, or to use the system trust store instead. +Depending on whether the Certificate Authority is private or public, you may want to instruct the agent to enforce `strict` CA verification, or to use the system trust store instead. From Rancher `2.9`, the [agent-tls-mode](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-references/tls-settings#agent-tls-enforcement) global setting will also apply to the installation of Elemental agents. -Note that if the `agent-tls-mode` setting changes, Elemental machines will need to be [reset](./reset.md) in order for the setting to apply. +Note that if the `agent-tls-mode` setting changes, Elemental machines will need to be [reset](./reset.md) in order for the setting to apply. + +:::info Let's Encrypt note +If using Let's Encrypt and `agent-tls-mode=strict` it is required for Rancher to have access to the CA which generated the certificate visible to the agents. This is not automatic, and extra configuration is needed. See the [Rancher installation guide](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster#3-choose-your-ssl-configuration) for more information on which scenarios require extra configuration. Another option is to set `agent-tls-mode=system-store` instead. When the value is set to system-store, Rancher's agents trust any certificate generated by a public Certificate Authority contained in the operating system's trust store including those signed by authorities such as Let's Encrypt. This can be a security risk, since any certificate generated by these external authorities, which are outside the user's control, are considered valid in this state. +::: ## Private CA certificate lifecycle When using a private CA, the recommendation is to always make sure that the same CA is also used for Rancher. -Elemental will make use of the `cacerts`, when including the CA cert to be trusted by agents. This is the same value as it appears on the `https://my.rancher.example/cacerts` URL. +Elemental will make use of the `cacerts`, when including the CA cert to be trusted by agents. This is the same value as it appears on the `https://my.rancher.example/cacerts` URL. Note however that it will not be possible to update this value after an Elemental machine has been installed. -Replacing the CA certificate on Rancher may lead to Elemental machines not being able to re-connect to Rancher and operating normally, when the `agent-tls-mode` is set to `strict`. - -For this reason the recommendation is to use the `agent-tls-mode: system-store` setting instead and manage the lifecycle of CA certs on Elemental machines directly, when a private Certificate Authority is in use. +Replacing the CA certificate on Rancher may lead to Elemental machines not being able to re-connect to Rancher and operating normally, when the `agent-tls-mode` is set to `strict`. The CA cert can be installed in [custom OS images](./custom-images.md) directly, or passed as a cloud-init configuration in Elemental resources. -For example the initial CA certificate can be included in the [MachineRegistration](./machineregistration-reference.md#configcloud-config) `cloud-config`: +For example the initial CA certificate can be included in the [MachineRegistration](./machineregistration-reference.md#configcloud-config) `cloud-config`: ```yaml apiVersion: elemental.cattle.io/v1beta1 @@ -66,7 +68,7 @@ spec: ``` Before the CA cert is replaced on Rancher, the new CA cert can be included on Elemental machines by upgrading them. -The **new** CA cert can be configured in the [ManagedOSImage](./managedosimage-reference.md#cloudconfig) `cloudConfig`: +The **new** CA cert can be configured in the [ManagedOSImage](./managedosimage-reference.md#cloudconfig) `cloudConfig`: ```yaml apiVersion: elemental.cattle.io/v1beta1 @@ -107,7 +109,7 @@ spec: - clusterName: volcano upgradeContainer: envs: - # Use FORCE to force an upgrade. + # Use FORCE to force an upgrade. # This is convenient when the `osImage` is the same, and only the `cloudConfig` changed. - name: FORCE value: "false" diff --git a/versioned_docs/version-1.8/certificate-authority.md b/versioned_docs/version-1.8/certificate-authority.md index f04b115a4..06329ba46 100644 --- a/versioned_docs/version-1.8/certificate-authority.md +++ b/versioned_docs/version-1.8/certificate-authority.md @@ -1,6 +1,6 @@ --- sidebar_label: Certificate Authority Verification -title: '' +title: "" --- @@ -9,25 +9,27 @@ title: '' # Certificate Authority Verification -The `elemental-register` and `elemental-system-agent` rely on the [Rancher's Certificate Authority configuration](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/update-rancher-certificate) to verify the [MachineRegistration](https://elemental.docs.rancher.com/machineregistration-reference#configelementalregistration) URL, and to remotely watch plans. +The `elemental-register` and `elemental-system-agent` rely on the [Rancher's Certificate Authority configuration](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/update-rancher-certificate) to verify the [MachineRegistration](https://elemental.docs.rancher.com/machineregistration-reference#configelementalregistration) URL, and to remotely watch plans. -Depending on whether the Certificate Authority is private or public, you may want to instruct the agent to enforce `strict` CA verification, or to use the system trust store instead. +Depending on whether the Certificate Authority is private or public, you may want to instruct the agent to enforce `strict` CA verification, or to use the system trust store instead. From Rancher `2.9`, the [agent-tls-mode](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-references/tls-settings#agent-tls-enforcement) global setting will also apply to the installation of Elemental agents. -Note that if the `agent-tls-mode` setting changes, Elemental machines will need to be [reset](./reset.md) in order for the setting to apply. +Note that if the `agent-tls-mode` setting changes, Elemental machines will need to be [reset](./reset.md) in order for the setting to apply. + +:::info Let's Encrypt note +If using Let's Encrypt and `agent-tls-mode=strict` it is required for Rancher to have access to the CA which generated the certificate visible to the agents. This is not automatic, and extra configuration is needed. See the [Rancher installation guide](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster#3-choose-your-ssl-configuration) for more information on which scenarios require extra configuration. Another option is to set `agent-tls-mode=system-store` instead. When the value is set to system-store, Rancher's agents trust any certificate generated by a public Certificate Authority contained in the operating system's trust store including those signed by authorities such as Let's Encrypt. This can be a security risk, since any certificate generated by these external authorities, which are outside the user's control, are considered valid in this state. +::: ## Private CA certificate lifecycle When using a private CA, the recommendation is to always make sure that the same CA is also used for Rancher. -Elemental will make use of the `cacerts`, when including the CA cert to be trusted by agents. This is the same value as it appears on the `https://my.rancher.example/cacerts` URL. +Elemental will make use of the `cacerts`, when including the CA cert to be trusted by agents. This is the same value as it appears on the `https://my.rancher.example/cacerts` URL. Note however that it will not be possible to update this value after an Elemental machine has been installed. -Replacing the CA certificate on Rancher may lead to Elemental machines not being able to re-connect to Rancher and operating normally, when the `agent-tls-mode` is set to `strict`. - -For this reason the recommendation is to use the `agent-tls-mode: system-store` setting instead and manage the lifecycle of CA certs on Elemental machines directly, when a private Certificate Authority is in use. +Replacing the CA certificate on Rancher may lead to Elemental machines not being able to re-connect to Rancher and operating normally, when the `agent-tls-mode` is set to `strict`. The CA cert can be installed in [custom OS images](./custom-images.md) directly, or passed as a cloud-init configuration in Elemental resources. -For example the initial CA certificate can be included in the [MachineRegistration](./machineregistration-reference.md#configcloud-config) `cloud-config`: +For example the initial CA certificate can be included in the [MachineRegistration](./machineregistration-reference.md#configcloud-config) `cloud-config`: ```yaml apiVersion: elemental.cattle.io/v1beta1 @@ -66,7 +68,7 @@ spec: ``` Before the CA cert is replaced on Rancher, the new CA cert can be included on Elemental machines by upgrading them. -The **new** CA cert can be configured in the [ManagedOSImage](./managedosimage-reference.md#cloudconfig) `cloudConfig`: +The **new** CA cert can be configured in the [ManagedOSImage](./managedosimage-reference.md#cloudconfig) `cloudConfig`: ```yaml apiVersion: elemental.cattle.io/v1beta1 @@ -107,7 +109,7 @@ spec: - clusterName: volcano upgradeContainer: envs: - # Use FORCE to force an upgrade. + # Use FORCE to force an upgrade. # This is convenient when the `osImage` is the same, and only the `cloudConfig` changed. - name: FORCE value: "false"