/ 
Rex-Rancher-0.002
/ Rex::Rancher::Node

NAME

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

VERSION

version 0.002

SYNOPSIS

use Rex::Rancher::Node;

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

# Minimal preparation — hostname left unchanged; timezone UTC and
# locale en_US.UTF-8 are still set (the defaults), chrony installed
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). The same "prepare_node" call is verified on Debian, Ubuntu, and RHEL/Rocky/Alma — the supported set. openSUSE Leap / SLES is unverified: the base-package step there falls through to Rex's generic pkg abstraction (zypper) and has never been exercised on real SUSE hardware, so it is unsupported and best-effort only.

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:

  • On Debian/Ubuntu, stop unattended-upgrades, apt-daily.service and apt-daily-upgrade.service (they hold the apt lock on a fresh boot) and run apt-get update. They are not restarted afterwards; their timers bring them back on schedule, unattended-upgrades at the next boot.

  • 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.