k0sctl

A command-line bootstrapping and management tool for k0s zero friction kubernetes clusters.

• Installation
• Development status
• Usage
• Configuration

Example output of k0sctl deploying a k0s cluster:

INFO ==> Running phase: Connect to hosts
INFO ==> Running phase: Detect host operating systems
INFO [ssh] 10.0.0.1:22: is running Ubuntu 20.10
INFO [ssh] 10.0.0.2:22: is running Ubuntu 20.10
INFO ==> Running phase: Prepare hosts
INFO ==> Running phase: Gather host facts
INFO [ssh] 10.0.0.1:22: discovered 10.12.18.133 as private address
INFO ==> Running phase: Validate hosts
INFO ==> Running phase: Gather k0s facts
INFO ==> Running phase: Download k0s binaries on hosts
INFO ==> Running phase: Configure k0s
INFO ==> Running phase: Initialize the k0s cluster
INFO [ssh] 10.0.0.1:22: installing k0s controller
INFO ==> Running phase: Install workers
INFO [ssh] 10.0.0.1:22: generating token
INFO [ssh] 10.0.0.2:22: installing k0s worker
INFO [ssh] 10.0.0.2:22: waiting for node to become ready
INFO ==> Running phase: Disconnect from hosts
INFO ==> Finished in 2m2s
INFO k0s cluster version 1.22.3+k0s.0 is now installed
INFO Tip: To access the cluster you can now fetch the admin kubeconfig using:
INFO      k0sctl kubeconfig

You can find example Terraform and bootloose configurations in the examples/ directory.

Installation

Install from the released binaries

Download the desired version for your operating system and processor architecture from the k0sctl releases page. Make the file executable and place it in a directory available in your $PATH.

As the released binaries aren't signed yet, on macOS and Windows, you must first run the executable via "Open" in the context menu and allow running it.

Install from the sources

If you have a working Go toolchain, you can use go install to install k0sctl to your $GOPATH/bin.

go install github.com/k0sproject/k0sctl@latest

Package managers

Homebrew (macOS, Linux)

brew install k0sproject/tap/k0sctl

Chocolatey (Windows)

Note: The chocolatey package is community maintained, any issues should be reported to the maintainer of the package.

choco install k0sctl

Container usage

It is possible to use k0sctl as a docker/OCI container:

# pull the image
docker pull ghcr.io/k0sproject/k0sctl:latest

# create a backup
docker run -it --workdir /backup \
  -v ./backup:/backup \
  -v ./k0sctl.yaml:/etc/k0s/k0sctl.yaml \
  ghcr.io/k0sproject/k0sctl:latest k0sctl backup --config /etc/k0s/k0sctl.yaml

Shell auto-completions

Bash

k0sctl completion > /etc/bash_completion.d/k0sctl

Zsh

k0sctl completion > /usr/local/share/zsh/site-functions/_k0sctl

# For oh my zsh
k0sctl completion > $ZSH_CACHE_DIR/completions/_k0sctl

Fish

k0sctl completion > ~/.config/fish/completions/k0sctl.fish

Development status

K0sctl is ready for use and in continuous development.

Contributing & Agent Guidelines

For repository layout, development, and testing guidelines (including notes for AI assistants), see AGENTS.md.

Usage

k0sctl apply

The main function of k0sctl is the k0sctl apply subcommand. Provided a configuration file describing the desired cluster state, k0sctl will connect to the listed hosts, determines the current state of the hosts and configures them as needed to form a k0s cluster.

The default location for the configuration file is k0sctl.yaml in the current working directory. To load a configuration from a different location, use:

k0sctl apply --config path/to/k0sctl.yaml

If the configuration cluster version spec.k0s.version is greater than the version detected on the cluster, a cluster upgrade will be performed. If the configuration lists hosts that are not part of the cluster, they will be configured to run k0s and will be joined to the cluster.

k0sctl init

Generate a configuration template. Use --k0s to include an example spec.k0s.config k0s configuration block. You can also supply a list of host addresses via arguments or stdin.

Output a minimal configuration template:

k0sctl init > k0sctl.yaml

Output an example configuration with a default k0s config:

k0sctl init --k0s > k0sctl.yaml

Create a configuration from a list of host addresses and pipe it to k0sctl apply:

k0sctl init 10.0.0.1 10.0.0.2 ubuntu@10.0.0.3:8022 | k0sctl apply --config -

k0sctl backup & restore

Takes a backup of the cluster control plane state into the current working directory.

The files are currently named with a running (unix epoch) timestamp, e.g. k0s_backup_1623220591.tar.gz.

Restoring a backup can be done as part of the k0sctl apply command using --restore-from k0s_backup_1623220591.tar.gz flag.

Restoring the cluster state is a full restoration of the cluster control plane state, including:

• Etcd datastore content
• Certificates
• Keys

In general restore is intended to be used as a disaster recovery mechanism and thus it expects that no k0s components actually exist on the controllers.

Known limitations in the current restore process:

• The control plane address (externalAddress) needs to remain the same between backup and restore. This is caused by the fact that all worker node components connect to this address and cannot currently be re-configured.

k0sctl reset

Uninstall k0s from the hosts listed in the configuration.

k0sctl kubeconfig

Connects to the cluster and outputs a kubeconfig file that can be used with kubectl or kubeadm to manage the kubernetes cluster.

Example:

$ k0sctl kubeconfig --config path/to/k0sctl.yaml > k0s.config
$ kubectl get node --kubeconfig k0s.config
NAME      STATUS     ROLES    AGE   VERSION
worker0   NotReady   <none>   10s   v1.20.2-k0s1

Configuration file

The configuration file is in YAML format and loosely resembles the syntax used in Kubernetes. YAML anchors and aliases can be used.

To generate a simple skeleton configuration file, you can use the k0sctl init subcommand.

Configuration example:

apiVersion: k0sctl.k0sproject.io/v1beta1
kind: Cluster
metadata:
  name: my-k0s-cluster
  user: admin
spec:
  hosts:
  - role: controller
    installFlags:
    - --debug
    ssh:
      address: 10.0.0.1
      user: root
      port: 22
      keyPath: ~/.ssh/id_rsa
  - role: worker
    installFlags:
    - --debug
    ssh:
      address: 10.0.0.2
  k0s:
    version: 0.10.0
    config:
      apiVersion: k0s.k0sproject.io/v1beta1
      kind: ClusterConfig
      metadata:
        name: my-k0s-cluster
      spec:
        images:
          calico:
            cni:
              image: calico/cni
              version: v3.16.2
  options:
    wait:
      enabled: true
    drain:
      enabled: true
    evictTaint:
      enabled: false
      taint: k0sctl.k0sproject.io/evict=true
      effect: NoExecute
    concurrency:
      limit: 30
      uploads: 5

Environment variable substitution

Simple bash-like expressions are supported in the configuration for environment variable substition.

• $VAR or ${VAR} value of VAR environment variable
• ${var:-DEFAULT_VALUE} will use VAR if non-empty, otherwise DEFAULT_VALUE
• $$var - escape, result will be $var.
• And several other expressions

Configuration Header Fields

apiVersion <string> (required)

The configuration file syntax version. Currently the only supported version is k0sctl.k0sproject.io/v1beta1.

kind <string> (required)

In the future, some of the configuration APIs can support multiple types of objects. For now, the only supported kind is Cluster.

spec <mapping> (required)

The main object definition, see below

metadata <mapping> (optional)

Information that can be used to uniquely identify the object.

Example:

metadata:
  name: k0s-cluster-name
  user: kubernetes-admin

Spec Fields

spec.hosts <sequence> (required)

A list of cluster hosts. Host requirements:

• Linux nodes are supported for all roles.
• Windows nodes can join as worker hosts when reachable over SSH or WinRM. This support is experimental and requires k0s version >= 1.34.
• On Linux, the SSH user must either be root or have passwordless sudo (or doas) access. Windows workers must allow WinRM access for the configured user (defaults to Administrator).
• The host must fulfill the k0s system requirements

See host object documentation below.

spec.k0s <mapping> (optional)

Settings related to the k0s cluster.

See k0s object documentation below.

Host Fields

spec.hosts[*].role <string> (required)

One of:

• controller - a controller host
• controller+worker - a controller host that will also run workloads
• single - a single-node cluster host, the configuration can only contain one host
• worker - a worker host

spec.hosts[*].noTaints <boolean> (optional) (default: false)

When true and used in conjuction with the controller+worker role, the default taints are disabled making regular workloads schedulable on the node. By default, k0s sets a node-role.kubernetes.io/master:NoS