Omni Documentation
Try OmniTalos Linux
  • Omni Documentation
  • Omni Support Matrix
  • Tutorials
    • Getting Started with Omni
    • Upgrading Omni Clusters
    • Installing Airgapped Omni
    • Using SAML and ACLs for fine-grained access control
    • Setting Up the Bare-Metal Infrastructure Provider
  • How-to guides
    • Using SAML with Omni
      • Add a User to Omni with SAML Enabled
      • Auto-assign roles to SAML users
      • Configure Workspace ONE Access for Omni
      • Configure Okta for Omni
      • Configure Entra ID AD for Omni
      • Configure Unifi Identity Enterprise for Omni
    • Register machines with Omni
      • Register a Bare Metal Machine (ISO)
      • Register a Bare Metal Machine (PXE/iPXE)
      • Register an AWS EC2 Instance
      • Register an Azure Instance
      • Register a GCP Instance
      • Register a Hetzner Server
    • Create a Cluster
    • Install talosctl
    • Install and Configure Omnictl
    • Use Kubectl With Omni
    • Create a Kubeconfig for a Kubernetes Service Account
    • Create a Patch For Cluster Machines
    • Manage Access Policies (ACLs)
    • Create a Hybrid Cluster
    • Run Omni on your own infrastructure
      • Deploy Omni On-prem
      • Configure Keycloak for Omni
      • Back Up On-prem Omni Database
      • How to expose Omni with Nginx (HTTPS)
    • Install Talos Linux Extensions
    • Scale a Cluster Up or Down
    • Etcd backups
    • Restore Etcd of a Cluster Managed by Cluster Templates
    • Create an Omni Service Account
    • Create a Machine Class
    • Expose an HTTP Service from a Cluster
    • Export a Cluster Template from a Cluster Created in the UI
    • Audit logs
    • Set Initial Machine Labels Using Omnictl or Image Factory
  • Explanation
    • Machine Registration
    • Authentication and Authorization
    • Omni KMS Disk Encryption
    • Infrastructure Providers
  • Reference
    • omnictl CLI
    • Access Policies (ACLs)
    • Generating omnictl CLI reference
    • Cluster Templates
Powered by GitBook
On this page
  • Prerequisites
  • Configure Authentication
  • Create Etcd Encryption Key
  • Deploy Omni
Edit on GitHub
Export as PDF
  1. How-to guides
  2. Run Omni on your own infrastructure

Deploy Omni On-prem

PreviousRun Omni on your own infrastructureNextConfigure Keycloak for Omni

Last updated 1 month ago

This guide shows you how to deploy Omni on-prem. This guide assumes that Omni will be deployed on an Ubuntu machine. Small differences should be expected when using a different OS.

For SAML integration sections, this guide assumes Azure AD will be the provider for SAML.

Omni is available via a which allows free installations in non-production environments. If you would like to deploy Omni for production use please contact . If you would like to subscribe to the hosted version of Omni please see the .

Prerequisites

There are several prerequisites for deploying Omni on-prem. We will assume you have an Ubuntu machine available. Any distribution with Docker should work.

Install Docker

Install Docker according to the Ubuntu installation guide . You will also need the docker compose plugin package if you want to use the example docker compose template.

curl -L https://get.docker.io | sh

Generate Certs

On-prem Omni will require valid SSL certificates. This means that self-signed certs will not work. Generating certificates is left as an exercise to the user, but here is a rough example that was tested using with certbot to generate certificates. The process should be very similar for other providers like Route53.

# Install certbot
$ sudo snap install --classic certbot

# Allow for root access
$ sudo snap set certbot trust-plugin-with-root=ok

# Install DNS provider
$ snap install certbot-dns-<provider>

# Create creds file with API tokens
$ echo '<creds example' > creds.ini

# Create certs for desired domain
$ certbot certonly --dns-<provider> -d <domain name for onprem omni>

Configure Authentication

Auth0

On the account level, configure "Authentication - Social" to allow GitHub and Google login.

Create an Auth0 application of the type "single page web application".

Configure the Auth0 application with the following:

  • Allowed callback URLs: https://<domain name for onprem omni>

  • Allowed web origins: https://<domain name for onprem omni>

  • Allowed logout URLs: https://<domain name for onprem omni>

Disable username/password auth on "Authentication - Database - Applications" tab.

Enable GitHub and Google login on the "Authentication - Social" tab.

Enable email access in the GitHub settings.

Take note of the following information from the Auth0 application:

  • Domain

  • Client ID

SAML Identity Providers

Other identity providers also work with Omni. Configuring these should be similar to Auth0.

Create Etcd Encryption Key

Generate a GPG key:

gpg --quick-generate-key "Omni (Used for etcd data encryption) how-to-guide@siderolabs.com" rsa4096 cert never

Find the fingerprint of the generated key:

gpg --list-secret-keys

