/ 
Rex-Rancher-0.002
/ Rex::Rancher::Agent

NAME

Rex::Rancher::Agent - Rancher Kubernetes agent (worker node) installation

VERSION

version 0.002

SYNOPSIS

use Rex::Rancher::Agent;

# Join an RKE2 cluster as worker
install_agent(
  server => 'https://10.0.0.1:9345',
  token  => 'K10abc123...',
);

# Join a K3s cluster as worker
install_agent(
  distribution => 'k3s',
  server       => 'https://10.0.0.1:6443',
  token        => 'K10abc123...',
  version      => 'v1.28.4+k3s1',
  node_name    => 'worker-01',
);

# With a pull-through registry mirror
install_agent(
  distribution => 'rke2',
  server       => 'https://10.0.0.1:9345',
  token        => 'K10abc123...',
  registries   => {
    mirrors => { 'docker.io' => { endpoint => ['http://cache.local:5000'] } },
  },
);

DESCRIPTION

Rex::Rancher::Agent installs and configures a Rancher Kubernetes worker node for either RKE2 or K3s. It handles:

  • Writing config.yaml with the server URL, token, and optional node name and node labels

  • Writing registries.yaml for private registry mirrors (optional)

  • Running the official distribution installer via curl | sh, or from a checksum-verified release artifact (install_method => 'artifact')

  • Enabling and starting the agent systemd service, and waiting until it is active (journal tail in the error if it is not)

For RKE2 the installer is fetched from https://get.rke2.io with INSTALL_RKE2_TYPE=agent. For K3s the installer from https://get.k3s.io is used with the K3S_URL environment variable and INSTALL_K3S_SKIP_START: instead of the script's own blocking restart, the agent is restarted with --no-block and waited on for at most 10 minutes, so an agent that cannot reach its server dies with its journal instead of hanging the deploy. For both distributions the token is read from config.yaml and never passed on the installer command line, where ps would show it. config.yaml and registries.yaml are written 0600 root:root.

Registry configuration uses the same YAML structure and helper as Rex::Rancher::Server, so mirrors configured for the server are directly reusable for agents.

install_agent

Write the agent configuration, optionally write registries.yaml, run the distribution installer, enable and start the agent service, and wait until systemctl is-active reports it active (up to 10 minutes). A service that ends up failed or never gets active dies with the last 50 lines of its journal in the message.

Required options:

server

URL of the server to join. For RKE2: https://SERVER_IP:9345. For K3s: https://SERVER_IP:6443.

token

Node join token. Obtain from the running server with "get_token" in Rex::Rancher::Server.

Optional options:

distribution

rke2 (default) or k3s.

version

Pinned version string, e.g. v1.28.4+rke2r1 for RKE2 or v1.28.4+k3s1 for K3s. If omitted, the latest stable release is installed. When given, the installed binary's --version is checked against it after the installer ran, and a mismatch dies (on RKE2 before the service is started; the K3s install script has already started it).

install_method

script (default: curl | sh, unchanged) or artifact: download the release artifact for the node's architecture on the host, verify it against the official sha256sum-ARCH.txt (a mismatch dies), and install from it. Requires version. Details, including the RPM-host caveat for RKE2, in "install_server" in Rex::Rancher::Server.

node_name

Override the Kubernetes node name. If omitted, the system hostname is used.

node_labels

Node labels applied at join time (node-label in config.yaml), as an arrayref of key=value strings. Same as "install_server" in Rex::Rancher::Server's node_labels; like there, labels are only read when the agent registers, not on a re-run against a node that already joined.

registries

Private registry mirror configuration hashref. Same structure as "install_server" in Rex::Rancher::Server's registries option. Written to registries.yaml in the distribution config directory.

nvidia_runtime_path

If true, and nvidia-container-runtime is on the host's PATH, write a PATH= line to /etc/default/rke2-agent before the installer runs, so rke2 finds a host-installed NVIDIA runtime at service start. Same behaviour as "install_server" in Rex::Rancher::Server's nvidia_runtime_path; no effect on k3s. Default: 0; "rancher_deploy_agent" in Rex::Rancher turns it on for gpu => 1, gpu_setup => 0.

install_agent(
  distribution => 'rke2',
  server       => 'https://10.0.0.1:9345',
  token        => 'K10abc123...',
);

SEE ALSO

Rex::Rancher, Rex::Rancher::Server, Rex::Rancher::Node, Rex

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/rex-rancher/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.