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.

Important

OS image updates are supported only on image-mode devices (status.capabilities.osMode=image). On package-mode devices, direct edits to spec.os.image are blocked by both the Flight Control web console and the API (HTTP 400). A fleet-delivered spec that includes an OS image is rejected as a whole by the agent; no configuration or application updates from that spec version are applied. To verify a device’s OS mode before updating, run flightctl get device/<device_name> -o yaml and check status.capabilities.osMode.

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:

Note

Fleet template editing remains available even when the fleet contains package-mode members. Package-mode devices that receive a delivered spec containing an OS image reject the entire spec, stay on the previously committed version, and typically show OutOfDate status. No configuration or application updates from that spec version are applied to package-mode members.

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:

1. Get the current resource manifest of the device by running the following command:

   flightctl get device/<device_name> -o yaml > my_device.yaml

2. Edit the Device resource to specify the new operating system name and version target.

   To reference an OCI image directly, use the image field:

   apiVersion: flightctl.io/v1beta1
   kind: Device
   metadata:
     name: <device_name>
   spec:
     os:
       image: registry.example.com/edge/rhel:9.5

   To deploy an operating system image from the Software Catalog instead, use the catalogItemRef field instead of image:

   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)>"

   The image and catalogItemRef fields are mutually exclusive. Use image when you know the exact OCI image reference. Use catalogItemRef when deploying from the Software Catalog so that Red Hat Edge Manager resolves the catalog item to a concrete image. For the complete field specification, see Catalog item reference field specification in the Additional resources section.

3. Apply the updated Device resource by running the following command:

   flightctl apply -f my_device.yaml