Skip to content

Installing RKE2 for Traceable SMP

This guide explains how to install RKE2 (Rancher Kubernetes Engine 2) for a Traceable SMP deployment using the clustermgr CLI.

Prerequisites

Before starting the RKE2 installation, ensure you have:

  • Downloaded the Traceable Platform package on each cluster node
  • Root or sudo access on all nodes
  • Network connectivity between all nodes
  • A default route configured on each node
  • iptables or xtables-nft installed
  • Ports 9345 and 6443 open between all nodes (and from agents to server/LB)
  • (Optional) Load balancer configured for HA setup

Overview

RKE2 installation is handled end-to-end by clustermgr. The installer automatically performs all pre-install checks and system configuration (swap, kernel modules, sysctl, NetworkManager, conflicting services), installs RKE2 binaries, and starts the RKE2 service.

The general command pattern is:

RKE2_VERSION=v1.35.3+rke2r3 clustermgr install --skip-ti

Environment variables control the behavior of each node installation. The key variables are:

Variable Description Default
RKE2_VERSION RKE2 version to install (e.g. v1.35.3+rke2r3) Required
INSTALL_RKE2_TYPE Node role: server or agent server
RKE2_SERVER_URL URL of the first server node (required for additional servers and agents) —
RKE2_TOKEN Cluster join token (required for additional servers and agents) —
RKE2_TLS_SAN Comma-separated additional TLS SANs (e.g. LB VIP or DNS name) —
ENABLE_INGRESS_NGINX Use rke2-ingress-nginx instead of Traefik false

Download Package on All Nodes

Before running the installer, download and extract the Traceable Platform package on each node:

Download from the Traceable downloads portal:

curl -LO https://downloads.traceable.ai/platform/installer/clustermgr/linux-amd64/traceable-clustermgr-<version>-linux-amd64.tgz

Extract the package:

tar -xvf traceable-clustermgr-<version>-linux-amd64.tgz
cd traceable-clustermgr-<version>-linux-amd64

Repeat this on every node (server and agent) before running clustermgr.

First Server Node (Primary Control Plane)

Run the following on the first server node:

RKE2_VERSION=v1.35.3+rke2r3 clustermgr install --skip-ti

For HA deployments with a load balancer, include the LB VIP or DNS name as a TLS SAN:

RKE2_VERSION=v1.35.3+rke2r3 RKE2_TLS_SAN=<LB-VIP-or-DNS> clustermgr install --skip-ti

After installation completes, the installer prints a summary including the node token and the exact commands needed to join additional nodes. If needed, retrieve the token directly:

cat /var/lib/rancher/rke2/server/node-token

Verify the first node is ready:

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
export PATH=/var/lib/rancher/rke2/bin:$PATH
kubectl get nodes

Airgap Installation

Download the airgap package from the Traceable downloads portal (https://downloads-onprem.traceable.ai/app/files/platform/), using the traceable-platform-airgap-{version}.tgz archive.

Extract the airgap package:

tar -xvf traceable-platform-airgap-{version}.tgz
cd traceable-platform-airgap-{version}/rke2

Run the following on the first server node:

RKE2_VERSION=v1.35.3+rke2r3 clustermgr install --skip-ti --airgap --skip-image-load

Follow the same steps as the non-airgap path, adding the --airgap and --skip-image-load flags to the clustermgr install command.

Additional Server Nodes (Additional Control Plane)

Verify connectivity to the first server before proceeding:

nc -zv <first-server-ip-or-LB> 9345

Run the following on each additional server node, using the token from the first server.

Online install:

RKE2_VERSION=v1.35.3+rke2r3 \
  INSTALL_RKE2_TYPE=server \
  RKE2_SERVER_URL=https://<first-server-ip-or-LB>:9345 \
  RKE2_TOKEN=<node-token-from-first-server> \
  clustermgr install --skip-ti

Airgap install:

RKE2_VERSION=v1.35.3+rke2r3 \
  ONLINE_INSTALL=false \
  INSTALL_RKE2_TYPE=server \
  RKE2_SERVER_URL=https://<first-server-ip-or-LB>:9345 \
  RKE2_TOKEN=<node-token-from-first-server> \
  clustermgr install --skip-ti --airgap

Note: Use the full token value from /var/lib/rancher/rke2/server/node-token (format: K10...::server:<CA_HASH>).

Agent Nodes (Worker Nodes)

Verify connectivity to the first server or load balancer before proceeding:

nc -zv <first-server-ip-or-LB> 9345

Run the following on each worker node.

Online install:

RKE2_VERSION=v1.35.3+rke2r3 \
  INSTALL_RKE2_TYPE=agent \
  RKE2_SERVER_URL=https://<first-server-ip-or-LB>:9345 \
  RKE2_TOKEN=<node-token-from-first-server> \
  clustermgr install --skip-ti

Airgap install:

RKE2_VERSION=v1.35.3+rke2r3 \
  ONLINE_INSTALL=false \
  INSTALL_RKE2_TYPE=agent \
  RKE2_SERVER_URL=https://<first-server-ip-or-LB>:9345 \
  RKE2_TOKEN=<node-token-from-first-server> \
  clustermgr install --skip-ti --airgap

Validate Cluster

On the first server node, verify all nodes have joined and are in Ready state:

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
export PATH=/var/lib/rancher/rke2/bin:$PATH
kubectl get nodes

Expected output (all nodes should show Ready):

NAME          STATUS   ROLES                       AGE   VERSION
node-1        Ready    control-plane,etcd,master   10m   v1.35.3+rke2r3
node-2        Ready    control-plane,etcd,master   8m    v1.35.3+rke2r3
node-3        Ready    control-plane,etcd,master   6m    v1.35.3+rke2r3
worker-1      Ready    <none>                      4m    v1.35.3+rke2r3

Important Notes

High Availability (HA) Setup

  • Configure a load balancer pointing to all server nodes on port 9345 (registration) and 6443 (Kubernetes API)
  • Pass the LB VIP or DNS name via RKE2_TLS_SAN on the first server node installation
  • Use the LB address in RKE2_SERVER_URL when joining additional servers and agents

RKE2 Storage

RKE2 stores data by default in /var/lib/rancher/rke2. A minimum of 100 GB is recommended for this path.

To change the data directory, add the following to /etc/rancher/rke2/config.yaml before starting RKE2:

data-dir: /traceable/

Note: This only changes the RKE2 data directory, not other paths such as /var/lib/kubelet or /var/lib/cni.

Troubleshooting

Port 9345 Not Accessible

  • Verify firewall rules allow traffic on port 9345 between all nodes
  • Check network connectivity: nc -zv <server-ip> 9345

Token Mismatch Errors

  • Use the full node token from /var/lib/rancher/rke2/server/node-token
  • Verify no extra whitespace or line breaks were included when copying the token

Nodes Not Joining the Cluster

Check the service status and logs on the failing node:

systemctl status rke2-server   # or rke2-agent for worker nodes
journalctl -u rke2-server -f   # or rke2-agent for worker nodes

Swap Not Disabled

The installer will prompt to disable swap interactively. To pre-disable swap before running the installer:

swapoff --all
sed -i '/\bswap\b/ s/^/#/' /etc/fstab

Next Steps

After all nodes are in Ready state:

  1. Proceed with Traceable Platform installation using clustermgr install-ti
  2. Refer to Multi-Node Installation for platform deployment steps

Support

For RKE2 installation assistance, contact: support@harness.io