Talos

Talos Linux is a minimal, immutable operating system designed specifically for running Kubernetes. It provides enhanced security through API-driven configuration with no shell access, automatic updates, and a reduced attack surface. This guide shows you how to use Talos with KSail for local development (Docker provider), cloud deployments (Hetzner Cloud provider), or managed clusters through Sidero Omni (Omni provider).

Talos is ideal for security-focused production workloads, GitOps workflows, and multi-cloud deployments requiring immutable infrastructure. It’s not suitable for quick prototyping or scenarios requiring shell access—use Vanilla or K3s instead.

Quick Start

Docker (Local)

Local Development with Docker

Create a Talos cluster on your local machine using Docker containers as nodes.

Prerequisites

Docker installed and running (see Docker Provider).

Step 1: Initialize Project

ksail cluster init \
  --name talos-dev \
  --distribution Talos \
  --provider Docker \
  --control-planes 1 \
  --workers 2

Step 2: Create Cluster

ksail cluster create

Step 3: Verify Cluster

ksail cluster info
kubectl get nodes
kubectl get pods -A

Step 4: Cleanup

ksail cluster delete

Hetzner (Cloud)

Production Deployment on Hetzner Cloud

Create a production-ready Talos cluster on Hetzner Cloud infrastructure.

Prerequisites

A Hetzner Cloud account and API token. See Hetzner Provider for full setup.

Step 1: Configure API Token

export HCLOUD_TOKEN=your-hetzner-api-token

Step 2: Initialize Project

ksail cluster init \
  --name talos-prod \
  --distribution Talos \
  --provider Hetzner \
  --control-planes 1 \
  --workers 2

Step 3: Create Cluster

ksail cluster create

Step 4: Verify Cluster

ksail cluster info
kubectl get nodes -o wide
kubectl get pods -n kube-system | grep hcloud-csi

Step 5: Cleanup

ksail cluster delete

[!WARNING] This deletes the Hetzner Cloud servers and load balancers. You will stop being charged, but the operation is irreversible.

Omni (Managed)

Managed Deployment via Sidero Omni

Create a Talos cluster managed through Sidero Omni, which handles machine lifecycle and cluster orchestration via a SaaS API.

Prerequisites

A Sidero Omni account with service account key and registered machines. See Omni Provider for full setup.

Step 1: Configure Credentials

export OMNI_SERVICE_ACCOUNT_KEY=your-base64-encoded-service-account-key

Step 2: Initialize Project

ksail cluster init \
  --name talos-omni \
  --distribution Talos \
  --provider Omni \
  --control-planes 1 \
  --workers 2

Step 3: Add the Omni Endpoint

The scaffolder does not create an omni: block in ksail.yaml. You must add spec.provider.omni.endpoint manually:

spec:
  provider:
    omni:
      endpoint: "https://<account>.omni.siderolabs.io:443"

[!NOTE] The endpoint is specific to your Omni account. You can find it in the Omni web UI.

Step 4: Create Cluster

ksail cluster create

[!NOTE] Omni generates the kubeconfig context name (e.g., <account>-<cluster>), which differs from the admin@<name> convention used by Docker and Hetzner Talos clusters. After creation, retrieve the context name from your kubeconfig and set it in ksail.yaml:

spec:
  cluster:
    connection:
      context: "your-omni-generated-context"

See the Omni Provider guide for full details.

Step 5: Cleanup

ksail cluster delete

[!NOTE] Deleting the cluster removes the Omni cluster resource and deallocates machines. The machines remain registered in Omni and can be reused.

Use Cases

See Use Cases for practical workflow examples with Talos.

Common Talos API Operations

talosctl -n <node-ip> get machineconfig   # View configuration
talosctl -n <node-ip> version             # Check Talos version
talosctl -n <node-ip> logs                # System logs

[!NOTE] The talosconfig file is written to ~/.talos/config by default. Set spec.cluster.talos.config in ksail.yaml for a custom path.

Architecture

Talos node architecture varies by provider. See the Docker Provider, Hetzner Provider, and Omni Provider pages for details.

Distribution Comparison

See the Support Matrix for a full breakdown of feature and component compatibility across all distributions.

Troubleshooting

Cluster Creation Fails

Check Docker status (docker ps, docker network ls), verify HCLOUD_TOKEN for Hetzner, or try cleaning up and retrying with ksail cluster delete && ksail cluster create.

Nodes Not Ready

• Check CNI pods are running: kubectl get pods -n kube-system and look for your CNI pods, e.g. cilium- or calico-.
• Verify Talos health: talosctl -n <node-ip> health.
• Reinstall CNI with ksail cluster update.

LoadBalancer Not Working (Docker)

Verify MetalLB is enabled in ksail.yaml (loadBalancer: Enabled), check MetalLB pods (kubectl get pods -n metallb-system), and verify IP pool exists (kubectl get ipaddresspools -n metallb-system). On macOS, Docker runs in a Linux VM so MetalLB virtual IPs are not routable from the host—use extraPortMappings instead (see Port Mappings (Docker Provider)).

Cannot Access Talos API

Check ~/.talos/config exists, verify node IPs with kubectl get nodes -o wide, and use explicit node IP with talosctl -n <node-ip> --talosconfig ~/.talos/config get members.

Advanced Topics

