Skip to main content
Version: v2.5

RancherD Configuration Reference

Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

In RancherD, a server node is defined as a machine (bare-metal or virtual) running the rancherd server command. The server runs the Kubernetes API as well as Kubernetes workloads.

An agent node is defined as a machine running the rancherd agent command. They don't run the Kubernetes API. To add nodes designated to run your apps and services, join agent nodes to your cluster.

In the RancherD installation instructions, we recommend running three server nodes in the Rancher server cluster. Agent nodes are not required.

Certificates for the Rancher Server

Rancherd does not use cert-manager to provision certs. Instead RancherD allows you to bring your own self-signed or trusted certs by storing the .pem files in /etc/rancher/ssl/. When doing this you should also set the publicCA parameter to true in your HelmChartConfig. For more information on the HelmChartConfig, refer to the section about customizing the RancherD Helm chart.

Private key: /etc/rancher/ssl/key.pem

Certificate: /etc/rancher/ssl/cert.pem

CA Certificate(self-signed): /etc/rancher/ssl/cacerts.pem

Additional CA Certificate: /etc/ssl/certs/ca-additional.pem

Node Taints

By default, server nodes will be schedulable and thus your workloads can get launched on them. If you wish to have a dedicated control plane where no user workloads will run, you can use taints. The node-taint parameter will allow you to configure nodes with taints. Here is an example of adding a node taint to the config.yaml:

node-taint:
- "CriticalAddonsOnly=true:NoExecute"

Customizing the RancherD Helm Chart

Rancher is launched as a Helm chart using the cluster’s Helm integration. This means that you can easily customize the application through a manifest file describing your custom parameters.

The RancherD chart provisions Rancher in a daemonset. It exposes hostport 8080/8443 down to the container port (80/443), and uses hostpath to mount certs if needed.

RancherD uses helm-controller to bootstrap the RancherD chart. To provide a customized values.yaml file, the configuration options must be passed in through the helm-controller custom resource definition.

Here is an example of the manifest:

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
name: rancher
namespace: kube-system
spec:
valuesContent: |
publicCA: true

Put this manifest on your host in /var/lib/rancher/rke2/server/manifests before running RancherD.

Common Options

ParameterDefault ValueDescription
addLocal"auto"string - Have Rancher detect and import the local Rancher server cluster
auditLog.destination"sidecar"string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
auditLog.hostPath"/var/log/rancher/audit"string - log file destination on host (only applies when auditLog.destination is set to hostPath)
auditLog.level0int - set the API Audit Log level. 0 is off. [0-3]
auditLog.maxAge1int - maximum number of days to retain old audit log files (only applies when auditLog.destination is set to hostPath)
auditLog.maxBackups1int - maximum number of audit log files to retain (only applies when auditLog.destination is set to hostPath)
auditLog.maxSize100int - maximum size in megabytes of the audit log file before it gets rotated (only applies when auditLog.destination is set to hostPath)
debugfalsebool - set debug flag on rancher server
extraEnv[]list - set additional environment variables for Rancher
imagePullSecrets[]list - list of names of Secret resource containing private registry credentials
proxy" "*string - HTTP[S] proxy server for Rancher
noProxy"127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"string - comma separated list of hostnames or ip address not to use the proxy
resources{}map - rancher pod resource requests & limits
rancherImage"rancher/rancher"string - rancher image source
rancherImageTagsame as chart versionstring - rancher/rancher image tag
rancherImagePullPolicy"IfNotPresent"string - Override imagePullPolicy for rancher server images - "Always", "Never", "IfNotPresent"
systemDefaultRegistry""string - private registry to be used for all system Docker images, e.g., [http://registry.example.com/]
useBundledSystemChartfalsebool - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations.
publicCAfalsebool - Set to true if your cert is signed by a public CA

RancherD Server CLI Options

The command to run the Rancher management server is:

rancherd server [OPTIONS]

It can be run with the following options:

Config

OptionDescription
--config FILE, -c FILELoad configuration from FILE (default: "/etc/rancher/rke2/config.yaml")

Logging

OptionDescription
--debugTurn on debug logs

Listener

OptionDescription
--bind-address valueRancherD bind address (default: 0.0.0.0)
--advertise-address valueIP address that apiserver uses to advertise to members of the cluster (default: node-external-ip/node-ip)
--tls-san valueAdd hostname or IP as a Subject Alternative Name in the TLS cert

Data

OptionDescription
--data-dir value, -d valueFolder to hold state (default: "/var/lib/rancher/rancherd")

Networking

OptionDescription
--cluster-cidr valueNetwork CIDR to use for pod IPs (default: "10.42.0.0/16")
--service-cidr valueNetwork CIDR to use for services IPs (default: "10.43.0.0/16")
--cluster-dns valueCluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10)
--cluster-domain valueCluster Domain (default: "cluster.local")

Cluster

OptionDescription
--token value, -t valueShared secret used to join a server or agent to a cluster
--token-file valueFile containing the cluster-secret/token

Client

OptionDescription
--write-kubeconfig value, -o valueWrite kubeconfig for admin client to this file
--write-kubeconfig-mode valueWrite kubeconfig with this mode

Flags

OptionDescription
--kube-apiserver-arg valueCustomized flag for kube-apiserver process
--kube-scheduler-arg valueCustomized flag for kube-scheduler process
--kube-controller-manager-arg valueCustomized flag for kube-controller-manager process

Database

OptionDescription
--etcd-disable-snapshotsDisable automatic etcd snapshots
--etcd-snapshot-schedule-cron valueSnapshot interval time in cron spec. eg. every 5 hours '* /5 * ' (default: "0 /12 * * *")
--etcd-snapshot-retention valueNumber of snapshots to retain (default: 5)
--etcd-snapshot-dir valueDirectory to save db snapshots. (Default location: ${data-dir}/db/snapshots)
--cluster-reset-restore-path valuePath to snapshot file to be restored

System Images Registry

OptionDescription
--system-default-registry valuePrivate registry to be used for all system Docker images

Components

OptionDescription
--disable valueDo not deploy packaged components and delete any deployed components (valid items: rancherd-canal, rancherd-coredns, rancherd-ingress, rancherd-kube-proxy, rancherd-metrics-server)

Cloud Provider

OptionDescription
--cloud-provider-name valueCloud provider name
--cloud-provider-config valueCloud provider configuration file path

Security

OptionDescription
--profile valueValidate system configuration against the selected benchmark (valid items: cis-1.5)

Agent Node

OptionDescription
--node-name valueNode name
--node-label valueRegistering and starting kubelet with set of labels
--node-taint valueRegistering kubelet with set of taints
--protect-kernel-defaultsKernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults.
--selinuxEnable SELinux in containerd

Agent Runtime

OptionDescription
--container-runtime-endpoint valueDisable embedded containerd and use alternative CRI implementation
--snapshotter valueOverride default containerd snapshotter (default: "overlayfs")
--private-registry valuePrivate registry configuration file (default: "/etc/rancher/rke2/registries.yaml")

Agent Networking

OptionDescription
--node-ip value, -i valueIP address to advertise for node
--resolv-conf valueKubelet resolv.conf file

Agent Flags

OptionDescription
--kubelet-arg valueCustomized flag for kubelet process
--kube-proxy-arg valueCustomized flag for kube-proxy process

Experimental

OptionDescription
--agent-token valueShared secret used to join agents to the cluster, but not servers
--agent-token-file valueFile containing the agent secret
--server value, -s valueServer to connect to, used to join a cluster
--cluster-resetForget all peers and become sole member of a new cluster
--secrets-encryptionEnable Secret encryption at rest

RancherD Agent CLI Options

The following command is used to run the RancherD agent:

rancherd agent [OPTIONS]

The following options are available.

Config

OptionDescription
--config FILE, -c FILELoad configuration from FILE (default: "/etc/rancher/rke2/config.yaml")

Data

OptionDescription
--data-dir value, -d valueFolder to hold state (default: "/var/lib/rancher/rancherd")

Logging

OptionDescription
--debugTurn on debug logs

Cluster

OptionDescription
--token value, -t valueToken to use for authentication
--token-file valueToken file to use for authentication
--server value, -s valueServer to connect to

Agent Node

OptionDescription
--node-name valueNode name
--node-label valueRegistering and starting kubelet with set of labels
--node-taint valueRegistering kubelet with set of taints
--selinuxEnable SELinux in containerd
--protect-kernel-defaultsKernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults.

Agent Runtime

OptionDescription
--container-runtime-endpoint valueDisable embedded containerd and use alternative CRI implementation
--snapshotter valueOverride default containerd snapshotter (default: "overlayfs")
--private-registry valuePrivate registry configuration file (default: "/etc/rancher/rke2/registries.yaml")

Agent Networking

OptionDescription
--node-ip value, -i valueIP address to advertise for node
--resolv-conf valueKubelet resolv.conf file

Agent Flags

OptionDescription
--kubelet-arg valueCustomized flag for kubelet process
--kube-proxy-arg valueCustomized flag for kube-proxy process

System Images Registry

OptionDescription
--system-default-registry valuePrivate registry to be used for all system Docker images

Cloud Provider

OptionDescription
--cloud-provider-name valueCloud provider name
--cloud-provider-config valueCloud provider configuration file path

Security

OptionDescription
--profile valueValidate system configuration against the selected benchmark (valid items: cis-1.5)