To manage your devices with Red Hat Edge Manager, you must enroll the devices to the Red Hat Edge Manager service.

The first time Red Hat Edge Manager agents runs on a device, the agent prepares for the enrollment process by generating a cryptographic key pair. The cryptographic key pair of the device consists of a public and a private key. The private key never leaves the device, so that the device cannot be duplicated or impersonated. The key pair is registered with the Red Hat Edge Manager service during enrollment and is deleted during decommissioning of the device.

When the device is not yet enrolled, the agent performs service discovery to find its Red Hat Edge Manager service instance. Then, the device establishes a secure, mTLS-protected network connection to the service. The device uses its X.509 enrollment certificate that the device acquired during image building or device provisioning. The device submits an enrollment request to the service that includes the following:

The device is not considered trusted and remains quarantined in a device lobby until an authorized user approves or denies the request.

For more information, read the following sections:

Prerequisites

Enrolling devices using the Flight Control CLI

You must enroll devices into the Red Hat Edge Manager service before you can manage them. Complete the following steps:

After you approve the enrollment request, the service issues the management certificate and registers the device in the inventory. The device appears in the inventory with its alias in the ALIAS column when the agent assigned an alias label during enrollment. The device is now ready to be managed.

The Red Hat Edge Manager agent collects built-in and custom system information from each device and reports it in device status under status.systemInfo. You configure which fields are collected independently of device labels. Labels are optional consumers of that data at enrollment time.

System information and device labels

System information collection and enrollment labels are configured independently:

You do not need to map system information to labels for the agent to report it in device status. For enrollment-time labels, including the device alias, see Device alias and enrollment labels in the Additional resources section.

Agent configuration for system information

The agent reads system information settings from /etc/flightctl/config.yaml. You can override supported keys with drop-in files under /etc/flightctl/conf.d/. Drop-in files currently support log-level, system-info, system-info-custom, system-info-timeout, and label-from-systeminfo.

The following parameters control system information collection:

Inspecting collected system information

On the device, list the values that built-in and custom collectors return:

sudo flightctl-agent system-info | jq '.'

After enrollment, view reported system information in the device resource. For example:

flightctl get device/<device_name> -o yaml

The status.systemInfo section includes core fields and any fields you enabled with system-info or system-info-custom. For more information about viewing device status, see View device inventory and device details in the Additional resources section.

Built-in system information fields

You can enable additional built-in collectors by listing their keys under system-info in config.yaml.

The following example enables a subset of built-in fields:

system-info: [hostname, kernel, distroName, distroVersion]

Managed system information collectors

The agent populates the following fields internally. They reflect agent lifecycle state and update only when the underlying state changes, such as certificate rotation or TPM initialization:

These fields follow the same configuration and reporting semantics as built-in collectors. Include or exclude them from device status by listing them under system-info in config.yaml. They are included in the default system-info list.

Custom system information collectors

Custom collectors let you report site-specific or application-specific values under status.systemInfo.customInfo.

To add a custom field:

Custom keys must be camelCase with no spaces or special characters. Script file names may be camelCase or lowercase.

The following example reports FIPS mode status:

Reported device status includes:

status:
  systemInfo:
    customInfo:
      fips: disabled

To map custom values to enrollment labels, enable the collector first, then use the customInfo.<key> syntax in label-from-systeminfo. For more information, see Enrollment-time label mapping in the Additional resources section.

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:

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 using the first applicable source in the following order:

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, 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 by using the field name on the right side of the mapping. 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):

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.

To obtain more information about the devices in your inventory, you can use the Flight Control CLI or the Flight Control web console.

Each device has a unique device name and when configured at enrollment, a human-readable alias shown in the ALIAS column.

In the web console, open a device from the inventory to review status and to access the Logs tab for journal and file-based device logs. For log viewing, streaming, and download steps, see Viewing, streaming, and downloading device logs in the web console in the Additional resources section.

Prerequisites

View device inventory and device details

When vulnerability reporting is enabled, you can review a paginated table of CVEs affecting the device in the Security overview card on the device details page. For more information, see View vulnerabilities on a device in the Additional resources section.

View devices in your device inventory. Complete the following steps:

The ALIAS column shows the device alias label. If no alias was assigned, the column shows <none>. For more information about how aliases are set during enrollment, see Device alias and enrollment labels in the Additional resources section.

