Installation script options

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.

The simplest form of this command is as follows:

  1. curl -sfL https://get.k3s.io | sh -

When using this method to install K3s, the following environment variables can be used to configure the installation:

  • INSTALL_K3S_SKIP_DOWNLOAD

If set to true will not download K3s hash or binary.

  • INSTALL_K3S_SYMLINK

If set to ‘skip’ will not create symlinks, ‘force’ will overwrite, default will symlink if command does not exist in path.

  • INSTALL_K3S_SKIP_START

If set to true will not start K3s service.

  • INSTALL_K3S_VERSION

Version of K3s to download from github. Will attempt to download the latest version if not specified.

  • INSTALL_K3S_BIN_DIR

Directory to install K3s binary, links, and uninstall script to, or use /usr/local/bin as the default.

  • INSTALL_K3S_BIN_DIR_READ_ONLY

If set to true will not write files to INSTALL_K3S_BIN_DIR, forces setting INSTALL_K3S_SKIP_DOWNLOAD=true.

  • INSTALL_K3S_SYSTEMD_DIR

Directory to install systemd service and environment files to, or use /etc/systemd/system as the default.

  • INSTALL_K3S_EXEC

Command with flags to use for launching K3s in the service. If the command is not specified, it will default to “agent” if K3S_URL is set or “server” if it is not set. The final systemd command resolves to a combination of this environment variable and script args. To illustrate this, the following commands result in the same behavior:

  1.  curl ... | INSTALL_K3S_EXEC="--no-flannel" sh -s -
  2.  curl ... | INSTALL_K3S_EXEC="server --no-flannel" sh -s -
  3.  curl ... | INSTALL_K3S_EXEC="server" sh -s - --no-flannel
  4.  curl ... | sh -s - server --no-flannel
  5.  curl ... | sh -s - --no-flannel

  • INSTALL_K3S_NAMEName of systemd service to create, will default from the K3s exec command if not specified. If specified the name will be prefixed with ‘k3s-’.

  • INSTALL_K3S_TYPEType of systemd service to create, will default from the K3s exec command if not specified.

Environment variables which begin with K3S_ will be preserved for the systemd and openrc services to use. Setting K3S_URL without explicitly setting an exec command will default the command to “agent”. When running the agent K3S_TOKEN must also be set.

Beyond the Installation Script

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. The K3s binary supports the following commands:

CommandDescription
k3s serverRun the K3s management server, which will also launch Kubernetes control plane components such as the API server, controller-manager, and scheduler.
k3s agentRun the K3s node agent. This will cause K3s to run as a worker node, launching the Kubernetes node services kubelet and kube-proxy.
k3s kubectlRun an embedded kubectl CLI. If the KUBECONFIG environment variable is not set, this will automatically attempt to use the config file that is created at /etc/rancher/k3s/k3s.yaml when launching a K3s server node.
k3s crictlRun an embedded crictl. This is a CLI for interacting with Kubernetes’s container runtime interface (CRI). Useful for debugging.
k3s ctrRun an embedded ctr. This is a CLI for containerd, the container daemon used by K3s. Useful for debugging.
k3s helpShows a list of commands or help for one command

The k3s server and k3s agent commands have additional configuration options that can be viewed with k3s server —help or k3s agent —help. For convenience, that help text is presented here:

k3s server

  1. NAME:
  2.    k3s server - Run management server
  4. USAGE:
  5.    k3s server [OPTIONS]
  7. OPTIONS:
  8.    -v value                                   (logging) Number for the log level verbosity (default: 0)
  9.    --vmodule value                            (logging) Comma-separated list of pattern=N settings for file-filtered logging
  10.    --log value, -l value                      (logging) Log to file
  11.    --alsologtostderr                          (logging) Log to standard error as well as file (if set)
  12.    --bind-address value                       (listener) k3s bind address (default: 0.0.0.0)
  13.    --https-listen-port value                  (listener) HTTPS listen port (default: 6443)
  14.    --advertise-address value                  (listener) IP address that apiserver uses to advertise to members of the cluster (default: node-external-ip/node-ip)
  15.    --advertise-port value                     (listener) Port that apiserver uses to advertise to members of the cluster (default: listen-port) (default: 0)
  16.    --tls-san value                            (listener) Add additional hostname or IP as a Subject Alternative Name in the TLS cert
  17.    --data-dir value, -d value                 (data) Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
  18.    --cluster-cidr value                       (networking) Network CIDR to use for pod IPs (default: "10.42.0.0/16")
  19.    --service-cidr value                       (networking) Network CIDR to use for services IPs (default: "10.43.0.0/16")
  20.    --cluster-dns value                        (networking) Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10)
  21.    --cluster-domain value                     (networking) Cluster Domain (default: "cluster.local")
  22.    --flannel-backend value                    (networking) One of 'none', 'vxlan', 'ipsec', or 'flannel' (default: "vxlan")
  23.    --token value, -t value                    (cluster) Shared secret used to join a server or agent to a cluster [$K3S_TOKEN]
  24.    --token-file value                         (cluster) File containing the cluster-secret/token [$K3S_TOKEN_FILE]
  25.    --write-kubeconfig value, -o value         (client) Write kubeconfig for admin client to this file [$K3S_KUBECONFIG_OUTPUT]
  26.    --write-kubeconfig-mode value              (client) Write kubeconfig with this mode [$K3S_KUBECONFIG_MODE]
  27.    --kube-apiserver-arg value                 (flags) Customized flag for kube-apiserver process
  28.    --kube-scheduler-arg value                 (flags) Customized flag for kube-scheduler process
  29.    --kube-controller-manager-arg value        (flags) Customized flag for kube-controller-manager process
  30.    --kube-cloud-controller-manager-arg value  (flags) Customized flag for kube-cloud-controller-manager process
  31.    --datastore-endpoint value                 (db) Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$K3S_DATASTORE_ENDPOINT]
  32.    --datastore-cafile value                   (db) TLS Certificate Authority file used to secure datastore backend communication [$K3S_DATASTORE_CAFILE]
  33.    --datastore-certfile value                 (db) TLS certification file used to secure datastore backend communication [$K3S_DATASTORE_CERTFILE]
  34.    --datastore-keyfile value                  (db) TLS key file used to secure datastore backend communication [$K3S_DATASTORE_KEYFILE]
  35.    --default-local-storage-path value         (storage) Default local storage path for local provisioner storage class
  36.    --no-deploy value                          (components) Do not deploy packaged components (valid items: coredns, servicelb, traefik, local-storage, metrics-server)
  37.    --disable-scheduler                        (components) Disable Kubernetes default scheduler
  38.    --disable-cloud-controller                 (components) Disable k3s default cloud controller manager
  39.    --disable-network-policy                   (components) Disable k3s default network policy controller
  40.    --node-name value                          (agent/node) Node name [$K3S_NODE_NAME]
  41.    --with-node-id                             (agent/node) Append id to node name
  42.    --node-label value                         (agent/node) Registering kubelet with set of labels
  43.    --node-taint value                         (agent/node) Registering kubelet with set of taints
  44.    --docker                                   (agent/runtime) Use docker instead of containerd
  45.    --container-runtime-endpoint value         (agent/runtime) Disable embedded containerd and use alternative CRI implementation
  46.    --pause-image value                        (agent/runtime) Customized pause image for containerd sandbox
  47.    --private-registry value                   (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
  48.    --node-ip value, -i value                  (agent/networking) IP address to advertise for node
  49.    --node-external-ip value                   (agent/networking) External IP address to advertise for node
  50.    --resolv-conf value                        (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
  51.    --flannel-iface value                      (agent/networking) Override default flannel interface
  52.    --flannel-conf value                       (agent/networking) Override default flannel config file
  53.    --kubelet-arg value                        (agent/flags) Customized flag for kubelet process
  54.    --kube-proxy-arg value                     (agent/flags) Customized flag for kube-proxy process
  55.    --rootless                                 (experimental) Run rootless
  56.    --agent-token value                        (experimental/cluster) Shared secret used to join agents to the cluster, but not servers [$K3S_AGENT_TOKEN]
  57.    --agent-token-file value                   (experimental/cluster) File containing the agent secret [$K3S_AGENT_TOKEN_FILE]
  58.    --server value, -s value                   (experimental/cluster) Server to connect to, used to join a cluster [$K3S_URL]
  59.    --cluster-init                             (experimental/cluster) Initialize new cluster master [$K3S_CLUSTER_INIT]
  60.    --cluster-reset                            (experimental/cluster) Forget all peers and become a single cluster new cluster master [$K3S_CLUSTER_RESET]
  61.    --no-flannel                               (deprecated) use --flannel-backend=none
  62.    --cluster-secret value                     (deprecated) use --token [$K3S_CLUSTER_SECRET]

k3s agent

  1. NAME:
  2.    k3s agent - Run node agent
  4. USAGE:
  5.    k3s agent [OPTIONS]
  7. OPTIONS:
  8.    -v value                            (logging) Number for the log level verbosity (default: 0)
  9.    --vmodule value                     (logging) Comma-separated list of pattern=N settings for file-filtered logging
  10.    --log value, -l value               (logging) Log to file
  11.    --alsologtostderr                   (logging) Log to standard error as well as file (if set)
  12.    --token value, -t value             (cluster) Token to use for authentication [$K3S_TOKEN]
  13.    --token-file value                  (cluster) Token file to use for authentication [$K3S_TOKEN_FILE]
  14.    --server value, -s value            (cluster) Server to connect to [$K3S_URL]
  15.    --data-dir value, -d value          (agent/data) Folder to hold state (default: "/var/lib/rancher/k3s")
  16.    --node-name value                   (agent/node) Node name [$K3S_NODE_NAME]
  17.    --with-node-id                      (agent/node) Append id to node name
  18.    --node-label value                  (agent/node) Registering kubelet with set of labels
  19.    --node-taint value                  (agent/node) Registering kubelet with set of taints
  20.    --docker                            (agent/runtime) Use docker instead of containerd
  21.    --container-runtime-endpoint value  (agent/runtime) Disable embedded containerd and use alternative CRI implementation
  22.    --pause-image value                 (agent/runtime) Customized pause image for containerd sandbox
  23.    --private-registry value            (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
  24.    --node-ip value, -i value           (agent/networking) IP address to advertise for node
  25.    --node-external-ip value            (agent/networking) External IP address to advertise for node
  26.    --resolv-conf value                 (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
  27.    --flannel-iface value               (agent/networking) Override default flannel interface
  28.    --flannel-conf value                (agent/networking) Override default flannel config file
  29.    --kubelet-arg value                 (agent/flags) Customized flag for kubelet process
  30.    --kube-proxy-arg value              (agent/flags) Customized flag for kube-proxy process
  31.    --rootless                          (experimental) Run rootless
  32.    --no-flannel                        (deprecated) use --flannel-backend=none
  33.    --cluster-secret value              (deprecated) use --token [$K3S_CLUSTER_SECRET]