/ 
Rex-Rancher-0.001
River stage zero No dependents
/ Rex::Rancher::Cilium

NAME

Rex::Rancher::Cilium - Cilium CNI installation for Rancher Kubernetes distributions

VERSION

version 0.001

SYNOPSIS

use Rex::Rancher::Cilium;

# Install Cilium on an RKE2 cluster (defaults to version 1.17.0)
install_cilium(
  distribution => 'rke2',
);

# Install Cilium on a K3s cluster with explicit version
install_cilium(
  distribution => 'k3s',
  version      => '1.17.0',
  cli_version  => 'v0.16.23',
);

# Upgrade an existing Cilium installation
upgrade_cilium(
  distribution => 'rke2',
  version      => '1.17.0',
);

DESCRIPTION

Rex::Rancher::Cilium provides Cilium CNI installation and upgrade for Rancher Kubernetes distributions (RKE2 and K3s). All operations are run on the remote server host via SSH.

Prerequisites

The server must already be running with cni: none and disable-kube-proxy: true in its config.yaml so that Cilium can own the CNI and kube-proxy roles. "install_server" in Rex::Rancher::Server sets these options by default when cilium => 1.

Helm values

Distribution-specific Helm values are written to /tmp/cilium-values-<dist>.yaml:

RKE2

kubeProxyReplacement: true, k8sServiceHost: 127.0.0.1, k8sServicePort: "6443", cni.exclusive: false, operator.replicas: 1.

K3s

cni.exclusive: true, operator.replicas: 1.

Both distributions use ipam.mode: kubernetes and share the same CNI binary/config paths (/opt/cni/bin, /etc/cni/net.d).

Default versions

The module ships with pinned defaults for reproducibility: Cilium 1.17.0 and Cilium CLI v0.16.23. Override with the version and cli_version options.

FUNCTIONS

install_cilium(%opts)

Install Cilium CNI on a Rancher Kubernetes cluster (RKE2 or K3s).

The Cilium CLI binary is downloaded from GitHub to /usr/local/bin/cilium on the remote host (skipped if the correct version is already present). Distribution-appropriate Helm values are generated and written to /tmp/cilium-values-<dist>.yaml, then cilium install is invoked with those values.

For RKE2, kubeProxyReplacement=true is passed to enable Cilium's eBPF-based kube-proxy replacement (the RKE2 server config must have disable-kube-proxy: true for this to work). For K3s, exclusive: true is set for the CNI plugin to ensure K3s's built-in Flannel does not conflict.

Options:

distribution

rke2 (default) or k3s.

version

Cilium version to install, e.g. 1.17.0. Default: 1.17.0.

cli_version

Cilium CLI version to download, e.g. v0.16.23. Default: v0.16.23.

api_server

Kubernetes API server URL, passed as --api-server to the CLI. Optional; the CLI uses the kubeconfig's server address if omitted.

upgrade_cilium(%opts)

Upgrade an existing Cilium installation to a new version using cilium upgrade. The Cilium CLI is updated first if needed. The same Helm values generation logic as "install_cilium" is used.

Options are the same as "install_cilium".

upgrade_cilium(
  distribution => 'rke2',
  version      => '1.17.0',
);

SEE ALSO

Rex::Rancher, Rex::Rancher::Server, Rex, https://docs.cilium.io/

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.