The status.systemInfo section always includes core fields such as architecture and operatingSystem. Additional built-in and custom fields appear when you enable them in the agent system-info and system-info-custom configuration. For more information, see Reporting system information from the agent in the Additional resources section.

When the device references Git, HTTP, or Kubernetes secret configuration providers, status.dependencySync.configRefs shows the upstream fingerprint last applied to the device. For more information, see Sync status on devices in the Additional resources section.

Device update status and update state

The status.updated.status field indicates whether the device’s running OS and configuration match the device spec. It can have the following values:

When an update is in progress, status.conditions includes an Updating condition whose reason field indicates the current phase. After a failed update and rollback, the reason is Error; the device has returned to the previous OS version and the agent will not retry that failed version automatically. The following update states can appear:

The status.updated.info field may contain a short message about the last transition. For troubleshooting a rollback or failed update, see Troubleshooting OS update rollback in the Additional resources section.

You can search, view, stream, and download logs from enrolled devices in the Flight Control web console without SSH access to the device. Log data is retrieved over the existing gRPC connection between the Red Hat Edge Manager agent and the Red Hat Edge Manager service, so operators on a different network than the device can troubleshoot when the device is reachable only through the management plane.

When to use console log access

Use the Logs view on a device when you need to inspect agent or system journal output, or files under /var/log, during day-2 operations, for example:

How log access uses the agent connection

The web console does not open a new inbound port on the edge device. Requests to retrieve, view, stream, and download logs use a device console session over the agent’s outbound gRPC connection to the Red Hat Edge Manager service. The agent runs commands on the device as the flightctl-console user to retrieve and stream log output through that session, similar to other agent-mediated operations.

Plan firewall rules so that enrolled devices can reach the agent API endpoint. For port numbers and deployment context, see Network ports for Red Hat Edge Manager and Red Hat Edge Manager API server in the Additional resources section.

Use the Logs tab on a device in the Flight Control web console to retrieve journal or file log output, stream new log lines in real time, and download a log file from the device.

For background on connectivity, see Device logs in the Flight Control web console in the Additional resources section.

Prerequisites

Decommissioning a device is the supported way to unenroll it and permanently remove it from Red Hat Edge Manager management. When you request decommissioning, the Red Hat Edge Manager service instructs the agent on the device to run a decommissioning process. That process removes the agent’s management certificate and private key, which erases the device’s Red Hat Edge Manager identity. You cannot undo this action. Always decommission a device before you delete its device resource from the service.

You can organize your resources, including individual devices, fleets and any other resources, by assigning them labels. For example, you can use labels to record location, hardware type, or purpose. The Red Hat Edge Manager labels follow the same syntax, principles, and operators as Kubernetes labels and label selectors.

You can select devices with labels when viewing the device inventory or applying operations to the devices.

Labels follow the key=value format, where you want to use the key to group devices. For example, if your labels follow the site=<location> naming convention, you can group your devices by site.

You can also use labels that only consist of keys.

Labels must adhere to the following rules to be valid:

You can apply labels to resources in the following ways:

The device alias label

The alias label provides a human-readable name for a device. The Flight Control CLI and web console display this value in the ALIAS column. The alias is distinct from the device name (metadata.name), which the agent generates and cannot be changed.

By default, the agent sets alias from the device hostname at enrollment unless you map alias from another system information field in the agent configuration. For system information collection and label mapping, see Reporting system information from the agent and Device alias and enrollment labels in the Additional resources section. You can change the alias label after enrollment using the same procedures as other device labels. The alias value must follow the Kubernetes label rules described in this section.

When resources are labeled, you can select a subset of resources by writing a label selector. A label selector is a comma-separated list of labels for selecting resources that have the same set of labels.

See the following examples:

For more information, see Labels and Selectors in the Additional resources section.

You can organize your devices by using labels.

Viewing devices and their labels using the Flight Control CLI

View devices and their associated labels. You can use labels to organize your devices and device fleets.

Complete the following steps:

Updating labels using the CLI

Update labels on your devices using the CLI. Complete the following steps:

Field selectors filter a list of Red Hat Edge Manager resources, including individual devices, fleets and any other resources, based on specific resource field values.

Field selectors follow the same syntax, principles, and operators as Kubernetes field and label selectors with additional operators available for more advanced search use cases.

Supported fields

The Red Hat Edge Manager resources give a set of metadata fields that you can select.

Each resource supports the following metadata fields:

Note: To query labels, use label selectors for advanced and flexible label filtering.

