Merge pull request #93006 from ShaunaDiaz/OSDOCS-13736

OSDOCS-13736: adds bootc to Updates MicroShift

Author: ShaunaDiaz

_topic_maps/_topic_map_ms.yml

@@ -100,6 +100,8 @@ Topics:
   File: microshift-update-rpms-ostree
 - Name: Manual updates with RPMs
   File: microshift-update-rpms-manually
+- Name: Migrating from RHEL for Edge to image mode for RHEL
+  File: microshift-update-rhel-edge-to-image-mode
 - Name: Listing update package contents
   File: microshift-list-update-contents
 ---

microshift_updating/microshift-update-options.adoc

@@ -30,7 +30,8 @@ Only `rpm-ostree` updates include automatic rollbacks.
 ====
 
 [id="microshift-update-options-rpm-ostree-updates_{context}"]
-=== RPM-OSTree updates
+=== {op-system-ostree} updates
+
 Using the {op-system-ostree} `rpm-ostree` update path allows for automated backup and system rollback in case any part of the update fails.
 
 * You can update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree} by building a new system image containing the new version of {microshift-short}.
@@ -83,12 +84,19 @@ You can update {op-system-ostree} or {op-system-base} and update {microshift-sho
 . Enable the correct {microshift-short} repository to ensure alignment between your {op-system-base} and {microshift-short} versions.
 . Use the {microshift-short} update type specific to your update path.
 
+[id="microshift-update-options-edge-to-image_{context}"]
+== Migrating {microshift-short} from {op-system-ostree} to {op-system-image}
+
+Starting with {microshift-short} 4.19, you can migrate your {microshift-short} cluster from {op-system-ostree} to {op-system-image} if the versions are compatible. Check compatibilities before beginning a migration. See the {op-system-base} documentation for instructions to migrate your image-based {op-system-base} system.
+//RHEL docs are coming soon
+
 //additional resources for updating RHEL and MicroShift
 [role="_additional-resources"]
 .Additional resources
 * link:https://access.redhat.com/articles/rhel-eus#c5[How to Access EUS]
 * link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/index[Composing a customized RHEL system image]
-* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system]
+* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an {op-system-ostree} system]
 * xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[Applying updates manually with RPMs]
 * xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot[The greenboot system health check]
 * xref:../microshift_running_apps/microshift-greenboot-workload-health-checks.adoc#microshift-greenboot-workload-health-checks[Greenboot workload health checks]
+//* xref:../microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc#microshift-update-rhel-edge-to-image[Migrating {microshift-short} from {op-system-ostree} to {op-system-image}]

microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="microshift-update-rhel-edge-to-image-mode"]
+include::_attributes/attributes-microshift.adoc[]
+= Migrating {microshift-short} from {op-system-ostree} to {op-system-image}
+:context: microshift-update-rhel-edge-to-image
+
+toc::[]
+
+To migrate {microshift-short} from {op-system-ostree-first}, embed {microshift-short} on a new {op-system-image} image.
+
+include::modules/microshift-update-edge-to-image.adoc[leveloffset=+1]
+
+include::modules/microshift-updates-edge-to-image-uid-drift.adoc[leveloffset=+1]
+
+//additional resources for image mode docs in RHEL
+//[role="_additional-resources"]
+//.Additional resources
+//TODO Add RHEL doc links when published

microshift_updating/microshift-update-rpms-manually.adoc

@@ -6,7 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-Updating {product-title} for non-OSTree systems such as {op-system-base-full} requires updating the RPMs. For patch releases, such as 4.19.1 to 4.19.2, simply update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager.
+Updating {product-title} for non-image-based {op-system-base-full} systems requires updating the RPMs. For patch releases, such as 4.19.1 to 4.19.2, simply update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager.
 
 [NOTE]
 ====

microshift_updating/microshift-update-rpms-ostree.adoc

@@ -1,18 +1,13 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-update-rpms-ostree"]
-= Updating RPMs on an OSTree system
+= Updating RPMs on a RHEL for Edge system
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-update-rpms-ostree
 
 toc::[]
 
-Updating {microshift-short} on an `rpm-ostree` system such as {op-system-ostree-first} requires building a new {op-system-ostree} image containing the new version of {microshift-short} and any associated optional RPMs. After you have the `rpm-ostree` image with {microshift-short} embedded, direct your system to boot into that operating system image.
+You can update {microshift-short} on {op-system-ostree-first} by embedding the new version of {microshift-short} on a new operating system image.
 
-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.
-
-[NOTE]
-====
-Downgrades other than automatic rollbacks are not supported. The following procedure is for updates only.
-====
+include::modules/microshift-updates-rpms-ostree-con.adoc[leveloffset=+1]
 
 include::modules/microshift-updating-rpms-ostree.adoc[leveloffset=+1]

modules/microshift-update-edge-to-image.adoc

