Build the operating system image with bootc

Build the operating system image with bootc that contains the Red Hat Edge Manager agent. You can optionally include the following items in your operating system image:

About this task

  • The agent configuration for early binding
  • The flightctl-onboarding RPM for first-boot onboarding when devices cannot use the standard enrollment flow at first boot
  • Any drivers
  • Host configuration
  • Application workloads that you need
Note

You must build the operating system image on a Red Hat Enterprise Linux host that has the required entitlement for the specified rhem repository.

Complete the following steps:

Procedure

  1. Create a Containerfile file with the following content to build a Red Hat Enterprise Linux based operating system image that includes the Red Hat Edge Manager agent and configuration. Replace required_os_version, edge-manager-<version>, and rhel-<version> with the values for your environment: 
    FROM registry.redhat.io/rhel9/rhel-bootc:<required_os_version>

RUN dnf config-manager --set-enabled edge-manager-<version>-for-rhel-<version>-$(uname -m)-rpms && \
    dnf -y install flightctl-agent flightctl-onboarding hostapd dnsmasq \
    firewalld policycoreutils flightctl-cli && \
    dnf -y clean all && \
    systemctl enable flightctl-agent.service && \
    systemctl enable flightctl-onboarding-setup.service && \
    useradd -r -s /sbin/nologin -d /var/home/flightctl -m flightctl
    Note

    The useradd command creates the flightctl system user for running rootless container and quadlet applications. This user is required if you specify runAs: flightctl in your application deployments. The options create a system user (-r) with no login shell (-s /sbin/nologin), home directory at /var/home/flightctl (-d), and creates the home directory (-m). If you use a different username in your runAs specifications, adjust the useradd command accordingly.

     Note

    The onboarding packages are optional. Include them only when you use first-boot onboarding — for example, when devices cannot connect to Red Hat Edge Manager through the standard enrollment flow at first boot. Omit all onboarding packages from the install list for agent-only images.

    • flightctl-onboarding — the Cockpit plugin, systemd units, and default configuration for the onboarding wizard.
    • hostapd — WiFi access point. Required only when devices use the WiFi access point for wizard access.
    • dnsmasq — provides DHCP and captive-portal DNS for WiFi AP mode, and DHCP for ethernet mode so that technicians do not need to assign a static IP on their laptop manually. Required for WiFi AP; optional for ethernet (ethernet falls back to manual static IP without it).
    • firewalld — creates a locked-down firewall zone for the WiFi AP that allows only DHCP, DNS, Cockpit, and captive-portal traffic. Required only for WiFi AP mode.
    • policycoreutils — provides restorecon for SELinux labeling of dnsmasq, hostapd, and enrollment certificate configuration files.
    • flightctl-cli — used by the enrollment script for login, certificate requests, and agent configuration. Required when the wizard performs late binding.

    For when to use first-boot onboarding and how the wizard works, see Device onboarding at first boot. For optional onboarding configuration, see Optional: Include first-boot onboarding (flightctl-onboarding).

     Note

    Installing the flightctl-agent package automatically masks the bootc-fetch-apply-updates.timer systemd timer. This disables Image Mode’s scheduled fetch-and-apply updates so that Red Hat Edge Manager is the control plane for operating system image changes.

    If the timer was already masked in your base image, installing the agent does not change that state. The mask persists across reboots. Installing the agent package on an existing host (for example, with dnf install flightctl-agent) applies the same masking behavior.

     Important

    If your device relies on containers from a private repository, the device pull secret must be placed in the /etc/ostree/auth.json path. The pull secret must exist on the device before the secret can be consumed.
    1. Optional: To enable Helm application support, include MicroShift in your operating system image. The Red Hat Edge Manager agent deploys Helm applications to MicroShift on the device. If your image includes MicroShift, you can add Helm chart workloads to the device specification in addition to, or instead of, Podman-based applications. See the MicroShift documentation for installation and enablement instructions.
    2. Optional: If you created the config.yaml for early binding, add the following section to the Containerfile: 
      ADD config.yaml /etc/flightctl/

    For more information, see Optional: Requesting an enrollment certificate for early binding in the Additional resources section.

  2. Define the Open Container Initiative (OCI) registry by running the following command: 
    OCI_REGISTRY=registry.redhat.io
  3. Define the image repository that you have permissions to write to by running the following command: 
    OCI_IMAGE_REPO=${OCI_REGISTRY}/<your_org>/<your_image>
  4. Define the image tag by running the following command: 
    OCI_IMAGE_TAG=v1
  5. Build the operating system image for your target platform: 
    sudo podman build -t ${OCI_IMAGE_REPO}:${OCI_IMAGE_TAG} .