Omni Documentation

• 1: Tutorials
• 1.1: Installing Airgapped Omni
• 2: How-to guides
• 2.1: How to Register a Bare Metal Machine (ISO)
• 2.2: How to Register a Bare Metal Machine (PXE/iPXE)
• 2.3: How to Register a GCP Instance
• 2.4: How to Register an AWS EC2 Instance
• 2.5: How to Register an Azure Instance
• 2.6: How to Create a Service Account Kubeconfig
• 2.7: How to Scale Down a Cluster
• 2.8: How to Scale Up a Cluster
• 2.9: How to Register a Hetzner Server
• 2.10: How to File an Issue
• 2.11: How to install talosctl
• 2.12: How to Create a Cluster
• 2.13: How to Create a Patch For Cluster Control Planes
• 2.14: How to Create a Patch For Cluster Machines
• 2.15: How to Create a Patch For Cluster Workers
• 2.16: How to Create a Hybrid Cluster
• 2.17: How to Use Kubectl With Omni
• 2.18: How to Install and Configure Omnictl
• 2.19: How to Deploy Omni On-prem
• 2.20: How to Back Up On-prem Omni Database
• 2.21: How to Configure Keycloak for Omni
• 3: Reference
• 3.1: Cluster Templates
• 3.2: omnictl CLI
• 4: Explanation
• 4.1: Machine Registration

1 - Tutorials

1.1 - Installing Airgapped Omni

Prerequisites

DNS server NTP server TLS certificates Installed on machine running Omni

• genuuid
  • Used to generate a unique account ID for Omni.
• Docker
  • Used for running the suite of applications
• Wireguard
  • Used by Siderolink

Overview

• Gathering Dependencies
  • Generate Certificates
  • Create app.ini file
  • Gathing Images
  • Move Dependencies
• Gitea
  • Install Gitea
  • Gitea Setup
  • Push Images to Gitea
• Keycloak
  • Start Keycloak
  • Configuring Keycloak
• Omni
  • Install Omni

Gathering Dependencies

In this package, we will be installing:

• Gitea
• Keycloak
• Omni

To keep everything organized, I am using the following directory structure to store all the dependencies and I will move them to the airgapped network all at once.

NOTE: The empty directories will be used for the persistent data volumes when we deploy these apps in Docker.

airgap
├── certs
├── gitea
├── keycloak
├── omni
└── registry

Generate Certificates

TLS Certificates

This tutorial will involve configuring all of the applications to be accessed via https with signed .pem certificates generated with certbot. There are many methods of configuring TLS certificates and this guide will not cover how to generate your own TLS certificates, but there are many resources available online to help with this subject if you do not have certificates already.

Omni Certificate

Omni uses etcd to store the data for our installation and we need to give it a private key to use for encryption of the etcd database.

1. First, Generate a GPG key.

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

This will generate a new GPG key pair with the specified properties.

What’s going on here?

• quick-gnerate-key allows us to quickly generate a new GPG key pair. -"Omni (Used for etcd data encryption) how-to-guide@siderolabs.com" is the user ID associated with the key which generally consists of the real name, a comment, and an email address for the user.
• rsa4096 specifies the algorithm type and key size.
• cert means this key can be used to certify other keys.
• never specifies that this key will never expire.

2. Add an encryption subkey

We will use the fingerprint of this key to create an encryption subkey.

To find the fingerprint of the key we just created, run:

gpg --list-secret-keys

Next, run the following command to create the encryption subkey, replacing $FPR with your own keys fingerprint.

gpg --quick-add-key $FPR rsa4096 encr never

In this command:

• $FPR is the fingprint of the key we are adding the subkey to.
• rsa4096 and encr specify that the new subkey will be an RSA encryption key with a size of 4096 bits.
• never means this subkey will never expire.

3. Export the secret key

Lastly we’ll export this key into an ASCII formatted file so Omni can use it.

gpg --export-secret-key --armor how-to-guide@siderolabs.com > certs/omni.asc

• --armor is an option which creates the output in ASCII format. Without it, the output would be binary.

Save this file to the certs directory in our package.

Create the app.ini File

Gitea uses a configuration file named app.ini which we can use to pre-configure with the necessary information to run Gitea and bypass the intitial startup page. When we start the container, we will mount this file as a volume using Docker.

Create the app.ini file

vim gitea/app.ini

Replace the DOMAIN, SSH_DOMAIN, and ROOT_URL values with your own hostname:

APP_NAME=Gitea: Git with a cup of tea
RUN_MODE=prod
RUN_USER=git
I_AM_BEING_UNSAFE_RUNNING_AS_ROOT=false

[server]
CERT_FILE=cert.pem
KEY_FILE=key.pem
APP_DATA_PATH=/data/gitea
DOMAIN=${GITEA_HOSTNAME}
SSH_DOMAIN=${GITEA_HOSTNAME}
HTTP_PORT=3000
ROOT_URL=https://${GITEA_HOSTNAME}:3000/
HTTP_ADDR=0.0.0.0
PROTOCOL=https
LOCAL_ROOT_URL=https://localhost:3000/

[database]
PATH=/data/gitea/gitea.db
DB_TYPE=sqlite3
HOST=localhost:3306
NAME=gitea
USER=root
PASSWD=

[security]
INSTALL_LOCK=true # This is the value which tells Gitea not to run the intitial configuration wizard on start up

NOTE: If running this in a production environment, you will also want to configure the database settings for a production database. This configuration will use an internal sqlite database in the container.

Gathering Images

Next we will gather all the images needed installing Gitea, Keycloak, Omni, and the images Omni will need for creating and installing Talos.

I’ll be using the following images for the tutorial:

Gitea

• docker.io/gitea/gitea:1.19.3 Keycloak
• quay.io/keycloak/keycloak:21.1.1 Omni
• ghcr.io/siderolabs/omni:v0.11.0
  • Contact Us if you would like the image used to deploy Omni in an airgapped, or on-prem environement.
• ghcr.io/siderolabs/imager:v1.4.5
  • pull this image to match the version of Talos you would like to use. Talos
• ghcr.io/siderolabs/flannel:v0.21.4
• ghcr.io/siderolabs/install-cni:v1.4.0-1-g9b07505
• docker.io/coredns/coredns:1.10.1
• gcr.io/etcd-development/etcd:v3.5.9
• registry.k8s.io/kube-apiserver:v1.27.2
• registry.k8s.io/kube-controller-manager:v1.27.2
• registry.k8s.io/kube-scheduler:v1.27.2
• registry.k8s.io/kube-proxy:v1.27.2
• ghcr.io/siderolabs/kubelet:v1.27.2
• ghcr.io/siderolabs/installer:v1.4.5
• registry.k8s.io/pause:3.6

NOTE: The Talos images needed may be found using the command talosctl images. If you do not have talosctl installed, you may find the instructions on how to install it here.

Package the images

1. Pull the images to load them locally into Docker.

• Run the following command for each of the images listed above except for the Omni image which will be provided to you as an archive file already.

sudo docker pull registry/repository/image-name:tag

2. Verify all of the images have been downloaded

sudo docker image ls

3. Save all of the images into an archive file.

• All of the images can be saved as a single archive file which can be used to load all at once on our airgapped machine with the following command.

docker save -o image-tarfile.tar \
  list \
  of \
  images

