Update device operating systems in disconnected environments

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.

Before you begin

  • Red Hat Edge Manager is running at the disconnected site and target devices are enrolled. See Enrolling devices in disconnected environments.
  • Devices run a bootc operating system image managed by Red Hat Edge Manager. See Operating system images for the Red Hat Edge Manager in the Additional resources section.
  • The updated OS image is published to a registry that edge devices can reach on the internal network (for example registry.internal.example.com:5000).
  • You can authenticate to the local Red Hat Edge Manager API with the Flight Control CLI or web console.

Procedure

  1. Build or mirror the target bootc image on a connected staging host, then push or copy it to a registry inside the site. For image building and transfer options, see the Additional resources section.
  2. Confirm the image is pullable from a host on the device network: 
    skopeo inspect docker://<local_registry>/flightctl/rhel:<version>

    Replace <local_registry> and <version> with your internal registry path and tag.

  3. Configure registry authentication on each bootc device when your local registry requires credentials. Skip this step when your registry allows anonymous pulls.

    Create or update /etc/ostree/auth.json before the agent pulls the image. OS updates read credentials from this path; application containers use /root/.config/containers/auth.json separately.

    {
  "auths": {
    "<local_registry>": {
      "auth": "<base64-encoded-username:password>"
    }
  }
}

    Generate the auth value with echo -n 'username:password' | base64.

  4. To persist credentials across reprovisioning, embed auth.json in the operating system image during build. See Using image pull secrets in the Additional resources section.
  5. Stage the update by changing spec.os.image in the device or fleet specification. Use your internal registry reference (for example <local_registry>/flightctl/rhel:<version>) instead of a public registry URL.

    Follow Updating the operating system of a device using the Flight Control CLI for a single device, or update fleet device templates as described in Device templates. See the Additional resources section.

    The agent pull, apply, reboot, and status reporting workflow is the same as a connected deployment. See Updating the operating system and Device update status and update state in the Additional resources section.

  6. Alternative: USB-based image transfer. Use this path when a device cannot reach the local registry during an update window but you can transfer files on removable media. After the manual bootc change, update the device specification in Red Hat Edge Manager so the desired state matches the running image.

    On a prep machine with access to the image, export it to a portable archive:

    skopeo copy \
  docker://<local_registry>/flightctl/rhel:<version> \
  oci-archive:~/rhem-os-<version>.tar
  7. Transfer ~/rhem-os-<version>.tar to the device. For transfer options, see the Additional resources section.
  8. On the device, load the archive into local container storage: 
    sudo skopeo copy \
  oci-archive:~/rhem-os-<version>.tar \
  containers-storage:<local_registry>/flightctl/rhel:<version>
  9. Switch the running OS to the staged image: 
    sudo bootc switch --transport containers-storage <local_registry>/flightctl/rhel:<version>
sudo bootc upgrade

    Reboot when bootc or the agent prompts for activation.

  10. Update spec.os.image in Red Hat Edge Manager to the same reference so the control plane matches the device.

Results

  • On the device, bootc status reports the expected image reference and a healthy staged deployment.