For more information, see Labels and label selectors in the Additional resources section.

List of additional supported fields

In addition to the metadata fields, each resource has its own unique set of fields that you can select, offering further flexibility in filtering and selection based on resource-specific attributes.

The following table lists the fields supported for filtering for each resource kind:

For Device resources, status.updated.status can be one of: UpToDate, Updating, OutOfDate, or Unknown. After a failed OS update and rollback, a device is typically OutOfDate (running the previous version). For more information, see Device update status and update state in the Additional resources section.

When vulnerability reporting is enabled, you can filter devices by CVE with the --cve-id option on flightctl get devices. For more information, see List devices affected by a CVE in the Additional resources section.

Field discovery

Some Red Hat Edge Manager resources might expose additional supported fields. You can discover the supported fields by using the flightctl command with the --field-selector option. If you try to use an unsupported field, the error message lists the available supported fields.

See the following examples:

flightctl get device --field-selector='text'

Error: listing devices: 400, message: unknown or unsupported selector: unable to resolve selector name "text". Supported selectors are: [metadata.alias metadata.creationTimestamp metadata.name metadata.nameOrAlias metadata.owner status.applicationsSummary.status status.lifecycle.status status.summary.status status.updated.status]

The field text is not a valid field for filtering. The error message provides a list of supported fields that you can use with --field-selector for the Device resource.

You can then use one of the supported fields:

flightctl get devices --field-selector 'metadata.alias contains cluster'

The metadata.alias field is checked with the containment operator contains to see if it has the value cluster.

The metadata.alias field reflects the device alias label. For more information about how the alias is set, see Device alias and enrollment labels in the Additional resources section.

Search by device name or alias

The metadata.nameOrAlias field matches either the device name or the alias. Use it when you know a human-readable alias but not the generated device name:

flightctl get devices --field-selector 'metadata.nameOrAlias=edge-host-01'

Examples

Excluding a specific device by name

The following command filters out a specific device by its name:

flightctl get devices --field-selector 'metadata.name!=<device_name>'

Filter by owner, labels, and creation timestamp

The following command retrieves devices that are owned by Fleet/pos-fleet, are located in the us region, and are created in 2024:

flightctl get devices --field-selector 'metadata.owner=Fleet/pos-fleet, metadata.creationTimestamp >= 2024-01-01T00:00:00Z, metadata.creationTimestamp < 2025-01-01T00:00:00Z' -l 'region=us'

Filter by owner, labels, and device status

The following command retrieves devices that are owned by Fleet/pos-fleet, are located in the us region, and have a status.updated.status of either Unknown or OutOfDate:

flightctl get devices --field-selector 'metadata.owner=Fleet/pos-fleet, status.updated.status in (Unknown, OutOfDate)' -l 'region=us'

Supported operators

Operators usage by field type

Each field type supports a specific subset of operators:

You can update the operating system of a device by updating the target operating system image name or version in the device specification. Alternatively, you can choose an OS image from the Software Catalog in the Flight Control web console and install or update from there without entering an OCI image reference manually.

Catalog-driven OS updates follow the upgrade graph that your administrator publishes for that image (allowed versions and transitions), as described in Validated upgrade paths and compatibility in the Additional resources section.

When the Red Hat Edge Manager agent communicates with the service, the agent detects the requested update. Then, the agent automatically starts downloading and verifying the new operating system version in the background.

The Red Hat Edge Manager agent schedules the actual system update according to the update policy. At the scheduled update time, the agent installs the new version without disrupting the currently running operating system.

Finally, the device reboots into the new version.

If the new OS version fails health checks after reboot, the device automatically rolls back to the previous working version. During a failed update, the device may reboot several times (greenboot retries) before the rollback completes; multiple reboots in quick succession are expected and do not indicate a separate problem. No manual intervention is required. For more information, see Automatic rollback when an OS update fails and Troubleshooting OS update rollback in the Additional resources section.

The Red Hat Edge Manager currently supports the following image type and image reference format:

During the process, the agent sends status updates to the service. You can monitor the update process by viewing the device status. For more information, see Viewing devices in the Additional resources section.

Updating the operating system of a device using the Flight Control CLI

To update the operating system of a device using the flightctl, complete the following steps:

Prepare enrollment credentials and agent configuration at a disconnected site. Approval, device lobby behavior, and post-enrollment management use the same workflow as a connected deployment.

