rancher · davidcassany · Feb 6, 2026 · Jan 28, 2026
@@ -1,6 +1,6 @@
 ---
 sidebar_label: Certificate Authority Verification
-title: ''
+title: ""
 ---
 
 <head>
@@ -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"

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Certificate Authority Verification
-title: ''
+title: ""
 ---
 
 <head>
@@ -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"

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Certificate Authority Verification
-title: ''
+title: ""
 ---
 
 <head>
@@ -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"