Skip to main content
This guide walks you through creating a high-availability Kubernetes cluster managed by Omni using Talos Linux.
While the example uses UTM/QEMU for local virtualization, the same process applies to bare metal machines, cloud instances, or edge devices. If you prefer a visual walkthrough, you can follow this short video tutorial:

​
Prerequisites

You must have the following to create a cluster with Omni:
  • Network access: Your machines must have outbound internet access and be able to reach the WireGuard endpoint shown on your Omni Home panel. This endpoint lists an IP address and port (e.g., 199.99.99.100:10001) that nodes connect to. Machines need to reach that address over:
    • UDP on the specified port (for WireGuard)
    • TCP on port 443 (for Omni communication)
  • Virtual or physical machines: You can use any virtualization platform that supports booting from an ISO image, for example, UTM, Proxmox, or VMware Fusion. Alternatively, you can deploy on cloud platforms or physical hardware. Bare metal systems can boot using a CD, USB drive, virtual media, or PXE.
  • CLI tools: To work effectively with Omni, you’ll need the CLI tools omnictl, talosctl, and kubelogin. Download talosctl, kubectl, kubectl-oidc-login, and omnictl for macOS and Linux systems by running this command: 
    brew install siderolabs/tap/sidero-tools
    For manual and Windows installation, refer to the alternate installation methods in the Talos documentation.
  • talosconfig and omniconfig files: Download the talosconfig and omniconfig configuration files from your Omni dashboard. These files let you manage your Talos nodes and connect to Omni from your local environment. Talosconfig and Omniconfig Alternatively, you can download the talosconfig file from the CLI by running the following command. Replace the <cluster-name> placeholder with your cluster’s name: 
    omnictl talosconfig --cluster <cluster-name>
    Once you’ve set up these prerequisites, you can move on to creating your cluster with Omni.

​
Step 1: Download Installation Media

Omni is a Bring Your Own Machine platform. You only need to boot a machine from a Talos image configured to connect to your Omni instance. You can download this Omni image from either the Omni UI or the CLI:
To download the Omni image from the Omni dashboard:
  1. Log in to your Omni dashboard.
  2. Click the Download Installation Media button to open its modal. Download Installation Media
  3. Choose the appropriate image for your machine. Appropriate Omni image
  4. Click Download to begin downloading the Omni image.
Note: Some platforms (like cloud providers) require additional steps to import the image, for example, uploading to an S3 bucket or creating a VM image. Follow the platform-specific instructions if prompted.

​
Step 2: Boot your machines

Boot each machine you want to add to the cluster using the Omni image you downloaded in Step 1. After the machines have booted, they’ll appear in the Machines section. Depending on your environment, you can use the following methods:
To create temporary VMs on your local system (requires Talosctl v1.12+), replace the $COPY_FROM_OMNI placeholder with the API endpoint from your Omni dashboard, then run:
talosctl cluster create qemu --omni-api-endpoint $COPY_FROM_OMNI
This command boots virtual machines locally and connects them to your Omni instance.

​
Step 3: Create Cluster

Now that your machines are visible in Omni, you can create your cluster by following these steps:
  1. In the Omni sidebar, go to Clusters → Create Cluster. Create cluster
  2. Enter a cluster name and select the Talos Linux and Kubernetes versions. Cluster Name
  3. (Optional) Add configuration patches. See Create a Patch for Cluster Machines to learn how to create and apply patches.
  4. Under the Available Machines section, select at least one machine as a control plane by clicking CP.
For high availability, use an odd number of control plane nodes. We suggest using 3 nodes.
Control Plane button
  1. Select one or more worker machines by clicking W0, W1, etc. Worker node button
  2. Click Create Cluster.
You’ll be redirected to the Cluster Overview page, where you can monitor the cluster’s creation progress.

​
Step 4: Download the kubeconfig file

Click the ⋯ button next to your cluster, then select Download kubeconfig to download the file. Download kubeconfig Alternatively, you can download the kubeconfig file from your CLI with this command: 
omnictl kubeconfig --cluster <cluster-name>
Replace the <cluster-name> placeholder with the name of your cluster.

​
Step 5: Merge your configuration

To make omnictl, talosctl, and kubectl automatically detect your cluster configuration, merge each configuration file into its default location: 
# Merge Omni configuration
omnictl config merge $HOME/Downloads/omniconfig.yaml

# Merge Talos configuration
talosctl config merge $HOME/Downloads/talosconfig.yaml

# Merge kubeconfig (combine and flatten)
export KUBECONFIG=~/.kube/config:$HOME/Downloads/talos-default-kubeconfig.yaml
kubectl config view --flatten > ~/.kube/config

​
Step 6: Access your Kubernetes cluster

Once your cluster is created, you can confirm that your nodes are registered in Kubernetes by running: 
kubectl get nodes
Note: The first time you run kubectl, a browser window will open prompting you to sign in with your identity provider (Google or GitHub). If you see the error error: unknown command "oidc-login", ensure you’ve installed the kubectl-oidc-login plugin as described in the prerequisites section.

​
Explore Omni

Congratulations, you have successfully created a Talos Linux cluster with Omni! From here, you can explore what else Omni can do, such as:

​
Example: Deploy a Kubernetes workload on your Omni cluster

You can find an example of a more advanced managed cluster, complete with a monitoring stack and application management, in our community contrib repo. This example includes components such as: