Skip to main content
Version: v2.5

Rancher Agent Options

Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to create a cluster with custom nodes and add the options to the generated docker run command when adding a node.

For an overview of how Rancher communicates with downstream clusters using node agents, refer to the architecture section.

General options

ParameterEnvironment variableDescription
--serverCATTLE_SERVERThe configured Rancher server-url setting which the agent connects to
--tokenCATTLE_TOKENToken that is needed to register the node in Rancher
--ca-checksumCATTLE_CA_CHECKSUMThe SHA256 checksum of the configured Rancher cacerts setting to validate
--node-nameCATTLE_NODE_NAMEOverride the hostname that is used to register the node (defaults to hostname -s)
--labelCATTLE_NODE_LABELAdd node labels to the node. For multiple labels, pass additional --label options. (--label key=value)
--taintsCATTLE_NODE_TAINTSAdd node taints to the node. For multiple taints, pass additional --taints options. (--taints key=value:effect)

Role options

ParameterEnvironment variableDescription
--all-rolesALL=trueApply all roles (etcd,controlplane,worker) to the node
--etcdETCD=trueApply the role etcd to the node
--controlplaneCONTROL=trueApply the role controlplane to the node
--workerWORKER=trueApply the role worker to the node

IP address options

ParameterEnvironment variableDescription
--addressCATTLE_ADDRESSThe IP address the node will be registered with (defaults to the IP used to reach 8.8.8.8)
--internal-addressCATTLE_INTERNAL_ADDRESSThe IP address used for inter-host communication on a private network

Dynamic IP address options

For automation purposes, you can't have a specific IP address in a command as it has to be generic to be used for every node. For this, we have dynamic IP address options. They are used as a value to the existing IP address options. This is supported for --address and --internal-address.

ValueExampleDescription
Interface name--address eth0The first configured IP address will be retrieved from the given interface
ipify--address ipifyValue retrieved from https://api.ipify.org will be used
awslocal--address awslocalValue retrieved from http://169.254.169.254/latest/meta-data/local-ipv4 will be used
awspublic--address awspublicValue retrieved from http://169.254.169.254/latest/meta-data/public-ipv4 will be used
doprivate--address doprivateValue retrieved from http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address will be used
dopublic--address dopublicValue retrieved from http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address will be used
azprivate--address azprivateValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/privateIpAddress?api-version=2017-08-01&format=text will be used
azpublic--address azpublicValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text will be used
gceinternal--address gceinternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/ip will be used
gceexternal--address gceexternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip will be used
packetlocal--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/local-ipv4 will be used
packetpublic--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/public-ipv4 will be used