From 4250a9be58c124ffb88fa9afa9e4fecf2452b0d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Mon, 18 Aug 2025 10:11:11 -0400 Subject: [PATCH] OSDOCS-15874: adds physically bound image building to bootc docs MicroShift --- _topic_maps/_topic_map_ms.yml | 2 + .../microshift-about-rhel-image-mode.adoc | 4 +- .../microshift-install-bootc-image.adoc | 4 +- ...oshift-install-bootc-physically-bound.adoc | 18 +++++ ...roshift-embed-cont-images-bootc-image.adoc | 80 +++++++++++++++++++ .../microshift-greenboot-check-update.adoc | 2 + .../microshift-install-bootc-build-image.adoc | 2 +- ...ft-install-bootc-physically-bound-con.adoc | 27 +++++++ ...ft-preparing-for-image-building-bootc.adoc | 8 +- ...croshift-preparing-for-image-building.adoc | 2 +- 10 files changed, 140 insertions(+), 9 deletions(-) create mode 100644 microshift_install_bootc/microshift-install-bootc-physically-bound.adoc create mode 100644 modules/microshift-embed-cont-images-bootc-image.adoc create mode 100644 modules/microshift-install-bootc-physically-bound-con.adoc diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index 2d4f35e5ed..962cda66ee 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_topic_maps/_topic_map_ms.yml @@ -82,6 +82,8 @@ Topics: File: microshift-install-bootc-image - Name: Running the bootc image in a virtual machine File: microshift-install-running-bootc-image-vm +- Name: Creating a fully self-contained bootc image + File: microshift-install-bootc-physically-bound --- Name: Using RHEL Kickstarts Dir: microshift_install_kickstarts diff --git a/microshift_install_bootc/microshift-about-rhel-image-mode.adoc b/microshift_install_bootc/microshift-about-rhel-image-mode.adoc index ad7b10882c..1b24026303 100644 --- a/microshift_install_bootc/microshift-about-rhel-image-mode.adoc +++ b/microshift_install_bootc/microshift-about-rhel-image-mode.adoc @@ -9,11 +9,11 @@ toc::[] You can embed {microshift-short} into an operating system image using image mode for {op-system-base-full}. include::modules/microshift-install-bootc-conc.adoc[leveloffset=+1] -include::modules/microshift-preparing-for-image-building-bootc.adoc[leveloffset=+1] +include::modules/microshift-preparing-for-image-building-bootc.adoc[leveloffset=+1] [id="_additional-resources_microshift-install-rhel-image-mode_{context}"] == Additional resources -* link:https://developers.redhat.com/products/rhel-image-mode/getting-started[Image mode for Red Hat Enterprise Linux learning exercises] +* link:https://developers.redhat.com/products/rhel-image-mode/getting-started[Image mode for Red Hat Enterprise Linux learning exercises] * link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/{op-system-version-major}/html/using_image_mode_for_rhel_to_build_deploy_and_manage_operating_systems/index[Using image mode for RHEL to build, deploy, and manage operating systems] \ No newline at end of file diff --git a/microshift_install_bootc/microshift-install-bootc-image.adoc b/microshift_install_bootc/microshift-install-bootc-image.adoc index b0e25966e3..feed061e37 100644 --- a/microshift_install_bootc/microshift-install-bootc-image.adoc +++ b/microshift_install_bootc/microshift-install-bootc-image.adoc @@ -1,8 +1,8 @@ :_mod-docs-content-type: ASSEMBLY -[id="microshift-install-publish-bootc-image"] +[id="microshift-install-bootc-image"] include::_attributes/attributes-microshift.adoc[] = Installing and publishing a bootc image to a registry -:context: microshift-install-rhel-bootc-image +:context: microshift-install-bootc-image toc::[] diff --git a/microshift_install_bootc/microshift-install-bootc-physically-bound.adoc b/microshift_install_bootc/microshift-install-bootc-physically-bound.adoc new file mode 100644 index 0000000000..0cb348a741 --- /dev/null +++ b/microshift_install_bootc/microshift-install-bootc-physically-bound.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-install-bootc-physically-bound"] +include::_attributes/attributes-microshift.adoc[] += Creating a fully self-contained bootc image +:context: microshift-install-bootc-physically-bound + +toc::[] + +If you need your bootc image to include everything required to run workloads, use physically-bound container images. Edge-computing scenarios involving embedded systems on specialized devices, high security, or high hardware control scenarios are likely candidates. + +include::modules/microshift-install-bootc-physically-bound-con.adoc[leveloffset=+1] + +include::modules/microshift-embed-cont-images-bootc-image.adoc[leveloffset=+1] + +[id="_additional-resources_microshift-install-bootc-physically-bound_{context}"] +== Additional resources + +* xref:../microshift_install_bootc/microshift-install-bootc-image.adoc#microshift-install-bootc-build-image_microshift-install-bootc-image[Building the bootc image] diff --git a/modules/microshift-embed-cont-images-bootc-image.adoc b/modules/microshift-embed-cont-images-bootc-image.adoc new file mode 100644 index 0000000000..7c921d0c49 --- /dev/null +++ b/modules/microshift-embed-cont-images-bootc-image.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// +// microshift_install_bootc/microshift-install-bootc-physically-bound.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-embed-cont-images-bootc-image_{context}"] += Embedding container images into a bootc image + +First, you must add instructions to an existing Containerfile to copy the images you want and list them in a file to keep track of the copied image names. Then, you must copy images locally from the `/usr/lib/containers/storage` directory to the local container storage. + +[IMPORTANT] +==== +You cannot store images in the default or additional container storage directory when you build bootc images. For example, if you update the additional container store setting in `/etc/containers/storage.conf` to point to the `/usr/lib/containers/storage` directory, bootc image updates fail. +==== + +.Prerequisites + +* You have root access to the host. +* You installed Podman. +* You installed skopeo. +* You have workload image references. +* You have a Containerfile for building {microshift-short} images. + +.Procedure + +. Add the pull secret to the container build procedure to ensure that images can be pulled by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ podman build --secret id=pullsecret,src=/__.json <1> +---- +<1> Specify the path to your pull secret in __. + +. Add the instructions to physically embed the image at build time by adding the following to your Containerfile: ++ +[source,text] +---- +ENV IMAGE_STORAGE_DIR=/usr/lib/containers/storage +ENV IMAGE_LIST_FILE=${IMAGE_STORAGE_DIR}/image-list.txt + +RUN dnf install -y microshift-release-info +RUN --mount=type=secret,id=pullsecret,dst=/run/secrets/pull-secret.json \ + images="$(jq -r ".images[]" /usr/share/microshift/release/release-"$(uname -m)".json)" ; \ + mkdir -p "${IMAGE_STORAGE_DIR}" ; \ + for img in ${images} ; do \ + sha="$(echo "${img}" | sha256sum | awk '{print $1}')" ; \ + skopeo copy --all --preserve-digests \ + --authfile /run/secrets/pull-secret.json \ + "docker://${img}" "dir:$IMAGE_STORAGE_DIR/${sha}" ; \ + echo "${img},${sha}" >> "${IMAGE_LIST_FILE}" ; \ + done +---- +When run, the Containerfile extracts the list of {microshift-short} container image dependencies from the `microshift-release-info` RPM and pulls them into a custom `/usr/lib/containers/storage` directory. The resulting image list file is saved at `/usr/lib/containers/storage/image-list.txt`. + +. Next, you must copy container images from the custom directory to the main container storage directory so that they are available to {microshift-short}. Add a script and a systemd service to your Containerfile to copy the embedded images from the `/usr/lib/containers/storage` directory to the local container storage. Copying happens at runtime before each {microshift-short} start. Use the following example: ++ +[source,text] +---- +RUN cat > /usr/bin/microshift-copy-images < /usr/lib/systemd/system/microshift.service.d/microshift-copy-images.conf < ---- <1> If your command returns `boot_success=0`, either the greenboot health check is still running, or the update is a failure. +-- diff --git a/modules/microshift-install-bootc-build-image.adoc b/modules/microshift-install-bootc-build-image.adoc index e507c65b8f..890709bba4 100644 --- a/modules/microshift-install-bootc-build-image.adoc +++ b/modules/microshift-install-bootc-build-image.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// microshift_install_bootc/microshift-install-rhel-bootc-image.adoc +// microshift_install_bootc/microshift-install-bootc-image.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-install-bootc-build-image_{context}"] diff --git a/modules/microshift-install-bootc-physically-bound-con.adoc b/modules/microshift-install-bootc-physically-bound-con.adoc new file mode 100644 index 0000000000..2ce64a6f50 --- /dev/null +++ b/modules/microshift-install-bootc-physically-bound-con.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// microshift_install_bootc/microshift-install-bootc-physically-bound.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-install-bootc-physically-bound_{context}"] += About physically bound bootc image building + +When a bootc image is fully self-contained, everything you need to run workloads is embedded with the bootc image, including {microshift-short} and application container images. The underlying mechanism is to pre-pull physically-bound images during image build and then make them available at runtime. + +Because embedded images might change with each system update, you cannot pull the images directly to the default container storage. Additional image stores do not work in this case because of current implementation limits. These limits do not allow bootc image updates for those container images. + +The manifest, layer tarballs, and signatures are exported as individual files into the directory. The `dir` transport type preserves the digest of the image, which is crucial for the original digest to reference the image. + +Technical details to understand include the following items: + +* Each image goes into the same top-level directory, but a separate subdirectory. +* Subdirectories are named after the image reference string `SHA`. +* An image list file maps image references to their name `SHA`. +* You must install the `microshift-release-info` RPM to get the image references required by {microshift-short}. +* You must have image references for your workloads. Apply the same methods to workload image references that you use for {microshift-short} image references. +* When you build the container, you must install the `microshift-release-info` RPM. The `release-x86_64.json` and `release-aarch64.json` files from this RPM reside in the `/usr/share/microshift/release/` directory. These files contain image references required by {microshift-short}. + +[IMPORTANT] +==== +You must keep track of the name of the image. A tag, digest, or a mix of both can reference images. Choosing the best way to reference the images you need can impact the quality and robustness of workloads. +==== diff --git a/modules/microshift-preparing-for-image-building-bootc.adoc b/modules/microshift-preparing-for-image-building-bootc.adoc index fb8055d9d7..ed10d21a75 100644 --- a/modules/microshift-preparing-for-image-building-bootc.adoc +++ b/modules/microshift-preparing-for-image-building-bootc.adoc @@ -3,11 +3,13 @@ // microshift_install_bootc/microshift-about-rhel-image-mode :_mod-docs-content-type: CONCEPT -[id="preparing-for-image-building_{context}"] -= Preparing for image building +[id="microshift-preparing-for-image-building_{context}"] += Preparing for bootc image building Use the image builder tool to compose customized {microshift-short} bootc images optimized for edge deployments. You can run a {microshift-short} cluster with your applications on a {op-system-image} virtual machine for development and testing first, then use your whole solution in edge production environments. Use the following {op-system-base} documentation to understand the full details of using {op-system-image}: -* Follow the instructions in link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/{op-system-version-major}/html/using_image_mode_for_rhel_to_build_deploy_and_manage_operating_systems/index[Using image mode for RHEL to build, deploy, and manage operating systems] +* Follow the instructions at the following link: + +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/{op-system-version-major}/html/using_image_mode_for_rhel_to_build_deploy_and_manage_operating_systems/index[Using image mode for RHEL to build, deploy, and manage operating systems] diff --git a/modules/microshift-preparing-for-image-building.adoc b/modules/microshift-preparing-for-image-building.adoc index 7708b29628..aa8a43475c 100644 --- a/modules/microshift-preparing-for-image-building.adoc +++ b/modules/microshift-preparing-for-image-building.adoc @@ -3,7 +3,7 @@ // microshift_install_rpm_ostree/microshift-embed-rpm-ostree.adoc :_mod-docs-content-type: CONCEPT -[id="preparing-for-image-building_{context}"] +[id="microshift-preparing-for-image-building_{context}"] = Preparing for image building Use the image builder tool to compose customized {op-system-ostree-first} images optimized for edge deployments. You can run a {microshift-short} cluster with your applications on a {op-system-ostree} virtual machine for development and testing first, then use your whole solution in edge production environments.