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 Desktop or Docker Engine installed and running
• docker ps command works

Step 1: Initialize Project

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

This creates:

• ksail.yaml — KSail configuration
• talos/ directory — Talos configuration patches

Step 2: Create Cluster

ksail cluster create

KSail downloads the Talos Docker image, creates containers as nodes, bootstraps Kubernetes, configures kubectl context, and installs the configured CNI (Flannel by default; Cilium or Calico can be enabled via ksail.yaml).

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

• Hetzner Cloud account
• Hetzner Cloud API token (get it from Hetzner Cloud Console → Project → Security → API Tokens)
• Docker installed locally (for cluster initialization)

Step 1: Configure API Token

export HCLOUD_TOKEN=your-hetzner-api-token

Tip

Add HCLOUD_TOKEN to your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

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

KSail creates Hetzner Cloud servers, boots them with Talos, bootstraps Kubernetes, configures kubectl context, and installs CNI, CSI drivers, and the Hetzner Cloud Controller Manager for LoadBalancer support.

Step 4: Verify Cluster

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

Step 5: Deploy with LoadBalancer

kubectl create deployment web --image=nginx --replicas=3
kubectl expose deployment web --port=80 --type=LoadBalancer
kubectl get svc web --watch

The LoadBalancer service provisions a real Hetzner Cloud Load Balancer with a public IP.

Step 6: 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
• Omni service account key (create one in the Omni web UI under Settings → Service Accounts)
• Your Omni API endpoint URL (e.g., https://<account>.omni.siderolabs.io:443)
• Machines already registered in Omni and available for allocation

Step 1: Configure Credentials

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

Tip

Add OMNI_SERVICE_ACCOUNT_KEY to your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

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.cluster.omni.endpoint manually:

spec:
  cluster:
    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

KSail connects to your Omni instance, allocates registered machines, applies Talos configuration patches via the Omni API, bootstraps Kubernetes, and configures kubectl context.

Step 5: Verify Cluster

ksail cluster info
kubectl get nodes
kubectl get pods -A

Step 6: 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 on Docker

Each node is a Docker container running Talos Linux communicating via a Docker bridge network. No VM overhead. MetalLB provides LoadBalancer services (optional, via --load-balancer Enabled).

Talos on Hetzner

Each node is a Hetzner Cloud server running Talos Linux. The Hetzner Cloud Controller Manager provisions load balancers, the Hetzner CSI Driver provisions persistent volumes, and servers have public IPs for external access.

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).

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

Persistent Storage (Hetzner)

Use Hetzner CSI driver for cloud volumes:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-pvc
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: hcloud-volumes
  resources:
    requests:
      storage: 10Gi

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.

GitOps Integration

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