Deploy Omni on Prem

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 Business Source License which allows free installations in non-production environments. If you would like to deploy Omni for production use please contact Sidero sales. If you would like to subscribe to the hosted version of Omni please see the SaaS pricing;

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 here. 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 DigitalOcean’s DNS integration 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

Create an Auth0 account. 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) [email protected]" 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 [email protected] > 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.

Docker Compose
Docker Run

Export variables

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

If you are running multiple Omni instances connected to a shared etcd backend you will need to set the accountUUID to a unique value. If you are not using shared backend storage then this option does not need to be unique.

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/${OMNI_VERSION}/deploy/env.template \
  | envsubst > omni.env

curl https://raw.githubusercontent.com/siderolabs/omni/${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>

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

OIDC

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-oidc-enabled \
    --auth-oidc-provider-url <URL of the OIDC provider> \
    --auth-oidc-client-id <id copied from the OIDC provider> \
    --auth-oidc-client-secret <secret copied from the OIDC provider> \
    --auth-oidc-logout-url <logout URL, optional, copied from the OIDC provider> \
    --auth-oidc-scopes openid \
    --auth-oidc-scopes profile \
    --auth-oidc-scopes email

NoteThe siderolink-wireguard-advertised-addr must point to an IP, not the domain name.NoteNote 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).

Overview

Getting Started

Infrastructure and Extensions

Omni Cluster Setup

Cluster Management

Security and Authentication

Reference

Troubleshooting and Support

Prerequisites

Install Docker

Generate Certs

Configure Authentication

Auth0

SAML Identity Providers

Create Etcd Encryption Key

Deploy Omni

Export variables

Download Assets

Verify settings

Run It!

Auth0

SAML

OIDC

Overview

Getting Started

Infrastructure and Extensions

Omni Cluster Setup

Cluster Management

Security and Authentication

Reference

Troubleshooting and Support

​Prerequisites

​Install Docker

​Generate Certs

​Configure Authentication

​Auth0

​SAML Identity Providers

​Create Etcd Encryption Key

​Deploy Omni

​Export variables

​Download Assets

​Verify settings

​Run It!

​Auth0

​SAML

​OIDC

Prerequisites

Install Docker

Generate Certs

Configure Authentication

Auth0

SAML Identity Providers

Create Etcd Encryption Key

Deploy Omni

Export variables

Download Assets

Verify settings

Run It!

Auth0

SAML

OIDC