diff --git a/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc b/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc index 936f60212ab6..1e11f4eb78f2 100644 --- a/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc +++ b/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc @@ -2,10 +2,12 @@ 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::[] +[role="_abstract"] Use a Kickstart file that automates the installation of an {op-system-base} image with {microshift-short}. include::modules/microshift-rhel-kickstarts-con.adoc[leveloffset=+1] diff --git a/microshift_install_rpm/microshift-access-node.adoc b/microshift_install_rpm/microshift-access-node.adoc index 43137c555f85..8a0117d16706 100644 --- a/microshift_install_rpm/microshift-access-node.adoc +++ b/microshift_install_rpm/microshift-access-node.adoc @@ -6,6 +6,7 @@ include::_attributes/attributes-microshift.adoc[] toc::[] +[role="_abstract"] Access a {microshift-short} node by using the {oc-first}. include::modules/microshift-accessing.adoc[leveloffset=+1] 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..282605cdb74e 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,16 @@ 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 +== 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] +* 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#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... - -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/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-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-about.adoc b/modules/microshift-about.adoc index 4ba1f89b1039..9277878064bb 100644 --- a/modules/microshift-about.adoc +++ b/modules/microshift-about.adoc @@ -6,6 +6,7 @@ [id="con-about-microshift_{context}"] = About {product-title} +[role="_abstract"] Working with resource-constrained field environments and hardware presents many challenges not experienced with cloud computing. {microshift-short} enables you to solve problems for edge devices by: * Running the same Kubernetes workloads you run in the cloud, but at the edge. 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-add-blueprint-build-iso.adoc b/modules/microshift-add-blueprint-build-iso.adoc index 39254748f468..7edcb2d18840 100644 --- a/modules/microshift-add-blueprint-build-iso.adoc +++ b/modules/microshift-add-blueprint-build-iso.adoc @@ -6,6 +6,11 @@ [id="microshift-add-blueprint-build-iso_{context}"] = Add the blueprint to image builder and build the ISO +[role="_abstract"] +You must add the blueprint to an image builder to build the ISO. + +.Procedure + . Add the blueprint to the image builder by running the following command: + [source,terminal] diff --git a/modules/microshift-adding-other-packages-to-blueprint.adoc b/modules/microshift-adding-other-packages-to-blueprint.adoc index 4406f9563b73..63d0afc8bcd8 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,29 +17,35 @@ 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: -** Create the ISO. -** Add the blueprint and build the ISO. -** Download the ISO and prepare it for use. -** Do any provisioning that is needed. + +. 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. +* Do any provisioning that is needed. diff --git a/modules/microshift-adding-repos-to-image-builder.adoc b/modules/microshift-adding-repos-to-image-builder.adoc index 3783db78058c..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. @@ -78,4 +81,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..6c2909f51a6f 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..c6615e14fb49 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] ==== @@ -40,7 +43,7 @@ path = "/etc/pki/ca-trust/source/anchors/cert1.pem" data = "" ---- -. To enable the certificate bundle in the system-wide trust store configuration, use the `update-ca-trust` command on the host where the image you are using has booted, for example: +. To enable the certificate bundle in the system-wide truststore configuration, use the `update-ca-trust` command on the host where the image you are using has booted, for example: + [source,terminal] ---- diff --git a/modules/microshift-ca-adding-bundle.adoc b/modules/microshift-ca-adding-bundle.adoc index 5214652f61f3..ce405f09cb98 100644 --- a/modules/microshift-ca-adding-bundle.adoc +++ b/modules/microshift-ca-adding-bundle.adoc @@ -6,4 +6,7 @@ [id="microshift-ca-adding-bundle_{context}"] = Adding a certificate authority bundle -{microshift-short} uses the host trust bundle when clients evaluate server certificates. You can also use a customized security certificate chain to improve the compatibility of your endpoint certificates with clients specific to your deployments. To do this, you can add a certificate authority (CA) bundle with root and intermediate certificates to the {op-system-ostree-first} system-wide truststore. +[role="_abstract"] +{microshift-short} uses the host trust bundle when clients evaluate server certificates. + +You can also use a customized security certificate chain to improve the compatibility of your endpoint certificates with clients specific to your deployments. To do this, you can add a certificate authority (CA) bundle with root and intermediate certificates to the {op-system-ostree-first} system-wide truststore. diff --git a/modules/microshift-creating-ostree-iso.adoc b/modules/microshift-creating-ostree-iso.adoc index 9ee4fc79bebe..fa950b70dcb6 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. @@ -86,7 +89,7 @@ $ sudo chmod a+r ${BUILDID}-container.tar $ IMAGEID=$(cat < "./${BUILDID}-container.tar" | sudo podman load | grep -o -P '(?<=sha256[@:])[a-z0-9]*') ---- -.. Use the `IMAGEID` variable result to execute the podman command step by running the following command: +.. Use the `IMAGEID` variable result to run the Podman command step by running the following command: + [source,terminal] ---- @@ -95,7 +98,7 @@ $ sudo podman run -d --name=minimal-microshift-server -p 8085:8080 ${IMAGEID} + This command also returns the ID of the container saved in the `IMAGEID` variable for monitoring. -. Generate the installer blueprint file by running the following command: +. Generate the installation program blueprint file by running the following command: + [source,text] ---- @@ -108,4 +111,4 @@ modules = [] groups = [] packages = [] EOF ----- \ No newline at end of file +---- diff --git a/modules/microshift-download-iso-prep-for-use.adoc b/modules/microshift-download-iso-prep-for-use.adoc index 99d6757a172e..0e1bb10c6082 100644 --- a/modules/microshift-download-iso-prep-for-use.adoc +++ b/modules/microshift-download-iso-prep-for-use.adoc @@ -7,6 +7,11 @@ [id="microshift-download-iso-prep-for-use_{context}"] = Download the ISO and prepare it for use +[role="_abstract"] +After creating the ISO, you must download it and prepare it for use. + +.Procedure + . Download the ISO using the ID by running the following command: + [source,terminal] 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 d64a02fa1ac0..d222b06ca6e6 100644 --- a/modules/microshift-embed-microshift-image-offline-deploy.adoc +++ b/modules/microshift-embed-microshift-image-offline-deploy.adoc @@ -7,10 +7,13 @@ [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] +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-embed-ostree-enable-eus-repos.adoc b/modules/microshift-embed-ostree-enable-eus-repos.adoc index d45b4573dd1a..a47957238427 100644 --- a/modules/microshift-embed-ostree-enable-eus-repos.adoc +++ b/modules/microshift-embed-ostree-enable-eus-repos.adoc @@ -6,13 +6,15 @@ [id="microshift-enable-eus-repos_{context}"] = Enabling extended support repositories for image building +[role="_abstract"] If you have an extended support (EUS) release of {microshift-short} or {op-system-base-full}, you must enable the {op-system-base} EUS repositories for image builder to use. If you do not have an EUS version, you can skip these steps. .Prerequisites -* You have an EUS version of {microshift-short} or {op-system-base} or are updating to one. +* You have either an EUS version of {microshift-short} or {op-system-base}, or you are updating to one. * You have root-user access to your build host. -* You reviewed the link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[{op-system-bundle} release compatibility matrix]. +* You have reviewed the following link: +** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[{op-system-bundle} release compatibility matrix] include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1] @@ -37,38 +39,42 @@ $ sudo cp /usr/share/osbuild-composer/repositories/rhel-{op-system-version}.json [source,terminal,subs="attributes+"] ---- # ... -"baseurl": "https://cdn.redhat.com/content/eus/rhel{op-system-version-major}/{op-system-version}//baseos/os", # <1> +"baseurl": "https://cdn.redhat.com/content/eus/rhel{op-system-version-major}/{op-system-version}//baseos/os", # ... ---- -<1> You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. ++ +You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. . Optional: Apply the `baseos` update by running the following command: + [source,terminal,subs="attributes+"] ---- $ sudo sed -i "s,dist/rhel{op-system-version-major}/{op-system-version}/$(uname -m)/baseos/,eus/rhel{op-system-version-major}/{op-system-version}/$(uname -m)/baseos/,g" \ -/etc/osbuild-composer/repositories/rhel-{op-system-version}.json # <1> +/etc/osbuild-composer/repositories/rhel-{op-system-version}.json ---- -<1> You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. ++ +You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. . Update the `appstream` source by modifying the `/etc/osbuild-composer/repositories/rhel-.json` file with the following values: + [source,terminal,subs="attributes+"] ---- # ... -"baseurl": "https://cdn.redhat.com/content/eus/rhel{op-system-version-major}/{op-system-version}//appstream/os", # <1> +"baseurl": "https://cdn.redhat.com/content/eus/rhel{op-system-version-major}/{op-system-version}//appstream/os", # ... ---- -<1> You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. ++ +You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. . Optional. Apply the `appstream` update by running the following command: + [source,terminal,subs="attributes+"] ---- $ sudo sed -i "s,dist/rhel{op-system-version-major}/{op-system-version}/$(uname -m)/appstream/,eus/rhel{op-system-version-major}/{op-system-version}/$(uname -m)/appstream/,g" \ -/etc/osbuild-composer/repositories/rhel-{op-system-version}.json # <1> +/etc/osbuild-composer/repositories/rhel-{op-system-version}.json ---- -<1> You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. ++ +You can replace _{op-system-version-major}_ with the major {op-system-base} version you are using if different from the value in this example, and replace _{op-system-version}_ with the __ version. Be certain that the {op-system-base} version you choose is compatible with the {microshift-short} version you are using. .Verification @@ -98,4 +104,4 @@ $ sudo composer-cli sources info appstream | grep 'url =' [source,text,subs="attributes+"] ---- url = "https://cdn.redhat.com/content/eus/rhel{op-system-version-major}/{op-system-version}/x86_64/appstream/os" ----- \ No newline at end of file +---- 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..dea0844b4a23 100644 --- a/modules/microshift-preparing-for-image-building.adoc +++ b/modules/microshift-preparing-for-image-building.adoc @@ -6,12 +6,21 @@ [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. + +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}: -* 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. 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 +==== diff --git a/snippets/microshift-unsupported-config-warn.adoc b/snippets/microshift-unsupported-config-warn.adoc index 5fc9c886dc38..0c9b69757692 100644 --- a/snippets/microshift-unsupported-config-warn.adoc +++ b/snippets/microshift-unsupported-config-warn.adoc @@ -8,5 +8,7 @@ [WARNING] ==== -Keeping component versions in a supported configuration of {op-system-bundle} can require updating {microshift-short} and {op-system-base} at the same time. Ensure that your version of {op-system-base} is compatible with the version of {microshift-short} you are updating to, especially if you are updating {microshift-short} across two minor versions. Otherwise, you can create an unsupported configuration, break your node, or both. For more information, see the link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[Red Hat Device Edge release compatibility matrix]. +Keeping component versions in a supported configuration of {op-system-bundle} can require updating {microshift-short} and {op-system-base} at the same time. Ensure that your version of {op-system-base} is compatible with the version of {microshift-short} you are updating to, especially if you are updating {microshift-short} across two minor versions. Otherwise, you can create an unsupported configuration, break your node, or both. For more information, see the following link: + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[Red Hat Device Edge release compatibility matrix] ==== \ No newline at end of file