Publish OS images to a registry inside the air-gapped site, configure pull authentication on bootc devices when required, then stage updates in Red Hat Edge Manager using the same device and fleet workflows as a connected deployment.

For catalog content in the web console, sync from a Git repository reachable inside the site. See Managing a catalog repository on the CLI in the Additional resources section.

Red Hat Edge Manager uses greenboot integration to provide autonomous failed upgrade recovery. When an OS update fails after reboot (for example, the new OS image fails health checks—such as the agent not becoming active in time or entering a crash loop), the device automatically rolls back to the previous working OS version. No manual intervention is required.

greenboot rollback operations

When an OS update fails health checks after reboot, greenboot performs rollback through the following sequence:

During the retry phase, the device may reboot multiple times before the final rollback. This is expected behavior, not a separate problem.

This keeps devices operational and avoids repeated failed update attempts.

When automatic rollback applies

Automatic rollback is available for devices that use image-based operating systems (such as bootc images) with greenboot enabled. For more information about image-based OS and transactional updates, see Operating system images for the Red Hat Edge Manager in the Additional resources section.

Observing rollback and update status

You can see whether a device rolled back or is in a failed-update state by viewing the device status. The status.updated.status field indicates whether the device is up to date, updating, or out of date. When an update fails and rollback completes, the update state is reported as Error and the device returns to the previous OS version. For details, see Device update status and update state in the Additional resources section.

If a device has rolled back or you need to diagnose a failed update, see Troubleshooting OS update rollback in the Additional resources section.

You can include an operating system-level host configuration in the image to provide maximum consistency and repeatability.

To update the configuration, you create a new operating system image and update devices with the new image.

However, updating devices with a new image can be impractical in the following cases:

For these cases, you can declare a set of configuration files that is present on the file system of the device. The Red Hat Edge Manager agent applies updates to the configuration files while ensuring that either all files are successfully updated in the file system, or rolled back to their pre-update state. If the user updates both an operating system and configuration set of a device at the same time, the Red Hat Edge Manager agent updates the operating system first, then applies the specified set of configuration files.

You can also specify a list of configuration sets that the Red Hat Edge Manager agent applies in sequence. In case of a conflict, the last applied configuration set is valid.

Important: After the Red Hat Edge Manager agent updates the configuration on the disk, the running applications need to reload the new configuration into memory for the configuration to become effective. If the update involves a reboot, systemd automatically restarts the applications with the new configuration and in the correct order. If the update does not involve a reboot, many application can detect changes to their configuration files and automatically reload the files. When an application does not support change detection, you can use device lifecycle hooks to run scripts or commands if certain conditions are met.

Configuration providers

You can provide configuration from multiple sources, called configuration providers, in Red Hat Edge Manager. The Red Hat Edge Manager currently supports the following configuration providers: A repository used by a provider must be set up once and can then be used for multiple devices or fleets.

Read more about the configuration providers in the following sections:

Configuration from a Git repository

You can store device configuration in a Git repository such as GitHub or GitLab. You can then add a Git Config Provider so that the Red Hat Edge Manager synchronizes the configuration from the repository to the file system of the device.

The Git Config Provider takes the following parameters:

The Repository resource defines the Git repository, the protocol and access credentials that the Red Hat Edge Manager must use. After the repository is set up, you can use it to configure individual devices or device fleets.

When a fleet or device references a Git repository, Red Hat Edge Manager can detect new commits on the configured branch or tag and roll out updates automatically. See Automatic synchronization of external configuration in the Additional resources section.

Secrets from a Kubernetes cluster

The Red Hat Edge Manager can query only the Kubernetes cluster that the Red Hat Edge Manager is running on for a Kubernetes secret. The content of that secret can be written to a path on the device file system.

The Kubernetes Secret Provider takes the following parameters:

To apply a Kubernetes secret to a device, add a config entry with secretRef to the device specification and apply it with the CLI (or API):

The following example shows a device spec with secretRef:

spec:
  config:
    - name: my-secret
      secretRef:
        name: my-secret-name
        namespace: my-secret-namespace
        mountPath: /etc/my-secret

Run flightctl apply -f <file>.yaml to apply the device or fleet manifest.

The Red Hat Edge Manager worker needs permission to read secrets from the cluster. You can either allow cluster-wide access at install time or grant namespace-scoped access with RBAC (least-privilege):

To detect secret rotation automatically, label secrets for synchronization and configure periodic service RBAC as described in Configuring synchronization in the Additional resources section.

