During enrollment, the Red Hat Edge Manager agent can assign a human-readable device alias and other labels automatically. You can configure how the alias is derived before enrollment, view the proposed alias when approving a device, and change the alias after the device is enrolled.

Device alias and device name

Each enrolled device has two identifiers:

• Device name (metadata.name): A unique, immutable name that the agent generates from its public key. You cannot change the device name.
• Device alias (alias label): A human-readable name shown in the ALIAS column of the Flight Control CLI and web console. The alias is stored as the alias label on the device and must follow Kubernetes label value rules.

If you do not configure the agent to set the alias explicitly, the agent assigns alias from the device hostname when it submits the enrollment request.

Enrollment-time labels on the agent

The agent reads optional label settings from /etc/flightctl/config.yaml. You can also override supported keys with drop-in files under /etc/flightctl/conf.d/; see Agent configuration for system information in the Additional resources section. During enrollment, the agent includes requested labels in the enrollment request.

Enrollment labels are separate from system information collection. The agent reports system information in device status regardless of label configuration. When you use label-from-systeminfo, the agent reads values from fields that you enabled with system-info or system-info-custom. For more information, see Reporting system information from the agent in the Additional resources section.

The following configuration parameters control enrollment labels:

Default alias behavior

The agent sets the alias label at enrollment by using the first applicable source in the following order:

1. default-labels: Set alias to a fixed value (highest precedence).
2. label-from-systeminfo: Map alias to a system information field.
3. Device hostname: If you do not set alias in default-labels or label-from-systeminfo, the agent uses the device hostname.

The alias appears in the device inventory after enrollment approval.

To set a fixed alias, add it to default-labels:

default-labels:
  alias: edge-factory-01

To set the alias from a system information field, map alias in label-from-systeminfo. For example, to use a custom product name collector:

system-info-custom: [productName]
label-from-systeminfo:
  alias: customInfo.productName

Ensure productName is enabled in system-info-custom and the collector exists under /usr/lib/flightctl/custom-info.d/ before you map it to a label.

Enrollment-time label mapping

During enrollment, the agent applies configured default-labels and maps collected system information to labels with label-from-systeminfo. The agent then includes the resulting labels in the enrollment request. After approval, those labels become part of the device metadata. You can use them in fleet selectors and fleet template placeholders the same way as manually assigned labels. For more information, see Example: fleet selection from system information and Device selection into a fleet in the Additional resources section.

You can map built-in system information fields to labels. Use the field name on the right side of the mapping as the source value. The label name on the left can be any valid Kubernetes label key. Enable the field under system-info if it is not in the default collection list. For built-in field names, see Built-in system information fields in the Additional resources section.

label-from-systeminfo:
  arch: architecture
  os-name: distroName
  os-version: distroVersion

Label values come from the mapped system information fields on each device. Values that contain spaces or special characters are sanitized automatically before enrollment. See Label validation and sanitization for an example using distroName.

You can map custom system information by using the customInfo. prefix. Enable each key under system-info-custom first. For more information, see Custom system information collectors in the Additional resources section.

system-info-custom: [region, siteId]
label-from-systeminfo:
  region: customInfo.region
  site: customInfo.siteId

Example: fleet selection from system information

The following example assigns devices to fleets based on a custom protocol collector and CPU architecture. First, create /usr/lib/flightctl/custom-info.d/waysideProtocol with executable permissions:

#!/bin/bash
cat /etc/wayside/protocol.txt

Then configure the agent to collect the custom field and map it to labels at enrollment:

system-info-custom: [waysideProtocol]
label-from-systeminfo:
  protocol: customInfo.waysideProtocol
  arch: architecture
default-labels:
  env: production

With this configuration, each device receives labels such as protocol=Wayside-Protocol-A, arch=amd64, and env=production. When you do not set alias in default-labels or map it in label-from-systeminfo, the agent also requests alias from the device hostname (for example, alias=edge-host-01). Define a fleet that selects devices by protocol:

apiVersion: flightctl.io/v1beta1
kind: Fleet
metadata:
  name: wayside-protocol-a
spec:
  selector:
    matchLabels:
      protocol: Wayside-Protocol-A
[...]

Before you apply the fleet, verify that the selector returns the expected devices:

flightctl get devices -l protocol=Wayside-Protocol-A -l env=production

For more information about fleet selectors, see Selecting devices into a fleet by using the CLI in the Additional resources section.

Label precedence at enrollment

When the same label key is defined in more than one place, labels are applied in the following order (highest to lowest precedence):

1. default-labels
2. label-from-systeminfo
3. Default alias=hostname (only when alias is not set in default-labels or label-from-systeminfo)

default-labels:
  env: production
label-from-systeminfo:
  env: customInfo.env
  region: customInfo.region

In this example, the device has env=production from default-labels. The env mapping from label-from-systeminfo is ignored. The device still receives region from custom info and alias from the hostname unless you set alias in default-labels or map it in label-from-systeminfo.

Label validation and sanitization

Values mapped with label-from-systeminfo are sanitized automatically so they meet Kubernetes label requirements. Spaces and special characters become hyphens, leading and trailing non-alphanumeric characters are removed, and values longer than 63 characters are truncated. For example, a distroName value of Red Hat Enterprise Linux becomes the label value Red-Hat-Enterprise-Linux.

Values in default-labels are validated but not modified. Invalid default-labels values are skipped and logged so enrollment can continue; fix the agent configuration if labels are missing after enrollment.

Long hostnames or other source values can exceed the 63-character label limit. The agent truncates or sanitizes values so the alias label remains valid. If a value cannot be sanitized into a valid label, the label is skipped and a warning is logged.

Alias and labels during enrollment approval

The enrollment request includes labels that the agent proposed, including the default or configured alias.

Approving with the Flight Control CLI

When you approve an enrollment request with the Flight Control CLI, you can add labels with the --label or -l flags.

By default, labels you specify at approval are merged with agent-provided labels (from default-labels, label-from-systeminfo, and the default hostname alias). Approval labels take precedence when the same key is defined in both places. For example:

flightctl approve -l region=eu-west-1 -l site=factory-berlin enrollmentrequest/<enrollment_request_name>

To set the exact label set on the device and ignore all agent-provided labels, use the --replace-labels flag. To apply no labels at approval, use --replace-labels without -l. For example:

flightctl approve -l env=production --replace-labels enrollmentrequest/<enrollment_request_name>
flightctl approve --replace-labels enrollmentrequest/<enrollment_request_name>

After approval, verify the device alias in the inventory:

flightctl get devices

See the following example output:

NAME           ALIAS              OWNER   SYSTEM  UPDATED     APPLICATIONS  LAST SEEN
<device_name>  edge-host-01       <none>  Online  Up-to-date  <none>        3 seconds ago

Approving with the Flight Control web console

In the Flight Control web console, open pending enrollment requests to review device metadata in the Approve pending device modal. The modal shows the alias in its own field and any other labels from the enrollment request in the Labels section. You can edit or remove those labels and add additional labels before you approve. When you approve the request, the enrolled device receives exactly the alias and labels shown in the modal. Label merging does not apply in the console. This behavior matches the CLI --replace-labels flag, not the default CLI merge behavior.

Changing the alias after enrollment

To change a device alias after enrollment, update the alias label on the device. For more information, see Updating labels using the CLI in the Additional resources section.

To search devices by alias or device name, use the metadata.nameOrAlias or metadata.alias field selectors. For more information, see Field selectors in the Additional resources section.

Including enrollment label configuration in an image

When you build an operating system image with early binding, you can add label-from-systeminfo, default-labels, system-info, system-info-custom, and related settings to the agent config.yaml that you embed in the image. For more information, see Optional: Requesting an enrollment certificate for early binding in the Additional resources section.