From 674b5be0d533b2a493e1d38d0f9c074dcbe55485 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Tue, 11 Nov 2025 15:11:02 -0500 Subject: [PATCH 1/5] OSDOCS-15566: adds rhel10 notes to install docs --- .../microshift-update-rpms-ostree.adoc | 2 +- ...hift-embed-microshift-image-offline-deploy.adoc | 2 ++ modules/microshift-updating-rpms-ostree.adoc | 2 ++ snippets/microshift-power-loss-embed-images.adoc | 2 +- snippets/microshift-rhel10-bootc-not-osbuild.adoc | 14 ++++++++++++++ 5 files changed, 20 insertions(+), 2 deletions(-) create mode 100644 snippets/microshift-rhel10-bootc-not-osbuild.adoc diff --git a/microshift_updating/microshift-update-rpms-ostree.adoc b/microshift_updating/microshift-update-rpms-ostree.adoc index 04fc12a2d936..6925b07955e4 100644 --- a/microshift_updating/microshift-update-rpms-ostree.adoc +++ b/microshift_updating/microshift-update-rpms-ostree.adoc @@ -8,7 +8,7 @@ include::_attributes/attributes-microshift.adoc[] toc::[] [role="_abstract"] -You can update {microshift-short} on {op-system-ostree-first} by embedding the new version of {microshift-short} on a new operating system image. +You can update {microshift-short} on {op-system-ostree-first} {rhel-major} by embedding the new version of {microshift-short} on a new operating system image. include::modules/microshift-updates-rpms-ostree-con.adoc[leveloffset=+1] diff --git a/modules/microshift-embed-microshift-image-offline-deploy.adoc b/modules/microshift-embed-microshift-image-offline-deploy.adoc index d64a02fa1ac0..27f78624a939 100644 --- a/modules/microshift-embed-microshift-image-offline-deploy.adoc +++ b/modules/microshift-embed-microshift-image-offline-deploy.adoc @@ -11,6 +11,8 @@ You can use image builder to create {op-system-ostree} images with embedded {mic include::snippets/microshift-power-loss-embed-images.adoc[leveloffset=1] +include::snippets/microshift-rhel10-bootc-not-osbuild.adoc[leveloffset=1] + .Prerequisites * You have root-user access to your build host. diff --git a/modules/microshift-updating-rpms-ostree.adoc b/modules/microshift-updating-rpms-ostree.adoc index 836e2b3ba3f5..3b33ea3af65b 100644 --- a/modules/microshift-updating-rpms-ostree.adoc +++ b/modules/microshift-updating-rpms-ostree.adoc @@ -9,6 +9,8 @@ [role="_abstract"] To update {microshift-short} on {op-system-ostree-first}, embed the new version of {microshift-short} on a new operating system image. +include::snippets/microshift-rhel10-bootc-not-osbuild.adoc[leveloffset=1] + .Prerequisites * The system requirements for installing {microshift-short} have been met. diff --git a/snippets/microshift-power-loss-embed-images.adoc b/snippets/microshift-power-loss-embed-images.adoc index 81bf7b08fcc6..d7e011da4510 100644 --- a/snippets/microshift-power-loss-embed-images.adoc +++ b/snippets/microshift-power-loss-embed-images.adoc @@ -1,6 +1,6 @@ // Text snippet included in the following modules: // -// * modules/ +// * modules/microshift-embed-microshift-image-offline-deployment.adoc // * modules/ :_mod-docs-content-type: SNIPPET diff --git a/snippets/microshift-rhel10-bootc-not-osbuild.adoc b/snippets/microshift-rhel10-bootc-not-osbuild.adoc new file mode 100644 index 000000000000..48ec2e1b096a --- /dev/null +++ b/snippets/microshift-rhel10-bootc-not-osbuild.adoc @@ -0,0 +1,14 @@ +// Text snippet included in the following modules: +// +// * modules/microshift-embed-microshift-image-offline-deployment.adoc +// * modules/ + +:_mod-docs-content-type: SNIPPET + + +[IMPORTANT] +==== +This procedure is for use with {op-system-base} 9 images only. {op-system-base} 10 images require bootc image building tools. For more information, see the following link: + +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/10/html/composing_installing_and_managing_rhel_for_edge_images/index +==== From afa405b80e2136a3322f10f88093acb84f41bffa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Thu, 13 Nov 2025 15:03:36 -0500 Subject: [PATCH 2/5] OSDOCS-15566: adds minimum DITA compliance --- .../microshift-rhel-kickstarts.adoc | 1 + ...shift-embed-in-rpm-ostree-offline-use.adoc | 6 ++- .../microshift-embed-in-rpm-ostree.adoc | 46 ++++--------------- .../microshift-update-rpms-manually.adoc | 7 +-- ...ft-about-offline-deployment-rhel-edge.adoc | 13 ++++++ .../microshift-accessing-node-locally.adoc | 1 + ...croshift-accessing-node-open-firewall.adoc | 5 +- .../microshift-accessing-node-remotely.adoc | 13 ++++-- modules/microshift-accessing.adoc | 1 + ...ft-adding-other-packages-to-blueprint.adoc | 31 ++++++++----- ...roshift-adding-repos-to-image-builder.adoc | 11 ++++- ...icroshift-adding-service-to-blueprint.adoc | 15 +++--- .../microshift-ca-adding-bundle-ostree.adoc | 9 ++-- modules/microshift-creating-ostree-iso.adoc | 11 +++-- .../microshift-embed-kickstart-in-iso.adoc | 11 ++++- ...croshift-embed-microshift-build-image.adoc | 5 +- ...embed-microshift-image-offline-deploy.adoc | 1 + ...ft-embed-registry-auth-image-building.adoc | 9 ++-- ...croshift-preparing-for-image-building.adoc | 15 ++++-- modules/microshift-updates-rpms-con.adoc | 18 ++++++++ .../microshift-updates-rpms-ostree-con.adoc | 6 ++- 21 files changed, 147 insertions(+), 88 deletions(-) create mode 100644 modules/microshift-about-offline-deployment-rhel-edge.adoc create mode 100644 modules/microshift-updates-rpms-con.adoc diff --git a/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc b/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc index 936f60212ab6..5b67f250c5e7 100644 --- a/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc +++ b/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc @@ -2,6 +2,7 @@ include::_attributes/attributes-microshift.adoc[] [id="microshift-rhel-kickstarts"] = Using Kickstart files for installing {microshift-short} in {op-system-base} + :context: microshift-rhel-kickstarts toc::[] diff --git a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc index dcf5bec83ea1..ecfcf3615a92 100644 --- a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc +++ b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc @@ -2,11 +2,15 @@ include::_attributes/attributes-microshift.adoc[] [id="microshift-embed-in-rpm-ostree-for-offline-use"] = Embedding in a {op-system-ostree} image for offline use + :context: microshift-embed-rpm-ostree-offline-use toc::[] -Embedding {microshift-short} containers in an `rpm-ostree` commit means that you can run a node 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 immediately without network connectivity. +[role="_abstract"] +You can embed {microshift-short} in a container by using {op-system-base-full} for fully offline deployments. + +include::modules/microshift-about-offline-deployment-rhel-edge.adoc[leveloffset=+1] include::modules/microshift-embed-microshift-image-offline-deploy.adoc[leveloffset=+1] diff --git a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc index 780701bd04dd..c9bf16508d53 100644 --- a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc +++ b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc @@ -2,11 +2,13 @@ include::_attributes/attributes-microshift.adoc[] [id="microshift-embed-in-rpm-ostree"] = Embedding in a {op-system-ostree} image using image builder + :context: microshift-embed-in-rpm-ostree toc::[] -Use this guide to build a {op-system-base} image containing {microshift-short}. +[role="_abstract"] +You can build a {op-system-base} image containing {microshift-short}. include::modules/microshift-preparing-for-image-building.adoc[leveloffset=+1] @@ -14,35 +16,14 @@ include::modules/microshift-embed-ostree-enable-eus-repos.adoc[leveloffset=+1] include::modules/microshift-adding-repos-to-image-builder.adoc[leveloffset=+1] -[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/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image builder system requirements] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-installing-image-builder_setting-up-image-builder[Installing image builder] - include::modules/microshift-adding-service-to-blueprint.adoc[leveloffset=+1] include::modules/microshift-adding-other-packages-to-blueprint.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources -* link:https://osbuild.org/docs/user-guide/blueprint-reference[Blueprint Reference] -* 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[Creating a {op-system-ostree} Container blueprint using image builder CLI] -* link:https://osbuild.org/docs/on-premises/commandline/building-ostree-images[Building OSTree image] -* link:https://podman.io/docs/installation[Installing Podman] - include::modules/microshift-ca-adding-bundle.adoc[leveloffset=+1] include::modules/microshift-ca-adding-bundle-ostree.adoc[leveloffset=+2] -[role="_additional-resources"] -.Additional resources -* xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-creating-ostree-iso_microshift-embed-in-rpm-ostree[Creating the {op-system-ostree} image] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks[Using Shared System Certificates ({op-system-base} 9)] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-system-images-with-composer-command-line-interface_composing-a-customized-rhel-system-image#image-customizations_creating-system-images-with-composer-command-line-interface[Supported image customizations ({op-system-base} 9)] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/creating-and-managing-ostree-image-updates_composing-installing-managing-rhel-for-edge-images[Creating and managing OSTree image updates] -* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system] - include::modules/microshift-creating-ostree-iso.adoc[leveloffset=+1] include::modules/microshift-add-blueprint-build-iso.adoc[leveloffset=+1] @@ -51,24 +32,15 @@ include::modules/microshift-download-iso-prep-for-use.adoc[leveloffset=+1] include::modules/microshift-embed-kickstart-in-iso.adoc[leveloffset=+2] +[id="additional-resources_microshift-embed-in-rpm-ostree"] [role="_additional-resources"] -.Additional resources - -* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images] +== Additional resources +* xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-creating-ostree-iso_microshift-embed-in-rpm-ostree[Creating the {op-system-ostree} image] +* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system] * xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing {microshift-short}] -* link:https://console.redhat.com/openshift/install/pull-secret[Red Hat Hybrid Cloud Console pull secret] * xref:../microshift_networking/microshift-firewall.adoc#microshift-firewall-req-settings_microshift-firewall[Required firewall settings] * xref:../microshift_install_kickstarts/microshift-rhel-kickstarts.adoc#microshift-rhel-kickstarts[Using Kickstart files for embedding {microshift-short} in {op-system-base} installation] -* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/creating-kickstart-files_rhel-installer[Creating Kickstart files] -* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/kickstart-script-file-format-reference_rhel-installer#kickstart-file-format_kickstart-script-file-format-reference[A.1. Kickstart file format] -* link:https://access.redhat.com/solutions/60959[How to embed a Kickstart file into an ISO image] +* link:https://console.redhat.com/openshift/install/pull-secret[Red Hat Hybrid Cloud Console pull secret] +* xref:../microshift_install_rpm/microshift-access-node.adoc[Accessing the {microshift-short} node with oc] //Add modules about using the VM and getting the ISO up and running, then starting MicroShift... - -include::modules/microshift-accessing.adoc[leveloffset=+1] - -include::modules/microshift-accessing-node-locally.adoc[leveloffset=+2] - -include::modules/microshift-accessing-node-open-firewall.adoc[leveloffset=+2] - -include::modules/microshift-accessing-node-remotely.adoc[leveloffset=+2] diff --git a/microshift_updating/microshift-update-rpms-manually.adoc b/microshift_updating/microshift-update-rpms-manually.adoc index 8817cf496ec8..48d65c0bccd4 100644 --- a/microshift_updating/microshift-update-rpms-manually.adoc +++ b/microshift_updating/microshift-update-rpms-manually.adoc @@ -8,12 +8,9 @@ include::_attributes/attributes-microshift.adoc[] toc::[] [role="_abstract"] -Updating {product-title} for non-image-based {op-system-base-full} systems requires updating the RPMs. For patch releases, such as {product-version}.1 to {product-version}.2, simply update the RPMs. For minor-version release updates, add the step of enabling the update repository by using your subscription manager. +You can update {microshift-short} or {op-system-bundle} manually using RPMs. -[NOTE] -==== -You can back up application data as needed and move the data copy to a secure location when using any update type. -==== +include::modules/microshift-updates-rpms-con.adoc[leveloffset=+1] include::modules/microshift-updating-rpms-z.adoc[leveloffset=+1] diff --git a/modules/microshift-about-offline-deployment-rhel-edge.adoc b/modules/microshift-about-offline-deployment-rhel-edge.adoc new file mode 100644 index 000000000000..75f435bb9c95 --- /dev/null +++ b/modules/microshift-about-offline-deployment-rhel-edge.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// microshift_running_applications/embed-microshift-offline-deploy.adoc +// microshift_install_rpm_ostree/microshift-embed-rpm-ostree-offline-use.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-about-offline-deployment-rhel-edge_{context}"] += About offline deployments with {op-system-ostree} + +[role="_abstract"] +Embedding {microshift-short} containers in an `rpm-ostree` commit means that you can run a node in 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 immediately without network connectivity. diff --git a/modules/microshift-accessing-node-locally.adoc b/modules/microshift-accessing-node-locally.adoc index 061c0da0c437..06cd1366e5cb 100644 --- a/modules/microshift-accessing-node-locally.adoc +++ b/modules/microshift-accessing-node-locally.adoc @@ -8,6 +8,7 @@ [id="accessing-microshift-node-locally_{context}"] = Accessing the {microshift-short} node locally +[role="_abstract"] Use the following procedure to access the {microshift-short} node locally by using a `kubeconfig` file. .Prerequisites diff --git a/modules/microshift-accessing-node-open-firewall.adoc b/modules/microshift-accessing-node-open-firewall.adoc index fbe994e023f2..0f6fe4df338a 100644 --- a/modules/microshift-accessing-node-open-firewall.adoc +++ b/modules/microshift-accessing-node-open-firewall.adoc @@ -8,7 +8,8 @@ [id="microshift-accessing-node-open-firewall_{context}"] = Opening the firewall for remote access to the {microshift-short} node -Use the following procedure to open the firewall so that a remote user can access the {microshift-short} service. You must complete this procedure before a workstation user can access the node remotely. +[role="_abstract"] +You must open the firewall before a workstation user can access the {microshift-short} node remotely. For this procedure, `user@microshift` is the user on the {microshift-short} host machine and is responsible for setting up that machine so that it can be accessed by a remote user on a separate workstation. @@ -32,4 +33,4 @@ For this procedure, `user@microshift` is the user on the {microshift-short} host + -- include::snippets/microshift-healthy-pods-snip.adoc[leveloffset=+2] --- \ No newline at end of file +-- diff --git a/modules/microshift-accessing-node-remotely.adoc b/modules/microshift-accessing-node-remotely.adoc index e366d34b0287..2e6c5acfc46c 100644 --- a/modules/microshift-accessing-node-remotely.adoc +++ b/modules/microshift-accessing-node-remotely.adoc @@ -8,7 +8,8 @@ [id="accessing-microshift-node-remotely_{context}"] = Accessing the {microshift-short} node remotely -Use the following procedure to access the {microshift-short} service from a remote location by using a `kubeconfig` file. +[role="_abstract"] +Access the {microshift-short} service from a remote location by using a `kubeconfig` file. The `user@workstation` login is used to access the host machine remotely. The `` value in the procedure is the name of the user that `user@workstation` logs in with to the {microshift-short} host. @@ -31,17 +32,19 @@ The `user@workstation` login is used to access the host machine remotely. The `< + [source,terminal,subs="+quotes"] ---- -[user@workstation]$ MICROSHIFT_MACHINE=__ # <1> +[user@workstation]$ MICROSHIFT_MACHINE=__ ---- -<1> Replace the value, _<{microshift-short}_hostname>_, with the either the name or the IP address of the host running {microshift}. ++ +Replace the value, _<{microshift-short}_hostname>_, with the either the name or the IP address of the host running {microshift}. . As `user@workstation`, copy the generated `kubeconfig` file that contains the hostname or IP address you want to connect to from the {op-system-base} machine running {microshift-short} to your local machine by running the following command: + [source,terminal,subs="+quotes"] ---- -[user@workstation]$ ssh __@$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/$MICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config # <1> +[user@workstation]$ ssh __@$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/$MICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config # ---- -<1> Replace __ with your SSH login credentials. ++ +Replace __ with your SSH login credentials. . As `user@workstation`, update the permissions on your `~/.kube/config` file by running the following command: + diff --git a/modules/microshift-accessing.adoc b/modules/microshift-accessing.adoc index 4eec7890718a..b6bc3489ed1c 100644 --- a/modules/microshift-accessing.adoc +++ b/modules/microshift-accessing.adoc @@ -7,6 +7,7 @@ [id="accessing-microshift-node_{context}"] = How to access the {microshift-short} node +[role="_abstract"] Access the {microshift-short} service by using the {oc-first}. * You can access the node from either the same machine running the {microshift-short} service or from a remote location. diff --git a/modules/microshift-adding-other-packages-to-blueprint.adoc b/modules/microshift-adding-other-packages-to-blueprint.adoc index 4406f9563b73..b97b71b75d77 100644 --- a/modules/microshift-adding-other-packages-to-blueprint.adoc +++ b/modules/microshift-adding-other-packages-to-blueprint.adoc @@ -6,6 +6,7 @@ [id="microshift-adding-other-services-to-blueprint_{context}"] = Adding other packages to a blueprint +[role="_abstract"] Add the references for optional RPM packages to your `ostree` blueprint to enable them. .Prerequisites @@ -16,28 +17,34 @@ Add the references for optional RPM packages to your `ostree` blueprint to enabl . Edit your `ostree` blueprint by running the following command: + -[source,terminal] -[subs="+quotes"] +[source,terminal,subs="+quotes"] ---- -$ vi ____ <1> +$ vi ____ ---- -<1> Replace `__` with the name of the blueprint file used for the {microshift-short} service. ++ +Replace `__` with the name of the blueprint file used for the {microshift-short} service. . Add the following example text to your blueprint: + -[source,text] -[subs="+quotes"] +[source,text,subs="+quotes"] ---- -[[packages]] <1> -name = "____" <2> +[[packages]] +name = "____" version = "*" ---- -<1> Include one stanza for each additional service that you want to add. -<2> Replace `__` with the name the RPM for the service you want to include. For example, `microshift-olm`. ++ +* `[[packages]] name =` Include one stanza for each additional service that you want to add. For example, replace `__` in with the name the RPM for the service you want to include such as `microshift-olm`. Add another stanza as needed. .Next steps -. Add custom certificate authorities to the blueprint as needed. -. After you are done adding to your blueprint, you can apply the manifests to an active cluster by building a new `ostree` system and deploying it on the client: + +. Add custom certificate authorities to the blueprint as needed. For more information, see the following links: + +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks[Using Shared System Certificates ({op-system-base} 9)] +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-system-images-with-composer-command-line-interface_composing-a-customized-rhel-system-image#image-customizations_creating-system-images-with-composer-command-line-interface[Supported image customizations ({op-system-base} 9)] +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/creating-and-managing-ostree-image-updates_composing-installing-managing-rhel-for-edge-images[Creating and managing OSTree image updates] + +. After you finish adding to your blueprint, you can apply the manifests to an active node by building a new {op-system-ostree} system and deploying it on the client: + ** Create the ISO. ** Add the blueprint and build the ISO. ** Download the ISO and prepare it for use. diff --git a/modules/microshift-adding-repos-to-image-builder.adoc b/modules/microshift-adding-repos-to-image-builder.adoc index 3783db78058c..8e96a1d800af 100644 --- a/modules/microshift-adding-repos-to-image-builder.adoc +++ b/modules/microshift-adding-repos-to-image-builder.adoc @@ -78,4 +78,13 @@ appstream baseos fast-datapath {rpm-repo-version} ----- \ No newline at end of file +---- + +.Next steps + +* Create the blueprint. For more information, see the following links: + +** link:https://osbuild.org/docs/user-guide/blueprint-reference[Blueprint Reference] +** link:https://docs.redhat.com/en/documentation/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[Creating a {op-system-ostree} Container blueprint using image builder CLI] +** link:https://osbuild.org/docs/on-premises/commandline/building-ostree-images[Building OSTree image] +** link:https://podman.io/docs/installation[Installing Podman] diff --git a/modules/microshift-adding-service-to-blueprint.adoc b/modules/microshift-adding-service-to-blueprint.adoc index 38149d0e3eca..42598080f661 100644 --- a/modules/microshift-adding-service-to-blueprint.adoc +++ b/modules/microshift-adding-service-to-blueprint.adoc @@ -7,6 +7,7 @@ [id="adding-microshift-service-to-blueprint_{context}"] = Adding the {microshift-short} service to a blueprint +[role="_abstract"] Adding the {microshift-short} RPM package to an image builder blueprint enables the build of a {op-system-ostree} image with {microshift-short} embedded. .Procedure @@ -22,13 +23,13 @@ version = "0.0.1" modules = [] groups = [] -[[packages]] <1> +[[packages]] name = "microshift" version = "{ocp-version}.1" ... ... -[customizations.services] <2> +[customizations.services] enabled = ["microshift"] [customizations.firewall] @@ -36,7 +37,7 @@ ports = ["ssh"] ... ... -[[containers]] <3> +[[containers]] source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f41e79c17e8b41f1b0a5a32c3e2dd7cd15b8274554d3f1ba12b2598a347475f4" [[containers]] @@ -45,9 +46,9 @@ source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:dbc65f1fba7d92b3 … EOF ---- -<1> References for all non-optional {microshift-short} RPM packages using the same version compatible with the `microshift-release-info` RPM. -<2> References for automatically enabling {microshift-short} on system startup and applying default networking settings. -<3> References for all non-optional {microshift-short} container images necessary for an offline deployment. The SHA depends on the release you are using. +* `[[packages]] name = "microshift"`: references for all non-optional {microshift-short} RPM packages using the same version compatible with the `microshift-release-info` RPM. +* `[customizations.services] enabled = ["microshift"]`: references for automatically enabling {microshift-short} on system startup and applying default networking settings. +* `[[containers]] source = "quay.io/openshift-release-dev/...`: references for all non-optional {microshift-short} container images necessary for an offline deployment. The SHA depends on the release you are using. . Add the blueprint to the image builder by running the following command: + @@ -78,4 +79,4 @@ blueprint: microshift_blueprint v0.0.1 [source,terminal,subs="+quotes"] ---- $ sudo composer-cli blueprints depsolve microshift_blueprint ----- \ No newline at end of file +---- diff --git a/modules/microshift-ca-adding-bundle-ostree.adoc b/modules/microshift-ca-adding-bundle-ostree.adoc index 9c912abeee5d..87becac76172 100644 --- a/modules/microshift-ca-adding-bundle-ostree.adoc +++ b/modules/microshift-ca-adding-bundle-ostree.adoc @@ -2,11 +2,14 @@ // //* microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc - :_mod-docs-content-type: PROCEDURE [id="microshift-ca-adding-bundle-ostree_{context}"] -= Adding a certificate authority bundle to an rpm-ostree image -You can include additional trusted certificate authorities (CAs) to the {op-system-ostree-first} `rpm-ostree` image by adding them to the blueprint that you use to create the image. Using the following procedure sets up additional CAs to be trusted by the operating system when pulling images from an image registry. += Adding a certificate authority bundle to a blueprint + +[role="_abstract"] +You can include additional trusted certificate authorities (CAs) to the {op-system-ostree-first} `rpm-ostree` image by adding them to the blueprint that you use to create the image. + +Using the following procedure sets up additional CAs to be trusted by the operating system when pulling images from an image registry. [NOTE] ==== diff --git a/modules/microshift-creating-ostree-iso.adoc b/modules/microshift-creating-ostree-iso.adoc index 9ee4fc79bebe..d2f688220e06 100644 --- a/modules/microshift-creating-ostree-iso.adoc +++ b/modules/microshift-creating-ostree-iso.adoc @@ -7,7 +7,10 @@ [id="microshift-creating-ostree-iso_{context}"] = Creating the {op-system-ostree} image with image builder -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. +[role="_abstract"] +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 @@ -22,9 +25,9 @@ Use the following procedure to create the ISO. The {op-system-ostree} Installer + [source,terminal,subs="+quotes"] ---- -$ BUILDID=$(sudo composer-cli compose start-ostree --ref "rhel/{op-system-version-major}/$(uname -m)/edge" ____ edge-container | awk '/^Compose/ {print $2}') <1> +$ BUILDID=$(sudo composer-cli compose start-ostree --ref "rhel/{op-system-version-major}/$(uname -m)/edge" ____ edge-container | awk '/^Compose/ {print $2}') ---- -<1> Replace `__` with the name of your blueprint. +Replace `__` with the name of your blueprint. + This command also returns the identification (ID) of the build for monitoring. @@ -108,4 +111,4 @@ modules = [] groups = [] packages = [] EOF ----- \ No newline at end of file +---- diff --git a/modules/microshift-embed-kickstart-in-iso.adoc b/modules/microshift-embed-kickstart-in-iso.adoc index 5df45ea3b236..52d5a3b602b3 100644 --- a/modules/microshift-embed-kickstart-in-iso.adoc +++ b/modules/microshift-embed-kickstart-in-iso.adoc @@ -6,7 +6,16 @@ [id="microshift-embed-kickstart-iso_{context}"] = Embedding a Kickstart file in an ISO -You can use the Kickstart file provided with {microshift-short}, or you can update an existing {op-system-ostree} Installer (ISO) Kickstart file. When ready, embed the Kickstart file into the ISO. Your Kickstart file must include detailed instructions about how to create a user and how to fetch and deploy the {op-system-ostree} image. +[role="_abstract"] +You can use the Kickstart file provided with {microshift-short}, or you can update an existing {op-system-ostree} Installer (ISO) Kickstart file. + +When ready, embed the Kickstart file into the ISO. Your Kickstart file must include detailed instructions about how to create a user and how to fetch and deploy the {op-system-ostree} image. + +For information about Kickstarts, see the following links: + +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/creating-kickstart-files_rhel-installer[Creating Kickstart files] +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/kickstart-script-file-format-reference_rhel-installer#kickstart-file-format_kickstart-script-file-format-reference[A.1. Kickstart file format] +* link:https://access.redhat.com/solutions/60959[How to embed a Kickstart file into an ISO image] .Prerequisites diff --git a/modules/microshift-embed-microshift-build-image.adoc b/modules/microshift-embed-microshift-build-image.adoc index c4f58dfbd313..596f4c93c0d9 100644 --- a/modules/microshift-embed-microshift-build-image.adoc +++ b/modules/microshift-embed-microshift-build-image.adoc @@ -6,7 +6,10 @@ [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. +[role="_abstract"] +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. diff --git a/modules/microshift-embed-microshift-image-offline-deploy.adoc b/modules/microshift-embed-microshift-image-offline-deploy.adoc index 27f78624a939..d222b06ca6e6 100644 --- a/modules/microshift-embed-microshift-image-offline-deploy.adoc +++ b/modules/microshift-embed-microshift-image-offline-deploy.adoc @@ -7,6 +7,7 @@ [id="microshift-embed-microshift-image-offline-deployment_{context}"] = Embedding {microshift-short} containers for offline deployments +[role="_abstract"] You can use image builder to create {op-system-ostree} images with embedded {microshift-short} container images. To embed container images, you must add the image references to your image builder blueprint file. include::snippets/microshift-power-loss-embed-images.adoc[leveloffset=1] diff --git a/modules/microshift-embed-registry-auth-image-building.adoc b/modules/microshift-embed-registry-auth-image-building.adoc index 2d8f6b4f2dfb..6e390214874c 100644 --- a/modules/microshift-embed-registry-auth-image-building.adoc +++ b/modules/microshift-embed-registry-auth-image-building.adoc @@ -6,13 +6,16 @@ [id="microshift-embed-registry-auth-image-building_{context}"] = Adding registry authentication to prepare for image building -After you have updated the blueprint, you must add authentication for the container registries to build the image with embedded {microshift-short} containers. To do this, update one of the systemd service files that are part of the Image Builder configuration. +[role="_abstract"] +After you have updated the blueprint, you must add authentication for the container registries to build the image with embedded {microshift-short} containers. + +To do this, update one of the systemd service files that are part of the image builder configuration. .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. +* Your build host meets the image builder system requirements. +* You have installed and set up image builder and the `composer-cli` tool. [NOTE] ==== diff --git a/modules/microshift-preparing-for-image-building.adoc b/modules/microshift-preparing-for-image-building.adoc index a9a29a9a4985..4c301ce9402a 100644 --- a/modules/microshift-preparing-for-image-building.adoc +++ b/modules/microshift-preparing-for-image-building.adoc @@ -6,12 +6,19 @@ [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} node with your applications on a {op-system-ostree} virtual machine for development and testing first, then use your whole solution in edge production environments. +[role="_abstract"] +Use the image builder tool to compose customized {op-system-ostree-first} images optimized for edge deployments. + +You can run a {microshift-short} node with your applications on a {op-system-ostree} 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-ostree}: -* Read link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/introducing-rhel-for-edge-images_composing-installing-managing-rhel-for-edge-images[Introduction to RHEL for Edge images]. +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/introducing-rhel-for-edge-images_composing-installing-managing-rhel-for-edge-images[Introduction to RHEL for Edge images] + +* To build an {op-system-ostree-first} {op-system-version} image for a given CPU architecture, you need a {op-system-base} {op-system-version} build host of the same CPU architecture that meets the image builder system requirements. See the following link for more information: + +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image builder system requirements] -* To build an {op-system-ostree-first} {op-system-version} image for a given CPU architecture, you need a {op-system-base} {op-system-version} build host of the same CPU architecture that meets the link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image builder system requirements]. +* To install image builder and the `composer-cli` tool, use the following instructions: -* Follow the instructions in link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-installing-image-builder_setting-up-image-builder[Installing image builder] to install image builder and the `composer-cli` tool. +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-installing-image-builder_setting-up-image-builder[Installing image builder] diff --git a/modules/microshift-updates-rpms-con.adoc b/modules/microshift-updates-rpms-con.adoc new file mode 100644 index 000000000000..9311dea7c48f --- /dev/null +++ b/modules/microshift-updates-rpms-con.adoc @@ -0,0 +1,18 @@ +//Module included in the following assemblies: +// +//* microshift_updating/microshift-update-rpms.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-updates-rpms-con_{context}"] += About updates using RPMs + +[role="_abstract"] +Updating {product-title} for non-image-based {op-system-base-full} systems requires updating the RPMs. + +* For patch releases, such as {product-version}.1 to {product-version}.2, simply update the RPMs. +* For minor-version release updates, add the step of enabling the compatible update repository by using your subscription manager. + +[NOTE] +==== +You can back up application data as needed and move the data copy to a secure location when using any update type. +==== diff --git a/modules/microshift-updates-rpms-ostree-con.adoc b/modules/microshift-updates-rpms-ostree-con.adoc index 29b7554b758a..0e06fe8b48b4 100644 --- a/modules/microshift-updates-rpms-ostree-con.adoc +++ b/modules/microshift-updates-rpms-ostree-con.adoc @@ -7,9 +7,11 @@ = {microshift-short} updates on an {op-system-ostree} system [role="_abstract"] -Updating {microshift-short} on a {op-system-ostree-first} system requires building a new {op-system-ostree} image containing the new version of {microshift-short} and any associated optional RPMs. After you create the `rpm-ostree` image with {microshift-short} embedded, you can boot into that operating system image. +Updating {microshift-short} on a {op-system-ostree-first} system requires building a new {op-system-ostree} image containing the new version of {microshift-short} and any associated optional RPMs. -The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.18 to 4.19 or from 4.19.2 to 4.19.3. The following details apply: +After you create the `rpm-ostree` image with {microshift-short} embedded, you can boot into that operating system image. + +The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.20 to 4.21 or from 4.21.2 to 4.21.3. The following details apply: * Back up and system rollback are automatic with this update type. * You can use the following workflow to update applications running in the {microshift-short} node. Ensure compatibilities between the application and the adjacent versions of {microshift-short} and {op-system-ostree} before starting an update. From 088bb76451a8d4e5e970991aeb2ea1df9245927d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Thu, 13 Nov 2025 15:07:56 -0500 Subject: [PATCH 3/5] OSDOCS-15566: adds snippet to a few other spots --- modules/microshift-adding-repos-to-image-builder.adoc | 3 +++ modules/microshift-preparing-for-image-building.adoc | 2 ++ 2 files changed, 5 insertions(+) diff --git a/modules/microshift-adding-repos-to-image-builder.adoc b/modules/microshift-adding-repos-to-image-builder.adoc index 8e96a1d800af..be0ef2168d47 100644 --- a/modules/microshift-adding-repos-to-image-builder.adoc +++ b/modules/microshift-adding-repos-to-image-builder.adoc @@ -7,8 +7,11 @@ [id="adding-microshift-repos-image-builder_{context}"] = Adding {microshift-short} repositories to image builder +[role="_abstract"] Use the following procedure to add the {microshift-short} repositories to image builder on your build host. +include::snippets/microshift-rhel10-bootc-not-osbuild.adoc[leveloffset=1] + .Prerequisites * Your build host meets the image builder system requirements. diff --git a/modules/microshift-preparing-for-image-building.adoc b/modules/microshift-preparing-for-image-building.adoc index 4c301ce9402a..dea0844b4a23 100644 --- a/modules/microshift-preparing-for-image-building.adoc +++ b/modules/microshift-preparing-for-image-building.adoc @@ -9,6 +9,8 @@ [role="_abstract"] Use the image builder tool to compose customized {op-system-ostree-first} images optimized for edge deployments. +include::snippets/microshift-rhel10-bootc-not-osbuild.adoc[leveloffset=1] + You can run a {microshift-short} node with your applications on a {op-system-ostree} 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-ostree}: From 195475b8ded3c0efb5172dcf4a32932b32a1afd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Fri, 14 Nov 2025 07:15:56 -0500 Subject: [PATCH 4/5] OSDOCS-15566: fix xref --- .../microshift-embed-in-rpm-ostree.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc index c9bf16508d53..ed36a321976c 100644 --- a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc +++ b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc @@ -41,6 +41,6 @@ include::modules/microshift-embed-kickstart-in-iso.adoc[leveloffset=+2] * xref:../microshift_networking/microshift-firewall.adoc#microshift-firewall-req-settings_microshift-firewall[Required firewall settings] * xref:../microshift_install_kickstarts/microshift-rhel-kickstarts.adoc#microshift-rhel-kickstarts[Using Kickstart files for embedding {microshift-short} in {op-system-base} installation] * link:https://console.redhat.com/openshift/install/pull-secret[Red Hat Hybrid Cloud Console pull secret] -* xref:../microshift_install_rpm/microshift-access-node.adoc[Accessing the {microshift-short} node with oc] +* xref:../microshift_install_rpm/microshift-access-node.adoc#microshift-access-node[Accessing the {microshift-short} node with oc] //Add modules about using the VM and getting the ISO up and running, then starting MicroShift... From 7e8b6464b29127b4b8fc02c2bea1cd6882f5daab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Fri, 14 Nov 2025 10:50:44 -0500 Subject: [PATCH 5/5] OSDOCS-15566: minor fix -restest --- .../microshift-embed-in-rpm-ostree.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc index ed36a321976c..282605cdb74e 100644 --- a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc +++ b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc @@ -35,6 +35,7 @@ include::modules/microshift-embed-kickstart-in-iso.adoc[leveloffset=+2] [id="additional-resources_microshift-embed-in-rpm-ostree"] [role="_additional-resources"] == Additional resources + * xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-creating-ostree-iso_microshift-embed-in-rpm-ostree[Creating the {op-system-ostree} image] * xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system] * xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing {microshift-short}]