The following example shows a Role and RoleBinding for flightctl-worker secret access:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: <secret_namespace>
  name: flightctl-worker-secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: <secret_namespace>
  name: flightctl-worker-secret-reader
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: flightctl-worker-secret-reader
subjects:
- kind: ServiceAccount
  name: flightctl-worker
  namespace: <worker_namespace>

Apply the manifest with oc apply -f <file>.yaml.

Configuration from an HTTP server

The Red Hat Edge Manager can query an HTTP server for configuration. The HTTP server can serve static or dynamically generated configuration for a device.

The HTTP Config Provider takes the following parameters:

The Repository resource specifies the HTTP server for the Red Hat Edge Manager to connect to, and the protocol and access credentials to use. After the repository is set up, you can use it to configure multiple devices or device fleets.

When content at the referenced URL changes, Red Hat Edge Manager can detect the change and roll out updates to fleets and devices. See Automatic synchronization of external configuration in the Additional resources section.

Configuration inline in the device specification

You can specify configuration inline in a device specification. When using the inline device specification, the Red Hat Edge Manager does not need to connect to external systems to fetch the configuration.

The Inline Config Provider takes a list of file specifications, where each file specification takes the following parameters:

For more information about device lifecycle hooks and the default rules used by the Red Hat Edge Manager agent, see Device lifecycle hooks in the Additional resources section.

When a fleet or device references configuration from Git, an HTTP endpoint, or a Kubernetes secret, Red Hat Edge Manager can automatically detect upstream changes and roll out updates without manual edits to the fleet or device specification.

How automatic synchronization works

Fleets and devices can reference external configuration through configuration providers:

When automatic synchronization is active, the Red Hat Edge Manager service periodically checks those upstream sources (or watches Kubernetes secrets) for changes. When a change is detected:

Automatic synchronization applies only when the specification uses gitRef, secretRef, or httpRef. Inline configuration in the device specification is not synchronized from external systems.

Synchronization is enabled by default when external references are present. You do not add fields to the fleet or device specification to turn it on.

Change detection by provider type

Git and HTTP checks use the global dependenciesSync.pollInterval as the minimum interval between probes for the same upstream resource. Probes for different resources are naturally spread over time because dependencies are registered at different times. Secret changes are detected near real time when the informer is running.

If a Git branch, HTTP suffix, or secret name contains template placeholders (for example {{ index .metadata.labels "target-branch" }}), Red Hat Edge Manager resolves the reference per device and triggers updates only for devices whose resolved upstream value changed.

When a device specification is rendered, Red Hat Edge Manager records the upstream fingerprint for each external configuration provider in status.dependencySync.configRefs. The lastUpdatedAt timestamp changes only when the fingerprint for that provider changes.

Template versions and rollouts

When a fleet-owned dependency changes, Red Hat Edge Manager creates a new template version and rolls it out to matching devices.

Both naming patterns can coexist for the same fleet. List template versions with the following command:

flightctl get templateversions --fleetname <fleet_name>

Sync status on devices

Synchronization state is reported on each device, not on the fleet resource.

The status.dependencySync.configRefs field lists one entry per external configuration provider referenced by the device. Each entry includes:

Configuration providers that use only inline content do not appear in configRefs.

In the Red Hat Edge Manager web console, open a device to view dependency sync details in the device detail view.

Events

The following event reasons help you distinguish automatic synchronization from user-initiated specification changes:

DependencyChangeDetected events can list a fleet or a device as the involved object, depending on ownership. Event details include resourceKey (for example git:my-repo/main or http:my-config/api/v1/config) and fingerprint. DependencySyncProbeFailed events include resourceKey and errorMessage. Inspect event details in YAML:

flightctl get events --field-selector 'involvedObject.kind=Device,involvedObject.name=<device_name>,reason=DependencyChangeDetected' -o yaml

List events for a device or fleet:

flightctl get events --field-selector 'involvedObject.kind=Device,involvedObject.name=<device_name>'

Configuring synchronization

Global synchronization settings are defined in service-config.yaml on Red Hat Enterprise Linux deployments, or in the equivalent configuration mounted by your Helm release on Red Hat OpenShift Container Platform. These settings are server-side only; you do not configure dependency synchronization in fleet or device specifications.

Polling interval and task schedule

Set the minimum interval between Git and HTTP probes for the same upstream resource:

