OSDOCS-8216: embed microshift in rpm-ostree commit

_topic_maps/_topic_map_ms.yml

@@ -422,6 +422,8 @@ Name: Running applications
 Dir: microshift_running_apps
 Distros: microshift
 Topics:
+- Name: Embedding MicroShift containers for offline deployments
+  File: microshift-embed-microshift-offline-deploy
 - Name: Embedding applications on RHEL for Edge
   File: microshift-embedded-apps-on-rhel-edge
 - Name: Embedding applications for offline use

microshift_running_apps/microshift-embed-apps-offline-use.adoc

@@ -6,7 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can embed microservices-based workloads and applications in a {op-system-ostree-first} image. This allows users to run a {microshift-short} cluster in air-gapped, disconnected, or offline environment.
+You can embed microservices-based workloads and applications in a {op-system-ostree-first} image. Embedding means you can run a {product-title} cluster in air-gapped, disconnected, or offline environments.
 
 include::modules/microshift-embed-images-offline-use.adoc[leveloffset=+1]
 

microshift_running_apps/microshift-embed-microshift-offline-deploy.adoc

@@ -0,0 +1,26 @@
+:_content-type: ASSEMBLY
+[id="microshift-embed-microshift-offline-deployments"]
+= Running a cluster in an offline deployment
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-embed-apps-offline-use
+
+toc::[]
+
+Embedding {microshift-short} containers in an `rpm-ostree` commit means that you can run a cluster in air-gapped, disconnected, or offline environments. You can embed {product-title} containers in a {op-system-ostree-first} image so that container engines do not need to pull images over a network from a container registry. Workloads can start up immediately without network connectivity.
+
+include::modules/microshift-embed-microshift-image-offline-deploy.adoc[leveloffset=+1]
+
+include::modules/microshift-embed-microshift-update-osbuilder-worker.adoc[leveloffset=+1]
+
+include::modules/microshift-embed-microshift-build-image.adoc[leveloffset=+1]
+
+include::modules/microshift-adding-service-to-blueprint.adoc[leveloffset=+2]
+
+include::modules/microshift-creating-ostree-iso.adoc[leveloffset=+2]
+
+[id="additional-resources_microshift-embed-microshift-offline-deployments_{context}"]
+[role="_additional-resources"]
+== Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image_composing-a-customized-rhel-system-image#con_the-container-registry-credentials_assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image[Pushing a container to a registry and embedding it into an image]
+* link:https://www.osbuild.org/guides/image-builder-on-premises/container-auth.html[Container registry credentials]

modules/microshift-creating-ostree-iso.adoc

@@ -5,15 +5,15 @@
 
 :_content-type: PROCEDURE
 [id="microshift-creating-ostree-iso_{context}"]
-= Creating the {op-system-ostree-first} image
+= Creating the {op-system-ostree} image
 
-Use the following procedure to create the ISO. The {op-system-ostree} Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded OSTree commit.
+Use the following procedure to create the ISO. The {op-system-ostree} Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded `rpm-ostree` commit.
 
 .Prerequisites
 * Your build host meets the Image Builder system requirements.
 * You have installed and set up Image Builder and the `composer-cli` tool.
 * You have root-user access to your build host.
-* You have the `podman` tool.
+* You have installed the `podman` tool.
 
 .Procedure
 

modules/microshift-embed-microshift-build-image.adoc

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embed-microshift-offline-deploy.adoc
+
+:_content-type: CONCEPT
+[id="microshift-embed-microshift-build-image-offline-deployment_{context}"]
+= Build and use the rpm-ostree image for offline deployments
+
+You can use Image Builder to create `rpm-ostree` system images with embedded {microshift-short} container images. To embed container images, you must add the image references to your Image Builder blueprint. You can create the commit and ISO as needed for your use case.
+
+Add the prerequisites listed here to the ones that are included in the procedures that follow.
+
+[id="microshift-embed-microshift-build-image-offline-deployment-prereqs_{context}"]
+== Additional prerequisites for offline deployments
+
+* You have created and updated a {op-system-ostree} image blueprint for offline use. The following procedures use the example of a blueprint created with container images. You must use the updated blueprint you created in the "Embedding MicroShift containers for offline deployments" procedure.
+* You have updated the `/etc/osbuild-worker/osbuild-worker.toml` configuration file for offline use.
+
+[IMPORTANT]
+====
+Replace `minimal-microshift.toml` in the following procedures with the name of the TOML you updated for offline use, <my_blueprint_name>.
+====

modules/microshift-embed-microshift-image-offline-deploy.adoc