Using the fingerprint, add an encryption subkey and export:

gpg --quick-add-key <fingerprint> rsa4096 encr never
gpg --export-secret-key --armor how-to-guide@siderolabs.com > omni.asc

Note: Do not add passphrases to keys during creation.

Deploy Omni

There are two easy ways to run Omni: docker-compose and a simple docker run. We recommend using docker-compose, but both are detailed in separate tabs below.

Export variables

You will need to specify some customizations for your installation. Export these variables with your information to use in the provided templates

export OMNI_VERSION=0.41.0
OMNI_ACCOUNT_UUID=$(uuidgen)
OMNI_DOMAIN_NAME=omni.siderolabs.com
OMNI_WG_IP=10.10.1.100
OMNI_ADMIN_EMAIL=omni@siderolabs.com
AUTH0_CLIENT_ID=xxxyyyzzz
AUTH0_DOMAIN=dev-aaabbbccc.us.auth0.com

Download Assets

To pull down the Omni deployment assets for Docker Compose, simply grab them with curl as follows.

curl https://raw.githubusercontent.com/siderolabs/omni/v${OMNI_VERSION}/deploy/env.template \
  | envsubst > omni.env

curl https://raw.githubusercontent.com/siderolabs/omni/v${OMNI_VERSION}/deploy/compose.yaml -o compose.yaml

Verify settings

Open the omni.env file to check that all of your variables have been set to your environment requirements.

Run It!

With your environment file in hand, it's now time to run Omni. This can be done with a simple docker compose command:

docker compose --env-file omni.env up -d

Deploying with a docker run is quite straight forward, with only some slight differences depending on the auth mechanism in use.

Auth0

docker run \
  --net=host \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  -v $PWD/etcd:/_out/etcd \
  -v <path to TLS certificate>:/tls.crt \
  -v <path to TLS key>:/tls.key \
  -v $PWD/omni.asc:/omni.asc \
  ghcr.io/siderolabs/omni:<tag> \
    --account-id=$(uuidgen) \
    --name=onprem-omni \
    --cert=/tls.crt \
    --key=/tls.key \
    --siderolink-api-cert=/tls.crt \
    --siderolink-api-key=/tls.key \
    --private-key-source=file:///omni.asc \
    --event-sink-port=8091 \
    --bind-addr=0.0.0.0:443 \
    --siderolink-api-bind-addr=0.0.0.0:8090 \
    --k8s-proxy-bind-addr=0.0.0.0:8100 \
    --advertised-api-url=https://<domain name for onprem omni>/ \
    --siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \
    --siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \
    --advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \
    --auth-auth0-enabled=true \
    --auth-auth0-domain=<Auth0 domain> \
    --auth-auth0-client-id=<Auth0 client ID> \
    --initial-users=<email address>

Note: The siderolink-wireguard-advertised-addr must point to an IP, not the domain name.

Note: you can omit the --cert, --key, --siderolink-api-cert, and --siderolink-api-key flags to run Omni insecurely.

Configuration options are available in the help menu (--help).

SAML

docker run \
  --net=host \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  -v $PWD/etcd:/_out/etcd \
  -v <path to full chain TLS certificate>:/tls.crt \
  -v <path to TLS key>:/tls.key \
  -v $PWD/omni.asc:/omni.asc \
  ghcr.io/siderolabs/omni:<tag> \
    --account-id=$(uuidgen) \
    --name=onprem-omni \
    --cert=/tls.crt \
    --key=/tls.key \
    --siderolink-api-cert=/tls.crt \
    --siderolink-api-key=/tls.key \
    --private-key-source=file:///omni.asc \
    --event-sink-port=8091 \
    --bind-addr=0.0.0.0:443 \
    --siderolink-api-bind-addr=0.0.0.0:8090 \
    --k8s-proxy-bind-addr=0.0.0.0:8100 \
    --advertised-api-url=https://<domain name for onprem omni>/ \
    --siderolink-api-advertised-url=https://<domain name for onprem omni>:8090/ \
    --siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \
    --advertised-kubernetes-proxy-url=https://<domain name for onprem omni>:8100/ \
    --auth-saml-enabled=true \
    --auth-saml-url=<app federation metadata url copied during Azure AD setup>

Note

In a default setup, the first user that logs in via SAML will be the “admin”. All subsequent users will receive a read-only role and may need to be granted additional access by the admin user from the “Users” tab in Omni.

Note

The siderolink-wireguard-advertised-addr must point to an IP, not the domain name.

Note

Note that you can omit the --cert, --key, --siderolink-api-cert, and --siderolink-api-key flags to run Omni insecurely.

Configuration options are available in the help menu (--help).

Create an .

Business Source License
Sidero sales
SaaS pricing
here
DigitalOcean's DNS integration
Auth0 account
EntraID/Azure AD
Keycloak
Okta
Workspace ONE Access
Unifi Identity Enterprise