dependenciesSync:
  pollInterval: 15m

The default is 15m. The interval applies cluster-wide, not per fleet or device.

The dependency sync periodic tasks run on an internal schedule (default every 3 minutes) to discover new dependency references and retry failed probes. That task interval is not configurable in service-config.yaml; only pollInterval is user-configurable under dependenciesSync.

Kubernetes secret auto-sync

Secret synchronization requires Red Hat Edge Manager to run in the cluster where the secrets are stored.

Security considerations

Viewing sync status with the CLI

Devices

View per-provider sync fingerprints on a device:

flightctl get device/<device_name> -o yaml

Inspect the status.dependencySync.configRefs block.

Fleets

Fleet resources do not include a dependencySync status block in YAML. To assess fleet-wide synchronization:

Metrics for cluster administrators

When Prometheus scrapes the Red Hat Edge Manager periodic service, the following metrics relate to dependency synchronization:

Use flightctl_dependency_sync_informer_connected to detect secret informer disconnects. For troubleshooting, see Secret informer disconnect or not running in the Additional resources section.

For troubleshooting steps, see Troubleshooting dependency synchronization in the Additional resources section.

If you have a device that runs an operating system image that includes MicroShift, you can configure the device to fetch Red Hat Advanced Cluster Management registration manifests with the HTTP Config Provider and auto-register the MicroShift cluster with Red Hat Advanced Cluster Management.

For the HTTP Config Provider parameters, see Configuration from an HTTP server in the Additional resources section.

To apply the same configuration across many devices by using a fleet device template, see Configuring fleets to auto-register MicroShift clusters in the Additional resources section.

Configuring your device

Complete the following steps:

Create and apply a device configuration in a Git repository.

Complete the following steps:

After the repository is referenced from a fleet or device, Red Hat Edge Manager can poll the repository and roll out new configuration when you push commits to the tracked branch. You do not need to edit the fleet or device specification to pick up Git changes. For details, see Automatic synchronization of external configuration in the Additional resources section.

You can add catalog content to Flight Control by creating a Repository resource that points to a Git repository containing catalog definitions, and a ResourceSync resource with type catalog that synchronizes those definitions. The Flight Control web console then displays the curated list of OS images, application images, and application data for discovery and deployment.

This procedure covers Git-synchronized catalogs. To publish catalog items from Image Builder instead, see Publishing an image build to the Software Catalog in the Additional resources section.

Default catalog

Every organization receives a default catalog automatically when the organization is first provisioned. You do not create this catalog manually. Image promotions and Git-synchronized catalogs can both target or coexist with the default catalog.

Verify the default catalog:

$ flightctl get catalog/default

Complete the following steps to synchronize catalog definitions from Git:

Defining catalogs and catalog items in Git

Your Git repository must contain Catalog and CatalogItem resources that describe what appears in the Software Catalog after synchronization. Store them under the directory (or file path) that you set in the ResourceSync spec.path field.

Organize files in a layout similar to the following:

catalogs/
  <catalog_name>/
    catalog.yaml
    <catalog_item_name>.yaml

Catalog resource

The following example shows a minimal Catalog resource:

apiVersion: flightctl.io/v1alpha1
kind: Catalog
metadata:
  name: <catalog_name>
spec:
  displayName: <human_readable_catalog_title>
  shortDescription: <one_line_description>

CatalogItem versions, channels, and artifacts

Each CatalogItem declares a spec.type (for example, container for an application image), one or more spec.artifacts entries with a type and a versionless uri, and a spec.versions list. Every version entry must include:

The following example defines two versions in a linear chain:

apiVersion: flightctl.io/v1alpha1
kind: CatalogItem
metadata:
  name: <catalog_item_name>
  catalog: <catalog_name>
spec:
  type: container
  displayName: <human_readable_item_title>
  artifacts:
    - type: container
      uri: quay.io/<namespace>/<image>
  versions:
    - version: "1.0.0"
      channels:
        - stable
      references:
        container: "1.0.0"
    - version: "1.1.0"
      channels:
        - stable
      references:
        container: "1.1.0"
      replaces: "1.0.0"

Defining upgrade paths

Flight Control models relationships between versions using the Cincinnati update protocol. Optional fields on each version entry describe which upgrades are valid:

If you omit these fields, only the linear replaces chain (when present) defines one-step moves.

API version for catalog resources

Verifying synchronized catalogs on the CLI

