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.