Merge pull request #63911 from ShaunaDiaz/OSDOCS-4558

michaelryanpeter · web-flow · commit 14f41e996e39 · 2023-09-20T16:35:45.000-04:00
OSDOCS-4558: embedding apps for microshift
diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml
@@ -157,6 +157,12 @@ Name: Running applications
 Dir: microshift_running_apps
 Distros: microshift
 Topics:
+- Name: Embedded applications on RHEL for Edge
+  File: microshift-embedded-apps-on-rhel-edge
+- Name: Embedding applications for offline use
+  File: microshift-embed-apps-offline-use
+- Name: Embedding applications tutorial
+  File: microshift-embedding-apps-tutorial
 - Name: Application deployment
   File: microshift-applications
 - Name: Operators
diff --git a/microshift_running_apps/microshift-embed-apps-offline-use.adoc b/microshift_running_apps/microshift-embed-apps-offline-use.adoc
@@ -0,0 +1,26 @@
+:_content-type: ASSEMBLY
+[id="microshift-embed-apps-offline-use"]
+= Embedding {product-title} applications for offline use
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-embed-apps-offline-use
+
+toc::[]
+
+You can embed microservices-based workloads and applications in a {op-system-ostree-first} image. This allows users to run a {product-title} cluster in air-gapped, disconnected, or offline environment.
+
+include::modules/microshift-embed-images-offline-use.adoc[leveloffset=+1]
+
+//additional resources for embedding images for offline use
+[id="Additional-resources_microshift-embed-apps-offline-use_{context}"]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../microshift_running_apps/microshift-embedded-apps-on-rhel-edge.adoc#microshift-embedded-apps-on-rhel-edge[Options for embedding {product-title} applications in a {op-system-ostree} image]
+
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-creating-ostree-iso_microshift-embed-in-rpm-ostree[Creating the {op-system-ostree} image]
+
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-add-blueprint-build-iso_microshift-embed-in-rpm-ostree[Add the blueprint to Image Builder and build the ISO]
+
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-download-iso-prep-for-use_microshift-embed-in-rpm-ostree[Download the ISO and prepare it for use]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index#upgrading_rhel_for_edge_systems[Upgrading {op-system-ostree} systems]
diff --git a/microshift_running_apps/microshift-embedded-apps-on-rhel-edge.adoc b/microshift_running_apps/microshift-embedded-apps-on-rhel-edge.adoc
@@ -0,0 +1,56 @@
+:_content-type: ASSEMBLY
+[id="microshift-embedded-apps-on-rhel-edge"]
+= Options for embedding {product-title} applications in a {op-system-ostree} image
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-embedded-apps-on-rhel-edge
+
+toc::[]
+
+You can embed microservices-based workloads and applications in a {op-system-ostree-first} image to run in a {product-title} cluster. Embedded applications can be installed directly on edge devices to run in air-gapped, disconnected, or offline environments.
+
+[id="microshift-add-app-RPMs-to-rpm-ostree-image_{context}"]
+== Adding application RPMs to an rpm-ostree image
+If you have an application that includes APIs, container images, and configuration files for deployment such as manifests, you can build application RPMs. You can then add the RPMs to your {op-system-ostree} system image.
+
+The following is an outline of the procedures to embed applications or workloads in an fully self-contained operating system image:
+
+* Build your own RPM that includes your application manifest.
+* Add the RPM to the blueprint you used to install {product-title}.
+* Add the workload container images to the same blueprint.
+* Create a bootable ISO.
+
+For a step-by-step tutorial about preparing and embedding applications in a {op-system-ostree} image, use the following tutorial:
+
+* xref:../microshift_running_apps/microshift-embedding-apps-tutorial.adoc#microshift-embedding-apps-tutorial[Embedding applications tutorial]
+
+[id="microshift-add-app-manifests-to-image_{context}"]
+== Adding application manifests to an image for offline use
+If you have a simple application that includes a few files for deployment such as manifests, you can add those manifests directly to a {op-system-ostree} system image.
+
+See the "Create a custom file blueprint customization" section of the following {op-system-ostree} documentation for an example:
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#image-customizations_composing-a-rhel-for-edge-image-using-image-builder-command-line[Create a custom file blueprint customization]
+
+[id="microshift-embed-apps-for-offline-use_{context}"]
+== Embedding applications for offline use
+If you have an application that includes more than a few files, you can embed the application for offline use. See the following procedure:
+
+* xref:../microshift_running_apps/microshift-embed-apps-offline-use.adoc#microshift-embed-apps-offline-use[Embedding applications for offline use]
+
+//additional resources for assembly
+[id="additional-resources_microshift-embed-apps-on-rhel-edge_{context}"]
+[role="_additional-resources"]
+== Additional resources
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-embed-in-rpm-ostree[Embedding {product-title} in an RPM-OSTree image]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing {op-system-ostree} images]
+
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#preparing-for-image-building_microshift-embed-in-rpm-ostree[Preparing for image building]
+
+* link:https://cloud.redhat.com/blog/meet-red-hat-device-edge-with-microshift[Meet Red Hat Device Edge]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images[Composing a RHEL for Edge image using image builder command-line]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#edge-image-builder-system-requirements_setting-up-image-builder[Image Builder system requirements]
+
+//* link:https://www.redhat.com/sysadmin/create-rpm-package[How to create a Linux RPM package]
diff --git a/microshift_running_apps/microshift-embedding-apps-tutorial.adoc b/microshift_running_apps/microshift-embedding-apps-tutorial.adoc
@@ -0,0 +1,44 @@
+:_content-type: ASSEMBLY
+[id="microshift-embedding-apps-tutorial"]
+= Embedding {product-title} applications tutorial
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-embedding-apps-tutorial
+
+toc::[]
+
+The following tutorial gives a detailed example of how to embed applications in a {op-system-ostree} image for use in a {product-title} cluster in various environments.
+
+include::modules/microshift-embed-app-rpms-tutorial.adoc[leveloffset=+1]
+
+include::modules/microshift-preparing-to-make-app-rpms.adoc[leveloffset=+2]
+
+include::modules/microshift-building-apps-rpms.adoc[leveloffset=+2]
+
+include::modules/microshift-adding-app-rpms-to-blueprint.adoc[leveloffset=+2]
+
+//additional resources for adding app rpms to blueprint
+[role="_additional-resources"]
+.Additional resources
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#doc-wrapper[Composing a {op-system-ostree} image using the Image Builder CLI]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#network_based_deployments_workflow[Network-based deployments workflow]
+
+//additional resources for assembly
+[id="additional-resources_microshift-embedding-apps-tutorial_{context}"]
+[role="_additional-resources"]
+== Additional resources
+* xref:../microshift_running_apps/microshift-embed-apps-offline-use.adoc#microshift-embed-apps-offline-use[Embedding applications for offline use]
+
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-embed-in-rpm-ostree[Embedding {product-title} in an RPM-OSTree image]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing {op-system-ostree} images]
+
+* xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#preparing-for-image-building_microshift-embed-in-rpm-ostree[Preparing for image building]
+
+* link:https://cloud.redhat.com/blog/meet-red-hat-device-edge-with-microshift[Meet Red Hat Device Edge with {product-title}]
+
+* link:https://www.redhat.com/sysadmin/create-rpm-package[How to create a Linux RPM package]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images[Composing a {op-system-ostree} image using image builder command-line]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#edge-image-builder-system-requirements_setting-up-image-builder[Image Builder system requirements]
diff --git a/modules/microshift-adding-app-rpms-to-blueprint.adoc b/modules/microshift-adding-app-rpms-to-blueprint.adoc
@@ -0,0 +1,86 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embedding-apps-tutorial.adoc
+
+:_content-type: PROCEDURE
+[id="microshift-adding-app-rpms-to-blueprint_{context}"]
+= Adding application RPMs to a blueprint
+
+To add application RPMs to a blueprint, you must create a local repository that Image Builder can use to create the ISO. With this procedure, the required container images for your workload can be pulled over the network.
+
+.Prerequisites
+
+* You have root access to the host.
+* Workload or application RPMs exist in the `~/rpmbuild/RPMS` directory.
+
+.Procedure
+
+. Create a local RPM repository by running the following command:
++
+[source,terminal]
+----
+$ createrepo ~/rpmbuild/RPMS/
+----
+
+. Give Image Builder access to the RPM repository by running the following command:
++
+[source,terminal]
+----
+$ sudo chmod a+rx ~
+----
++
+[NOTE]
+====
+You must ensure that Image Builder has all of the necessary permissions to access all of the files needed for image building, or the build cannot proceed.
+====
++
+. Create the blueprint file, `repo-local-rpmbuild.toml` using the following template:
++
+[source,toml]
+----
+id = "local-rpm-build"
+name = "RPMs build locally"
+type = "yum-baseurl"
+url = "file://<path>/rpmbuild/RPMS" <1>
+check_gpg = false
+check_ssl = false
+system = false
+----
+<1> Specify part of the path to create a location that you choose. Use this path in the later commands to set up the repository and copy the RPMs.
+
+. Add the repository as a source for Image Builder by running the following command:
++
+[source,terminal]
+----
+$ sudo composer-cli sources add repo-local-rpmbuild.toml
+----
+
+. Add the RPM to your blueprint, by adding the following lines:
++
+[source,toml]
+----
+…
+[[packages]]
+name = "<application_workload_manifests>" <1>
+version = "*"
+…
+----
+<1> Add the name of your workload here.
+
+. Push the updated blueprint to Image Builder by running the following command:
++
+[source,terminal]
+----
+$ sudo composer-cli blueprints push repo-local-rpmbuild.toml
+----
+
+. At this point, you can either run Image Builder to create the ISO, or embed the container images for offline use.
+
+.. To create the ISO, start Image Builder by running the following command:
++
+[source,terminal]
+----
+$ sudo composer-cli compose start-ostree repo-local-rpmbuild edge-commit
+----
+
+In this scenario, the container images are pulled over the network by the edge device during startup.
diff --git a/modules/microshift-building-apps-rpms.adoc b/modules/microshift-building-apps-rpms.adoc
@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embedding-apps-tutorial.adoc
+
+:_content-type: PROCEDURE
+[id="microshift-building-apps-rpms_{context}"]
+= Building the RPM package for the application manifests
+
+To building your own RPMs, you must create a spec file that adds the application manifests to the RPM package. The following is an example procedure. As long as the application RPMs and other elements needed for image building are accessible to Image Builder, you can use the method that you prefer.
+
+.Prerequisites
+* You have set up a {op-system-ostree-first} {op-system-version} build host that meets the Image Builder system requirements.
+* You have root access to the host.
+* The file tree required to build RPM packages was created.
+
+.Procedure
+
+. In the `~/rpmbuild/SPECS` directory, create a file such as `<application_workload_manifests.spec>` using the following template:
++
+.Example `.spec` file
+[source,terminal]
+----
+Name: <application_workload_manifests>
+Version: 0.0.1
+Release: 1%{?dist}
+Summary: Adds workload manifests to microshift
+BuildArch: noarch
+License: GPL
+Source0: %{name}-%{version}.tar.gz
+#Requires: microshift
+%description
+Adds workload manifests to microshift
+%prep
+%autosetup
+%install <1>
+rm -rf $RPM_BUILD_ROOT
+mkdir -p $RPM_BUILD_ROOT/%{_prefix}/lib/microshift/manifests
+cp -pr ~/manifests $RPM_BUILD_ROOT/%{_prefix}/lib/microshift/
+%clean
+rm -rf $RPM_BUILD_ROOT
+
+%files
+%{_prefix}/lib/microshift/manifests/**
+%changelog
+* <DDD MM DD YYYY username@domain - V major.minor.patch>
+- <your_change_log_comment>
+----
+<1> The `%install` section creates the target directory inside the RPM package, `/usr/lib/microshift/manifests/`
+and copies the manifests from the source home directory, `~/manifests`.
++
+[IMPORTANT]
+====
+All of the required YAML files must be in the source home directory `~/manifests`, including a `kustomize.yaml` file if you are using kustomize.
+====
+
+. Build your RPM package in the `~/rpmbuild/RPMS` directory by running the following command:
++
+[source,terminal]
+----
+$ rpmbuild -bb ~/rpmbuild/SPECS/<application_workload_manifests.spec>
+----
diff --git a/modules/microshift-embed-app-rpms-tutorial.adoc b/modules/microshift-embed-app-rpms-tutorial.adoc
@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embedding-apps-tutorial.adoc
+
+:_content-type: CONCEPT
+[id="microshift-embed-app-rpms-tutorial_{context}"]
+= Embed application RPMs tutorial
+
+The following tutorial reviews the {product-title} installation steps and adds a description of the workflow for embedding applications. If you are already familiar with `rpm-ostree` systems such as {op-system-ostree-first} and {product-title}, you can go straight to the procedures.
+
+[id="microshift-installation-workflow-review"]
+== Installation workflow review
+Embedding applications requires a similar workflow to embedding {product-title} into a {op-system-ostree} image. Reviewing those steps can help you understand the steps needed to embed an application:
+//larger concept image here
+
+. To embed {product-title} on {op-system-ostree}, you added the {product-title} repositories to Image Builder.
+
+. You created a blueprint that declared all the RPMs, container images, files and customizations you needed, including the addition of {product-title}.
+
+. You added the blueprint to Image Builder and ran a build with the Image Builder CLI tool (`composer-cli`). This step created `rpm-ostree` commits, which were used to create the container image. This image contained {op-system-ostree}.
+
+. You added the installer blueprint to Image Builder to create an `rpm-ostree` image (ISO) to boot from. This build contained both {op-system-ostree} and {product-title}.
+
+. You downloaded the ISO with {product-title} embedded, prepared it for use, provisioned it, then installed it onto your edge devices.
+
+[id="microshift-embed-app-rpms-workflow"]
+== Embed application RPMs workflow
+
+After you have set up a build host that meets the Image Builder requirements, you can add your application in the form of a directory of manifests to the image. After those steps, the simplest way to embed your application or workload into a new ISO is to create your own RPMs that include the manifests. Your application RPMs contain all of the configuration files describing your deployment.
+
+The following procedures use the `rpmbuild` tool to create a `.spec` file and local repository. The `.spec` file defines how the package is built, moving your application manifests to the correct location inside the RPM package for {product-title} to pick them up. That RPM package is then embedded in the ISO.
+
+//rpm workflow image here
diff --git a/modules/microshift-embed-images-offline-use.adoc b/modules/microshift-embed-images-offline-use.adoc
@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// microshift_running_applications/embed-microshift-apps-on-rhel-edge.adoc
+
+:_content-type: PROCEDURE
+[id="microshift-embed-images-offline-use_{context}"]
+= Embedding workload container images for offline use
+
+To embed container images in devices at the edge that do not have any network connection, you must create a new container, mount the ISO, and then copy the contents into the file system.
+
+.Prerequisites
+
+* You have root access to the host.
+* Application RPMs have been added to a blueprint.
+
+.Procedure
+
+. Render the manifests, extract all of the container image references, and translate the application image to blueprint container sources by running the following command:
++
+[source,terminal]
+----
+$ oc kustomize ~/manifests | grep "image:" | grep -oE '[^ ]+$' | while read line; do echo -e "[[containers]]\nsource = \"${line}\"\n"; done >><my_blueprint>.toml
+----
+
+. Push the updated blueprint to Image Builder by running the following command:
++
+[source, terminal]
+----
+$ sudo composer-cli blueprints push <my_blueprint>.toml
+----
+
+. If your workload containers are located in a private repository, you must provide Image Builder with the necessary pull secrets:
+
+.. Set the `auth_file_path` in the `[containers]` section of the `osbuilder worker` configuration in the `/etc/osbuild-worker/osbuild-worker.toml` file to point to the pull secret.
+
+.. If needed, create a directory and file for the pull secret, for example:
++
+.Example directory and file
++
+[source,terminal]
+----
+[containers]
+auth_file_path = "/<path>/pull-secret.json" <1>
+----
+<1> Use the custom location previously set for copying and retrieving images.
+
+. Build the container image by running the following command:
++
+[source,terminal]
+----
+$ sudo composer-cli compose start-ostree <my_blueprint> edge-commit
+----
+
+. Proceed with your preferred `rpm-ostree` image flow, such as waiting for the build to complete, exporting the image and integrating it into your `rpm-ostree` repository or creating a bootable ISO.
diff --git a/modules/microshift-preparing-to-make-app-rpms.adoc b/modules/microshift-preparing-to-make-app-rpms.adoc
