Skip to main content
Version: v2.5

Rancher Agents

There are two different agent resources deployed on Rancher managed clusters:

For a conceptual overview of how the Rancher server provisions clusters and communicates with them, refer to the architecture

cattle-cluster-agent

The cattle-cluster-agent is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The cattle-cluster-agent is deployed using a Deployment resource.

cattle-node-agent

The cattle-node-agent is used to interact with nodes in a Rancher Launched Kubernetes cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node. The cattle-node-agent is used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when cattle-cluster-agent is unavailable.

Scheduling rules

Applies to v2.5.4 and higher

Starting with Rancher v2.5.4, the tolerations for the cattle-cluster-agent changed from operator:Exists (allowing all taints) to a fixed set of tolerations (listed below, if no controlplane nodes are visible in the cluster) or dynamically added tolerations based on taints applied to the controlplane nodes. This change was made to allow Taint based Evictions to work properly for cattle-cluster-agent. The default tolerations are described below. If controlplane nodes are present the cluster, the tolerations will be replaced with tolerations matching the taints on the controlplane nodes.

ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
cattle-cluster-agentbeta.kubernetes.io/os:NotIn:windowsnoneNote: These are the default tolerations, and will be replaced by tolerations matching taints applied to controlplane nodes.

effect:NoSchedule
key:node-role.kubernetes.io/controlplane
value:true

effect:NoSchedule
key:node-role.kubernetes.io/control-plane
operator:Exists

effect:NoSchedule
key:node-role.kubernetes.io/master
operator:Exists
cattle-node-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists

The cattle-cluster-agent Deployment has preferred scheduling rules using preferredDuringSchedulingIgnoredDuringExecution, favoring to be scheduled on nodes with the controlplane node. When there are no controlplane nodes visible in the cluster (this is usually the case when using Clusters from Hosted Kubernetes Providers), you can add the label cattle.io/cluster-agent=true on a node to prefer scheduling the cattle-cluster-agent pod to that node.

See Kubernetes: Assigning Pods to Nodes to find more information about scheduling rules.

The preferredDuringSchedulingIgnoredDuringExecution configuration is shown in the table below:

WeightExpression
100node-role.kubernetes.io/controlplane:In:"true"
100node-role.kubernetes.io/control-plane:In:"true"
100node-role.kubernetes.io/master:In:"true"
1cattle.io/cluster-agent:In:"true"

Applies to v2.3.0 up to v2.5.3

ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
cattle-cluster-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists
cattle-node-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists

The cattle-cluster-agent Deployment has preferred scheduling rules using preferredDuringSchedulingIgnoredDuringExecution, favoring to be scheduled on nodes with the controlplane node. See Kubernetes: Assigning Pods to Nodes to find more information about scheduling rules.

The preferredDuringSchedulingIgnoredDuringExecution configuration is shown in the table below:

WeightExpression
100node-role.kubernetes.io/controlplane:In:"true"
1node-role.kubernetes.io/etcd:In:"true"