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 Getting Started with Talos — Docker.

Prerequisites

1. Sidero Omni account — Sign up at siderolabs.com
2. Registered machines — At least one machine must be registered and available in your Omni instance (see Omni docs: Register a Machine)
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.cluster.omni.serviceAccountKeyEnvVar in ksail.yaml.

ksail.yaml Reference

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

apiVersion: ksail.io/v1alpha1
kind: Cluster
metadata:
  name: my-omni-cluster
spec:
  cluster:
    distribution: Talos
    provider: Omni
    omni:
      # Required: your Omni API endpoint
      endpoint: "https://<account>.omni.siderolabs.io:443"
      # Optional: override the default env var name (default: OMNI_SERVICE_ACCOUNT_KEY)
      # serviceAccountKeyEnvVar: "MY_CUSTOM_OMNI_KEY"
    talos:
      controlPlanes: 1
      workers: 2

Field	Type	Default	Description
omni.endpoint	string	(required)	Omni API endpoint URL
omni.serviceAccountKeyEnvVar	string	OMNI_SERVICE_ACCOUNT_KEY	Environment variable containing the service account key

Quick Start

Step 1: Configure Credentials

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

Step 2: Initialize Project

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

This creates:

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

Step 3: Add the Omni Endpoint

The scaffolder does not generate the omni: block automatically. Open ksail.yaml and add the endpoint:

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

Step 4: Create Cluster

ksail cluster create

KSail will:

1. Connect to your Omni instance using the service account key
2. Allocate registered machines to the cluster
3. Apply Talos configuration patches via the Omni API
4. Bootstrap the Kubernetes cluster
5. Configure kubectl context

Step 5: Verify Cluster

# Check cluster info
ksail cluster info

# View nodes
kubectl get nodes

# View all pods
kubectl get pods -A

Step 6: Cleanup

# Delete the cluster (deallocates machines in Omni, does not wipe them)
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 for future clusters.

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

Key characteristics:

• KSail authenticates via a service account key — no direct SSH or Talos API access needed for provisioning
• Omni allocates registered machines to the cluster and applies Talos configuration
• Machine lifecycle (registration, health, upgrades) is managed entirely by Omni
• 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.cluster.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.). Node scaling changes for Talos are applied in-place. See the Update Behavior table for details.

Troubleshooting

Authentication Failures

Symptom: omni service account key is not set

Cause: The environment variable is missing or empty.

Fix:

# Verify the variable is set
echo $OMNI_SERVICE_ACCOUNT_KEY

# Re-export if needed
export OMNI_SERVICE_ACCOUNT_KEY=your-base64-encoded-key

If you use a custom variable name, ensure it matches spec.cluster.omni.serviceAccountKeyEnvVar in your ksail.yaml.

Endpoint Not Configured

Symptom: omni endpoint is required

Cause: spec.cluster.omni.endpoint is missing from ksail.yaml.

Fix: Add the endpoint to your configuration:

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

No Machines Available

Symptom: Cluster creation hangs or reports no nodes.

Cause: No machines are registered and available in your Omni instance.

Fix:

1. Log in to the Omni web UI
2. Navigate to Machines and verify machines are registered
3. Ensure machines are not already allocated to another cluster
4. See Omni docs: Register a Machine

Connection Timeout

Symptom: context deadline exceeded or connection errors.

Cause: Network issues or incorrect endpoint URL.

Fix:

1. Verify the endpoint URL is correct and includes the port (:443)
2. Check network connectivity: curl -I https://<account>.omni.siderolabs.io:443
3. Ensure no firewall or proxy is blocking outbound HTTPS traffic

Next Steps

• Getting Started with Talos — Complete Talos guide with Docker, Hetzner, and Omni tabs
• Support Matrix — Distribution × Provider compatibility
• Configuration — Full configuration reference
• Concepts — Providers — Provider concept overview

Resources

• Sidero Omni: https://www.siderolabs.com/platform/saas-for-kubernetes/
• Omni Documentation: https://omni.siderolabs.com/docs/
• Omni — Register a Machine: https://omni.siderolabs.com/docs/how-to-guides/how-to-register-a-machine/
• Omni — Create a Cluster: https://omni.siderolabs.com/docs/how-to-guides/how-to-create-a-cluster/
• Talos Linux: https://www.talos.dev/