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:
Parameter | Description | Default | Available options |
---|---|---|---|
CATTLE_TLS_MIN_VERSION | Minimum TLS version | 1.2 | 1.0 , 1.1 , 1.2 , 1.3 |
CATTLE_TLS_CIPHERS | Allowed TLS cipher suites | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 ,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 | See Golang tls constants |
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.
If you specify the value through the Helm chart, you may only modify the value with Helm.
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:
Rancher checks the status of all downstream clusters to prevent outages. Overriding this check is not recommended, and should be done with great caution.
- As an admin, generate a kubeconfig for the local cluster. In the below examples, this was saved to the
local_kubeconfig.yaml
file. - Retrieve the current setting and save it to
setting.yaml
:
kubectl get setting agent-tls-mode -o yaml --kubeconfig=local_kubeconfig.yaml > setting.yaml
- Update the
setting.yaml
file, replacingvalue
withstrict
. Adding thecattle.io/force: "true"
annotation overrides the cluster condition check, and should only be done with great care:
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
- Apply the new version of the setting:
kubectl apply -f setting.yaml --kubeconfig=local_kubeconfig.yaml