Omni Provider

The Omni provider manages Talos Linux clusters through the Sidero Omni SaaS platform. Omni handles machine lifecycle, cluster orchestration, and configuration distribution — KSail connects to the Omni API to create, manage, and tear down clusters using machines you’ve already registered in Omni.

When to Use the Omni Provider

The Omni provider is ideal when you:

• Manage bare-metal or cloud machines through a centralized SaaS platform
• Want Omni to handle machine registration, health monitoring, and Talos upgrades
• Need enterprise-grade cluster orchestration without managing infrastructure directly
• Run Talos across heterogeneous hardware (bare-metal servers, VMs, edge devices)

Note

The Omni provider only supports the Talos distribution. For local Docker-based clusters, see the Talos distribution guide.

Prerequisites

1. Sidero Omni account — Sign up at siderolabs.com
2. Registered machines — At least one machine must be registered in your Omni instance and available for allocation (see Omni docs: Register a Machine). Machines can be allocated dynamically via a machine class, statically by UUID list, or auto-discovered from the available pool when neither is configured.
3. Service account key — Create one in the Omni web UI under Settings → Service Accounts; the key is a base64-encoded string
4. Omni API endpoint — Your account-specific URL, typically https://<account>.omni.siderolabs.io:443
5. Docker — Required locally for ksail CLI operations

Configuration

Environment Variable

Export the service account key so KSail can authenticate with the Omni API:

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

Tip

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

By default, KSail reads from OMNI_SERVICE_ACCOUNT_KEY. To use a different environment variable name, set spec.provider.omni.serviceAccountKeyEnvVar in ksail.yaml.

ksail.yaml Reference

The Omni provider is configured through spec.provider.omni in ksail.yaml:

apiVersion: ksail.io/v1alpha1
kind: Cluster
metadata:
  name: my-omni-cluster
spec:
  cluster:
    distribution: Talos
    provider: Omni
    talos:
      controlPlanes: 1
      workers: 2
  provider:
    omni:
      # Required: your Omni API endpoint
      endpoint: "https://<account>.omni.siderolabs.io:443"
      # Optional: pin the Talos version to deploy.
      # If omitted, KSail resolves the latest available version from Omni.
      talosVersion: "v1.9.5"
      # Optional: pin the Kubernetes version to deploy.
      # If omitted, KSail resolves a compatible version from Omni or Talos config defaults.
      kubernetesVersion: "v1.32.3"
      # Machine allocation strategy — choose one (or omit both to auto-discover):
      # Dynamic: allocate machines from a named machine class
      machineClass: "my-machine-class"
      # Static: allocate specific machines by UUID
      # machines:
      #   - "uuid-of-machine-1"
      #   - "uuid-of-machine-2"
      # Auto-discover: omit both machineClass and machines to let KSail
      # query Omni for available (unallocated) machines at cluster creation time.
      # Optional: override default env var names
      # serviceAccountKeyEnvVar: "MY_CUSTOM_OMNI_KEY"
      # endpointEnvVar: "MY_CUSTOM_OMNI_ENDPOINT"

Field	Type	Default	Description
omni.endpoint	string	—	Omni API endpoint URL. Overridden by the env var in endpointEnvVar.
omni.endpointEnvVar	string	OMNI_ENDPOINT	Environment variable containing the Omni API endpoint URL. Takes precedence over endpoint.
omni.serviceAccountKeyEnvVar	string	OMNI_SERVICE_ACCOUNT_KEY	Environment variable containing the service account key
omni.talosVersion	string	Omni latest	Talos Linux version to deploy (e.g., v1.9.5 or 1.9.5). If omitted, KSail resolves the latest available version from Omni. The v prefix is added automatically if omitted.
omni.kubernetesVersion	string	Auto-resolved	Kubernetes version to deploy (e.g., v1.32.3 or 1.32.3). If omitted, KSail resolves a compatible version from Omni or Talos config defaults. The v prefix is added automatically if omitted.
omni.machineClass	string	—	Omni machine class name for dynamic node allocation. The class must exist in your Omni account. Mutually exclusive with machines.
omni.machines	list of strings	—	List of Omni machine UUIDs for static allocation. The first N are assigned as control planes. Mutually exclusive with machineClass.

When neither machineClass nor machines is set, KSail automatically queries Omni for available (unallocated) machines and assigns the required number at cluster creation time. Setting both fields at once returns an error.

Quick Start

Step 1: Configure Credentials

Set OMNI_SERVICE_ACCOUNT_KEY as described in the Configuration section above, then verify it is exported in your shell.

Step 2: Initialize Project

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

This creates ksail.yaml and a talos/ directory for Talos configuration patches.

Step 3: Configure Omni Options

The scaffolder does not generate the omni: block automatically. Open ksail.yaml and add the Omni endpoint and machine allocation. You may also pin talosVersion and kubernetesVersion explicitly; if omitted, KSail resolves them from Omni automatically:

spec:
  provider:
    omni:
      endpoint: "https://<account>.omni.siderolabs.io:443"
      # Optional: pin versions (auto-resolved from Omni if omitted)
      # talosVersion: "v1.9.5"
      # kubernetesVersion: "v1.32.3"
      # Choose a machine allocation strategy (or omit both to auto-discover):
      machineClass: "my-machine-class"
      # machines:
      #   - "uuid-of-machine-1"
      #   - "uuid-of-machine-2"

If you omit both machineClass and machines, KSail queries Omni for available (unallocated) machines at cluster creation time and assigns the required count automatically.

Step 4: Create Cluster

ksail cluster create

Note

Omni generates the kubeconfig context name (e.g., devantler-prod). This differs from the admin@<name> convention used by Docker/Hetzner Talos clusters. After creation, retrieve the context name from your kubeconfig and set it in ksail.yaml so KSail can resolve it:

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

See Context defaults by distribution for the full reference.

Note

Deleting the cluster removes the Omni cluster resource and deallocates machines. The machines remain registered in Omni and can be reused for future clusters.

Step 5: Cleanup

# Delete the cluster (deallocates machines in Omni, does not wipe them)
ksail cluster delete

Architecture

KSail communicates with the Omni SaaS API to manage cluster resources. Omni owns the machine lifecycle — KSail never connects to nodes directly for provisioning.

graph TB
    subgraph "Your Machine"
        KSAIL["ksail CLI"]
    end

    subgraph "Sidero Omni SaaS"
        API["Omni API"]
        ORCH["Cluster Orchestrator"]
        REG["Machine Registry"]
    end

    subgraph "Registered Machines"
        CP["Control Plane Node"]
        W1["Worker Node 1"]
        W2["Worker Node 2"]
    end

    KSAIL -->|"service account key"| API
    API --> ORCH
    ORCH -->|"allocate & configure"| REG
    REG -->|"Talos config patches"| CP
    REG -->|"Talos config patches"| W1
    REG -->|"Talos config patches"| W2
    CP -.->|"kubeconfig"| KSAIL

KSail authenticates via a service account key — no direct SSH or Talos API access needed. Omni allocates registered machines to the cluster and applies Talos configuration. ksail cluster delete deallocates machines without destroying them — they return to the available pool.

Operations

List Clusters

ksail cluster list

Lists all clusters visible to your Omni account, including clusters created outside KSail, when both OMNI_SERVICE_ACCOUNT_KEY and OMNI_ENDPOINT are set in your environment. The list command does not read spec.provider.omni.endpoint from ksail.yaml, so OMNI_ENDPOINT must be configured explicitly for listing.

Cluster Info

ksail cluster info

Displays Kubernetes control-plane and core service endpoints for the current context (thin wrapper around kubectl cluster-info). For Omni-specific machine stages and node roles, use the Omni web UI or Omni CLI.

Update Cluster

ksail cluster update

Applies in-place changes to components (CNI, GitOps engine, cert-manager, etc.) and node counts. KSail scales Omni clusters declaratively: it rebuilds the cluster template with updated control-plane and worker counts and syncs it to the Omni API, which handles machine allocation and deallocation. All three allocation strategies are supported — machine class, static UUIDs, and auto-discovery. See the Update Behavior table for details.

Backup & Restore

ksail cluster backup --output ./backup.tar.gz
ksail cluster restore --input ./backup.tar.gz

KSail detects the Omni provider automatically from the server URL (*.omni.siderolabs.io) and embeds the correct distribution and provider metadata in the backup archive. This works even when the current context name (for example, devantler-service-account@omni) doesn’t follow KSail’s default naming conventions. See Backup & Restore for full details.

Kubeconfig Tokens

KSail manages your Omni kubeconfig automatically:

• Initial fetch — If no kubeconfig exists (e.g., a fresh CI runner), KSail fetches it from Omni before running any command. The parent directory (~/.kube/) is created if needed.
• Token refresh — Tokens have a 30-day TTL and are renewed transparently before any CLI command runs (when the token has 5 minutes or less remaining).

No manual action is required in either case.

Note

Automatic kubeconfig management is skipped when you pass --kubeconfig explicitly. In that case, you are managing the kubeconfig yourself and KSail will not modify it.

Troubleshooting

failed to determine Talos version — KSail could not auto-resolve the Talos version from Omni (for example the Omni API was unreachable or returned no versions). Set talosVersion and kubernetesVersion explicitly to bypass version discovery:

spec:
  provider:
    omni:
      talosVersion: "v1.9.5"
      kubernetesVersion: "v1.32.3"

TalosVersion is required or KubernetesVersion is required — Version resolution produced an empty value. This typically means the Omni query returned no results and no fallback was available. Set both fields explicitly as shown above.

omni service account key is not set — The env var is missing or empty. Run echo $OMNI_SERVICE_ACCOUNT_KEY to check. Re-export if needed. If you use a custom variable name, verify it matches spec.provider.omni.serviceAccountKeyEnvVar in ksail.yaml.

omni endpoint is required — spec.provider.omni.endpoint is missing from ksail.yaml and the OMNI_ENDPOINT env var is not set. Add it:

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

Cluster creation hangs or reports no nodes — No machines are registered and available in your Omni instance. Log in to the Omni web UI, navigate to Machines, and verify machines are registered and not already allocated. See Omni docs: Register a Machine.

cloud provider requires an external registry — Omni-managed nodes cannot reach Docker-based local registries running on your machine. When spec.cluster.localRegistry is enabled, it must point to an internet-accessible registry (e.g., ghcr.io/myorg). KSail returns this error early if a non-external registry is configured.

context deadline exceeded or connection errors — Verify the endpoint URL is correct and includes the port (:443). Check connectivity with curl -I https://<account>.omni.siderolabs.io:443 and ensure no firewall blocks outbound HTTPS.

not enough available machines in Omni for the requested node count — Auto-discovery found fewer available (unallocated) machines than the cluster requires. Log in to the Omni web UI, navigate to Machines, and verify enough machines are registered and not already allocated to another cluster. Alternatively, set machineClass or machines explicitly to control allocation.

MachineClass and Machines are mutually exclusive (set one or the other) — Both spec.provider.omni.machineClass and spec.provider.omni.machines are set in ksail.yaml. Remove one: use machineClass for dynamic allocation, machines for static allocation, or omit both for auto-discovery.