After the ResourceSync reports a successful sync, you can list catalogs and items:

flightctl get catalogs
flightctl get catalogitems --catalog <catalog_name>

The catalog contents from the synchronized repository will be available in the Software Catalog in the Flight Control web console. For operator tasks in the console, see Using the Software Catalog in the Additional resources section. For image-build publication, see Publishing an image build to the Software Catalog in the Additional resources section.

The Red Hat Edge Manager agent can run user-defined commands at specific points in the device lifecycle by using device lifecycle hooks. For example, you can add a shell script to your operating system images that backs up your application data. You can then specify that the script must run and complete successfully before the agent can start updating the operating system.

As another example, certain applications or system services do not automatically reload their configuration file when the file changes on the disk. You can manually reload the configuration file by specifying a command as another hook, which is called after the agent completes the update process.

The Red Hat Edge Manager agent discovers hook rules only in subdirectories of /etc/flightctl/hooks.d/ and /usr/lib/flightctl/hooks.d/. Those subdirectory names are case-sensitive and must be all lowercase. For example, afterUpdating is not valid; use afterupdating.

The following subdirectories are supported:

Rule files

You can define device lifecycle hooks by adding rule files under one of the following directory trees on the device:

In both paths, replace <hook_directory> with one of beforeupdating, afterupdating, beforerebooting, or afterrebooting. For example, a custom rule that runs after the update is written to disk belongs in a file such as /etc/flightctl/hooks.d/afterupdating/50-my-hook.yaml.

When creating and placing the files, you must consider the following practices:

A rule file is written in YAML format and contains a list of one or more actions. An action can be an instruction to run an external command.

When you specify many actions for a hook, the actions are performed in sequence, finishing one action before starting the next.

If an action returns with a failure, the following actions are skipped.

A run action takes the following parameters:

By default, actions are performed every time the hook is triggered. However, for the afterupdating hook, you can use the If parameter to add conditions that must be true for an action to be performed. Otherwise, the action is skipped.

For example, to run an action only if a given file or directory changes during the update, you can define a path condition that takes the following parameters:

If you specify a path condition for an action in the afterupdating hook, you have the following variables that you can include in arguments to your command and are replaced with the absolute paths to the changed files:

The Red Hat Edge Manager agent includes a built-in set of rules defined in /usr/lib/flightctl/hooks.d/afterupdating/00-default.yaml. The following commands are executed if certain files are changed:

For networking configuration details, see Configuring and managing networking in the Additional resources section.

The Red Hat Edge Manager Software Catalog provides a curated list of operating system images, application images, and application data (for example, AI models) that you can discover and deploy from the Flight Control web console. Using the catalog, you can install or update software on a device, or apply catalog software through a fleet device template so that every device selected into the fleet receives the configuration, without entering Open Container Initiative (OCI) image references manually.

Catalog content can come from Git-synchronized catalog definitions managed by administrators, from image builds published through ImagePromotion, or from both sources in the same organization. For the build-to-catalog workflow, see Publishing an image build to the Software Catalog in the Additional resources section.

Catalog content sources

The Software Catalog can display items from the following sources:

Every organization also has a default catalog that is created automatically. Image promotions can target this catalog without additional administrator setup.

Catalog contents

The catalog can include:

Catalog contents are provided by catalog endpoints configured by your administrator. The catalog surface in the web console is analogous to the Software Catalog in the Red Hat OpenShift Container Platform web console.

Configuring catalog endpoints (administrators)

Administrators configure one or more catalog endpoints in Flight Control so that operators see a curated list of software. For Git-backed catalogs, create a catalog Repository and ResourceSync. For image-build content, ensure that OCI repositories and base image lists are configured and that publishers have permission to create ImagePromotion resources. Access to the catalog is controlled by permissions; operators either have access to view the catalog or they do not. The same catalog content is available to every operator who has access, regardless of which devices or fleets they manage; fleet-specific or environment-specific catalog visibility is not supported.

Catalog repository type

Flight Control supports a catalog resource sync in addition to fleet resource syncs. A catalog resource sync points to a catalog endpoint and can use optional authentication. For details, see Managing a catalog repository in the Additional resources section.

Using the Software Catalog (operators)

Browsing the catalog