Here is an an example of the command used for the images in this tutuorial:

docker save -o registry/all_images.tar \
  docker.io/gitea/gitea:1.19.3 \
  quay.io/keycloak/keycloak:21.1.1 \
  ghcr.io/siderolabs/imager:v1.4.5 \
  ghcr.io/siderolabs/flannel:v0.21.4 \
  ghcr.io/siderolabs/install-cni:v1.4.0-1-g9b07505 \
  docker.io/coredns/coredns:1.10.1 \
  gcr.io/etcd-development/etcd:v3.5.9 \
  registry.k8s.io/kube-apiserver:v1.27.2 \
  registry.k8s.io/kube-controller-manager:v1.27.2 \
  registry.k8s.io/kube-scheduler:v1.27.2 \
  registry.k8s.io/kube-proxy:v1.27.2 \
  ghcr.io/siderolabs/kubelet:v1.27.2 \
  ghcr.io/siderolabs/installer:v1.4.5 \
  registry.k8s.io/pause:3.6

Move Dependencies

Now that we have all the packages necessary for the airgapped deployment of Omni, we’ll create a compressed archive file and move it to our airgapped network.

The directory structure should look like this now:

airgap
├── certs
│   ├── fullchain.pem
│   ├── omni.asc
│   └── privkey.pem
├── gitea
│   └── app.ini
├── keycloak
├── omni
└── registry
    ├── omni-image.tar # Provided to you by Sidero Labs
    └── all_images.tar

Create a compressed archive file to move to our airgap machine.

cd ../
tar czvf omni-airgap.tar.gz airgap/

Now I will use scp to move this file to my machine which does not have internet access. Use whatever method you prefer to move this file.

scp omni-airgap.tar.gz $USERNAME@$AIRGAP_MACHINE:/home/$USERNAME/

Lastly, I will log in to my airgapped machine and extract the compressed archive file in the home directory

cd ~/
tar xzvf omni-airgap.tar.gz

Log in Airgapped Machine

From here on out, the rest of the tutorial will take place from the airgapped machine we will be installing Omni, Keycloak, and Gitea on.

Gitea

Gitea will be used as a container registry for storing our images, but also many other functionalities including Git, Large File Storage, and the ability to store packages for many different package types. For more information on what you can use Gitea for, visit their documentation.

Install Gitea

Load the images we moved over. This will load all the images into Docker on the airgapped machine.

docker load -i registry/omni-image.tar
docker load -i registry/all_images.tar

Run Gitea using Docker:

• The app.ini file is already configured and mounted below with the - v argument.

sudo docker run -it \
    -v $PWD/certs/privkey.pem:/data/gitea/key.pem \
    -v $PWD/certs/fullchain.pem:/data/gitea/cert.pem \
    -v $PWD/gitea/app.ini:/data/gitea/conf/app.ini \
    -v $PWD/gitea/data/:/data/gitea/ \
    -p 3000:3000 \
    gitea/gitea:1.19.3

You may now log in at the https://${GITEA_HOSTNAME}:3000 to begin configuring Gitea to store all the images needed for Omni and Talos.

Gitea setup