Custom Node Counts

Adjust control plane and worker nodes in your existing ksail.yaml (requires distribution: Talos):

# Partial snippet — add to your existing ksail.yaml
spec:
  cluster:
    distribution: Talos
    controlPlanes: 3  # HA setup
    workers: 5

Port Mappings (Docker Provider)

On macOS, Docker runs in a Linux VM, so MetalLB virtual IPs are not directly accessible from the host. For Talos clusters using the Docker provider only, use extraPortMappings in ksail.yaml to expose container ports on the host (Hetzner and Omni Talos clusters do not use Docker port mappings):

# Partial snippet — add to your existing ksail.yaml
spec:
  cluster:
    distribution: Talos
    talos:
      extraPortMappings:
        - containerPort: 80
          hostPort: 8080
          protocol: TCP
        - containerPort: 443
          hostPort: 8443
          protocol: TCP

Access services at http://localhost:<hostPort> (for the example above, http://localhost:8080). Ports are applied to the first control-plane node only—in multi-control-plane clusters, additional control-plane nodes do not receive port mappings to avoid Docker host port collisions. See the Declarative Configuration reference for the full field specification.

Persistent Storage (Hetzner)

For cloud volumes, use the hcloud-volumes storage class installed automatically by the Hetzner Provider.

Talos Upgrades

ksail cluster update reconciles the Talos OS version automatically: it follows the latest supported version when spec.cluster.talos.version is unset, or reconciles toward the pinned version when it is set (also overridable per run with --distribution-version). The same field governs ksail cluster create.

# Follow the latest supported Talos version
ksail cluster update

# Pin a specific Talos OS version
ksail cluster update --distribution-version v1.13.3

KSail performs a rolling upgrade, one node at a time:

1. Worker nodes are upgraded one at a time
2. Control-plane nodes are upgraded one at a time after all workers complete

For each node, KSail selects the upgrade API based on the node’s running Talos version — nodes on Talos 1.13+ use the LifecycleService/ImageService APIs, while older nodes (for example 1.12.x) use the legacy MachineService upgrade API — then triggers the upgrade and waits for the node to be ready before proceeding.

[!NOTE] Omni-managed clusters are excluded from KSail-driven upgrades — Omni handles OS upgrades externally through its own cluster lifecycle management.

For manual upgrades outside of KSail, see the Talos upgrade docs.

Image Verification (Talos 1.13+)

Talos 1.13 introduced ImageVerificationConfig, which enforces machine-wide container image signature verification before any image is pulled. KSail can scaffold a starter configuration:

ksail cluster init \
  --distribution Talos \
  --image-verification Enabled

This generates talos/cluster/image-verification.yaml with a default skip-all rule and commented examples. The file is a valid Talos config document that KSail applies alongside your MachineConfig during cluster creation.

# Talos ImageVerificationConfig (Talos 1.13+)
# Rules are evaluated in order; the first matching rule applies.
apiVersion: v1alpha1
kind: ImageVerificationConfig
rules:
  # Default: skip verification for all images.
  # Remove or modify this rule and add specific verification rules below.
  - image: "*"
    skip: true
  # Example: Verify registry.k8s.io images using keyless (Cosign/OIDC) verification
  # - image: "registry.k8s.io/*"
  #   keyless:
  #     issuer: "https://accounts.google.com"
  #     subject: "krel-trust@k8s-releng-prod.iam.gserviceaccount.com"
  # Example: Verify images from a private registry using a public key
  # - image: "my-registry.example.com/*"
  #   publicKey:
  #     certificate: |
  #       -----BEGIN CERTIFICATE-----
  #       <your PEM-encoded certificate here>
  #       -----END CERTIFICATE-----
  # Example: Deny all images from an untrusted registry
  # - image: "untrusted-registry.example.com/*"
  #   deny: true

Edit the file to enforce your signature policy, then run ksail cluster create.

[!NOTE] For Talos, --image-verification Enabled scaffolds a native ImageVerificationConfig document and requires Talos 1.13+. For earlier Talos versions, omit the flag or use --image-verification Disabled.

[!NOTE] The Vanilla (Kind) distribution also supports --image-verification Enabled via containerd config patches — see Vanilla Image Verification.

See the Talos image verification docs for the full rule schema.

Environment Variables (EnvironmentConfig)

Talos 1.9 introduced the EnvironmentConfig resource as the preferred way to set environment variables for system services (kubelet, containerd, etc.). The legacy .machine.env field in MachineConfig is deprecated and will be removed in Talos 1.13.

KSail does not generate .machine.env in any scaffolded patches. If you need to set environment variables (e.g. HTTP proxy settings, custom kubelet flags via env), create an EnvironmentConfig document in your Talos patches directory:

apiVersion: v1alpha1
kind: EnvironmentConfig
environment:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"
  NO_PROXY: "10.0.0.0/8,192.168.0.0/16,localhost"

Place the file under your talos/ patches directory (e.g. talos/cluster/environment.yaml) and KSail will apply it alongside other config documents during cluster creation.

[!NOTE] Do not use .machine.env in custom patches — it is deprecated and will stop working in Talos 1.13+. Use EnvironmentConfig instead.

GitOps Integration

Enable Flux or ArgoCD for declarative workload management—see GitOps Workflows.