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

The first time the Red Hat Edge Manager agent 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 Red Hat Edge Manager service populates device.status.capabilities.osMode from the enrollment request at approval time. The OS mode is available on the device immediately after enrollment approval, without waiting for a subsequent status report.

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 by 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.

Red Hat Edge Manager manages different aspects of a device depending on whether the device runs in image mode or package mode. Understanding which capabilities apply to each mode helps you set operational expectations and plan complementary tooling for tasks outside Red Hat Edge Manager scope.

The following table compares Red Hat Edge Manager management capabilities by operating system (OS) mode:

Agent behavior on package-mode devices

On package-mode devices, the agent skips OS update reconciliation entirely. The agent detects that the host does not use image-based updates and skips OS image staging, bootc invocation, and rollback checks entirely. No error-level log messages are generated from the absence of image-mode tooling; the agent operates as though OS update steps do not exist.

If the delivered spec includes a spec.os.image field, the agent rejects the entire spec. No configuration overlays or application workloads from that spec version are applied; the device stays on its previously committed spec. Configuration and applications apply normally only when the delivered spec has no OS image target.

For more information about how the agent handles OS image fields on package-mode devices, see Additional resources.

OS identity on package-mode devices

Package-mode devices report their operating system identity through status.systemInfo fields such as distroName and distroVersion. The status.os.image field is empty on package-mode devices because no bootable container image is associated with the running OS.

For a known package-mode device, a direct device edit that sets or changes spec.os.image is rejected by both the Flight Control web console and the API (HTTP 400). Fleet delivery of an OS image in the template is still allowed; the agent then rejects the full delivered spec as described above.

For more information about console and agent-side handling, see Additional resources.

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 Trusted Platform Module (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

You can report site-specific or application-specific values under status.systemInfo.customInfo by using custom collectors.

To add a custom field:

Custom keys must be camel case with no spaces or special characters. Script file names can be camel case 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 by 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. 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):

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.capabilities section reports device capabilities detected by the agent. The osMode field indicates whether the device runs in image mode (bootc-based OS with transactional updates) or package mode (traditional Red Hat Enterprise Linux managed through dnf or yum). Package-mode devices report an empty status.os.image field because no bootable container image is associated with the running OS. OS identity on package-mode devices is available through status.systemInfo fields such as distroName and distroVersion.

In the Flight Control web console, the device details page displays the OS mode. Package-mode devices show N/A or empty for the system image field.

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 might 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. This session runs 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 by using the same procedures as other device labels. The alias value must follow the Kubernetes label rules described in the following sections.

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 by 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 by using the CLI

Update labels on your devices by 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:

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.

Use status.capabilities.osMode to filter devices by their OS mode. For example, to list only package-mode devices:

flightctl get devices --field-selector 'status.capabilities.osMode=package'

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.capabilities.osMode 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 changing the target image in the device specification or by choosing an image from the Software Catalog in the Flight Control web console.

Catalog-driven operating system 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 operating system version fails health checks after reboot, the device automatically rolls back to the previous working version. During a failed update, the device might 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 by using the Flight Control CLI

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

Red Hat Edge Manager uses console-level controls and agent-side handling to manage operating system (OS) image settings on package-mode devices.

Console and API validation for direct device edits

For a known package-mode device, a direct device edit that sets or changes spec.os.image is rejected by both the Flight Control web console and the API (HTTP 400). Fleet templates can still include an OS image; that path is not blocked at the API.

Agent handling of OS image fields on package-mode devices

When a fleet template includes an OS image target, the Red Hat Edge Manager service renders the full template spec and delivers it to all devices in the fleet. The service does not filter the template content per device OS mode.

When a package-mode device receives a delivered spec that contains a spec.os.image field, the agent rejects the entire spec. The rejection occurs before any reconciler runs:

When the fleet template is updated to deliver a spec without an OS image target, the package-mode device accepts and reconciles the new spec normally, including any configuration and application changes.

Backward compatibility

Devices with an unknown or missing status.capabilities.osMode value are handled according to the agent’s legacy behavior. This ensures that older agents that do not yet report OS mode continue to operate without disruption.

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.

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 the resources that will be imported into the Software Catalog. 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 by 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>

After synchronization completes, the catalog contents from the synchronized repository are available in the Software Catalog in Flight Control. 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 Software Catalog provides a curated list of operating system images, application images, and application data that you can discover and deploy from the Flight Control web console.

You can install or update software on a device or apply catalog software through a fleet device template. 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:

Application catalog content (application images and application data) is fully available to both image-mode and package-mode devices.

Catalog contents are provided by catalog sources 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 sources (administrators)

Administrators configure one or more catalog sources 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 source 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 operating system 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 select 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

