The Config File

Instead of long command-line flags, put your k3s options in a YAML config file.

Syntax/etc/rancher/k3s/config.yaml

Passing many flags to k3s server gets messy. k3s can read them from a config file at /etc/rancher/k3s/config.yaml instead. Each flag becomes a key in the YAML.

Why use it

  • Cleaner than a huge command line.
  • Easy to version-control and ship with a machine image.
  • Changes apply on the next service restart.

Flags and config-file entries can be combined; the config file is usually the tidier home for permanent settings.

Example

Example · yaml
# /etc/rancher/k3s/config.yaml
write-kubeconfig-mode: "644"
node-name: server-1
tls-san:
  - myserver.example.com
disable:
  - traefik
# Restart to apply:  sudo systemctl restart k3s

When to use it

  • A platform engineer stores all k3s server flags in /etc/rancher/k3s/config.yaml and commits it to version control for reproducible cluster builds.
  • An operator uses the config file to set node-labels, disable add-ons, and specify a custom cluster CIDR without editing the systemd unit file.
  • A team manages a fleet of edge nodes by distributing a common config.yaml via Ansible, ensuring every node has identical k3s settings.

More examples

Create a k3s config file

Defines common k3s server options in the config file; k3s reads this automatically on startup.

Example · yaml
# /etc/rancher/k3s/config.yaml
write-kubeconfig-mode: '0644'
tls-san:
  - 203.0.113.10
  - k3s.example.com
disable:
  - traefik
node-label:
  - environment=production

Verify config is loaded

Restarts k3s after editing the config file and checks the logs to confirm the flags were picked up.

Example · bash
cat /etc/rancher/k3s/config.yaml
systemctl restart k3s
journalctl -u k3s -n 30 --no-pager | grep -E 'tls-san|disable|label'

Override config with env variable

Uses the K3S_CONFIG_FILE environment variable to load config from a custom path instead of the default location.

Example · bash
# Point to a non-default config location:
export K3S_CONFIG_FILE=/opt/k3s/custom-config.yaml
systemctl restart k3s
kubectl get nodes

Related

k3s disabling componentsk3s server node

Discussion

  • Be the first to comment on this lesson.