Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

このコンテンツは選択した言語では利用できません。

Chapter 1. Operating system images for the Red Hat Edge Manager

Image-based operating systems allow the operating system and the configuration and applications to be versioned, deployed, and updated as a single unit. Using an image-based operating system reduces operational risks with the following capability:

  • Minimizing drift between tested and deployed environments.
  • Reducing failed updates through transactional updates and rollbacks, and reducing maintenance and replacement costs.

The Red Hat Edge Manager focuses on image-based Linux operating systems that run bootable container image (bootc). For more information, see https://bootc-dev.github.io/bootc/.

Important: The bootc tool does not update package-based operating systems.

See the following description for the operating system images process:

  • Choose a base bootc operating system image, such as a Fedora, CentOS, or RHEL image.

  • Create a container file that layers the following items onto the base bootc image:

    • The Red Hat Edge Manager agent and configuration.
    • Optional: Any drivers specific to your target deployment environment.
    • Optional: Host configuration, for example certificate authority bundles, and application workloads that are common to all deployments.
  • Build, publish, and sign a bootc operating system image using podman and skopeo.
  • Create an operating system disk image by using bootc-image-builder.
  • Build, publish, and sign an operating system disk image using skopeo.

Note: The operating system disk image contains partitions, volumes, the file system, and the initial bootc image. The operating system disk image only needs to be created once, during provisioning.

For subsequent device updates, only the bootc operating system image is required, which contains the files in the file system.

See the following image building topics:

1.1. Special considerations for building images
リンクのコピー

1.1.1. Build-time configuration over dynamic runtime configuration
リンクのコピー

Add configuration to the operating system image at build time. Adding configuration at build time ensures that the configurations are tested, distributed, and updated together. In cases when build-time configuration is not feasible or desirable, you can dynamically configure devices at runtime instead with the Red Hat Edge Manager.

Dynamic runtime configuration is preferable in the following cases:

  • You have a configuration that is deployment or site-specific, such as a hostname or a site-specific network credential.
  • You have secrets that are not secure to distribute with the image.
  • You have application workloads that need to be added, updated, or deleted without reboot or they are on a faster cadence than the operating system.

1.1.2. Configuration in /usr directory
リンクのコピー

Place configuration files in the /usr directory if the configuration is static and the application or service supports that configuration. By placing the configuration in the /usr directory, the configuration remains read-only and fully defined by the image.

It is not feasible or desirable to place the configuration in the /usr directory in the following cases:

  • The configuration is deployment or site-specific.
  • The application or service only supports reading configuration from the /etc directory.
  • The configuration might need to be changed at runtime.

1.1.3. Drop-in directories
リンクのコピー

Use drop-in directories to add, replace, or remove configuration files that the service aggregates. Do not directly edit your configuration files that might cause deviation from the target configuration.

Note: You can identify drop-in directories by the .d/ at the end of the directory name. For example, /etc/containers/certs.d, /etc/cron.d, and /etc/NetworkManager/conf.d.

1.1.4. Operating system images with scripts
リンクのコピー

Avoid executing scripts or commands that change the file system. The bootc or the Red Hat Edge Manager can overwrite the changed files that might cause a deviation or failed integrity checks.

Instead, run such scripts or commands during image building, so changes are part of the image. Alternatively, use the configuration management mechanisms of the Red Hat Edge Manager.

1.1.5. Additional resources
リンクのコピー

1.2. Building a bootc operating system image for the Red Hat Edge Manager
リンクのコピー

  • To prepare your device to be managed by the Red Hat Edge Manager, build a bootc operating system image that contains the Red Hat Edge Manager agent. Then build an operating system disk image for your devices.

For more information, read the following sections:

1.2.1. Prerequisites
リンクのコピー

See the following prerequisites for building a bootc operating system image:

1.2.2. Installing the Red Hat Edge Manager CLI
リンクのコピー

To install the Red Hat Edge Manager CLI, complete the following steps:

  1. Enable the subscription manager for the repository appropriate for your system by running the following command: 

    sudo subscription-manager repos --enable edge-manager-1.0-for-rhel-9-x86_64-rpms
    Copy to Clipboard Toggle word wrap

    For a full list of available repositories for the Red Hat Edge Manager, see the Additional resources section.

  2. Install the flightctl CLI with your package manager by running the following command: 

    sudo dnf install -y flightctl-cli
    Copy to Clipboard Toggle word wrap