The Flight Control web console monitors catalog software on each device. When a newer version exists along an allowed update path, the console shows that an update is available. The same applies when a fleet device template defines catalog software for its devices. The update notification appears on the Catalog tab when you open a device or view fleet details.

If the catalog publisher includes release notes or change highlights for a version, that information is displayed 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 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. An update is offered only when the target version includes the same channel as the currently deployed version. When the graph does not define a direct jump, apply the intermediate versions that the console offers first. Alternatively, ask your administrator to extend the catalog definitions. The console guides you toward allowed targets and avoids disallowed jumps when those guardrails are enforced.

Deploying catalog software by using the API or CLI

When you deploy catalog software by using the Flight Control CLI or API instead of the web console, you reference catalog items directly in Device and Fleet specification YAML by using the catalogItemRef field. The catalogItemRef field provides a first-class, API-validated mechanism that replaces manual entry of OCI image references for catalog-sourced deployments.

For the complete field specification, sub-field descriptions, and YAML examples, see Catalog item reference field specification in the Additional resources section.

Catalog references are resolved server-side during device rendering. The Red Hat Edge Manager service looks up the catalog item version and substitutes a concrete OCI image URL into the rendered device specification. The device agent receives only standard image references and does not need to know about catalog items. For details about how resolution works, see How catalog references are resolved for devices in the Additional resources section.

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 operating system image or application is available along an allowed path, you can update from the catalog. You can apply the update to an individual fleetless device or to a fleet device template. For devices that are bound to a fleet, updates must be applied at the fleet level through the fleet device template. Installed catalog software is compared to published versions and upgrade edges. For details, see Validated upgrade paths and compatibility 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 catalogItemRef field lets you reference Software Catalog items directly in Device and Fleet specifications through the CLI or API, replacing manual OCI image references with an API-validated catalog reference.

The catalogItemRef field is mutually exclusive with the image field. In spec.os and in each entry under spec.applications, you specify either image (a direct OCI image reference) or catalogItemRef (a catalog-sourced reference), but not both. The image and catalogItemRef fields apply to Container, Quadlet, Compose, and Helm application types. VM applications use neither field and must specify their configuration as an inline vm.yaml file.

The YAML examples in this section show Device and Fleet resources, which use the flightctl.io/v1beta1 API version. Catalog and CatalogItem resources use flightctl.io/v1alpha1. For catalog definition examples, see Managing a catalog repository on the CLI in the Additional resources section.

catalogItemRef sub-fields

The following table describes the sub-fields of the catalogItemRef object:

Referencing a catalog operating system image for a device

The following example shows a Device resource that uses catalogItemRef in spec.os to deploy an operating system image from the catalog:

apiVersion: flightctl.io/v1beta1
kind: Device
metadata:
  name: <device_name>
spec:
  os:
    catalogItemRef:
      catalog: <catalog_name>
      item: <os_image_item_name>
      version: "<version>"
      channel: "<channel (optional)>"

Where:

Referencing a catalog application for a device

The following example shows a Device resource that uses catalogItemRef in spec.applications to deploy an application from the catalog:

apiVersion: flightctl.io/v1beta1
kind: Device
metadata:
  name: <device_name>
spec:
  applications:
  - name: <application_name>
    appType: container
    catalogItemRef:
      catalog: <catalog_name>
      item: <app_item_name>
      version: "<version>"
      channel: "<channel (optional)>"
    runAs: flightctl
    envVars:
      APP_ENV: production

Where:

Referencing catalog items in a fleet device template

You can use catalogItemRef in a fleet device template so that all devices in the fleet receive the catalog-sourced operating system image and applications. The following example shows a Fleet resource with catalogItemRef for both the operating system image and an application:

apiVersion: flightctl.io/v1beta1
kind: Fleet
metadata:
  name: <fleet_name>
spec:
  selector:
    matchLabels:
      region: <region>
  template:
    spec:
      os:
        catalogItemRef:
          catalog: <catalog_name>
          item: <os_image_item_name>
          version: "<version>"
          channel: "<channel (optional)>"
      applications:
      - name: <application_name>
        appType: container
        catalogItemRef:
          catalog: <catalog_name>
          item: <app_item_name>
          version: "<version>"
          channel: "<channel (optional)>"
        runAs: flightctl

When a Device or Fleet specification uses the catalogItemRef field, the Red Hat Edge Manager service resolves the catalog reference to a concrete OCI image URL during the device render stage before sending the rendered specification to the device agent.

The device agent receives only standard image references and has no knowledge of catalog items. Catalog-based deployments are completely transparent to the agent, which means existing agents work without modification when you introduce catalog references.

