Red Hat Edge Manager provides a simplified image building workflow to build, deploy, and update RHEL image-mode images for edge devices without customizing the build process. The system automatically includes the Red Hat Edge Manager agent and required services using your pre-configured registries.

• When to use the simplified workflow: You need a RHEL image-mode image quickly and do not require advanced customization (custom layers, drivers, or manual signing).
• When to use the advanced workflow: You need full control over the image contents, signing, or build pipeline. For more information, see Additional resources.

Simplified workflow overview

The simplified workflow consists of a few steps:

1. Base image selection: Choose the source registry, image name, and tag for the RHEL base image. After an administrator configures trusted base images on the OCI repository, select from the pre-populated picker instead of typing registry paths manually. See Configuring trusted base images on an OCI repository in the Additional resources section.
2. Output: Choose the target registry, image name, and tag for the built image. Optionally select one or more disk image formats (ISO, VMDK, QCOW2) to export.
3. Catalog publication (web console): Optionally enable Publish to Software Catalog (enabled by default) and configure the target catalog item and version. See Publishing an image build to the Software Catalog in the Additional resources section.
4. Binding mode: Choose Early or Late binding. For early binding, select the enrollment certificate so it is included in the image. For late binding, the enrollment endpoint and certificate are provided at provisioning time, for example, through cloud-init. See Enrollment methods in the Additional resources section for details.

The system builds the image by using the standard image builder pipeline, includes the Red Hat Edge Manager agent and required system services, and pushes the result to your configured registry. You can use the image for provisioning devices.

You can create and manage image builds from the UI or from the command line by using the Flight Control CLI and a YAML manifest.

Creating an image build from the UI

In the Red Hat Edge Manager UI, use the image building workflow to create an image build. The workflow guides you through the choices described in Simplified workflow overview in the Additional resources section. You configure the base image, output destination, optional catalog publication, optional disk image formats (ISO, VMDK, QCOW2), and binding mode (Early or Late).

When Publish to Software Catalog is enabled, the service creates an ImagePromotion after the build completes. You can also publish manually from the image build details page. See Build status and logs, Image export, Creating a new image version, and Publishing an image build to the Software Catalog in the Additional resources section.

Creating an image build from the CLI

You can define an image build in a YAML file and apply it with the flightctl CLI. Before you create an ImageBuild, ensure that the source and destination OCI Repository resources already exist in the Red Hat Edge Manager service. The destination repository must have read-write access so the built image can be pushed. In spec.source.repository and spec.destination.repository, use the names of those existing repositories.

After the build is created, use flightctl get imagebuild to check status and flightctl logs imagebuild/<name> to stream build logs.

1. Create a YAML file that defines the image build. In spec.source and spec.destination, use the names of your configured OCI Repository resources for the repository field. The following example shows a late-binding build:

   apiVersion: flightctl.io/v1alpha1
   kind: ImageBuild
   metadata:
     name: my-image-build
   spec:
     source:
       repository: quay-io
       imageName: centos-bootc/centos-bootc
       imageTag: stream9
     destination:
       repository: my-registry
       imageName: my-user/centos-bootc-custom
       imageTag: v1.0.0
     binding:
       type: late

2. Apply the image build by running the following command:

   flightctl apply -f imagebuild.yaml

3. Check build status by running the following command:

   flightctl get imagebuild/my-image-build

4. Stream build logs by running the following command. Add the -f flag to follow logs in real time:

   flightctl logs imagebuild/my-image-build -f

To export the built image to a disk image format (ISO, VMDK, QCOW2), create a separate ImageExport resource that references the ImageBuild by name. For example:

apiVersion: flightctl.io/v1alpha1
kind: ImageExport
metadata:
  name: my-image-export
spec:
  source:
    type: imageBuild
    imageBuildRef: my-image-build
  format: qcow2

Apply it with flightctl apply -f imageexport.yaml. Use flightctl logs imageexport/<name> -f to stream export logs and flightctl download imageexport/<name> ./output-file to download the disk image.

Build status and logs

You can monitor each image build from the image build screen:

• Queued: The build is waiting to start.
• Building: The build is in progress.
• Complete: The image was built successfully and pushed to the registry.
• Failed: The build or registry push failed. You can view logs and retry the registry push if the failure was due to a push error.

Build logs and image export logs stream while the build runs. For completed builds, only the last 500 lines of logs are retained. You can view retained logs from the image build details in the UI or by running flightctl logs imagebuild/<image_build_name>. For failed builds, logs are also available from the image build details or the CLI.

Image export

You can export a built image to one or more disk image formats:

• ISO: For bare metal or installable media.
• VMDK: For VMware vSphere.
• QCOW2 file (download): A .qcow2 disk image you download and use with KVM, Red Hat OpenShift Virtualization, or similar environments.
• QCOW2 for Red Hat OpenShift Virtualization (in-cluster artifact): A QCOW2-based artifact consumed from within Red Hat OpenShift Virtualization; it is not delivered as a downloadable file.

You can select the desired format(s) when creating the image build. The system creates the corresponding image export task(s) that run after the build completes. You can also create image export tasks separately by specifying the registry, image name, tag, and required formats.

Downloading the exported image

When an ImageExport completes and the chosen format is a downloadable file (ISO, VMDK, or QCOW2 file download), you can copy the disk image to your local machine. In-cluster Red Hat OpenShift Virtualization QCOW2 artifacts are not available through this download method. From the CLI, run the following command:

flightctl download imageexport/<export_name> <output_file>

Replace <export_name> with the name of your ImageExport resource and <output_file> with the local path for the downloaded file (for example, ./disk.qcow2 or ./install.iso).

Creating a new image version

An ImageBuild or ImageExport task produces its result and cannot be modified afterward. To produce a new image version, use the New version action in the web console or the flightctl new-version command. The service copies the parent build specification, sets the flightctl.io/new-version-from annotation to the parent build name, and creates a new ImageBuild resource.

$ flightctl new-version imagebuild/<parent_build_name> --name <new_build_name>

Optional flags override the source or destination tag copied from the parent:

$ flightctl new-version imagebuild/<parent_build_name> --name <new_build_name> \
    --source-image-tag <tag> \
    --destination-image-tag <tag>

After the new build completes, create an ImagePromotion that references the new build. This publishes the next catalog item version on the same catalog item. Alternatively, use the optional publish step in the New version workflow. The publish step can prefill catalog name, catalog item name, an incremented version, and replaces from the parent’s last successful promotion. See Publishing an image build to the Software Catalog in the Additional resources section.

Do not reuse the same destination image name and tag when pushing updates unless your registry policy and catalog versioning strategy intentionally allow it. Use a new tag for each new image version so that catalog references and device pull behavior remain predictable.

If you push a new image by using an existing tag, the registry might reject the overwrite. The image build can fail with 403 Forbidden, depending on registry policy. If the registry allows the overwrite, whether devices pull the new image or continue using the old one depends on the pull policy configured on the devices. Overwriting a tag can also leave some references pointing to the previous image.