k3s
Description
Ansible role for managing rancher k3s, lightweight, cncf-certified kubernetes distribution.
This role can be used to install simple single-node or multi-master HA clusters.
It can be used to manage multiple k3s clusters in single ansible inventory.
It's also heavily customizable for almost any purpose - you can edit pretty much any k3s setting.
It can install gvisor, additional host dependencies, load specific kernel modules, adjust k3s-related sysctl settings and so on.
Documentation
Detailed docs are available here
Requirements
Apart from what k3s requires, this role also needs systemd, so it should work on any modern distro.
Variables
| Variable name | Default value | Description |
|---|---|---|
| k3s_version | v1.29.3+k3s1 |
version of k3s to install |
| k3s_systemd_dir | /etc/systemd/system | Directory for systemd unit file |
| k3s_master | false |
installs k3s master when true |
| k3s_agent | false |
installs k3s agent when true |
| k3s_master_ip | first node in k3s_master_group group | ip/hostname of master node |
| k3s_master_port | 6443 |
port of masterserver |
| k3s_install_mode | online |
k3s install mode - online or airgap |
| k3s_flannel_backend | vxlan |
k3s flannel backend to use. Set to none to disable flannel |
| k3s_master_disable | [] |
array of k3s packaged components to disable (traefik,metrics-server,etc) |
| k3s_master_extra_args | [] |
extra arguments for k3s server (official docs) |
| k3s_master_extra_config | `` | YAML with extra config for k3s master |
| k3s_agent_extra_config | `` | YAML with extra config for k3s agent |
| k3s_kubelet_extra_config | `` | Additional arguments for kubelet, see docs |
| k3s_agent_extra_args | [] |
extra arguments for k3s agent (official docs) |
| k3s_extra_config_files | {} |
extra configfiles for k3s |
| k3s_bpffs | false |
mounts /sys/fs/bpf bpffs (needed by some network stacks) |
| k3s_external_ip | `` | specifies k3s external ip |
| k3s_internal_ip | `` | specifies k3s node ip |
| k3s_registries | `` | Configures custom registries, see official docs for format |
| k3s_cronjob_prune_images | absent |
Configures cronjob that prunes unused images in containerd daily. Either absent or present |
| k3s_gvisor | false |
Installs gvisor |
| k3s_gvisor_version | 20231218 |
gvisor version to install |
| k3s_gvisor_platform | systrap |
Selects platform to use in gvisor |
| k3s_gvisor_config | `` | Sets additional options for gvisor runsc. See notes |
| k3s_gvisor_create_runtimeclass | true |
Automatically create gvisor RuntimeClass in kubernetes |
| k3s_kubeconfig | false | Downloads kubeconfig to machine from which role was launched |
| k3s_kubeconfig_server | see below | specifies server for use in kubeconfig |
| k3s_kubeconfig_context | k3s | specifies context to use in kubeconfig |
| k3s_kubeconfig_target: | {{ k3s_kubeconfig_context }} |
specifies filename for downloading kubeconfig |
| k3s_agent_group | k3s_node | specifies ansible group name for k3s nodes |
| k3s_master_group | k3s_master | specifies ansible group name for k3s master(s) |
| k3s_extra_packages | [] |
Installs additional packages if needed by workloads (ie iscsid) |
| k3s_extra_services | [] |
Enables additional services if needed by workloads (ie iscsid) |
| k3s_extra_config_files | {} |
additional config files for kubelet/kubeapi |
| k3s_sysctl_config | {} |
Allows setting arbitrary sysctl settings |
| k3s_extra_manifests | {} |
Allows applying kubernetes manifests |
Changelog
Changelog is available in separate file
Tests
This role is continiously tested via ansible-molecule with github actions in on Ubuntu 22.04 and Rocky Linux 8 in different scenarios, including:
- single-node install
- single-node install with customized config
- single-node airgapped install
- cluster install (3 masters, 1 node)
Other ansible roles to check out
If you got interested in that role, you might want to check out others that go nicely with my k3s one:
- haproxy by Oafenweb - used in example with haproxy
- keepalived by Oafenweb - used in example with keepalived
- zot registy by me - for light on resources (but also very powerful) OCI container registry
ansible-galaxy install rlex/ansible-role-k3s