@@ -0,0 +1,16 @@
+//Module included in the following assemblies:
+//
+//*  microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-updates-edge-to-image-mode_{context}"]
+= Migrating {microshift-short} to {op-system-image}
+
+Migrating {microshift-short} from a {op-system-ostree-first} system to a {op-system-image} system requires building a new {op-system-image} image containing the required version of {microshift-short} and any associated optional RPMs.
+
+See the {op-system-base-full} documentation for general instructions on migrating {op-system-ostree} systems to {op-system-image} using the `bootc switch` command. Plan the upgrade process carefully. The following tips apply:
+
+* Follow the instructions in the {op-system-base} documentation for converting `rpm-ostree` blueprint files to image mode container files.
+* You can use the `rpm-ostree compose container-encapsulate` image-compose command to create a base container image that can be used for bootc container builds. Then you can derive and familiarize yourself with an {op-system-image} image that is based on existing `ostree` commits.
+* To fully adopt {op-system-image}, define a container build pipeline.
+* Plan for UID and GID drift because {op-system-ostree} and {op-system-image} are not derived from the same parent image. See the {op-system-base} documentation for more information.

modules/microshift-updates-edge-to-image-uid-drift.adoc

@@ -0,0 +1,38 @@
+//Module included in the following assemblies:
+//
+//*  microshift_updating/microshift-update-rhel-edge-to-image-mode.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-updates-edge-to-image-uid-drift_{context}"]
+= Working around UID and GID drift when migrating to {op-system-image}
+
+If you do not re-install operating systems that are running {microshift-short}, you must use a workaround for a possible UID and GID drift during the migration process. One way to solve this problem is to add `systemd` units that apply the necessary fixes before the affected system services are started.
+
+.Prerequisites
+
+* You have an existing {op-system-ostree} deployment running {microshift-short}.
+* You have root access to the build host.
+* You have an image that you want to deploy.
+
+.Procedure
+
+* Solve the potential UID or GID drift for the Open vSwitch (OVS) `systemd` service, `ovsdb-server.service`, by adding the following command to the {microshift-short} image-build procedure:
++
+[source,terminal]
+----
+# Install systemd configuration drop-ins to fix potential permission problems when upgrading from rpm-ostree commits to image mode container layers
+RUN mkdir -p /usr/lib/systemd/system/ovsdb-server.service.d && \
+    cat > /usr/lib/systemd/system/ovsdb-server.service.d/microshift-ovsdb-ownership.conf <<'EOF'
+# The openvswitch database files must be owned by the appropriate user and its primary group. That the user and its group can be overwritten, recreate them.
+[Service]
+ExecStartPre=/bin/sh -c '/bin/getent passwd openvswitch >/dev/null || useradd -r openvswitch'
+ExecStartPre=/bin/sh -c '/bin/getent group hugetlbfs >/dev/null || groupadd -r hugetlbfs'
+ExecStartPre=/sbin/usermod -a -G hugetlbfs openvswitch
+ExecStartPre=/bin/chown -Rhv openvswitch. /etc/openvswitch
+EOF
+----
+
+[IMPORTANT]
+====
+After the {microshift-short} migration to {op-system-image} is complete, this workaround is not needed and can be removed.
+====

modules/microshift-updates-rhde-config-rhel-repos.adoc

@@ -24,15 +24,6 @@ $ sudo subscription-manager release --set=_<x.y>_ # <1>
 ----
 <1> Replace _<x.y>_ with the major and minor version of your compatible {op-system-base} system. For example, _9.6_.
 
-//this is the same command as above; is this correct?
-. Update both {microshift-short} and {op-system-base} versions by running the following command:
-+
-[source,terminal]
-----
-$ sudo subscription-manager release --set={ocp-version} # <1>
-----
-<1> You can replace _{ocp-version}_ with the major and minor version of your compatible {op-system-base} system if it is not the same version given in this example.
-
 . If you are using an EUS {microshift-short} release, disable the {op-system-base} standard-support-scope repositories by running the following command:
 +
 [source,terminal]

modules/microshift-updates-rpms-ostree-con.adoc

@@ -0,0 +1,20 @@
+//Module included in the following assemblies:
+//
+//*  microshift_updating/microshift-update-rpms-ostree.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-updates-rpms-ostree-con_{context}"]
+= {microshift-short} updates on an {op-system-ostree} system
+
+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.
+
+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:
+
+* 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} cluster. Ensure compatibilities between the application and the adjacent versions of {microshift-short} and {op-system-ostree} before starting an update.
+* Downgrades other than automatic rollbacks are not supported. The following procedure is for updates only.
++
+[IMPORTANT]
+====
+The steps you use depends on how your existing deployment is set up. The following procedure outlines the general steps you can take, with links to the {op-system-ostree} documentation. The {op-system-ostree} documentation is your resource for specific details on building an updated operating system image.
+====

modules/microshift-updating-rpms-ostree.adoc

@@ -4,17 +4,9 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-updates-rpms-ostree_{context}"]
-= Applying updates on an rpm-ostree system
+= Applying updates on an {op-system-ostree} system
 
-To update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree-first}, embed the new version of {microshift-short} on a new operating system image.
-
-* Back up and system rollback are automatic with this update type.
-* You can also use this workflow to update applications running in the {microshift-short} cluster. Ensure compatibility between the application and the adjacent versions of {microshift-short} and {op-system-ostree} before starting an update.
-
-[IMPORTANT]
-====
-The steps you use depends on how your existing deployment is set up. The following procedure outlines the general steps you can take, with links to the {op-system-ostree} documentation. The {op-system-ostree} documentation is your resource for specific details on building an updated operating system image.
-====
+To update {microshift-short} on {op-system-ostree-first}, embed the new version of {microshift-short} on a new operating system image.
 
 .Prerequisites