In this section, you’ll learn how to configure the K3s agent.
Throughout the K3s documentation, you will see some options that can be passed in as both command flags and environment variables. For help with passing in options, refer to How to Use Flags and Environment Variables.
Config
Flag |
Default |
Description |
--config FILE, -c FILE |
”/etc/rancher/k3s/config.yaml” |
Load configuration from FILE |
Logging
Flag |
Default |
Environment Variable |
Description |
--debug |
N/A |
K3S_DEBUG |
Turn on debug logs |
-v value |
0 |
N/A |
Number for the log level verbosity |
--vmodule value |
N/A |
N/A |
Comma-separated list of pattern=N settings for file-filtered logging |
--log value, -l value |
N/A |
N/A |
Log to file |
--alsologtostderr |
N/A |
N/A |
Log to standard error as well as file (if set) |
Cluster Options
Flag |
Environment Variable |
Description |
--token value, -t value |
K3S_TOKEN |
Token to use for authentication |
--token-file value |
K3S_TOKEN_FILE |
Token file to use for authentication |
--server value, -s value |
K3S_URL |
Server to connect to |
Data
Flag |
Default |
Description |
--data-dir value, -d value |
”/var/lib/rancher/k3s” |
Folder to hold state |
Node
Flag |
Default |
Environment Variable |
Description |
--node-name value |
N/A |
K3S_NODE_NAME |
Node name |
--with-node-id |
N/A |
N/A |
Append id to node name |
--node-label value |
N/A |
N/A |
Registering and starting kubelet with set of labels |
--node-taint value |
N/A |
N/A |
Registering kubelet with set of taints |
--image-credential-provider-bin-dir value |
”/var/lib/rancher/credentialprovider/bin” |
N/A |
The path to the directory where credential provider plugin binaries are located |
--image-credential-provider-config value |
”/var/lib/rancher/credentialprovider/config.yaml” |
N/A |
The path to the credential provider plugin config file |
--protect-kernel-defaults |
N/A |
N/A |
Kernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults |
--selinux |
N/A |
K3S_SELINUX |
Enable SELinux in containerd. |
--lb-server-port value |
6444 |
K3S_LB_SERVER_PORT |
Local port for supervisor client load-balancer. If the supervisor and apiserver are not colocated an additional port 1 less than this port will also be used for the apiserver client load-balancer. |
Runtime
Flag |
Default |
Description |
--docker |
N/A |
Use docker instead of containerd |
--container-runtime-endpoint value |
N/A |
Disable embedded containerd and use alternative CRI implementation |
--pause-image value |
“docker.io/rancher/pause:3.1” |
Customized pause image for containerd or docker sandbox |
--snapshotter value |
overlayfs |
Override default containerd snapshotter |
--private-registry value |
/etc/rancher/k3s/registries.yaml |
Private registry configuration file |
Networking
Flag |
Environment Variable |
Description |
--node-ip value, -i value |
N/A |
IP address to advertise for node |
--node-external-ip value |
N/A |
External IP address to advertise for node |
--resolv-conf value |
K3S_RESOLV_CONF |
Kubelet resolv.conf file |
--flannel-iface value |
N/A |
Override default flannel interface |
--flannel-conf value |
N/A |
Override default flannel config file |
Note: if you wish to directly set the kubelet --resolv-conf
value, use --kubelet-arg=resolv-conf=value
instead. The k3s flag is only passed through to the kubelet if set to the path of a valid resolv.conf file.
Customized Flags
Flag |
Description |
--kubelet-arg value |
Customized flag for kubelet process |
--kube-proxy-arg value |
Customized flag for kube-proxy process |
Experimental
Flag |
Description |
--rootless |
Run rootless |
Deprecated
Flag |
Environment Variable |
Description |
--no-flannel |
N/A |
Use --flannel-backend=none |
--cluster-secret value |
K3S_CLUSTER_SECRET |
Use --token |
Node Labels and Taints for Agents
K3s agents can be configured with the options --node-label
and --node-taint
which adds a label and taint to the kubelet. The two options only add labels and/or taints at registration time, so they can only be added once and not changed after that again by running K3s commands.
Below is an example showing how to add labels and a taint:
--node-label foo=bar \
--node-label hello=world \
--node-taint key1=value1:NoExecute
If you want to change node labels and taints after node registration you should use kubectl
. Refer to the official Kubernetes documentation for details on how to add taints and node labels.
K3s Agent CLI Help
If an option appears in brackets below, for example [$K3S_URL]
, it means that the option can be passed in as an environment variable of that name.
NAME:
k3s agent - Run node agent
USAGE:
k3s agent [OPTIONS]
OPTIONS:
--config FILE, -c FILE (config) Load configuration from FILE (default: "/etc/rancher/k3s/config.yaml") [$K3S_CONFIG_FILE]
--debug (logging) Turn on debug logs [$K3S_DEBUG]
-v value (logging) Number for the log level verbosity (default: 0)
--vmodule value (logging) Comma-separated list of pattern=N settings for file-filtered logging
--log value, -l value (logging) Log to file
--alsologtostderr (logging) Log to standard error as well as file (if set)
--token value, -t value (cluster) Token to use for authentication [$K3S_TOKEN]
--token-file value (cluster) Token file to use for authentication [$K3S_TOKEN_FILE]
--server value, -s value (cluster) Server to connect to [$K3S_URL]
--data-dir value, -d value (agent/data) Folder to hold state (default: "/var/lib/rancher/k3s")
--node-name value (agent/node) Node name [$K3S_NODE_NAME]
--with-node-id (agent/node) Append id to node name
--node-label value (agent/node) Registering and starting kubelet with set of labels
--node-taint value (agent/node) Registering kubelet with set of taints
--image-credential-provider-bin-dir value (agent/node) The path to the directory where credential provider plugin binaries are located (default: "/var/lib/rancher/credentialprovider/bin")
--image-credential-provider-config value (agent/node) The path to the credential provider plugin config file (default: "/var/lib/rancher/credentialprovider/config.yaml")
--docker (agent/runtime) Use docker instead of containerd
--container-runtime-endpoint value (agent/runtime) Disable embedded containerd and use alternative CRI implementation
--pause-image value (agent/runtime) Customized pause image for containerd or docker sandbox (default: "rancher/mirrored-pause:3.6")
--snapshotter value (agent/runtime) Override default containerd snapshotter (default: "overlayfs")
--private-registry value (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
--node-ip value, -i value (agent/networking) IPv4/IPv6 addresses to advertise for node
--node-external-ip value (agent/networking) IPv4/IPv6 external IP addresses to advertise for node
--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
--flannel-iface value (agent/networking) Override default flannel interface
--flannel-conf value (agent/networking) Override default flannel config file
--kubelet-arg value (agent/flags) Customized flag for kubelet process
--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process
--protect-kernel-defaults (agent/node) Kernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults.
--rootless (experimental) Run rootless
--selinux (agent/node) Enable SELinux in containerd [$K3S_SELINUX]
--lb-server-port value (agent/node) Local port for supervisor client load-balancer. If the supervisor and apiserver are not colocated an additional port 1 less than this port will also be used for the apiserver client load-balancer. (default: 6444) [$K3S_LB_SERVER_PORT]
--no-flannel (deprecated) use --flannel-backend=none
--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]