This page focuses on the options that can be used when you set up K3s for the first time:
For more advanced options, refer to this page.
Configuration with install script
You can use a combination of
K3S_ environment variables, and command flags to configure the installation.
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="--flannel-backend none --token 12345" sh -s -
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --flannel-backend none" K3S_TOKEN=12345 sh -s -
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" sh -s - --flannel-backend none
curl -sfL https://get.k3s.io | K3S_TOKEN=12345 sh -s - server --flannel-backend none
curl -sfL https://get.k3s.io | sh -s - --flannel-backend none --token 12345
For details on all environment variables, see Environment Variables.
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. Or you can install K3s without enabling it as a service:
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_ENABLE=true sh -
You can configure K3s in this manner through
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 Server Configuration.
For details on configuring the K3s agent, see Agent Configuration.
You can also use the
--help flag to see a list of all available options.
It is important to match critical flags on your server/agent installations. For example, if you use the flag
--disable servicelb or
--cluster-cidr=10.42.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 with:
failed to validate server configuration: critical configuration value mismatch.
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, values present in a YAML file located at
/etc/rancher/k3s/config.yaml will be used on install.
An example of a basic
server config file is below:
In general, CLI arguments map to their respective YAML key, with repeatable CLI arguments being represented as YAML lists.
An identical configuration using only CLI arguments is shown below to demonstrate this:
k3s server \
--write-kubeconfig-mode "0644" \
--tls-san "foo.local" \
--node-label "foo=bar" \
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.
Finally, the location of the config file can be changed either through the CLI argument
--config FILE, -c FILE, or the environment variable
Putting it all together
All of the above options can be combined into a single example.
config.yaml file is created at
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