DOCSEARCHbyAlgolia
Submit Docs

k0sctl Documentation

repository·main·Indexed 20 days ago

https://github.com/k0sproject/k0sctl

A command-line tool to bootstrap and manage k0s zero-friction Kubernetes clusters. k0sctl automates host detection, binary installation, cluster initialization, and lifecycle management, including upgrades, backups, and restores. It supports various deployment environments, including AWS and Hetzner via Terraform, and provides flexible configuration for Linux and Windows hosts using SSH, OpenSSH, or WinRM.

Tokens
8.6K
Snippets
40
Records
48
Agent score
69%

What's inside k0sctl

  1. Use tokens in k0sDownloadURL and file sources

    main

    When using k0sDownloadURL or spec.hosts[*].files[*].src, you can use tokens that k0sctl expands based on host information:

    • %%: Literal % character.
    • %p: Host architecture (e.g., amd64, arm64).
    • %v: k0s version (e.g., v1.21.0+k0s.0).
    • %x: k0s binary extension (.exe on Windows, empty elsewhere).
    k0sDownloadURL: https://files.example.com/k0s-%v-%p%x
# Expands to: https://files.example.com/k0s-v1.21.0+k0s.0-amd64

  2. Use hooks to run commands during k0sctl operations

    main

    Hooks allow you to execute commands on remote hosts at specific lifecycle stages. Hooks run using the same remote user as the connection; use sudo if elevated privileges are needed.

    Available Hook Points:

    • connect.after: After OS detection.
    • apply.before: After validation, before configuring k0s.
    • apply.after: Before disconnecting after a successful apply.
    • upgrade.before: Before an upgrade begins on a specific host.
    • upgrade.after: After an upgrade completes on a specific host.
    • install.before: Before installing k0s components.
    • install.after: After k0s components are installed and ready.
    • backup.before: Before running k0s backup.
    • backup.after: Before disconnecting after a backup.
    • reset.before: Before removing k0s installation.
    • reset.after: After a successful reset operation.
    hooks:
  upgrade:
    before:
      - echo "about to upgrade"
    after:
      - echo "upgraded"

  3. Use environment variable substitution in k0sctl configuration

    main

    The k0sctl configuration supports bash-like expressions for environment variable substitution. This is useful for injecting secrets or dynamic values without hardcoding them in the YAML file.

    Supported patterns:

    • $VAR or ${VAR}: The value of the environment variable VAR.
    • ${var:-DEFAULT_VALUE}: Uses VAR if non-empty; otherwise, uses DEFAULT_VALUE.
    • $$var: Escapes the character, resulting in the literal string $var.

    Note: k0sctl uses envsubst logic for these substitutions.

  4. Install k0sctl

    main

    You can install k0sctl using several methods depending on your environment:

    From Released Binaries

    Download the appropriate binary for your OS and architecture from the k0sctl releases page, make it executable, and add it to your $PATH. Note: On macOS and Windows, you may need to manually allow the executable to run via the context menu as binaries are not yet signed.

    From Source

    If you have a Go toolchain installed, use go install:

    go install github.com/k0sproject/k0sctl@latest

    Using Package Managers

    • Homebrew (macOS/Linux): brew install k0sproject/tap/k0sctl
    • Nix (Linux/macOS): nix profile install nixpkgs#k0sctl
    • Alpine (Linux): apk add k0sctl
    • openSUSE (Linux): zypper install k0sctl
    • Arch Linux (AUR): yay -S k0sctl-bin or paru -S k0sctl-bin
    • Chocolatey (Windows): choco install k0sctl
    • WinGet (Windows): winget install k0sproject.k0sctl
    go install github.com/k0sproject/k0sctl@latest

  6. Backup and restore k0s cluster state

    main

    Backup

    k0sctl backup creates a backup of the cluster control plane state (including Etcd, certificates, and keys) into the current working directory. Files are named using a Unix epoch timestamp (e.g., k0s_backup_1623220591.tar.gz).

    Restore

    To restore, use the --restore-from flag with the k0sctl apply command:

    k0sctl apply --config k0sctl.yaml --restore-from k0s_backup_1623220591.tar.gz

    Important Constraints:

    • Restore is intended for disaster recovery and expects no existing k0s components on the controllers.
    • The control plane address (externalAddress) must remain the same between backup and restore, as worker nodes cannot currently be re-configured to a new address.
    k0sctl apply --config k0sctl.yaml --restore-from k0s_backup_1623220591.tar.gz

  7. Generate a k0sctl configuration skeleton

    main
    To create a starting point for your cluster configuration, use the k0sctl init subcommand. The resulting configuration file is in YAML format and supports Kubernetes-like syntax, including YAML anchors and aliases.
    k0sctl init

  8. Generate a k0sctl configuration template

    main

    Use the k0sctl init command to generate a configuration file.

    • To output a minimal template to a file: k0sctl init > k0sctl.yaml
    • To include an example spec.k0s.config block: k0sctl init --k0s > k0sctl.yaml
    • To generate a configuration from a list of host addresses and pipe it directly to apply: k0sctl init 10.0.0.1 10.0.0.2 ubuntu@10.0.0.3:8022 | k0sctl apply --config -
    k0sctl init --k0s > k0sctl.yaml

  9. Use k0sctl as a container

    main

    You can run k0sctl using a Docker/OCI container. This is useful for running tasks like backups without installing the binary locally.

    To pull the image:

    docker pull ghcr.io/k0sproject/k0sctl:latest

    To run a backup via container:

    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
    docker pull ghcr.io/k0sproject/k0sctl:latest

  10. Manage AWS k0s cluster deployment using Makefile

    main

    If a Makefile is present in the directory, you can use it to simplify the deployment, configuration retrieval, and teardown processes for the AWS k0s cluster.

    Available Makefile Commands

    • Deploy the cluster: make apply (runs Terraform and k0sctl steps).
    • Retrieve kubeconfig: make kubeconfig (extracts the credentials needed to interact with the cluster).
    • Teardown the cluster: make destroy (removes the AWS resources created by Terraform).
    make apply
make kubeconfig
make destroy

  11. Bootstrap a k0s cluster on AWS using Terraform

    main

    This example demonstrates how to use k0sctl in conjunction with Terraform to bootstrap a k0s cluster on AWS. The workflow creates a cluster consisting of a single controller and worker nodes.

    Prerequisites

    • AWS credentials configured: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
    • Terraform version >=v0.14.3 installed.
    • The k0sctl binary must be available in your PATH.

    Manual Deployment Steps

    1. Initialize Terraform: terraform init
    2. Apply Terraform configuration: terraform apply
    3. Pass the cluster configuration from Terraform output directly to k0sctl: terraform output -raw k0s_cluster | k0sctl apply --config -

    Customizing Configuration

    To override the default cluster behavior, create a terraform.tfvars file. You can use the provided terraform.tfvars.example as a template for your specific requirements.

    terraform init
terraform apply
terraform output -raw k0s_cluster | k0sctl apply --config -

  12. Configure shell auto-completions for k0sctl

    main

    Generate completion scripts for your shell:

    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
    k0sctl completion > /etc/bash_completion.d/k0sctl