1.2.3. Optional: Requesting an enrollment certificate for early binding
リンクのコピー

  1. To include an agent configuration in the image, complete the following steps:

    • For Red Hat Edge Manager on OpenShift:

      • Get the Red Hat Edge Manager API interface server. Run the following command: 

        export RHEM_API_SERVER_URL=$(oc get route -n open-cluster-management flightctl-api-route -o json | jq -r .spec.host)
        Copy to Clipboard Toggle word wrap

      • Authenticate with the Red Hat Edge Manager service by using the flightctl CLI. Run the following command: 

        flightctl login --username=<your_user> --password=<your_password> https://$RHEM_API_SERVER_URL
        Copy to Clipboard Toggle word wrap

    • For Red Hat Edge Manager on Red Hat Enterprise Linux:

      • Get the Red Hat Edge Manager API interface server. Run the following command: 

        export RHEM_API_SERVER_URL=<DNS_Name>:3443
        Copy to Clipboard Toggle word wrap

      • Authenticate with the Red Hat Edge Manager service by using the flightctl CLI. Run the following command: 

        flightctl login --username=<your_user> --password=<your_password> https://<DNS Name>:3443
        Copy to Clipboard Toggle word wrap
      Note

      The CLI uses the certificate authority pool of the host to verify the identity of the Red Hat Edge Manager service. The verification can lead to a TLS verification error when using self-signed certificates, if you do not add your certificate authority certificate to the pool. You can bypass the server verification by adding the --insecure-skip-tls-verify flag to your command.

  2. Obtain the enrollment credentials in the format of an agent configuration file by running the following command: 

    flightctl certificate request --signer=enrollment --expiration=365d --output=embedded > config.yaml
    Copy to Clipboard Toggle word wrap

    Notes:

    • The --expiration=365d option specifies that the credentials are valid for a year.

    • The --output=embedded option specifies that the output is an agent configuration file with the enrollment credentials embedded.

      The returned config.yaml contains the URLs of the Red Hat Edge Manager service, the certificate authority bundle, and the enrollment client certificate and key for the agent. See the following example: 

    enrollment-service:
  authentication:
    client-certificate-data: LS0tLS1CRUdJTiBD...
    client-key-data: LS0tLS1CRUdJTiBF...
  service:
    certificate-authority-data: LS0tLS1CRUdJTiBD...
    server: https://agent-api.flightctl.127.0.0.1.nip.io:7443
  enrollment-ui-endpoint: https://ui.flightctl.127.0.0.1.nip.io:8081
    Copy to Clipboard Toggle word wrap

1.2.4. Optional: Using image pull secrets
リンクのコピー

If your device relies on containers from a private repository, you must configure a pull secret for the registry. Complete the following steps:

  1. Depending on the kind of container image you use, place the pull secret in one or both of the following system paths on the device:

    • Operating system images use the /etc/ostree/auth.json path.
    • Application container images use the /root/.config/containers/auth.json path.

    Important: The pull secret must exist on the device before the secret can be consumed.

  2. Ensure that the pull secrets have the following format: 

    {
  "auths": {
    "registry.example.com": {
      "auth": "base64-encoded-credentials"
    }
  }
}
    Copy to Clipboard Toggle word wrap

For more information, see the Additional resources section.

1.2.5. Building 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:

  • The agent configuration for early binding
  • 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:

  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 edge-manager-<version> and rhel-<version> with the versions of the products that you are using: 

    FROM registry.redhat.io/rhel9/rhel-bootc:<required_os_version>
    1 
    

RUN dnf config-manager --set-enabled edge-manager-<version>-for-rhel-<version>-$(uname -m)-rpms && \
    dnf -y install flightctl-agent && \
    dnf -y clean all && \
    systemctl enable flightctl-agent.service && \
    systemctl mask bootc-fetch-apply-updates.timer
    2
    Copy to Clipboard Toggle word wrap
    1
    The base image that is referenced in FROM is a bootable container (bootc) image that already contains a Linux kernel, which allows you to reuse existing standard container build tools and workflows.
    2
    Disables the default automatic updates. The updates are managed by the Red Hat Edge Manager.

    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 podman-compose application support, add the following section to the Containerfile file: 

      RUN dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \
    dnf -y install podman-compose && \
    dnf -y clean all && \
    systemctl enable podman.service
      Copy to Clipboard Toggle word wrap

    2. Optional: If you created the config.yaml for early binding, add the following section to the Containerfile: 

      ADD config.yaml /etc/flightctl/
      Copy to Clipboard Toggle word wrap

    For more information, see Optional: Requesting an enrollment certificate for early binding.

  2. Define the Open Container Initiative (OCI) registry by running the following command: 

    OCI_REGISTRY=registry.redhat.io
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

  4. Define the image tag by running the following command: 

    OCI_IMAGE_TAG=v1
    Copy to Clipboard Toggle word wrap

  5. Build the operating system image for your target platform: 

    sudo podman build -t ${OCI_IMAGE_REPO}:${OCI_IMAGE_TAG} .
    Copy to Clipboard Toggle word wrap

1.2.6. Signing and publishing the bootc operating system image by using Sigstore
リンクのコピー

