TLS Settings

Changing the default TLS settings depends on the chosen installation method.

Running Rancher in a highly available Kubernetes cluster

When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster’s ingress controller. The possible TLS settings depend on the used ingress controller:

• nginx-ingress-controller (default for RKE1 and RKE2): Default TLS Version and Ciphers.
• traefik (default for K3s): TLS Options.

Running Rancher in a single Docker container

The default TLS configuration only accepts TLS 1.2 and secure TLS cipher suites. You can change this by setting the following environment variables:

Agent TLS Enforcement

The agent-tls-mode setting controls how Rancher’s agents (cluster-agent, fleet-agent, and system-agent) validate Rancher’s certificate.

When the value is set to strict, Rancher’s agents only trust certificates generated by the Certificate Authority contained in the cacerts setting. 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.

While the strict option enables a higher level of security, it requires Rancher to have access to the CA which generated the certificate visible to the agents. In the case of certain certificate configurations (notably, external certificates), this is not automatic, and extra configuration is needed. See the installation guide for more information on which scenarios require extra configuration.

In Rancher v2.9.0 and later, this setting defaults to strict on new installs. For users installing or upgrading from a prior Rancher version, it is set to system-store.

Preparing for the Setting Change

Each cluster contains a condition in the status field called AgentTlsStrictCheck. If AgentTlsStrictCheck is set to "True", this indicates that the agents for the cluster are ready to operate in strict mode. You can manually inspect each cluster to see if they are ready using the Rancher UI or a kubectl command such as the following:

## the below command skips ouputs $CLUSTER_NAME,$STATUS for all non-local clusters
kubectl get cluster.management.cattle.io -o jsonpath='{range .items[?(@.metadata.name!="local")]}{.metadata.name},{.status.conditions[?(@.type=="AgentTlsStrictCheck")].status}{"\n"}{end}'

Changing the Setting

You can change the setting using the Rancher UI or the agentTLSMode helm chart option.

note

If you specify the value through the Helm chart, you may only modify the value with Helm.

danger

Depending on your cert setup, additional action may be required, such as uploading the Certificate Authority which signed your certs. Review the installation guide before changing the setting to see if any additional requirements apply to your setup.

To change the setting’s value through the UI, navigate to the Global Settings page, and find the agent-tls-mode setting near the bottom of the page. When you change the setting through the UI, Rancher first checks that all downstream clusters have the condition AgentTlsStrictCheck set to "True" before allowing the request. This prevents outages from a certificate mismatch.

Overriding the Setting Validation Checks

In some cases, you may want to override the check ensuring all agents can accept the new TLS configuration:

danger

Rancher checks the status of all downstream clusters to prevent outages. Overriding this check is not recommended, and should be done with great caution.

1. As an admin, generate a kubeconfig for the local cluster. In the below examples, this was saved to the local_kubeconfig.yaml file.
2. Retrieve the current setting and save it to setting.yaml:

kubectl get setting agent-tls-mode -o yaml --kubeconfig=local_kubeconfig.yaml > setting.yaml

1. Update the setting.yaml file, replacing value with strict. Adding the cattle.io/force: "true" annotation overrides the cluster condition check, and should only be done with great care:

danger

Including the cattle.io/force annotation with any value (including, for example "false") overrides the cluster condition check.

apiVersion: management.cattle.io/v3
customized: false
default: strict
kind: Setting
metadata:
  name: agent-tls-mode
  annotations:
    cattle.io/force: "true"
source: ""
value: strict

1. Apply the new version of the setting:

kubectl apply -f setting.yaml --kubeconfig=local_kubeconfig.yaml