NAME

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

VERSION

version 0.001

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 pull-through registry cache
install_agent(
  distribution   => 'rke2',
  server         => 'https://10.0.0.1:9345',
  token          => 'K10abc123...',
  registry_cache => '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

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

• Running the official distribution installer via curl | sh

• Enabling and starting the agent systemd service

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 K3S_URL and K3S_TOKEN environment variables.

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.

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.

node_name

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

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.

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.