Configuration Options
This page focuses on the options that are commonly used when setting up K3s for the first time. Refer to the documentation on Advanced Options and Configuration and the server and agent command documentation for more in-depth coverage.
Configuration with install script
As mentioned in the Quick-Start Guide, you can use the installation script available at https://get.k3s.io to install K3s as a service on systemd and openrc based systems.
You can use a combination of INSTALL_K3S_EXEC, K3S_ environment variables, and command flags to pass configuration to the service configuration.
The prefixed environment variables, INSTALL_K3S_EXEC value, and trailing shell arguments are all persisted into the service configuration.
After installation, configuration may be altered by editing the environment file, editing the service configuration, or simply re-running the installer with new options.
To illustrate this, the following commands all result in the same behavior of registering a server without flannel and with a token:
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" sh -s - --flannel-backend none --token 12345
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --flannel-backend none" K3S_TOKEN=12345 sh -s -
curl -sfL https://get.k3s.io | K3S_TOKEN=12345 sh -s - server --flannel-backend none
# server is assumed below because there is no K3S_URL
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--flannel-backend none --token 12345" sh -s -
curl -sfL https://get.k3s.io | sh -s - --flannel-backend none --token 12345
When registering an agent, the following commands all result in the same behavior:
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="agent --server https://k3s.example.com --token mypassword" sh -s -
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="agent" K3S_TOKEN="mypassword" sh -s - --server https://k3s.example.com
curl -sfL https://get.k3s.io | K3S_URL=https://k3s.example.com sh -s - agent --token mypassword
curl -sfL https://get.k3s.io | K3S_URL=https://k3s.example.com K3S_TOKEN=mypassword sh -s - # agent is assumed because of K3S_URL
For details on all environment variables, see Environment Variables.
If you set configuration when running the install script, but do not set it again when re-running the install script, the original values will be lost.
The contents of the configuration file are not managed by the install script. If you want your configuration to be independent from the install script, you should use a configuration file instead of passing environment variables or arguments to the install script.
Configuration with binary
As stated, the installation script is primarily concerned with configuring K3s to run as a service.
If you choose to not use the script, you can run K3s simply by downloading the binary from our release page, placing it on your path, and executing it. This is not particularly useful for permanent installations, but may be useful when performing quick tests that do not merit managing K3s as a system service.
curl -Lo /usr/local/bin/k3s https://github.com/k3s-io/k3s/releases/download/v1.26.5+k3s1/k3s; chmod a+x /usr/local/bin/k3s
You can pass configuration by setting K3S_ environment variables:
K3S_KUBECONFIG_MODE="644" k3s server
Or command flags:
k3s server --write-kubeconfig-mode=644
The k3s agent can also be configured this way:
k3s agent --server https://k3s.example.com --token mypassword
For details on configuring the K3s server, see the k3s server documentation.
For details on configuring the K3s agent, see the k3s agent documentation.
You can also use the --help flag to see a list of all available options, and their corresponding environment variables.
It is important to match critical flags on your server nodes. For example, if you use the flag
--disable servicelb or --cluster-cidr=10.200.0.0/16 on your master node, but don't set it on other server nodes, the nodes will fail to join. They will print errors such as:
failed to validate server configuration: critical configuration value mismatch.
See the Server Configuration documentation (linked above) for more information on which flags must be set identically on server nodes.
Configuration File
Available as of v1.19.1+k3s1
In addition to configuring K3s with environment variables and CLI arguments, K3s can also use a config file.
By default, configuration is loaded from /etc/rancher/k3s/config.yaml, and drop-in files are loaded from /etc/rancher/k3s/config.yaml.d/*.yaml in alphabetical order.
This path is configurable via the --config CLI flag or K3S_CONFIG_FILE env var.
When overriding the default config file name, the drop-in directory path is also modified.
An example of a basic server config file is below:
write-kubeconfig-mode: "0644"
tls-san:
- "foo.local"
node-label:
- "foo=bar"
- "something=amazing"
cluster-init: true
This is equivalent to the following CLI arguments:
k3s server \
--write-kubeconfig-mode "0644" \
--tls-san "foo.local" \
--node-label "foo=bar" \
--node-label "something=amazing" \
--cluster-init
In general, CLI arguments map to their respective YAML key, with repeatable CLI arguments being represented as YAML lists. Boolean flags are represented as true or false in the YAML file.
It is also possible to use both a configuration file and CLI arguments. In these situations, values will be loaded from both sources, but CLI arguments will take precedence. For repeatable arguments such as --node-label, the CLI arguments will overwrite all values in the list.
Multiple Config Files
If present in multiple files, the last value found for a given key will be used. A + can be appended to the key to append the value to the existing string or slice, instead of replacing it. All occurrences of this key in subsequent files will also require a + to prevent overwriting the accumulated value.
An example of multiple config files is below:
# config.yaml
token: boop
node-label:
- foo=bar
- bar=baz
# config.yaml.d/test1.yaml
write-kubeconfig-mode: 600
node-taint:
- alice=bob:NoExecute
# config.yaml.d/test2.yaml
write-kubeconfig-mode: 777
node-label:
- other=what
- foo=three
node-taint+:
- charlie=delta:NoSchedule
This results in a final configuration of:
write-kubeconfig-mode: 777
token: boop
node-label:
- other=what
- foo=three
node-taint:
- alice=bob:NoExecute
- charlie=delta:NoSchedule
Putting it all together
All of the above options can be combined into a single example.
A config.yaml file is created at /etc/rancher/k3s/config.yaml:
token: "secret"
debug: true
Then the installation script is run with a combination of environment variables and flags:
curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" INSTALL_K3S_EXEC="server" sh -s - --flannel-backend none
Or if you have already installed the K3s Binary:
K3S_KUBECONFIG_MODE="644" k3s server --flannel-backend none
This results in a server with:
- A kubeconfig file with permissions
644 - Flannel backend set to
none - The token set to
secret - Debug logging enabled
Kubelet configuration
The drop-in directory for kubelet configuration files or the config file (options 1 and 2 below) are only available in v1.32 and above. For lower minors, you should use the kubelet args directly (option number 3 below)
Following on from upstream behavior, kubelet configuration can be changed in different ways with a specific order of precedence.
K3s uses a default kubelet configuration which is stored under /var/lib/rancher/k3s/agent/etc/kubelet.conf.d/00-k3s-defaults.conf. If you would like to change the default configuration parameters, there are three ways to do so:
- (Recommended) Drop a config file in
/var/lib/rancher/k3s/agent/etc/kubelet.conf.d/ - By using the flag
--kubelet-arg=config=$PATHTOFILE, where$PATHTOFILEis the path to a file that includes kubelet config parameters (e.g./etc/rancher/k3s/kubelet.conf) or the flag--kubelet-arg=config-dir=$PATHTODIR, where$PATHTODIRis the path to a directory which can include files that contain kubelet config parameters (e.g./etc/rancher/k3s/kubelet.conf.d) - By using the flag
--kubelet-arg=$FLAG, where$FLAGis a kubelet configuration parameter (e.g.image-gc-high-threshold=100).