In the Flight Control web console, open the Software Catalog to browse available OS images, application images, and application data. Filter by catalog when your organization defines more than one catalog (including the automatically provisioned default catalog). Published catalog definitions can organize versions into channels (for example, stable, candidate, or testing) when your administrator or publisher configures them that way. A version can belong to more than one channel. The catalog shows eligible versions and, where applicable, validated upgrade paths so you can choose appropriate updates. When image builds are published to an existing catalog item, version history stays on that item (for example 1.0.0, 1.1.0, 1.2.0) instead of creating unrelated entries.

Update availability and release information

When a device runs catalog software, or devices in a fleet run catalog software that is defined in the fleet device template, and a newer version exists along an allowed update path, the Flight Control web console surfaces that an update is available—for example from the Catalog tab when you open a device or the details for a fleet.

If the catalog publisher includes release notes or change highlights for a version, that information can appear when you review an update so you can decide whether and when to apply it. Which details you see depends on what your administrator publishes in the catalog definitions.

Validated upgrade paths and compatibility

Catalog items can define an upgrade graph. Each published version is a node, and each allowed upgrade path (an edge in the graph) connects one version to the next. That model follows the Cincinnati update protocol, which Red Hat OpenShift Container Platform uses for cluster updates. The graph lets your organization expose tested transitions instead of every tag in a registry.

You might not be offered every newer tag as a direct update from your current version. When the graph does not define a jump, apply the intermediate versions that the console offers first, or ask your administrator to extend the catalog definitions. The console guides you toward allowed targets and avoids disallowed jumps when those guardrails are enforced.

Installing from the catalog

You can install an OS image or application on a single device, or add it to a fleet device template so that all devices in the fleet receive it, directly from the catalog:

Updating from the catalog

When a newer version of an OS image or application is available along an allowed path in the catalog, you can update an individual device or update catalog software configured in a fleet device template from the catalog. Installed catalog software is compared to published versions and upgrade edges; see Validated upgrade paths and compatibility in the Additional resources section. For what you might see before you choose to update, see Update availability and release information in the Additional resources section.

Updates are visible in the Catalog tab of the device details view, or of the fleet details view for fleets whose device template includes catalog-defined software.

Provisioning guidance when installing a bootc image to a new device

When you choose to install a bootc image from the catalog to a device that is not yet enrolled, the Flight Control web console can provide scenario-specific provisioning guidance, for example:

Use that guidance together with the procedures in Provisioning devices to complete enrollment.

The Red Hat Edge Manager agent can automatically remove unused container images and OCI artifacts from devices to free disk space. This helps prevent storage exhaustion on edge devices with limited capacity.

How pruning works

Image and artifact pruning uses a "lost reference" model:

What gets pruned

The pruning process considers the following types of OCI targets:

Configuring pruning

Image and artifact pruning is disabled by default. To enable it, configure the agent pruning settings.

Base configuration

Add the pruning configuration to the main agent configuration file at /etc/flightctl/config.yaml:

image-pruning:
  enabled: true

Drop-in configuration

You can also configure pruning using drop-in files in /etc/flightctl/conf.d/. This allows you to enable or disable pruning for specific devices or fleets without changing the base configuration.

Create a drop-in file (for example, /etc/flightctl/conf.d/enable-pruning.yaml):

image-pruning:
  enabled: true

Drop-in files are processed in lexical order and override the base configuration. For example, to disable pruning via a drop-in file:

image-pruning:
  enabled: false

Pruning behavior

Example scenarios

Scenario 1: Application update * Device initially runs application quay.io/myorg/app:v1.0 * Application is updated to quay.io/myorg/app:v2.0 * After successful update, the v1.0 image is pruned (if it was previously recorded)

Scenario 2: Application removal * Device runs multiple applications * One application is removed from the device specification * After successful update, images and artifacts used only by the removed application are pruned

Scenario 3: OS image update * Device OS is updated from registry.example.com/edge/rhel:9.4 to registry.example.com/edge/rhel:9.5 * After successful update, the old OS image (9.4) is pruned (if it was previously recorded)

Monitoring pruning

Pruning operations are logged by the agent. You can monitor pruning activity as follows:

You can set up resource monitors for device resources and create alerts when the utilization of resources crosses a defined threshold. When the agent alerts the Red Hat Edge Manager service, the service sets the device status to degraded or error, depending on the severity level.

Resource monitors take the following parameters:

Alert rules take the following parameters:

Monitoring device resources using the CLI

Monitor the resources of your device through the CLI, providing you with the tools and commands to track performance and troubleshoot issues.

Complete the following steps: