arillso.container.k3s role – Install and configure K3s lightweight Kubernetes

Note

This role is part of the arillso.container collection (version 2.1.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install arillso.container.

To use it in a playbook, specify: arillso.container.k3s.

Entry point agent – K3s agent entry point

Synopsis

  • Entry point for K3s worker nodes (agents). Automatically sets k3s_role=agent.

Parameters

Parameter

Comments

k3s_node_labels

list / elements=string

Node labels to apply

Default: []

k3s_node_name

string / required

K3s node name

k3s_node_taints

list / elements=string

Node taints to apply

Default: []

k3s_server_url

string / required

K3s server URL to connect to

k3s_token

string / required

K3s cluster token

k3s_version

string / required

K3s version to install

Authors

  • Simon Bärlocher

Entry point main – Install and configure K3s lightweight Kubernetes

Synopsis

  • Main entry point for K3s installation with full configuration options. Supports both server and agent roles with manual configuration.

Parameters

Parameter

Comments

k3s_anonymous_auth

boolean

Allow anonymous requests to the kube-apiserver. When false and k3s_security_hardening is enabled, anonymous-auth=false is passed to the apiserver.

Choices:

  • false ← (default)

  • true

k3s_apparmor_profile

boolean

Deploy and load the K3s AppArmor profile. When false, any existing profile is unloaded and removed, along with a hand-placed /etc/apparmor.d/disable/k3s symlink.

Choices:

  • false ← (default)

  • true

k3s_audit_log_enabled

boolean

Enable kube-apiserver audit logging on servers. Requires k3s_security_hardening to take effect.

Choices:

  • false

  • true ← (default)

k3s_audit_log_level

string

Audit level for the catch-all rule in the generated audit policy. Secrets and configmaps are always capped at Metadata regardless of this setting.

Choices:

  • "None"

  • "Metadata" ← (default)

  • "Request"

  • "RequestResponse"

k3s_audit_log_maxage

integer

Retention in days for rotated audit log files

Default: 30

k3s_auto_facts

boolean

Enable automatic facts collection

Choices:

  • false

  • true ← (default)

k3s_binary_checksum

string

Expected checksum of the K3s binary

Default: ""

k3s_bind_address

string

K3s API server bind address

Default: "{{ ansible_facts['default_ipv4']['address'] }}"

k3s_channel

string

K3s release channel (e.g., stable, latest, testing)

Default: "stable"

k3s_cluster_cidr

string

CIDR range for pod IPs

Default: "10.42.0.0/16"

k3s_cluster_dns

string

Cluster DNS service IP address

Default: "10.43.0.10"

k3s_cluster_domain

string

Kubernetes cluster domain

Default: "cluster.local"

k3s_config_dir

string

K3s configuration directory path

Default: "/etc/rancher/k3s"

k3s_container_log_max_files

integer

Maximum number of container log files kept per container, passed to kubelet as container-log-max-files. Set to 0 to omit the flag and leave the kubelet default in place.

Default: 5

k3s_container_log_max_size

string

Maximum size of a container log file before it is rotated, passed to kubelet as container-log-max-size. An empty string omits the flag and leaves the kubelet default in place.

Default: "10Mi"

k3s_create_bash_completion

boolean

Create bash completion for kubectl

Choices:

  • false

  • true ← (default)

k3s_create_killall_script

boolean

Create K3s killall script

Choices:

  • false

  • true ← (default)

boolean

Create symlinks for kubectl, crictl, ctr

Choices:

  • false

  • true ← (default)

k3s_create_uninstall_script

boolean

Create K3s uninstall script

Choices:

  • false

  • true ← (default)

k3s_cri_apparmor_profile_enabled

boolean

Deploy and load the cri-containerd AppArmor profile. When false, any existing profile is unloaded and removed (e.g. workaround for kernel 6.17 profile-stacking bugs).

Choices:

  • false

  • true ← (default)

k3s_data_dir

string

K3s data directory path

Default: "/var/lib/rancher/k3s"

k3s_debug_facts

boolean

Enable debug logging in the facts collection script

Choices:

  • false ← (default)

  • true

k3s_debug_security

boolean

Enable security debugging output

Choices:

  • false ← (default)

  • true

k3s_disable_cloud_controller

boolean

Disable built-in cloud controller manager

Choices:

  • false ← (default)

  • true

k3s_disable_helm_controller

boolean

Disable built-in Helm controller

Choices:

  • false ← (default)

  • true

k3s_disable_local_storage

boolean

Disable built-in local storage provisioner

Choices:

  • false ← (default)

  • true

k3s_disable_metrics_server

boolean

Disable built-in metrics server

Choices:

  • false ← (default)

  • true

k3s_disable_network_policy

boolean

Disable K3s default network policy controller

Choices:

  • false ← (default)

  • true

k3s_disable_servicelb

boolean

Disable built-in service load balancer

Choices:

  • false ← (default)

  • true

k3s_disable_traefik

boolean

Disable built-in Traefik ingress controller

Choices:

  • false ← (default)

  • true

k3s_enable_helm_integration

boolean

Detect Helm installation and version in facts output

Choices:

  • false ← (default)

  • true

k3s_environment_vars

dictionary

Environment variables for K3s service

Default: {}

k3s_etcd_expose_metrics

boolean

Expose etcd metrics (`etcd-expose-metrics`). Omitted when undefined.

Choices:

  • false

  • true

k3s_etcd_s3

boolean

Enable uploading etcd snapshots to an S3-compatible store (`etcd-s3`). Passed through `| bool`, so a string value such as “False” is treated correctly. Omitted when undefined.

Choices:

  • false

  • true

k3s_etcd_s3_access_key

string

Access key for the S3-compatible etcd snapshot store (`etcd-s3-access-key`). Rendered into the server config (mode 0600). Omitted when undefined.

k3s_etcd_s3_bucket

string

S3 bucket for etcd snapshot uploads (`etcd-s3-bucket`). Omitted when undefined.

k3s_etcd_s3_endpoint

string

S3 endpoint host for etcd snapshot uploads (`etcd-s3-endpoint`), without scheme. Omitted when undefined.

k3s_etcd_s3_folder

string

Folder/prefix within the S3 bucket for etcd snapshots (`etcd-s3-folder`). Omitted when undefined.

k3s_etcd_s3_region

string

S3 region for etcd snapshot uploads (`etcd-s3-region`, e.g. `auto` for Cloudflare R2). Omitted when undefined.

k3s_etcd_s3_secret_key

string

Secret key for the S3-compatible etcd snapshot store (`etcd-s3-secret-key`). Rendered into the server config (mode 0600). Omitted when undefined.

k3s_etcd_snapshot_dir

string

Directory for local etcd snapshots (`etcd-snapshot-dir`). Omitted when undefined (K3s default location).

k3s_etcd_snapshot_retention

integer

Number of etcd snapshots to retain (`etcd-snapshot-retention`). Applies to both local and S3 snapshots. Omitted when undefined.

k3s_etcd_snapshot_schedule_cron

string

Cron schedule for automatic etcd snapshots (`etcd-snapshot-schedule-cron`, e.g. `0 */6 * * *`). Omitted when undefined.

k3s_extra_agent_args

list / elements=string

Additional arguments for K3s agent

Default: []

k3s_extra_server_args

list / elements=string

Additional arguments for K3s server

Default: []

k3s_facts_cache_enabled

boolean

Enable caching of collected K3s facts

Choices:

  • false

  • true ← (default)

k3s_facts_cache_ttl

integer

Cache time-to-live in seconds for K3s facts

Default: 300

k3s_facts_collect_cluster_state

boolean

Collect cluster state in facts (initialization, health, node counts)

Choices:

  • false

  • true ← (default)

k3s_facts_collect_health_metrics

boolean

Collect health check metrics in facts (duration, timestamps)

Choices:

  • false

  • true ← (default)

k3s_facts_collect_inventory_info

boolean

Collect Ansible inventory group information in facts

Choices:

  • false

  • true ← (default)

k3s_facts_collect_service_status

boolean

Collect K3s service status in facts (active, enabled, version)

Choices:

  • false

  • true ← (default)

k3s_facts_collection_timeout

integer

Timeout in seconds for API calls during facts collection

Default: 30

k3s_facts_health_check_timeout

integer

Timeout in seconds for health check commands

Default: 60

k3s_fallback_mode_allowed

boolean

Allow fallback mode on errors (outputs error JSON instead of failing)

Choices:

  • false

  • true ← (default)

k3s_flannel_backend

string

Flannel backend type

Choices:

  • "vxlan" ← (default)

  • "host-gw"

  • "wireguard-native"

  • "none"

k3s_health_check_delay

integer

Pre-sleep before the server API readiness probe (wait_for). Set to 0 to skip the idle wait when running against an already-converged server; timeout/sleep still cover the cold-bootstrap race.

Default: 30

k3s_health_check_sleep

integer

Poll interval for the server API readiness probe (wait_for)

Default: 10

k3s_health_check_timeout

integer

Timeout for the server API readiness probe (wait_for)

Default: 600

k3s_https_listen_port

integer

K3s HTTPS API server listen port

Default: 6443

k3s_install_dependencies

boolean

Install required system packages

Choices:

  • false

  • true ← (default)

k3s_kubeconfig_group

string

Group ownership of kubeconfig

Default: "root"

k3s_kubeconfig_mode

string

File permissions for kubeconfig

Default: "0644"

k3s_kubeconfig_owner

string

Owner of kubeconfig file

Default: "root"

k3s_kubelet_read_only_port_disabled

boolean

Disable the unauthenticated kubelet read-only port 10255. Requires k3s_security_hardening to take effect.

Choices:

  • false

  • true ← (default)

k3s_max_pods

integer

Maximum number of pods per node

Default: 110

k3s_node_ip

string

K3s node IP address

Default: "{{ ansible_facts['default_ipv4']['address'] }}"

k3s_node_labels

list / elements=string

Node labels to apply (format: key=value)

Default: []

k3s_node_name

string / required

K3s node name (usually inventory_hostname)

k3s_node_restriction

boolean

Enable the NodeRestriction admission plugin. Requires k3s_security_hardening to take effect.

Choices:

  • false

  • true ← (default)

k3s_node_taints

list / elements=string

Node taints to apply (format: key=value:effect)

Default: []

k3s_pod_security_admission_profile

string

Cluster-wide default Pod Security Admission profile. Empty disables the admission configuration. Requires k3s_security_hardening to take effect.

Choices:

  • "" ← (default)

  • "privileged"

  • "baseline"

  • "restricted"

k3s_private_registries

list / elements=dictionary

Private container registry configurations

Default: []

k3s_protect_kernel_defaults

boolean

Fail K3s startup when kernel sysctls differ from the kubelet defaults. Off by default because the role does not set those sysctls. Requires k3s_security_hardening.

Choices:

  • false ← (default)

  • true

k3s_required_packages

list / elements=string

Required system packages for K3s. The NFS client entry defaults to nfs-utils on RedHat and nfs-common elsewhere.

Default: ["curl", "iptables", "nfs-common"]

k3s_role

string / required

K3s node role - server (control plane) or agent (worker)

Choices:

  • "server"

  • "agent"

k3s_secrets_encryption

boolean

Enable at-rest encryption of Kubernetes secrets on servers. Requires k3s_security_hardening to take effect.

Choices:

  • false

  • true ← (default)

k3s_security_hardening

boolean

Enable K3s security hardening

Choices:

  • false

  • true ← (default)

k3s_selinux_custom_policy

boolean

Apply custom SELinux policy for K3s

Choices:

  • false ← (default)

  • true

k3s_server_init

boolean

Initialize K3s cluster (only for first server node)

Choices:

  • false ← (default)

  • true

k3s_server_url

string

K3s server URL for agents and joining servers

Default: ""

k3s_service_cidr

string

CIDR range for service IPs

Default: "10.43.0.0/16"

k3s_service_enabled

boolean

Enable K3s service on boot

Choices:

  • false

  • true ← (default)

k3s_service_state

string

Desired state of K3s service

Choices:

  • "started" ← (default)

  • "stopped"

  • "restarted"

  • "reloaded"

list / elements=string

List of commands to create symlinks for

Default: ["kubectl", "crictl", "ctr"]

boolean

Force overwrite existing symlinks

Choices:

  • false ← (default)

  • true

k3s_tls_san

list / elements=string

Additional TLS SANs for API server certificate

Default: []

k3s_token

string

K3s cluster token for authentication

Default: ""

k3s_token_discovered

boolean

Set by the role when the token was read from this node’s own node-token file. Such a token is redundant in config.yaml and is left out of the server config, which keeps the file stable across runs. A token fetched from another host is a join credential and is always written. Not intended to be set manually.

Choices:

  • false ← (default)

  • true

k3s_token_file

string

Path to the K3s node token file

Default: "/var/lib/rancher/k3s/server/node-token"

k3s_validate_facts_schema

boolean

Validate facts output is valid JSON before caching

Choices:

  • false

  • true ← (default)

k3s_version

string / required

K3s version to install (e.g., v1.35.2+k3s1)

k3s_write_kubeconfig_mode

string

File mode k3s writes the kubeconfig with

Authors

  • Simon Bärlocher

Entry point server_init – K3s server initialization entry point

Synopsis

  • Entry point for initializing a new K3s cluster. Automatically sets k3s_role=server and k3s_server_init=true.

Parameters

Parameter

Comments

k3s_bind_address

string

K3s API server bind address

Default: "{{ ansible_facts['default_ipv4']['address'] }}"

k3s_https_listen_port

integer

K3s HTTPS API server listen port

Default: 6443

k3s_node_name

string / required

K3s node name

k3s_tls_san

list / elements=string

Additional TLS SANs for API server

Default: []

k3s_version

string / required

K3s version to install

Authors

  • Simon Bärlocher

Entry point server_join – K3s server join entry point

Synopsis

  • Entry point for joining additional servers to existing K3s cluster. Automatically sets k3s_role=server and k3s_server_init=false.

Parameters

Parameter

Comments

k3s_bind_address

string

K3s API server bind address

Default: "{{ ansible_facts['default_ipv4']['address'] }}"

k3s_https_listen_port

integer

K3s HTTPS API server listen port

Default: 6443

k3s_node_name

string / required

K3s node name

k3s_server_url

string / required

K3s server URL to join

k3s_token

string / required

K3s cluster token

k3s_version

string / required

K3s version to install

Authors

  • Simon Bärlocher