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

Caution

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 generate the omni: block automatically. Open ksail.yaml and 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., devantler-prod), 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

Talos excels at immutable infrastructure, security-focused production deployments, and multi-environment consistency—the same distribution works from local Docker development through Hetzner Cloud production without “works on my machine” issues. See Use Cases for practical workflow examples.

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
talosctl -n <node-ip> upgrade --image ghcr.io/siderolabs/installer:v1.6.0

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), or 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
    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

Upgrade without cluster recreation: talosctl -n <node-ip> upgrade --image ghcr.io/siderolabs/installer:v1.6.0. See Talos upgrade docs for coordination details.

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+)
# This document enables machine-wide container image signature verification.
# Rules are evaluated in order; the first matching rule applies.
# See: https://www.talos.dev/v1.13/talos-guides/configuration/image-verification/
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. Rules are evaluated in order; the first matching rule applies.

Note

--image-verification is only available for the Talos distribution and requires Talos 1.13+. For earlier Talos versions, omit the flag or use --image-verification Disabled.

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

GitOps Integration

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