NAME

Rex::Rancher::Node - Linux node preparation for Rancher Kubernetes distributions (RKE2/K3s)

VERSION

version 0.001

SYNOPSIS

use Rex::Rancher::Node;

# Full preparation with hostname
prepare_node(
  hostname => 'worker-01',
  domain   => 'k8s.local',
  timezone => 'Europe/Berlin',
);

# Minimal preparation — leave hostname and locale at OS defaults
prepare_node();

# Skip NTP (e.g. host is a VM with hypervisor time sync)
prepare_node(
  hostname => 'vm-01',
  domain   => 'k8s.local',
  ntp      => 0,
);

DESCRIPTION

Rex::Rancher::Node prepares a Linux node for Rancher Kubernetes distributions (RKE2 and K3s). It is distribution-agnostic — the same "prepare_node" call works on Debian, Ubuntu, RHEL/Rocky/Alma, and openSUSE Leap.

The module sets OS-level configuration that Kubernetes requires:

• Swap disabled — Kubernetes does not function correctly with swap enabled.

• Kernel modules — br_netfilter is needed for iptables to see bridged traffic; overlay is required for containerd's overlay filesystem.

• Sysctl parameters — IP forwarding and bridge netfilter settings required by Kubernetes networking and CNI plugins.

• NTP — Time skew between nodes causes certificate validation failures and etcd instability. chrony is installed and started.

Called automatically by "rancher_deploy_server" in Rex::Rancher and "rancher_deploy_agent" in Rex::Rancher.

prepare_node

Prepare a Linux node for Kubernetes. Performs all OS-level configuration required before installing RKE2 or K3s:

• Install curl and ca-certificates

• Set hostname via hostnamectl or /etc/hostname (optional)

• Add FQDN entry to /etc/hosts (when both hostname and domain given)

• Set timezone via timedatectl or symlink (default: UTC)

• Set locale via localectl or /etc/default/locale (default: en_US.UTF-8)

• Install and start chrony for NTP synchronisation (default: enabled)

• Disable and remove swap entries from /etc/fstab

• Load br_netfilter and overlay kernel modules and persist to /etc/modules-load.d/kubernetes.conf

• Write /etc/sysctl.d/99-kubernetes.conf with net.ipv4.ip_forward, net.bridge.bridge-nf-call-iptables, and net.bridge.bridge-nf-call-ip6tables, then apply with sysctl --system

prepare_node(
  hostname => 'worker-01',      # optional — short hostname
  domain   => 'k8s.local',      # optional — domain suffix for FQDN
  timezone => 'Europe/Berlin',  # optional, default: UTC
  locale   => 'en_US.UTF-8',    # optional, default: en_US.UTF-8
  ntp      => 1,                 # optional, default: 1 (enable chrony)
);

If hostname is provided without domain, the hostname is still set but no /etc/hosts entry is written.

SEE ALSO

Rex::Rancher, Rex::Rancher::Server, Rex::Rancher::Agent, 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.