Server-side resolution

The Red Hat Edge Manager service resolves each catalogItemRef by looking up the specified catalog, item, and version. The service retrieves the corresponding artifact reference from the CatalogItem resource and substitutes a concrete OCI image URL into the rendered device specification.

When a fleet device template contains catalogItemRef fields, the Red Hat Edge Manager worker resolves all catalog references during fleet-to-device rendering. Each device in the fleet receives a fully resolved specification with standard image URLs.

Rendered version behavior

The rendered device specification version is incremented whenever a catalog reference resolves to a different image than the previous render. This version change triggers the device agent to reconcile, downloading and applying the updated image.

If the catalog reference resolves to the same image as the previous render, the rendered version does not change and the agent takes no action.

Resolution failure indicators

In rare cases, the service might be unable to resolve a catalogItemRef (for example, if an unexpected sequence of events causes a catalog item to become unavailable or a version reference to become invalid). Such a failure surfaces as a DeviceSpecValid condition error on the service side. Resolution failures do not appear in agent-side logs because the agent never receives an invalid specification.

To diagnose resolution failures, check the device status conditions:

flightctl get device/<device_name> -o yaml

Look for the DeviceSpecValid condition in the status.conditions section. A False status with a message referencing the catalog item indicates a resolution failure.

Red Hat Edge Manager enforces lifecycle protection rules that prevent destructive operations on catalog items that are actively referenced by devices or fleets. These protections ensure that catalog-to-device relationships remain stable and that deployed software is not disrupted by catalog changes.

Deletion and alteration protection

A catalog item version is considered actively referenced when any device or fleet specification contains a catalogItemRef field that points to that catalog, item, and version. The Red Hat Edge Manager API blocks the following operations on actively referenced catalog item versions:

To delete or modify an actively referenced catalog item version, you must first remove the catalogItemRef references from all affected devices and fleets. For the step-by-step procedure, see Safely remove or update in-use catalog items in the Additional resources section.

Type-contradiction validation

The Red Hat Edge Manager API validates that catalog item references match the expected context in the device or fleet specification. Referencing a catalog item from the wrong specification context results in a type-mismatch error:

Type-contradiction validation runs when you create or update a device or fleet specification. The API rejects the request immediately with a descriptive error message.

You can remove or update a catalog item version that is actively referenced by devices or fleets by first removing the references from all affected resources. Red Hat Edge Manager blocks deletion or modification of in-use catalog item versions.

Error: catalog item version is actively referenced by one or more devices or fleets

To resolve this error, repeat steps 1 through 3 to identify and remove all remaining references before retrying the operation.

The Red Hat Edge Manager API enforces lifecycle protection and type-validation rules for catalog items. When an operation violates these rules, the API returns an error with a descriptive message and an HTTP status code that indicates the cause and resolution.

The label-based catalog reference mechanism is replaced by the catalogItemRef specification field. Update your CLI or API workflows to use catalogItemRef instead of catalog-related labels.

Deprecated labels

The following labels were previously used as a UI-only convention to associate catalog items with devices and fleets. These labels are no longer used for catalog associations:

Why the label-based model is replaced

The label-based catalog reference model was a UI-only convention that was not enforced by the Flight Control API. This approach had several limitations:

The catalogItemRef field addresses these limitations by providing a first-class, API-validated mechanism for catalog references. The field is part of the Device and Fleet specification, which means it is subject to API validation, lifecycle protection, and type checking.

Who is affected

When you upgrade Red Hat Edge Manager from a previous version, the upgrade process automatically migrates label-based catalog references to the catalogItemRef field in Device and Fleet specifications.

When you upgrade Red Hat Edge Manager from a previous version, the automatic database migration converts label-based catalog references to catalogItemRef fields. In certain scenarios, the migration cannot convert a reference and the catalog association is lost.

When an OS update fails health checks after reboot, the device automatically rolls back to the previous working operating system version without manual intervention.

Red Hat Edge Manager uses greenboot integration to provide autonomous failed upgrade recovery. When the new OS image fails health checks (for example, the agent not becoming active in time or entering a crash loop), the device reverts to the previous working OS version.

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 might 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 requires image-mode (bootc) devices with greenboot enabled. Package-mode devices do not support transactional OS updates or greenboot-based rollback. 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. 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.

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 configured 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 configured, you can use it for 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 configured, you can use it for 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 you use 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 setting. This value specifies 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 for changes. When you push commits to the tracked branch, Red Hat Edge Manager rolls out the new configuration. 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.

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 can use the following variables in arguments to your command. These variables 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 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 by using drop-in files in /etc/flightctl/conf.d/. You can 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 by using 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 configure 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:

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 by 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.