RKE2 Worker Setup

This runbook documents how to add a Linux worker node to an existing RKE2 cluster.

Prerequisites

Before joining a worker, confirm that:

• The RKE2 control plane is healthy.
• The worker can reach the control plane on TCP port 9345.
• You have obtained the RKE2 node token through a secure channel.
• The worker has a unique hostname or node name.
• The supported firewall paths between the worker and control plane are open.

Do not store the node token in Git, a public wiki, shell history, screenshots, or shared logs.

Install the RKE2 agent

Run the standard RKE2 agent installer on the worker:

curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -

Configure the worker

Create the RKE2 configuration directory:

sudo mkdir -p /etc/rancher/rke2

Create or edit the agent configuration:

sudo vim /etc/rancher/rke2/config.yaml

Use the following structure:

server: https://<CONTROL_PLANE_IP>:9345
token: <RKE2_NODE_TOKEN>
node-name: <WORKER_NODE_NAME>

Replace each placeholder locally. Never commit the populated configuration file to a public repository.

Enable and start the agent

sudo systemctl enable rke2-agent.service
sudo systemctl start rke2-agent.service

Verify the worker

From a trusted administration workstation with cluster access:

kubectl get nodes

The control-plane and worker nodes should both report Ready. A plain worker may have no explicit role shown in the ROLES column unless a custom role label was added.

Inspect the cluster workloads:

kubectl get pods -A

Confirm that the RKE2 networking components are running on the worker and that core cluster services are healthy.

System jobs after the first worker joins

When the control-plane node is tainted or reserved for control-plane workloads, some RKE2 installation jobs may remain pending until a schedulable worker is available.

In the validated deployment, the pending RKE2 system jobs completed after the worker joined and became Ready. These included installation jobs associated with:

• Canal
• CoreDNS
• Metrics Server
• RuntimeClasses
• Snapshot Controller
• Snapshot Controller CRDs

This is a useful validation that the new worker is schedulable and participating correctly in the cluster.

Verification checklist

• The rke2-agent service is active.
• The worker appears in kubectl get nodes.
• The worker reports Ready.
• The RKE2 network plugin is running on the worker.
• CoreDNS and Metrics Server are healthy.
• Previously pending system installation jobs have completed.

Additional troubleshooting

Check the agent service:

sudo systemctl status rke2-agent

Follow the agent logs:

sudo journalctl -u rke2-agent -f

Confirm that the worker can reach the RKE2 supervisor:

curl -k https://<CONTROL_PLANE_IP>:9345

Inspect the node and recent cluster events:

kubectl describe node <WORKER_NODE_NAME>
kubectl get events -A --sort-by=.lastTimestamp

If the node does not join, verify the control-plane address, port reachability, system clock, hostname uniqueness, and the locally supplied node token.

Security

Never publish or commit:

• RKE2 node tokens
• Kubeconfig credentials
• SSH private keys
• Passwords
• Kubernetes service-account tokens

Use placeholders in all public examples.