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:

• No configuration overlays from the new spec are applied.
• No application workloads from the new spec are updated.
• The device stays on its previously committed spec.

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.