> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Initial Machine Labels

> Configure machine labels at boot time for automated grouping and selection in Omni.

export const release = 'v1.13.2';

Machine labels help you organize and manage machines in your Omni environment more effectively.

For example, you can use labels to group machines by environment (production, staging, or development) or by location (regions and zones). This makes it easier to automate workflows such as CI/CD pipelines and targeted deployments.

This guide shows how to set machine labels at boot time when generating installation media or PXE URLs. You can add labels using one of the following methods:

* Through the Omni UI
* Using the `omnictl` CLI
* Using Image Factory

## Set machine labels using the Omni UI

To set machine labels using the Omni UI:

1. Log in to your Omni dashboard.

2. Click the **Download Installation Media** button to open the **Create New Media** wizard.

3. On each page of the **Create New Media** wizard, select the appropriate options for your setup, then click **Next** to continue.

   The **Create New Media** wizard is identical to the [Image Factory](https://factory.talos.dev/) and it is split across multiple pages. Each page presents a different set of configuration options, such as architecture, hardware type, and Talos Linux version, that you can use to customize your Talos Omni image.

4. In the **Machine User Labels** section add the labels you want your machines to have and click **Next** to continue customizing your Talos Omni image.

<img src="https://mintcdn.com/siderolabs-fe86397c/S48yOnJoHHyY3CUo/omni/omni-cluster-setup/images/how-to-set-initial-machine-labels-machine-user-labels.png?fit=max&auto=format&n=S48yOnJoHHyY3CUo&q=85&s=b875e19596112137cc7e3a0917db8eb6" alt="Machine User Labels" width="3024" height="1252" data-path="omni/omni-cluster-setup/images/how-to-set-initial-machine-labels-machine-user-labels.png" />

5. Select the appropriate boot option for your machine on the **Schematic Ready** page to download the Talos Omni image.

6. Boot your machines using the downloaded image to have your machines labelled.

## Set machine user labels using `omnictl`

When generating Talos installation media or a PXE boot URL with `omnictl`, you can define initial machine labels using the `--initial-labels` flag. This lets you assign key-value pairs to any machine that boots from that media.

Here is the syntax for adding machine user labels using `omnictl`:

```bash theme={null}
omnictl download <image-name> \
  --initial-labels <key1>=<value1>,<key2>=<value2> \
  [--pxe]
```

For example, to download an amd64 ISO image with two labels (`environment=production` and `region=us-west`):

```bash theme={null}
omnictl download iso --arch amd64 \
  --initial-labels environment=production,region=us-west
```

Behind the scenes, this command generates a schematic and submits it to Image Factory. The schematic includes both the required kernel arguments for connecting to Omni and the labels you specified:

```yaml theme={null}
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
```

Each generated schematic is assigned a unique ID, which can later be used to download installation media or construct PXE URLs.

The schematic includes the extra kernel arguments Talos needs to connect to your Omni instance on boot via SideroLink, as well as your machine labels stored in the `meta` section under key `12` — a Talos META key reserved by Omni for initial machine labels.

<Info>
  Initial labels work across most installation methods, including ISOs and PXE boot URLs.

  **For example:**

  ```bash theme={null}
  omnictl download iso --initial-labels environment=production,region=us-west --pxe
  ```

  This command outputs a PXE boot URL and exits.
</Info>

## Set machine user labels using Image Factory

Instead of using `omnictl`, you can generate labeled boot media or PXE URLs by sending requests directly to the Image Factory API. This is useful when you need more control over schematic generation or want to integrate with your own tooling.

### Step 1: Get your Omni kernel arguments

You need the kernel arguments for your Omni instance.

Retrieve them using **either** one of these methods:

1. Click **Copy Kernel Parameters** on your Omni overview page
2. Run `omnictl get connectionparams -oyaml` and read the values under `.spec.args`

These kernel arguments are the same for all machines you boot from a given schematic, so this is a one-time lookup.

### Step 2: Submit a schematic to Image Factory

Split the kernel arguments by whitespace and include them in a `curl` POST request to the Image Factory:

```bash theme={null}
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
'
```

The response will contain a schematic ID:

```json theme={null}
{"id":"d2f4229b6157ba7e1dba8c3b4de42263e4baa35111e960b6a18841332d0f2035"}
```

<Info>
  This schematic ID will be identical to the one generated when using `omnictl` with the same labels.
</Info>

### Step 3: Download the installation media

Use the schematic ID to download your installation media:

<CodeBlock>
  {`
    curl -O https://factory.talos.dev/image/d2f4229b6157ba7e1dba8c3b4de42263e4baa35111e960b6a18841332d0f2035/${release}/metal-amd64.iso
    `}
</CodeBlock>

For additional options, see the [Image Factory reference](https://github.com/siderolabs/image-factory/blob/main/README.md).

<Warning>
  The standalone [Image Factory web UI](https://factory.talos.dev) does not currently support specifying META values, so initial machine labels cannot be set there.

  However, the Image Factory UI built into Omni **does** support initial machine labels.
</Warning>

## Verifying labels

After a machine boots from the labeled media or PXE URL and registers with Omni, you can verify its labels using the Omni UI or omnictl.

To check labels with omnictl, run either of the following commands, replacing `<machine-id>` with your machine's ID:

```bash theme={null}
omnictl get machinelabels -oyaml <machine-id>
```

**or**

```bash theme={null}
omnictl get machinestatus -oyaml <machine-id>
```

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