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
  • Using omnictl
  • Using Image Factory Directly
  • Verifying Labels
Edit on GitHub
Export as PDF
  1. How-to guides

Set Initial Machine Labels Using Omnictl or Image Factory

Setting initial labels on the machines connecting to Omni.

PreviousAudit logsNextExplanation

Last updated 17 days ago

Machine labels can be useful for organizing and selecting machines in your Omni environment. For example, you might use them to distinguish between different environments (production, staging, development) or geographical locations (regions, zones). This helps various automation scenarios, such as integrating with your CI pipeline.

Choose label keys and values that are meaningful for your infrastructure organization.

The simplest way to set machine labels is by using the "Download Installation Media" form from the homepage of Omni, which allows you set machine labels in the downloaded media (or the generated PXE endpoint.)

Both methods allow you to label your machines programmatically.

Using omnictl

When generating Talos installation media or a PXE boot URL using omnictl, you can set initial machine labels using the --initial-labels flag. This allows you to assign key-value pairs as labels to the machines that boot from that media or the PXE boot URL.

Here's the basic syntax for adding initial labels:

omnictl download <image-name> \
  --initial-labels <key1>=<value1>,<key2>=<value2> \
  [--pxe]

Let's say you want to download an amd64 ISO image and set two labels: environment=production and region=us-west. Here's how you would do that:

omnictl download iso --arch amd64 \
  --initial-labels environment=production,region=us-west

Running this command will prepare a schematic under the hood and submit it in a request to the Image Factory. The generated schematic will look like the following:

customization:
  extraKernelArgs:
    - siderolink.api=grpc://YOUR_INSTANCE.siderolink.omni.siderolabs.io?grpc_tunnel=true&jointoken=YOUR_JOIN_TOKEN
    - talos.events.sink=[fdae:41e4:649b:9303::1]:8090
    - talos.logging.kernel=tcp://[fdae:41e4:649b:9303::1]:8092
  meta:
    - key: 12
      value: |
        machineLabels:
            environment: production
            region: us-west

The schematic will also get a unique ID, such as d2f4229b6157ba7e1dba8c3b4de42263e4baa35111e960b6a18841332d0f2035.

These initial labels work not only for ISOs but for most installation media and for PXE boot URL. For example, to get a PXE boot URL for a Raspberry Pi board, you can run

omnictl download rpi_generic --initial-labels environment=production,region=us-west --pxe.

This command will print the PXE boot URL and exit.

Using Image Factory Directly

Instead of using your Omni instance to generate labeled boot media or PXE URLs, you can use the image factory directly.

To do this, you need to craft an HTTP POST request with the schematic YAML in its body.

First, you need to find the Kernel arguments for your Omni instance.

You can do this by either:

  • clicking "Copy Kernel Parameters" on your Omni overview page, which will copy them to your clipboard

  • or by running omnictl get connectionparams -oyaml , which will print them under .spec.args field.

Note that this is a one-time operation - these kernel arguments will stay the same for all the machines you boot from the generated schematic ID.

After retreiving the Kernel arguments, split them by white spaces, and put them into your request body. Your CURL command should look like the following:

curl -X POST https://factory.talos.dev/schematics \
  -H "Content-Type: application/yaml" \
  -d '
customization:
  extraKernelArgs:
    - siderolink.api=grpc://YOUR_INSTANCE.siderolink.omni.siderolabs.io?grpc_tunnel=true&jointoken=YOUR_JOIN_TOKEN
    - talos.events.sink=[fdae:41e4:649b:9303::1]:8090
    - talos.logging.kernel=tcp://[fdae:41e4:649b:9303::1]:8092
  meta:
    - key: 12
      value: |
        machineLabels:
            environment: production
            region: us-west
'

This command will produce output similar to:

{"id":"d2f4229b6157ba7e1dba8c3b4de42263e4baa35111e960b6a18841332d0f2035"}

Note that the printed schematic ID is the same as the one we got when we used omnictl.

Then you can use this ID in your PXE boot URL or download an installation media, for example:

curl -O https://factory.talos.dev/image/d2f4229b6157ba7e1dba8c3b4de42263e4baa35111e960b6a18841332d0f2035/v1.7.6/metal-amd64.iso

The version of the Image Factory UI built into Omni does support specifying initial machine labels.

Verifying Labels

After a machine boots from the labeled media/PXE URL and registers with Omni, you can verify the labels using the Omni web interface or the omnictl CLI tool.

To check labels using omnictl, you can use either of these commands (replace <machine-id> with the actual machine ID):

omnictl get machinelabels -oyaml <machine-id>

or

omnictl get machinestatus -oyaml <machine-id>

These commands will display information about the labels on the machine.

This guide demonstrates how to set initial machine labels when generating boot media / URL using the omnictl CLI tool or using directly.

Here, you can see that the custom image contains the extra Kernel arguments for Talos to connect to your Omni instance on boot using . It also contains the machine labels you have specified in a nested yaml in the meta section with key 12. Here, the key 12 is a Talos META key reserved for Omni for the initial machine labels.

For more options, see the reference.

Although Image Factory has a , it is currently not possible to specify META values on the UI. Therefore, the initial machine labels cannot be specified on the UI at the moment.

Image Factory
Siderolink
Image Factory
web UI