To sign the bootc operating system image by using Sigstore, complete the following steps:

  1. Generate a Sigstore key pair named signingkey.pub and signingkey.private: 

    skopeo generate-sigstore-key --output-prefix signingkey
    Copy to Clipboard Toggle word wrap

  2. Configure container tools such as Podman and Skopeo to upload Sigstore signatures together with your signed image to your OCI registry: 

    sudo tee "/etc/containers/registries.d/${OCI_REGISTRY}.yaml" > /dev/null <<EOF
docker:
    ${OCI_REGISTRY}:
        use-sigstore-attachments: true
EOF
    Copy to Clipboard Toggle word wrap

  3. Log in to your OCI registry by running the following command: 

    sudo podman login ${OCI_REGISTRY}
    Copy to Clipboard Toggle word wrap

  4. Sign and publish the operating system image by running the following command: 

    sudo podman push \
    --sign-by-sigstore-private-key ./signingkey.private \
    ${OCI_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

1.2.7. Building the operating system disk image
リンクのコピー

Build the operating system disk image that contains the file system for your devices. Complete the following steps:

  1. Create a directory called output by running the following command: 

    mkdir -p output
    Copy to Clipboard Toggle word wrap

  2. Use bootc-image-builder to generate an operating system disk image of type iso from your operating system image. Run the following command: 

    sudo podman run --rm -it --privileged --pull=newer \
    --security-opt label=type:unconfined_t \
    -v "${PWD}/output":/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel9/bootc-image-builder:latest \
    --type iso \
    ${OCI_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

When the bootc-image-builder completes, you can find the ISO disk image at the ${PWD}/output/bootiso/install.iso path.

1.2.8. Optional: Signing and publishing the operating system disk image to an Open Container Initiative registry
リンクのコピー

Sign and publish your disk image to your Open Container Initiative (OCI) registry. Optionally, you can compress and publish the disk image as an OCI artifact to the same OCI registry as your bootc images, which facilitates a unified hosting and distribution of bootc and disk images. To publish your ISO disk image to a repository named after your bootc image with /diskimage-iso appended, complete the following steps:

1.2.8.1. Prerequisites
リンクのコピー

1.2.8.2. Optional: Signing and publishing the operating system disk image to an OCI registry
リンクのコピー

Sign and publish your disk image to your OCI registry. Complete the following steps:

  1. Change the owner of the directory where the ISO disk image is located from root to your current user. Run the following command: 

    sudo chown -R $(whoami):$(whoami) "${PWD}/output"
    Copy to Clipboard Toggle word wrap

  2. Define the OCI_DISK_IMAGE_REPO environmental variable to be the same repository as your bootc image with /diskimage-iso appended. Run the following command: 

    OCI_DISK_IMAGE_REPO=${OCI_IMAGE_REPO}/diskimage-iso
    Copy to Clipboard Toggle word wrap

  3. Create a manifest list by running the following command: 

    sudo podman manifest create \
    ${OCI_DISK_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

  4. Add the ISO disk image to the manifest list as an OCI artifact by running the following command: 

    sudo podman manifest add \
    --artifact --artifact-type application/vnd.diskimage.iso \
    --arch=amd64 --os=linux \
    ${OCI_DISK_IMAGE_REPO}:${OCI_IMAGE_TAG} \
    "${PWD}/output/bootiso/install.iso"
    Copy to Clipboard Toggle word wrap

  5. Sign the manifest list with your private Sigstore key and push the image to the registry. Run the following command: 

    sudo podman manifest push --all \
     --sign-by-sigstore-private-key ./signingkey.private \
    ${OCI_DISK_IMAGE_REPO}:${OCI_IMAGE_TAG} \
    docker://${OCI_DISK_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

1.2.9. Additional resources
リンクのコピー

1.3. Building for specific target platforms
リンクのコピー

For optimized provisioning and integration with Red Hat OpenShift Virtualization and VMware vSphere, enrollment certificates and agent configurations can be provided with cloud-init utility, rather than embedding them in the image. Additionally, you can include appropriate guest tools for better platform integration. This process generates platform-specific image formats, such as QCOW2 for Red Hat OpenShift Virtualization and VMDK for vSphere.

1.3.1. Building images for Red Hat OpenShift Virtualization
リンクのコピー

When building operating system images and disk images for Red Hat OpenShift Virtualization, you can follow the Building a bootc operating system image for the Red Hat Edge Manager process with the following changes:

  • Use late binding by injecting the enrollment certificate or the agent configuration through cloud-init when provisioning the virtual device.
  • Add the open-vm-tools guest tools to the image.
  • Build a disk image of type qcow2 instead of iso.

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

Complete the generic steps with changes to the following steps:

  1. Build an operating system image that is based on RHEL 9 that includes the Red Hat Edge Manager agent and virtual machine guest tools, but excludes the agent configuration.

  2. Create a file named Containerfile with the following content. Replace rhacm-<2.x> and rhel-<version> with the version of the products that you are using: 

    FROM registry.redhat.io/rhel9/bootc-image-builder:latest

RUN dnf config-manager --set-enabled rhacm-<2.x>-for-rhel-<version>-$(uname -m)-rpms && \
    dnf -y install flightctl-agent && \
    dnf -y clean all && \
    systemctl enable flightctl-agent.service

RUN dnf -y install cloud-init open-vm-tools && \
    dnf -y clean all && \
    ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
    systemctl enable vmtoolsd.service
    Copy to Clipboard Toggle word wrap

  3. Optional: To enable podman-compose application support, add the following section to the Containerfile file: 

    RUN dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \
    dnf -y install podman-compose && \
    dnf -y clean all && \
    systemctl enable podman.service
    Copy to Clipboard Toggle word wrap

Build, sign, and publish the bootc operating system image by following the generic image building process.

  1. Create a directory called output by running the following command: 

    mkdir -p output
    Copy to Clipboard Toggle word wrap

  2. Generate an operating system disk image of type qcow2 from your operating system image by running the following command: 

    sudo podman run --rm -it --privileged --pull=newer \
    --security-opt label=type:unconfined_t \
    -v "${PWD}/output":/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel9/bootc-image-builder:latest \
    --type qcow2 \
    ${OCI_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

When bootc-image-builder completes, you can find the disk image in the ${PWD}/output/vmdk/disk.vmdk path.

Red Hat OpenShift Virtualization can download disk images from an Open Container Initiative (OCI) registry, but it uses a container disk image instead of an OCI artifact.

Complete the following steps to build, sign, and upload the QCoW2 disk image:

  1. Create a file that is named Containerfile.qcow2 with the following content: 

    FROM registry.access.redhat.com/ubi9/ubi:latest AS builder
ADD --chown=107:107 output/qcow2/disk.qcow2 /disk/
    1 
    
RUN chmod 0440 /disk/*
    2 
    
FROM scratch
COPY --from=builder /disk/* /disk/
    3
    Copy to Clipboard Toggle word wrap
    1
    Adds the QCoW2 disk image to a builder container to set the required 107 file ownership, which is the QEMU user.
    2
    Sets the required 0440 file permissions.
    3
    Copies the file to a scratch image.

  2. Build, sign, and publish your disk image. Run the following command: 

    sudo chown -R $(whoami):$(whoami) "${PWD}/output"
OCI_DISK_IMAGE_REPO=${OCI_IMAGE_REPO}/diskimage-qcow2
sudo podman build -t ${OCI_DISK_IMAGE_REPO}:${OCI_IMAGE_TAG} -f Containerfile.qcow2 .
sudo podman push --sign-by-sigstore-private-key ./signingkey.private ${OCI_DISK_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

1.3.2. Building images for VMware vSphere
リンクのコピー

When building operating system images and disk images for VMware vSphere, you can follow the Building a bootc operating system image for the Red Hat Edge Manager process with the following changes:

  • Using late binding by injecting the enrollment certificate or the agent configuration through cloud-init when provisioning the virtual device.
  • Adding the open-vm-tools guest tools to the image.
  • Building a disk image of type vmdk instead of iso.

Build an operating system image that is based on RHEL 9 that includes the Red Hat Edge Manager agent and VM guest tools, but excludes the agent configuration.

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

Complete the generic steps with changes to the following steps:

  1. Create a file that is named Containerfile with the following content. Replace rhacm-<2.x> and rhel-<version> with the version of the products that you are using: 

    FROM registry.redhat.io/rhel9/bootc-image-builder:latest

RUN dnf config-manager --set-enabled rhacm-<2.x>-for-rhel-<version>-$(uname -m)-rpms && \
    dnf -y install flightctl-agent && \
    dnf -y clean all && \
    systemctl enable flightctl-agent.service && \

RUN dnf -y install cloud-init open-vm-tools && \
    dnf -y clean all && \
    ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
    systemctl enable vmtoolsd.service
    Copy to Clipboard Toggle word wrap

  2. Create a directory named output by running the following command: 

    mkdir -p output
    Copy to Clipboard Toggle word wrap

  3. Generate an operating system disk image of type vmdk from your operating system image by running the following command: 

    sudo podman run --rm -it --privileged --pull=newer \
    --security-opt label=type:unconfined_t \
    -v "${PWD}/output":/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel9/bootc-image-builder:latest \
    --type vmdk \
    ${OCI_IMAGE_REPO}:${OCI_IMAGE_TAG}
    Copy to Clipboard Toggle word wrap

When bootc-image-builder completes, you can find the disk image in the ${PWD}/output/vmdk/disk.vmdk path.

Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る