Set Initial Machine Labels Using Omnictl or Image Factory
A guide on how to set initial labels on the machines connecting to Omni.
Last updated
A guide on how to set initial labels on the machines connecting to Omni.
Last updated
This guide demonstrates how to set initial machine labels when generating an boot media / URL using the omnictl CLI tool or using directly.
Both methods allow you to programmatically label your machines, which can be useful for various automation scenarios, such as integrating with your CI pipeline.
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).
omnictlWhen 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 will boot from that media or the PXE boot URL.
Here's the basic syntax for adding initial labels:
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:
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:
The schematic will also get a unique ID, such as d2f4229b6157ba7e1dba8c3b4de42263e4baa35111e960b6a18841332d0f2035.
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 it:
Either by 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 would boot.
After getting the Kernel arguments, split them by white spaces, and put them into your request body. Your CURL command should look like the following:
This command will produce output similar to:
Then you can use this ID in your PXE boot URL or download an installation media, for example:
The version of the Image Factory UI built into Omni does support specifying initial machine 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):
or
These commands will display information about the labels on the machine.
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.