@@ -0,0 +1,117 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embed-microshift-offline-deploy.adoc
+
+:_content-type: PROCEDURE
+[id="microshift-embed-microshift-image-offline-deployment_{context}"]
+= Embedding {microshift-short} containers for offline deployments
+
+You can use Image Builder to create `rpm-ostree` system images with embedded {microshift-short} container images. To embed container images, you must add the image references to your Image Builder blueprint.
+
+.Prerequisites
+
+* You have root-user access to your build host.
+* Your build host meets the Image Builder system requirements.
+* You have installed and set up Image Builder and the `composer-cli` tool.
+* You have created a {op-system-ostree} image blueprint.
+* You have installed jq.
+
+.Procedure
+
+. Get the exact list of container image references used by the {microshift-short} version you are deploying. You can either install the `microshift-release-info` RPM package by following step 2 or download and unpack the RPM by following step 3.
+
+. To install the `microshift-release-info` RPM package:
+
+.. Install the `microshift-release-info` RPM package by running the following command:
++
+[source,terminal]
+----
+$ sudo dnf install -y microshift-release-info-<release_version>
+----
+Replace `<release_version>` with the numerical value of the release you are deploying, using the entire version number, such as `4.14.0`.
+
+.. List the contents of the `/usr/share/microshift/release` directory to verify the presence of the release information files by running the following command:
++
+[source,terminal]
+----
+$ ls /usr/share/microshift/release
+----
++
+.Example output
+[source,terminal]
+----
+release-x86_64.json
+release-aarch64.json
+----
++
+If you installed the `microshift-release-info` RPM, you can proceed to step 4.
+
+. If you did not complete step 2, download and unpack the `microshift-release-info` RPM without installing it:
+
+.. Download the RPM package by running the following command:
++
+[source,terminal]
+----
+$ sudo dnf download microshift-release-info-<release_version>
+----
+Replace `<release_version>` with the numerical value of the release you are deploying, using the entire version number, such as `4.14.0`.
++
+.Example rpm
+[source,terminal]
+----
+microshift-release-info-4.14.0.*.el9.noarch.rpm <1>
+----
+<1> The `*` represents the date and commit ID. Your output should contain both, for example `-202311101230.p0.g7dc6a00.assembly.4.14.0`.
+
+.. Unpack the RPM package without installing it by running the following command:
++
+[source,terminal]
+----
+$ rpm2cpio <my_microshift_release_info> | cpio -idmv <1>
+./usr/share/microshift/release/release-aarch64.json
+./usr/share/microshift/release/release-x86_64.json
+----
+<1> Replace `<my_microshift_release_info>` with the name of the RPM package from the previous step.
+
+. Define the location of your JSON file, which contains the container reference information, by running the following command:
++
+[source,terminal]
+----
+$ RELEASE_FILE=</path/to/your/release-$(uname -m).json>
+----
+Replace `</path/to/your/release-$(uname -m).json>` with the full path to your JSON file. Be sure to use the file needed for your architecture.
+
+. Define the location of your TOML file, which contains instructions for building the image, by running the following command:
++
+[source,terminal]
+----
+$ BLUEPRINT_FILE=</path/to/your/blueprint.toml>
+----
+Replace `</path/to/your/blueprint.toml>` with the full path to your JSON file.
+
+. Generate and then embed the container image references in your blueprint TOML file by running the following command:
++
+[source,terminal]
+----
+$  jq -r '.images | .[] | ("[[containers]]\nsource = \"" + . + "\"\n")' "${RELEASE_FILE}" >> "${BLUEPRINT_FILE}"
+----
++
+.Example resulting `<my_blueprint.toml>` fragment showing container references
+[source,terminal]
+----
+[[containers]]
+source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db"
+
+[[containers]]
+source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:82cfef91557f9a70cff5a90accba45841a37524e9b93f98a97b20f6b2b69e5db"
+----
+
+. You can manually embed any container image by adding it to the Image Builder blueprint using the following example:
++
+.Example section for manually embedding container image to Image Builder
+[source,terminal]
+----
+[[containers]]
+source = "<my_image_pullspec_with_tag_or_digest>"
+----
+Replace `<my_image_pullspec_with_tag_or_digest>` with the exact reference to a container image used by the {microshift-short} version you are deploying.

modules/microshift-embed-microshift-update-osbuilder-worker.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embed-microshift-offline-deploy.adoc
+
+:_content-type: PROCEDURE
+[id="microshift-embed-microshift-update-osbuilder-worker_{context}"]
+= Updating osbuilder worker configuration to prepare for image building
+
+After you have updated the blueprint, you must update the osbuilder worker configuration to prepare for building the image with embedded {microshift-short} containers.
+
+.Prerequisites
+
+* You have root-user access to your build host.
+* Your build host meets the Image Builder system requirements.
+* You have installed and set up Image Builder and the `composer-cli` tool.
+
+[NOTE]
+====
+You can create an `/etc/osbuild-worker/osbuild-worker.toml` directory and configuration file if they do not exist.
+====
+
+.Procedure
+
+. Add a pull secret for authenticating to the registry by setting the `auth_file_path` in the `[containers]` section of the `/etc/osbuild-worker/osbuild-worker.toml` osbuilder worker configuration file:
++
+[source,terminal]
+----
+[containers]
+auth_file_path = "/etc/osbuild-worker/pull-secret.json"
+----
+
+. Restart the `osbuild-worker` to apply configuration changes by restarting the host. Restarting the host ensures that all `osbuild-worker` services currently running are restarted.