This is just the bare minimum setup to run Omni. Gitea has many additional configuration options and security measures to use in accordance with your industry’s security standards. More information on the configuration of Gitea can be found (here)[https://docs.gitea.com/].

Create a user

Click the Register button at the top right corner. The first user created will be created as an admin and permissions which can be adjusted accordingly afterwards if you like.

Create organizations

After registering an admin user, the organizations, can be created which will act as the package repositories for storing images. Create the following organizations:

• siderolabs
• keycloak
• coredns
• etcd-development
• registry-k8s-io-proxy

NOTE: If you are using self-signed certs and would like to push images to your local Gitea using Docker, you will also need to configure your certs.d directory as described (here)[https://docs.docker.com/engine/security/certificates/].

Push Images to Gitea

Now that all of our organizations have been created, we can push the images we loaded into our Gitea for deploying Keycloak, Omni, and storing images used by Talos.

For all of the images loaded, we first need to tag them for our Gitea.

sudo docker tag original-image:tag gitea:3000/new-image:tag

For example, if I am tagging the kube-proxy image it will look like this:

NOTE: Don’t forget to tag all of the images from registry.k8s.io to go to the registry-k8s-io-proxy organization created in Gitea.

docker tag registry.k8s.io/kube-proxy:v1.27.2 ${GITEA_HOSTNAME}:3000/registry-k8s-io-proxy/kube-proxy:v1.27.2

Finally, push all the images into Gitea.

docker push ${GITEA_HOSTNAME}:3000/registry-k8s-io-proxy/kube-proxy:v1.27.2

Keycloak

Install Keycloak

The image used for keycloak is already loaded into Gitea and there are no files to stage before starting it so I’ll run the following command to start it. Replace KEYCLOAK_HOSTNAME and GITEA_HOSTNAME with your own hostnames.

sudo docker run -it \
    -p 8080:8080 \
    -p 8443:8443 \
    -v $PWD/certs/fullchain.pem:/etc/x509/https/tls.crt \
    -v $PWD/certs/privkey.pem:/etc/x509/https/tls.key \
    -v $PWD/keycloak/data:/opt/keycloak/data \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin \
    -e KC_HOSTNAME=${KEYCLOAK_HOSTNAME} \
    -e KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/tls.crt \
    -e KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/tls.key \
    ${GITEA_HOSTNAME}:3000/keycloak/keycloak:21.1.1 \
    start

Once Keycloak is installed, you can reach it in your browser at `https://${KEYCLOAK_HOSTNAME}:3000

Configuring Keycloak

For details on configuring Keycloak as a SAML Identity Provider to be used with Omni, follow this guide: Configuring Keycloak SAML

Omni

With Keycloak and Gitea installed and configured, we’re ready to start up Omni and start creating and managing clusters.

Install Omni

To install Omni, first generate a UUID to pass to Omni when we start it.

export OMNI_ACCOUNT_UUID=$(uuidgen)

Next run the following command, replacing hostnames for Omni, Gitea, or Keycloak with your own.

sudo docker run \
  --net=host \
  --cap-add=NET_ADMIN \
  -v $PWD/etcd:/_out/etcd \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $PWD/certs/fullchain.pem:/fullchain.pem \
  -v $PWD/certs/privkey.pem:/privkey.pem \
  -v $PWD/certs/omni.asc:/omni.asc \
  ${GITEA_HOSTNAME}:3000/siderolabs/omni:v0.12.0 \
    --account-id=${OMNI_ACCOUNT_UUID} \
    --name=omni \
    --cert=/fullchain.pem \
    --key=/privkey.pem \
    --siderolink-api-cert=/fullchain.pem \
    --siderolink-api-key=/privkey.pem \
    --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://${OMNI_HOSTNAME}:443/ \
    --siderolink-api-advertised-url=https://${OMNI_HOSTNAME}:8090/ \
    --siderolink-wireguard-advertised-addr=${OMNI_HOSTNAME}:50180 \
    --advertised-kubernetes-proxy-url=https://${OMNI_HOSTNAME}:8100/ \
    --auth-auth0-enabled=false \
    --auth-saml-enabled \
    --talos-installer-registry=${GITEA_HOSTNAME}:3000/siderolabs/installer \
    --talos-imager-image=${GITEA_HOSTNAME}:3000/siderolabs/imager:v1.4.5 \
    --kubernetes-registry=${GITEA_HOSTNAME}:3000/siderolabs/kubelet \
    --auth-saml-url "https://${KEYCLOAK_HOSTNAME}:8443/realms/omni/protocol/saml/descriptor"

What’s going on here:

• --auth-auth0-enabled=false tells Omni not to use Auth0.
• --auth-saml-enabled enables SAML authentication.
• --talos-installer-registry, --talos-imager-image and --kubernetes-registry allow you to set the default images used by Omni to point to your local repository.
• --auth-saml-url is the URL we saved earlier in the configuration of Keycloak.
  • --auth-saml-metadata may also be used if you would like to pass it as a file instead of a URL and can be used if using self-signed certificates for Keycloak.

Creating a cluster

Guides on creating a cluster on Omni can be found here:

• Creating an Omni cluster

Because we’re working in an airgapped environment we will need the following values added to our cluster configs so they know where to pull images from. More information on the Talos MachineConfig.registries can be found here.

NOTE: In this example, cluster discovery is also disabled. You may also configure cluster discovery on your network. More information on the Discovery Service can be found here

machine:
  registries:
    mirrors:
    docker.io:
      endpoints:
      - https://${GITEA_HOSTNAME}:3000
    gcr.io:
      endpoints:
      - https://${GITEA_HOSTNAME}:3000
    ghcr.io:
      endpoints:
      - https://${GITEA_HOSTNAME}:3000
    registry.k8s.io:
      endpoints:
      - https://${GITEA_HOSTNAME}:3000/v2/registry-k8s-io-proxy
      overridePath: true
cluster:
  discovery:
    enabled: false

Specifics on patching machines can be found here:

• Create a Patch for Cluster Machines

Closure

With Omni, Gitea, and Keycloak set up, you are ready to start managing and installing Talos clusters on your network! The suite of applications installed in this tutorial is an example of how an airgapped environment can be set up to make the most out of the Kubernetes clusters on your network. Other container registries or authentication providers may also be used with a similar setup, but this suite was chosen to give you starting point and an example of what your environment could look like.

2 - How-to guides

2.1 - How to Register a Bare Metal Machine (ISO)

This guide shows you how to register a bare metal machine with Omni by booting from an ISO.

Dashboard

Upon logging in you will be presented with the Omni dashboard.

Download the ISO

First, download the ISO from the Omni portal by clicking on the “Download Installation Media” button. Now, click on the “Options” dropdown menu and search for the “ISO” option. Notice there are two options: one for amd64 and another for arm64. Select the appropriate option for the machine you are registering. Now that you have selected the ISO option for the appropriate architecture, click the “Download” button.

Write the ISO to a USB Stick

First, plug the USB drive into your local machine. Now, find the device path for your USB drive and write the ISO to the USB drive.

• macOS
• Linux

diskutil list
...
/dev/disk2 (internal, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:                                                   *31.9 GB    disk2
...

dd if=<path to ISO> of=/dev/disk2 conv=fdatasync

$ lsblk
...
NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sdb      8:0    0 39.1G  0 disk
...

dd if=<path to ISO> of=/dev/sdb conv=fdatasync

Boot the Machine

Now that we have our bootable USB drive, plug it into the machine you are registering. Once the machine is booting you will notice logs from Talos Linux on the console stating that it is reachable over an IP address.

Conclusion

Navigate to the “Machines” menu in the sidebar. You should now see a machine listed.

You now have a bare metal machine registered with Omni and ready to provision.

2.2 - How to Register a Bare Metal Machine (PXE/iPXE)

This guide shows you how to register a bare metal machine with Omni by PXE/iPXE booting.

Copy the Required Kernel Parameters

Upon logging in you will be presented with the Omni dashboard. Click the “Copy Kernel Parameters” button and save the value for later.

• Matchbox

{
  "id": "default",
  "name": "default",
  "boot": {
    "kernel": "/assets/vmlinuz",
    "initrd": ["/assets/initramfs.xz"],
    "args": [
      "initrd=initramfs.xz",
      "init_on_alloc=1",
      "slab_nomerge",
      "pti=on",
      "console=tty0",
      "console=ttyS0",
      "printk.devkmsg=on",
      "talos.platform=metal",
      "siderolink.api=<your siderolink.api value>",
      "talos.events.sink=<your talos.events.sink value>",
      "talos.logging.kernel=<your talos.logging.kernel value>"
    ]
  }
}

{
  "id": "default",
  "name": "default",
  "profile": "default"
}

Once your machine is configured to PXE boot using your tool of choice, power the machine on.

Conclusion

Navigate to the “Machines” menu in the sidebar. You should now see a machine listed.

You now have a bare metal machine registered with Omni and ready to provision.

2.3 - How to Register a GCP Instance

This guide shows you how to register a GCP instance with Omni.

Dashboard

Upon logging in you will be presented with the Omni dashboard.

Download the Image

First, download the GCP image from the Omni portal by clicking on the “Download Installation Media” button. Now, click on the “Options” dropdown menu and search for the “GCP” option. Notice there are two options: one for amd64 and another for arm64. Select the appropriate option for the machine you are registering. Now that you have selected the GCP option for the appropriate architecture, click the “Download” button.

Upload the Image

• UI

Convert the Image

• UI

Create a GCP Instance

• UI

Conclusion

Navigate to the “Machines” menu in the sidebar. You should now see a machine listed.

You now have a GCP machine registered with Omni and ready to provision.

2.4 - How to Register an AWS EC2 Instance

This guide shows you how to register an AWS EC2 instance with Omni.

Set your AWS region

REGION="us-west-2"

Creating the subnet

First, we need to know what VPC to create the subnet on, so let’s describe the VPCs in the region where we want to create the Omni machines.

$ aws ec2 describe-vpcs --region $REGION
{
    "Vpcs": [
        {
            "CidrBlock": "172.31.0.0/16",
            "DhcpOptionsId": "dopt-0238fea7541672af0",
            "State": "available",
            "VpcId": "vpc-04ea926270c55d724",
            "OwnerId": "753518523373",
            "InstanceTenancy": "default",
            "CidrBlockAssociationSet": [
                {
                    "AssociationId": "vpc-cidr-assoc-0e518f7ac9d02907d",
                    "CidrBlock": "172.31.0.0/16",
                    "CidrBlockState": {
                        "State": "associated"
                    }
                }
            ],
            "IsDefault": true
        }
    ]
}

Note the VpcId (vpc-04ea926270c55d724).

Now, create a subnet on that VPC with a CIDR block that is within the CIDR block of the VPC. In the above example, as the VPC has a CIDR block of 172.31.0.0/16, we can use 172.31.128.0/20.

$ aws ec2 create-subnet \
    --vpc-id vpc-04ea926270c55d724 \
    --region us-west-2 \
    --cidr-block 172.31.128.0/20
{
    "Subnet": {
        "AvailabilityZone": "us-west-2c",
        "AvailabilityZoneId": "usw2-az3",
        "AvailableIpAddressCount": 4091,
        "CidrBlock": "172.31.192.0/20",
        "DefaultForAz": false,
        "MapPublicIpOnLaunch": false,
        "State": "available",
        "SubnetId": "subnet-04f4d6708a2c2fb0d",
        "VpcId": "vpc-04ea926270c55d724",
        "OwnerId": "753518523373",
        "AssignIpv6AddressOnCreation": false,
        "Ipv6CidrBlockAssociationSet": [],
        "SubnetArn": "arn:aws:ec2:us-west-2:753518523373:subnet/subnet-04f4d6708a2c2fb0d",
        "EnableDns64": false,
        "Ipv6Native": false,
        "PrivateDnsNameOptionsOnLaunch": {
            "HostnameType": "ip-name",
            "EnableResourceNameDnsARecord": false,
            "EnableResourceNameDnsAAAARecord": false
        }
    }
}

Note the SubnetID (subnet-04f4d6708a2c2fb0d).

Create the Security Group

$ aws ec2 create-security-group \
    --region $REGION \
    --group-name omni-aws-sg \
    --description "Security Group for Omni EC2 instances"
{
    "GroupId": "sg-0b2073b72a3ca4b03"
}

Note the GroupId (sg-0b2073b72a3ca4b03).

Allow all internal traffic within the same security group, so that Kubernetes applications can talk to each other on different machines:

aws ec2 authorize-security-group-ingress \
    --region $REGION \
    --group-name omni-aws-sg \
    --protocol all \
    --port 0 \
    --source-group omni-aws-sg

Creating the bootable AMI

To do so, log in to your Omni account, and, from the Omni overview page, select “Download Installation Media”. Select “AWS AMI (amd64)” or “AWS AMI (arm64)”, as appropriate for your desired EC2 instances. (Most are amd64.) Click “Download”, and the AMI will be downloaded to you local machine.

Extract the downloaded aws-amd64.tar.gz Then copy the disk.raw file to S3. We need to create a bucket, copy the image file to it, import it as a snapshot, then register an AMI image from it.

Create S3 bucket

REGION="us-west-2"
aws s3api create-bucket \
    --bucket <bucket name> \
    --create-bucket-configuration LocationConstraint=$REGION \
    --acl private

Copy image file to the bucket

aws s3 cp disk.raw s3://<bucket name>/omni-aws.raw

Import the image as a snapshot

$ aws ec2 import-snapshot \
    --region $REGION \
    --description "Omni AWS" \
    --disk-container "Format=raw,UserBucket={S3Bucket=<bucket name>,S3Key=omni-aws.raw}"
{
    "Description": "Omni AWS",
    "ImportTaskId": "import-snap-1234567890abcdef0",
    "SnapshotTaskDetail": {
        "Description": "Omni AWS",
        "DiskImageSize": "0.0",
        "Format": "RAW",
        "Progress": "3",
        "Status": "active",
        "StatusMessage": "pending"
        "UserBucket": {
            "S3Bucket": "<bucket name>",
            "S3Key": "omni-aws.raw"
        }
    }
}

Check the status of the import with:

$ aws ec2 describe-import-snapshot-tasks \
    --region $REGION \
    --import-task-ids
{
    "ImportSnapshotTasks": [
        {
            "Description": "Omni AWS",
            "ImportTaskId": "import-snap-1234567890abcdef0",
            "SnapshotTaskDetail": {
                "Description": "Omni AWS",
                "DiskImageSize": "705638400.0",
                "Format": "RAW",
                "Progress": "42",
                "Status": "active",
                "StatusMessage": "downloading/converting",
                "UserBucket": {
                    "S3Bucket": "<bucket name>",
                    "S3Key": "omni-aws.raw"
                }
            }
        }
    ]
}

Once the Status is completed note the SnapshotId (snap-0298efd6f5c8d5cff).

Register the Image

$ aws ec2 register-image \
    --region $REGION \
    --block-device-mappings "DeviceName=/dev/xvda,VirtualName=talos,Ebs={DeleteOnTermination=true,SnapshotId=$SNAPSHOT,VolumeSize=4,VolumeType=gp2}" \
    --root-device-name /dev/xvda \
    --virtualization-type hvm \
    --architecture x86_64 \
    --ena-support \
    --name omni-aws-ami
{
    "ImageId": "ami-07961b424e87e827f"
}

Note the ImageId (ami-07961b424e87e827f).

Create EC2 instances from the AMI

Now, using the AMI we created, along with the security group created above, provision EC2 instances:

 aws ec2 run-instances \
    --region  $REGION \
    --image-id ami-07961b424e87e827f \
    --count 1 \
    --instance-type t3.small   \
    --subnet-id subnet-0a7f5f87f62c301ea \
    --security-group-ids $SECURITY_GROUP   \
    --associate-public-ip-address \
    --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=omni-aws-ami}]" \
    --instance-market-options '{"MarketType":"spot"}'

2.5 - How to Register an Azure Instance

This guide shows you how to register an Azure instance with Omni.

Dashboard

Upon logging in you will be presented with the Omni dashboard.

Download the Image

Download the Azure image from the Omni portal by clicking on the “Download Installation Media” button. Click on the “Options” dropdown menu and search for the “Azure” option. Notice there are two options: one for amd64 and another for arm64. Select the appropriate architecture for the machine you are registering, then click the “Download” button.

Once downloaded to your local machine, untar with tar -xvf /path/to/image

Upload the Image

• UI
• CLI

# Storage account to use
export STORAGE_ACCOUNT="StorageAccountName"

# Storage container to upload to
export STORAGE_CONTAINER="StorageContainerName"

# Resource group name
export GROUP="ResourceGroupName"

# Location
export LOCATION="centralus"

# Get storage account connection string based on info above
export CONNECTION=$(az storage account show-connection-string \
                    -n $STORAGE_ACCOUNT \
                    -g $GROUP \
                    -o tsv)

az storage blob upload \
  --connection-string $CONNECTION \
  --container-name $STORAGE_CONTAINER \
  -f /path/to/extracted/disk.vhd \
  -n omni-azure.vhd

Convert the Image

• UI
• CLI

az image create \
  --name omni \
  --source https://$STORAGE_ACCOUNT.blob.core.windows.net/$STORAGE_CONTAINER/omni-azure.vhd \
  --os-type linux \
  -g $GROUP

Create an Azure Instance

• CLI

az vm create \
    --name azure-worker \
    --image omni \
    -g $GROUP \
    --admin-username talos \
    --generate-ssh-keys \
    --verbose \
    --os-disk-size-gb 20 

Conclusion

In the Omni UI, navigate to the “Machines” menu in the sidebar. You should now see the Azure machine that was created listed as an available machine, registered with Omni and ready to provision.

2.6 - How to Create a Service Account Kubeconfig

This guide shows you how to create a service account kubeconfig in Omni.

You need omnictl installed and configured to follow this guide. If you haven’t done so already, follow the omnictl guide.

You also need to have a cluster created in Omni to follow this guide.

Creating the Service Account Kubeconfig

To create a service account kubeconfig, run the following command:

omnictl kubeconfig --service-account -c <cluster> --user <user> <path to kubeconfig>

This command will create a service account token with the given username and obtain a kubeconfig file for the given cluster and username.

You can now use kubectl with the generated kubeconfig.

2.7 - How to Scale Down a Cluster

This guide shows you how to delete machines in a cluster with Omni.

Upon logging in, click the “Clusters” menu item on the left, then the name of the cluster you wish to delete nodes from. Click the “Nodes” menu item on the left. Now, select “Destroy” from the menu under the elipsis:

The cluster will now scale down.

2.8 - How to Scale Up a Cluster

This guide shows you how to add machines to a cluster with Omni. Upon logging in, click the “Cluster” menu item on the left, then the name of the cluster you wish to add nodes to. From the “Cluster Overview” tab, click the “Add Machines” button in the sidebar on the right.

From the list of available machines that is shown, identify the machine or machines you wish to add, and then click “ControlPlane” or “Worker”, to add the machine with that role. You may add multiple machines in one operation. Click “Add Machines” when all machines have been selected to be added.

The cluster will now scale up.

2.9 - How to Register a Hetzner Server

This guide shows you how to register a Hetzner server with Omni.

Dashboard

Upon logging in you will be presented with the Omni dashboard.

Download the Hetzner Image

First, download the Hetzner image from the Omni portal by clicking on the “Download Installation Media” button. Now, click on the “Options” dropdown menu and search for the “Hetzner” option. Notice there are two options: one for amd64 and another for arm64. Select the appropriate option for the machine you are registering. Now, click the “Download” button.

• Packer

packer {
  required_plugins {
    hcloud = {
      version = ">= 1.0.0"
      source  = "github.com/hashicorp/hcloud"
    }
  }
}

locals {
  image = "<path to downloaded installation media>"
}

source "hcloud" "talos" {
  rescue       = "linux64"
  image        = "debian-11"
  location     = "hel1"
  server_type  = "cx11"
  ssh_username = "root"

  snapshot_name = "Omni Image"
}

build {
  sources = ["source.hcloud.talos"]

  provisioner "file" {
    source = "${local.image}"
    destination = "/tmp/talos.raw.xz"
  }

  provisioner "shell" {
    inline = [
      "xz -d -c /tmp/talos.raw.xz | dd of=/dev/sda && sync",
    ]
  }
}

export HCLOUD_TOKEN=${TOKEN}
packer init .
packer build .

Create a Server

hcloud context create talos

hcloud server create --name omni-talos-1 \
    --image <image ID> \
    --type cx21 --location <location>

Conclusion

Navigate to the “Machines” menu in the sidebar. You should now see a machine listed.

You now have a Hetzner server registered with Omni and ready to provision.

2.10 - How to File an Issue

This guide shows you file an issue for Omni.

Click on the “Report an issue” button in the header:

Now, click on the “New issue” button:

Choose the issue type, fill in the details, and submit the issue.

2.11 - How to install talosctl

This guide shows you how to install talosctl.

Run the following:

curl -sL https://talos.dev/install | sh

You now have talosctl installed.

2.12 - How to Create a Cluster

This guide shows you how to create and a cluster from registered machines.

• UI
• CLI

First, click the “Clusters” section button in the sidebar. Next, click the “Create Cluster” button.

<figcaption class="card-body px-0 pt-2 pb-0">
	<p class="card-text">

Select the role for each machine you would like to create a cluster from. Now that each machine has a role, choose the install disk from the dropdown menu for each machine. Finally, click “Create Cluster”

<figcaption class="card-body px-0 pt-2 pb-0">
	<p class="card-text">

Create a file called cluster.yaml with the following content:

kind: Cluster
name: example
kubernetes:
  version: v1.26.0
talos:
  version: v1.3.2
---
kind: ControlPlane
machines:
  - <control plane machine UUID>
---
kind: Workers
machines:
  - <worker machine UUID>
---
kind: Machine
name: <control plane machine UUID>
install:
  disk: /dev/<disk>
---
kind: Machine
name: <worker machine UUID>
install:
  disk: /dev/<disk>

Note

Be sure to update the UUIDs and install disks with the UUIDs and disks of the machines in your account.

Now, validate the document:

omnictl cluster template validate -f cluster.yaml

Create the cluster:

omnictl cluster template sync -f cluster.yaml --verbose

Finally, wait for the cluster to be up:

omnictl cluster template status -f cluster.yaml

2.13 - How to Create a Patch For Cluster Control Planes

This guide shows you how to create a patch for the control plane machine set of a cluster.

Upon logging in, click the “Clusters” menu item on the left. Now, select “Config Patches” from the menu under the elipsis:

Next, click “Create Patch”:

Pick the “Control Planes” option from the “Patch Target” dropdown:

Type in the desired config patch:

Click “Save” to create the config patch:

2.14 - How to Create a Patch For Cluster Machines

This guide shows you how to create a patch for a machine in a cluster.

Upon logging in, click the “Clusters” menu item on the left. Now, select “Config Patches” from the menu under the elipsis:

Next, click “Create Patch”:

Pick the specific machine from the “Patch Target” dropdown:

Type in the desired config patch:

Click “Save” to create the config patch:

2.15 - How to Create a Patch For Cluster Workers

This guide shows you how to create a patch for the worker machine set of a cluster.

Upon logging in, click the “Clusters” menu item on the left. Now, select “Config Patches” from the menu under the elipsis:

Next, click “Create Patch”:

Pick the “Workers” option from the “Patch Target” dropdown:

Type in the desired config patch:

Click “Save” to create the config patch:

2.16 - How to Create a Hybrid Cluster

This guide shows you how to create and configure a cluster consisting of machines that are any combination of bare metal, cloud virtual machines, on-premise virtual machines, or SBCs, using KubeSpan, which enables Kubernetes to communicate securely with machines in the cluster on different networks.

Refer to the general guide on creating a cluster to get started. To create a hybid cluster apply the following cluster patch by clicking on “Config Patches” and navigating the the “Cluster” tab:

machine:
  network:
    kubespan:
      enabled: true

2.17 - How to Use Kubectl With Omni

This guide shows you how to use kubectl with an Omni-managed cluster.

Navigate to the clusters page by clicking on the “Clusters” button in the sidebar.

Click the three dots in the cluster’s item to access the options menu.

Click “Download kubeconfig”.

Alternatively you can click on the cluster and download the kubeconfig from the cluster dashboard.

Install the oidc-login plugin per the official documentation: https://github.com/int128/kubelogin.

2.18 - How to Install and Configure Omnictl

This guide shows you how to install and configure omnictl.

Download omnictl and omniconfig from the Omni dashboard.

Add the downloaded omniconfig.yaml to the default location to use it with omnictl:

omnictl config merge ./omniconfig.yaml

List the contexts to verify that the omniconfig was added:

$ omnictl config contexts
CURRENT   NAME         URL
          ...
          example      https://example.omni.siderolabs.io/
          ...

Run omnictl for the first time to perform initial authentication using a web browser:

omnictl get clusters

If the browser window does not open automatically, it can be opened manually by copying and pasting the URL into a web browser:

BROWSER=echo omnictl get clusters

2.19 - How to Deploy Omni On-prem

This guide shows you how to deploy Omni on-prem.

First, you will need 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://localhost:8080/
• Allowed web origins: https://localhost:8080/
• Allowed logout URLs: https://localhost:8080/

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

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

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

Generate a TLS certificate:

A valid TLS certificate is required by Omni. This is an excercise left up to the user.

Generate a UUID:

export OMNI_ACCOUNT_UUID=$(uuidgen)

Ensure that docker is installed on the same machine as omni.

Finally, run omni:

docker run \
  --net=host \
  --cap-add=NET_ADMIN \
  --sysctl net.ipv6.conf.all.disable_ipv6=0 \
  -v $PWD/etcd:_out/etcd \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v <path to TLS certificate>:/tls.crt \
  -v <path to TLS key>/tls.key:/tls.key \
  -v $PWD/omni.asc:/omni.asc \
  ghcr.io/siderolabs/omni:<tag> \
    --account-id=${OMNI_ACCOUNT_UUID} \
    --name=how-to-guide \
    --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:8080 \
    --siderolink-api-bind-addr=0.0.0.0:8090 \
    --k8s-proxy-bind-addr=0.0.0.0:8100 \
    --advertised-api-url=https://<ip address of the host running Omni>:8080/ \
    --siderolink-api-advertised-url=https://<ip address of the host running Omni>:8090/ \
    --siderolink-wireguard-advertised-addr=<ip address of the host running Omni>:50180 \
    --advertised-kubernetes-proxy-url=https://<ip address of the host running Omni>:8100/ \
    --auth-auth0-enabled=true \
    --auth-auth0-domain=<Auth0 domain> \
    --auth-auth0-client-id=<Auth0 client ID> \
    --initial-users=<email address>

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

2.20 - How to Back Up On-prem Omni Database

This guide shows you how to back up the database of an on-prem Omni instance.

Omni uses etcd as its database.

There are 2 operating modes for etcd: embedded and external.

When Omni is run with --etcd-embedded=true flag, it will configure the embedded etcd server to listen the addresses specified by the --etcd-endpoints flag (http://localhost:2379 by default).

In the same host where Omni is running (in Docker, --network=host needs to be used), you can use the etcdctl command to back up the database:

etcdctl --endpoints http://localhost:2379 snapshot save snapshot.db

The command will save the snapshot of the database to the snapshot.db file.

It is recommended to periodically (e.g. with a cron job) take snapshots and store them in a safe location, like an S3 bucket.

2.21 - How to Configure Keycloak for Omni

1. Log in to Keycloak.

2. Create a realm.

• In the upper left corner of the page, select the dropdown where it says master

• Fill in the realm name and select create

3. Find the realm metadata.

• In the realm settings, there is a link to the metadata needed for SAML under Endpoints.
  • Copy the link or save the data to a file. It will be needed for the installation of Omni.

4. Create a client

• Select the Clients tab on the left

• Fill in the General Settings as shown in the example below. Replace the hostname in the example with your own Omni hostname or IP.
  • Client type
  • Client ID
  • Name

• Fill in the Login settings as shown in the example below. Replace the hostname in the example with your own Omni hostname or IP.
  • Root URL
  • Valid redirect URIs
  • Master SAML PRocessing URL

• Modify the Signature and Encryption settings.
  • Sign documents: off
  • Sign assertions: on

• Set the Client signature required value to off.

• Modify Client Scopes

• Select Add predefined mapper.

• The following mappers need to be added because they will be used by Omni will use these attributes for assigning permissions.
  • X500 email
  • X500 givenName
  • X500 surname

• Add a new user (optional)
  • If Keycloak is being used as an Identity Provider, users can be created here.

• Enter the user information and set the Email verified to Yes

• Set a password for the user.

3 - Reference

3.1 - Cluster Templates

Cluster templates are parsed, validated, and converted to Omni resources, which are then created or updated via the Omni API. Omni guarantees backward compatibility for cluster templates, so the same template can be used with any future version of Omni.

All referenced files in machine configuration patches should be stored relative to the current working directory.

Structure

The Cluster Template is a YAML file consisting of multiple documents, with each document having a kind field that specifies the type of the document. Some documents might also have a name field that specifies the name (ID) of the document.

kind: Cluster
name: example
labels:
  my-label: my-value
kubernetes:
  version: v1.26.0
talos:
  version: v1.3.2
patches:
  - name: kubespan-enabled
    inline:
      machine:
        network:
          kubespan:
            enabled: true
---
kind: ControlPlane
machines:
  - 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
  - 4bd92fba-998d-4ef3-ab43-638b806dd3fe
  - 8fdb574a-a252-4d7d-94f0-5cdea73e140a
---
kind: Workers
machines:
  - b885f565-b64f-4c7a-a1ac-d2c8c2781373
---
kind: Machine
name: 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
install:
  disk: /dev/vda
---
kind: Machine
name: 4bd92fba-998d-4ef3-ab43-638b806dd3fe
install:
  disk: /dev/vda
---
kind: Machine
name: 8fdb574a-a252-4d7d-94f0-5cdea73e140a
install:
  disk: /dev/vda
---
kind: Machine
name: b885f565-b64f-4c7a-a1ac-d2c8c2781373
install:
  disk: /dev/vda

Each cluster template should have exactly one document of kind: Cluster, kind: ControlPlane, and kind: Workers.

Every Machine document must be referenced by either a ControlPlane or Workers document.

Document Types

Cluster

The Cluster document specifies the cluster configuration, labels, defines the cluster name and base component versions.

kind: Cluster
name: example
labels:
  my-label: my-value
kubernetes:
  version: v1.26.1
talos:
  version: v1.3.3
patches:
  - file: patches/example-patch.yaml

ControlPlane

The ControlPlane document specifies the control plane configuration, defines the number of control plane nodes, and the list of machines to use.

As control plane machines run an etcd cluster, it is recommended to use a number of machines for the control plane that can achieve a stable quorum (i.e. 1, 3, 5, etc.). Changing the set of machines in the control plane will trigger a rolling scale-up/scale-down of the control plane.

The control plane should have at least a single machine, but it is recommended to use at least 3 machines for the control plane for high-availability.

kind: ControlPlane
machines:
  - 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
  - 4bd92fba-998d-4ef3-ab43-638b806dd3fe
  - 8fdb574a-a252-4d7d-94f0-5cdea73e140a
patches:
  - file: patches/example-controlplane-patch.yaml

Workers

The Workers document specifies the worker configuration, defines the number of worker nodes, and the list of machines to use.

kind: Workers
machines:
  - b885f565-b64f-4c7a-a1ac-d2c8c2781373
patches:
  - file: patches/example-workers-patch.yaml

Machine

The Machine document specifies the install disk and machine-specific configuration patches. They are optional, but every Machine document must be be referenced by either a ControlPlane or Workers document.

kind: Machine
name: 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
install:
  disk: /dev/vda
patches:
  - file: patches/example-machine-patch.yaml

Common Fields

patches

The patches field is a list of machine configuration patches to apply to a cluster, a machine set, or an individual machine. Config patches modify the configuration before it is applied to each machine in the cluster. Changing configuration patches modifies the machine configuration which gets automatically applied to the machine.

patches:
  - file: patches/example-patch.yaml
  - name: kubespan-enabled
    inline:
      machine:
        network:
          kubespan:
            enabled: true

A configuration patch may be either inline or file based. Inline patches are useful for small changes, file-based patches are useful for more complex changes, or changes shared across multiple clusters.

3.2 - omnictl CLI

omnictl apply

Create or update resource using YAML file as an input

omnictl apply [flags]

Options

  -d, --dry-run       Dry run, implies verbose
  -f, --file string   Resource file to load and apply
  -h, --help          help for apply
  -v, --verbose       Verbose output

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl cluster delete

Delete all cluster resources.

Synopsis

Delete all resources related to the cluster. The command waits for the cluster to be fully destroyed.

omnictl cluster delete cluster-name [flags]

Options

  -d, --dry-run   dry run
  -h, --help      help for delete
  -v, --verbose   verbose output (show diff for each resource)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster - Cluster-related subcommands.

omnictl cluster status

Show cluster status, wait for the cluster to be ready.

Synopsis

Shows current cluster status, if the terminal supports it, watch the status as it updates. The command waits for the cluster to be ready by default.

omnictl cluster status cluster-name [flags]

Options

  -h, --help            help for status
  -q, --quiet           suppress output
  -w, --wait duration   wait timeout, if zero, report current status and exit (default 5m0s)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster - Cluster-related subcommands.

omnictl cluster template delete

Delete all cluster template resources from Omni.

Synopsis

Delete all resources related to the cluster template. This command requires API access.

omnictl cluster template delete [flags]

Options

  -d, --dry-run   dry run
  -h, --help      help for delete
  -v, --verbose   verbose output (show diff for each resource)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -f, --file string         path to the cluster template file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster template - Cluster template management subcommands.

omnictl cluster template diff

Show diff in resources if the template is synced.

Synopsis

Query existing resources for the cluster and compare them with the resources generated from the template. This command requires API access.

omnictl cluster template diff [flags]

Options

  -h, --help   help for diff

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -f, --file string         path to the cluster template file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster template - Cluster template management subcommands.

omnictl cluster template render

Render a cluster template to a set of resources.

Synopsis

Validate template contents, convert to resources and output resources to stdout as YAML. This command is offline (doesn’t access API).

omnictl cluster template render [flags]

Options

  -h, --help   help for render

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -f, --file string         path to the cluster template file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster template - Cluster template management subcommands.

omnictl cluster template status

Show template cluster status, wait for the cluster to be ready.

Synopsis

Shows current cluster status, if the terminal supports it, watch the status as it updates. The command waits for the cluster to be ready by default.

omnictl cluster template status [flags]

Options

  -h, --help            help for status
  -q, --quiet           suppress output
  -w, --wait duration   wait timeout, if zero, report current status and exit (default 5m0s)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -f, --file string         path to the cluster template file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster template - Cluster template management subcommands.

omnictl cluster template sync

Apply template to the Omni.

Synopsis

Query existing resources for the cluster and compare them with the resources generated from the template, create/update/delete resources as needed. This command requires API access.

omnictl cluster template sync [flags]

Options

  -d, --dry-run   dry run
  -h, --help      help for sync
  -v, --verbose   verbose output (show diff for each resource)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -f, --file string         path to the cluster template file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster template - Cluster template management subcommands.

omnictl cluster template validate

Validate a cluster template.

Synopsis

Validate that template contains valid structures, and there are no other warnings. This command is offline (doesn’t access API).

omnictl cluster template validate [flags]

Options

  -h, --help   help for validate

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -f, --file string         path to the cluster template file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster template - Cluster template management subcommands.

omnictl cluster template

Cluster template management subcommands.

Synopsis

Commands to render, validate, manage cluster templates.

Options

  -f, --file string   path to the cluster template file.
  -h, --help          help for template

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl cluster - Cluster-related subcommands.
• omnictl cluster template delete - Delete all cluster template resources from Omni.
• omnictl cluster template diff - Show diff in resources if the template is synced.
• omnictl cluster template render - Render a cluster template to a set of resources.
• omnictl cluster template status - Show template cluster status, wait for the cluster to be ready.
• omnictl cluster template sync - Apply template to the Omni.
• omnictl cluster template validate - Validate a cluster template.

omnictl cluster

Cluster-related subcommands.

Synopsis

Commands to destroy clusters and manage cluster templates.

Options

  -h, --help   help for cluster

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.
• omnictl cluster delete - Delete all cluster resources.
• omnictl cluster status - Show cluster status, wait for the cluster to be ready.
• omnictl cluster template - Cluster template management subcommands.

omnictl completion bash

Generate the autocompletion script for bash

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(omnictl completion bash)

To load completions for every new session, execute once:

Linux:

omnictl completion bash > /etc/bash_completion.d/omnictl

macOS:

omnictl completion bash > $(brew --prefix)/etc/bash_completion.d/omnictl

You will need to start a new shell for this setup to take effect.

omnictl completion bash

Options

  -h, --help              help for bash
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl completion - Generate the autocompletion script for the specified shell

omnictl completion fish

Generate the autocompletion script for fish

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

omnictl completion fish | source

To load completions for every new session, execute once:

omnictl completion fish > ~/.config/fish/completions/omnictl.fish

You will need to start a new shell for this setup to take effect.

omnictl completion fish [flags]

Options

  -h, --help              help for fish
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl completion - Generate the autocompletion script for the specified shell

omnictl completion powershell

Generate the autocompletion script for powershell

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

omnictl completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

omnictl completion powershell [flags]

Options

  -h, --help              help for powershell
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl completion - Generate the autocompletion script for the specified shell

omnictl completion zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(omnictl completion zsh); compdef _omnictl omnictl

To load completions for every new session, execute once:

Linux:

omnictl completion zsh > "${fpath[1]}/_omnictl"

macOS:

omnictl completion zsh > $(brew --prefix)/share/zsh/site-functions/_omnictl

You will need to start a new shell for this setup to take effect.

omnictl completion zsh [flags]

Options

  -h, --help              help for zsh
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl completion - Generate the autocompletion script for the specified shell

omnictl completion

Generate the autocompletion script for the specified shell

Synopsis

Generate the autocompletion script for omnictl for the specified shell. See each sub-command’s help for details on how to use the generated script.

Options

  -h, --help   help for completion

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.
• omnictl completion bash - Generate the autocompletion script for bash
• omnictl completion fish - Generate the autocompletion script for fish
• omnictl completion powershell - Generate the autocompletion script for powershell
• omnictl completion zsh - Generate the autocompletion script for zsh

omnictl config add

Add a new context

omnictl config add <context> [flags]

Options

      --basic-auth string   basic auth credentials
  -h, --help                help for add
      --identity string     identity to use for authentication
      --url string          URL of the server (default "grpc://127.0.0.1:8080")

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config basic-auth

Set the basic auth credentials

omnictl config basic-auth <username> <password> [flags]

Options

  -h, --help   help for basic-auth

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config context

Set the current context

omnictl config context <context> [flags]

Options

  -h, --help   help for context

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config contexts

List defined contexts

omnictl config contexts [flags]

Options

  -h, --help   help for contexts

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config identity

Set the auth identity for the current context

omnictl config identity <identity> [flags]

Options

  -h, --help   help for identity

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config info

Show information about the current context

omnictl config info [flags]

Options

  -h, --help   help for info

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config merge

Merge additional contexts from another client configuration file

Synopsis

Contexts with the same name are renamed while merging configs.

omnictl config merge <from> [flags]

Options

  -h, --help   help for merge

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config new

Generate a new client configuration file

omnictl config new [<path>] [flags]

Options

      --basic-auth string   basic auth credentials
  -h, --help                help for new
      --identity string     identity to use for authentication
      --url string          URL of the server (default "grpc://127.0.0.1:8080")

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config url

Set the URL for the current context

omnictl config url <url> [flags]

Options

  -h, --help   help for url

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl config - Manage the client configuration file (omniconfig)

omnictl config

Manage the client configuration file (omniconfig)

Options

  -h, --help   help for config

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.
• omnictl config add - Add a new context
• omnictl config basic-auth - Set the basic auth credentials
• omnictl config context - Set the current context
• omnictl config contexts - List defined contexts
• omnictl config identity - Set the auth identity for the current context
• omnictl config info - Show information about the current context
• omnictl config merge - Merge additional contexts from another client configuration file
• omnictl config new - Generate a new client configuration file
• omnictl config url - Set the URL for the current context

omnictl delete

Delete a specific resource by ID or all resources of the type.

Synopsis

Similar to ‘kubectl delete’, ‘omnictl delete’ initiates resource deletion and waits for the operation to complete.

omnictl delete <type> [<id>] [flags]

Options

      --all                Delete all resources of the type.
  -h, --help               help for delete
  -n, --namespace string   The resource namespace. (default "default")

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl download

Download installer media

Synopsis

This command downloads installer media from the server

It accepts one argument, which is the name of the image to download. Name can be one of the following:

 * iso - downloads the latest ISO image
 * AWS AMI (amd64), Vultr (arm64), Raspberry Pi 4 Model B - full image name
 * oracle, aws, vmware - platform name
 * rockpi_4, rock64 - board name

To get the full list of available images, look at the output of the following command: omnictl get installationmedia -o yaml

The download command tries to match the passed string in this order:

* name
* platform
* board

By default it will download amd64 image if there are multiple images available for the same name.

For example, to download the latest ISO image for arm64, run:

omnictl download iso --arch amd64

To download the latest Vultr image, run:

omnictl download "vultr"

To download the latest Radxa ROCK PI 4 image, run:

omnictl download "rockpi_4"

omnictl download <image name> [flags]

Options

      --arch string     Image architecture to download (amd64, arm64) (default "amd64")
  -h, --help            help for download
      --output string   Output file or directory, defaults to current working directory (default ".")

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl get

Get a specific resource or list of resources.

Synopsis

Similar to ‘kubectl get’, ‘omnictl get’ returns a set of resources from the OS. To get a list of all available resource definitions, issue ‘omnictl get rd’

omnictl get <type> [<id>] [flags]

Options

  -h, --help                     help for get
      --id-match-regexp string   Match resource ID against a regular expression.
  -n, --namespace string         The resource namespace. (default "default")
  -o, --output string            Output format (json, table, yaml, jsonpath). (default "table")
  -l, --selector string          Selector (label query) to filter on, supports '=' and '==' (e.g. -l key1=value1,key2=value2)
  -w, --watch                    Watch the resource state.

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl kubeconfig

Download the admin kubeconfig of a cluster

Synopsis

Download the admin kubeconfig of a cluster. If merge flag is defined, config will be merged with ~/.kube/config or [local-path] if specified. Otherwise kubeconfig will be written to PWD or [local-path] if specified.

omnictl kubeconfig [local-path] [flags]

Options

  -c, --cluster string              cluster to use
  -f, --force                       force overwrite of kubeconfig if already present, force overwrite on kubeconfig merge
      --force-context-name string   force context name for kubeconfig merge
      --groups strings              group to be used in the service account token (groups). only used when --service-account is set to true (default [system:masters])
  -h, --help                        help for kubeconfig
  -m, --merge                       merge with existing kubeconfig (default true)
      --service-account             create a service account type kubeconfig instead of a OIDC-authenticated user type
      --ttl duration                ttl for the service account token. only used when --service-account is set to true (default 8760h0m0s)
      --user string                 user to be used in the service account token (sub). required when --service-account is set to true

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl machine-logs

Get logs for a machine

Synopsis

Get logs for a provided machine id

omnictl machine-logs machineID [flags]

Options

  -f, --follow              specify if the logs should be streamed
  -h, --help                help for machine-logs
      --log-format string   log format (raw, omni, dmesg) to display (default is to display in raw format) (default "raw")
      --tail int32          lines of log file to display (default is to show from the beginning) (default -1)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl serviceaccount create

Create a service account

omnictl serviceaccount create <name> [flags]

Options

  -h, --help              help for create
  -s, --scopes strings    scopes of the service account. only used when --use-user-scopes=false
  -t, --ttl duration      TTL for the service account key (default 8760h0m0s)
  -u, --use-user-scopes   use the scopes of the creating user. if true, --scopes is ignored (default true)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl serviceaccount - Manage service accounts

omnictl serviceaccount destroy

Destroy a service account

omnictl serviceaccount destroy <name> [flags]

Options

  -h, --help   help for destroy

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl serviceaccount - Manage service accounts

omnictl serviceaccount list

List service accounts

omnictl serviceaccount list [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl serviceaccount - Manage service accounts

omnictl serviceaccount renew

Renew a service account by registering a new public key to it

omnictl serviceaccount renew <name> [flags]

Options

  -h, --help           help for renew
  -t, --ttl duration   TTL for the service account key (default 8760h0m0s)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl serviceaccount - Manage service accounts

omnictl serviceaccount

Manage service accounts

Options

  -h, --help   help for serviceaccount

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.
• omnictl serviceaccount create - Create a service account
• omnictl serviceaccount destroy - Destroy a service account
• omnictl serviceaccount list - List service accounts
• omnictl serviceaccount renew - Renew a service account by registering a new public key to it

omnictl talosconfig

Download the admin talosconfig of a cluster

Synopsis

Download the admin talosconfig of a cluster. If merge flag is defined, config will be merged with ~/.talos/config or [local-path] if specified. Otherwise talosconfig will be written to PWD or [local-path] if specified.

omnictl talosconfig [local-path] [flags]

Options

  -c, --cluster string   cluster to use
  -f, --force            force overwrite of talosconfig if already present
  -h, --help             help for talosconfig
  -m, --merge            merge with existing talosconfig (default true)

Options inherited from parent commands

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl - A CLI for accessing Omni API.

omnictl

A CLI for accessing Omni API.

Options

      --context string      The context to be used. Defaults to the selected context in the omniconfig file.
  -h, --help                help for omnictl
      --omniconfig string   The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

SEE ALSO

• omnictl apply - Create or update resource using YAML file as an input
• omnictl cluster - Cluster-related subcommands.
• omnictl completion - Generate the autocompletion script for the specified shell
• omnictl config - Manage the client configuration file (omniconfig)
• omnictl delete - Delete a specific resource by ID or all resources of the type.
• omnictl download - Download installer media
• omnictl get - Get a specific resource or list of resources.
• omnictl kubeconfig - Download the admin kubeconfig of a cluster
• omnictl machine-logs - Get logs for a machine
• omnictl serviceaccount - Manage service accounts
• omnictl talosconfig - Download the admin talosconfig of a cluster

4 - Explanation

4.1 - Machine Registration

Machine registration is built on top of the extremely fast WireGuard® technology built in to Linux. A technology dubbed SideroLink builds upon WireGuard in order to provide a fully automated way of setting up and maintaining a WireGuard tunnel between Omni and each registered machine. Once the secure tunnel is established between a machine it is possible to manage a machine from nearly anywhere in the world.

The SideroLink network is an overlay network used within the data and management planes within Omni. The sole requirements are that your machine has egress to port 443 and the WireGuard port assigned to your account.