From 40b140338820444a0e8ac7f58698374613b7c0b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Wed, 8 Oct 2025 13:31:50 -0400 Subject: [PATCH] OSDOCS-13908-416: manual CP --- ...microshift-installing-troubleshooting.adoc | 2 +- .../microshift-troubleshoot-updates.adoc | 22 ++--- .../microshift-list-update-contents.adoc | 4 +- .../microshift-update-options.adoc | 77 ++++-------------- .../microshift-update-rpms-manually.adoc | 18 ++--- .../microshift-update-rpms-ostree.adoc | 12 +-- microshift_welcome/index.adoc | 3 +- ...microshift-check-journal-logs-updates.adoc | 8 +- modules/microshift-get-rpm-release-info.adoc | 1 + .../microshift-greenboot-check-status.adoc | 3 +- modules/microshift-manual-rpm-updates.adoc | 16 ++++ modules/microshift-rhde-updates.adoc | 14 ++++ modules/microshift-rpm-ostree-updates.adoc | 31 +++++++ ...-simultaneous-microshift-rhel-updates.adoc | 15 ++++ .../microshift-standalone-rhel-updates.adoc | 16 ++++ modules/microshift-standalone-updates.adoc | 23 ++++++ ...oshift-updates-rhde-config-rhel-repos.adoc | 80 +++++++++++++++++++ .../microshift-updates-rpms-ostree-con.adoc | 21 +++++ .../microshift-updates-troubleshooting.adoc | 22 ++--- modules/microshift-updating-rpms-ostree.adoc | 8 +- modules/microshift-updating-rpms-y.adoc | 4 +- modules/microshift-updating-rpms-z.adoc | 5 +- snippets/microshift-healthy-pods-snip.adoc | 4 +- ...roshift-rhde-compatibility-table-snip.adoc | 2 +- .../microshift-unsupported-config-warn.adoc | 4 +- 25 files changed, 287 insertions(+), 128 deletions(-) create mode 100644 modules/microshift-manual-rpm-updates.adoc create mode 100644 modules/microshift-rhde-updates.adoc create mode 100644 modules/microshift-rpm-ostree-updates.adoc create mode 100644 modules/microshift-simultaneous-microshift-rhel-updates.adoc create mode 100644 modules/microshift-standalone-rhel-updates.adoc create mode 100644 modules/microshift-standalone-updates.adoc create mode 100644 modules/microshift-updates-rhde-config-rhel-repos.adoc create mode 100644 modules/microshift-updates-rpms-ostree-con.adoc diff --git a/microshift_troubleshooting/microshift-installing-troubleshooting.adoc b/microshift_troubleshooting/microshift-installing-troubleshooting.adoc index 962f493b468f..5da35cf99bda 100644 --- a/microshift_troubleshooting/microshift-installing-troubleshooting.adoc +++ b/microshift_troubleshooting/microshift-installing-troubleshooting.adoc @@ -10,7 +10,7 @@ To troubleshoot a failed {microshift-short} installation, you can run an sos rep include::modules/microshift-gathering-sos-report.adoc[leveloffset=+1] -[id="additional-resources_microshift-installing-troubleshooting_{context}"] +[id="additional-resources_microshift-installing-troubleshooting"] [role="_additional-resources"] == Additional resources * xref:../microshift_support/microshift-sos-report.adoc#microshift-sos-report[About {microshift-short} sos reports] diff --git a/microshift_troubleshooting/microshift-troubleshoot-updates.adoc b/microshift_troubleshooting/microshift-troubleshoot-updates.adoc index 841333796e8a..6d6ca89d0bf3 100644 --- a/microshift_troubleshooting/microshift-troubleshoot-updates.adoc +++ b/microshift_troubleshooting/microshift-troubleshoot-updates.adoc @@ -1,25 +1,27 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-troubleshoot-updates"] -= Troubleshoot updates += Troubleshooting updates + include::_attributes/attributes-microshift.adoc[] :context: microshift-troubleshoot-updates toc::[] -To troubleshoot {microshift-short} updates, use the following guide. +[role="_abstract"] +To troubleshoot {microshift-short} updates, you can check update paths, review journal and greenboot health check logs, and use other techniques to help you solve update problems. include::modules/microshift-updates-troubleshooting.adoc[leveloffset=+1] -//additional resources for troubleshooting module +include::modules/microshift-check-journal-logs-updates.adoc[leveloffset=+1] + +include::modules/microshift-greenboot-check-status.adoc[leveloffset=+1] + +[id="additional-resources_microshift-troubleshoot-updates"] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot-systemd-journal-data_microshift-greenboot[Enabling `systemd` journal service data persistency] * xref:../microshift_troubleshooting/microshift-version.adoc#microshift-version[Checking the MicroShift version] * xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-service-stopping_microshift-install-rpm[Stopping the MicroShift service] * xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-service-starting_microshift-install-rpm[Starting the MicroShift service] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index#rolling_back_rhel_for_edge_images[Rolling back RHEL for Edge images] - -include::modules/microshift-check-journal-logs-updates.adoc[leveloffset=+1] - -include::modules/microshift-greenboot-check-status.adoc[leveloffset=+1] \ No newline at end of file +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images] +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index#rolling_back_rhel_for_edge_images[Rolling back RHEL for Edge images] \ No newline at end of file diff --git a/microshift_updating/microshift-list-update-contents.adoc b/microshift_updating/microshift-list-update-contents.adoc index 8f02263f518d..4119b068712c 100644 --- a/microshift_updating/microshift-list-update-contents.adoc +++ b/microshift_updating/microshift-list-update-contents.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-list-update-contents"] = Listing RPM update package contents + include::_attributes/attributes-microshift.adoc[] :context: microshift-list-update-contents toc::[] -You can preview the contents of a {microshift-short} RPM package update before installing. +[role="_abstract"] +You can preview the contents of a {microshift-short} RPM package update before installing. This helps you make sure that the update you are planning is a supported configuration of {op-system-bundle}. include::modules/microshift-get-rpm-release-info.adoc[leveloffset=+1] diff --git a/microshift_updating/microshift-update-options.adoc b/microshift_updating/microshift-update-options.adoc index f6d7eddffbae..fcc7c09a6dc9 100644 --- a/microshift_updating/microshift-update-options.adoc +++ b/microshift_updating/microshift-update-options.adoc @@ -1,78 +1,35 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-update-options"] -= Update options with {product-title} and {op-system-bundle} += Update options for Red Hat Device Edge + include::_attributes/attributes-microshift.adoc[] :context: microshift-update-options toc::[] -You can update {op-system-ostree-first} images or {op-system-base-full} with or without updating the {product-title} version if the version combination is supported. See the following table for details: - -include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1] - -include::snippets/microshift-update-paths-snip.adoc[leveloffset=+1] - -[IMPORTANT] -==== -Updates of {microshift-short} are supported with a maximum of two minor versions. For example, you can update from 4.14 to 4.16 in a single step. Updating 4.14 to 4.15 first is not required. -==== - -[id="microshift-update-options-standalone-updates_{context}"] -== Standalone {microshift-short} updates -Consider the following when planning to update {microshift-short}: - -* You can potentially update {microshift-short} without reinstalling your applications and Operators. -* {op-system-base} or {op-system-ostree} updates are only required to update {microshift-short} if the existing operating system is not compatible with the new version of {microshift-short} that you want to use. -* {microshift-short} operates as an in-place update and does not require removal of the previous version. Data backups beyond those required for the usual functioning of your applications are also not required. +[role="_abstract"] +To update {op-system-bundle}, you can update both {product-title} and {op-system-base-full}, or each part by itself without updating the other. You must keep the parts in a supported configuration. Consider the following options when planning updates to your current deployments. -include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1] +include::modules/microshift-rhde-updates.adoc[leveloffset=+1] -[id="microshift-update-options-rpm-ostree-updates_{context}"] -=== RPM-OSTree updates -You can update {microshift-short} on an `rpm-ostree` system such as {op-system-ostree} by building a new image containing the new version of {microshift-short}. Ensure that the version of the operating system you want to use is compatible with the new version of {microshift-short} that you update to. +include::modules/microshift-standalone-updates.adoc[leveloffset=+1] -The following features are available in the {op-system-ostree} update path: +include::modules/microshift-rpm-ostree-updates.adoc[leveloffset=+2] -* The system automatically rolls back to a previous healthy system state if the update fails. -* Applications do not need to be reinstalled. -* Operators do not need to be reinstalled. -* You can update an application without updating {microshift-short} using this update type. -* The image you build can contain other updates as needed. +include::modules/microshift-manual-rpm-updates.adoc[leveloffset=+2] -To begin a {microshift-short} update by embedding in a {op-system-ostree} image, use the procedures in the following documentation: +include::modules/microshift-updates-rhde-config-rhel-repos.adoc[leveloffset=+3] -* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system] +include::modules/microshift-standalone-rhel-updates.adoc[leveloffset=+1] -To understand more about Greenboot, see the following documentation: +include::modules/microshift-simultaneous-microshift-rhel-updates.adoc[leveloffset=+1] -* xref:../microshift_install_get_ready/microshift-greenboot.adoc#microshift-greenboot[The Greenboot health check] -* xref:../microshift_running_apps/microshift-greenboot-workload-scripts.adoc#microshift-greenboot-workload-scripts[Greenboot workload health check scripts] - -[id="microshift-update-options-manual-rpm-updates_{context}"] -=== Manual RPM updates -You can update {microshift-short} manually on a non-OSTree system such as {op-system-base-full} by downloading and updating the RPMs. To complete this update type, use the subscription manager to access the repository containing the new RPMs. To begin a manual RPM update, use the procedures in the following documentation: - -* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[About updating MicroShift RPMs manually] - -[id="microshift-update-options-standalone-rhel-updates_{context}"] -== Standalone {op-system-ostree} updates -You can update {op-system-ostree} or {op-system-base} without updating {microshift-short}, on the condition that the two versions are compatible. Check compatibilities before beginning an update. Use the {op-system-ostree} documentation specific to your update path. - -//additional resources for updating RHEL alone +[id="additional-resources_microshift-update-options"] [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/index[Managing RHEL for Edge images] +== Additional resources -[id="microshift-update-options-simultaneous-microshift-rhel-updates_{context}"] -== Simultaneous {microshift-short} and operating system updates -You can update {op-system-ostree} or {op-system-base} and update {microshift-short} at the same time, on the condition that the versions are compatible. Check for compatibility before beginning an update. First use the {op-system-ostree} and {op-system-base} documentation specific to your update path to plan and update the operating system. Then use the {microshift-short} update type specific to your update path. +* 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_install_get_ready/microshift-greenboot.adoc#microshift-greenboot[The greenboot system health check] +* xref:../microshift_running_apps/microshift-greenboot-workload-scripts.adoc#microshift-greenboot-workload-scripts[Greenboot workload health checks] -//additional resources for updating RHEL and MicroShift -[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/index[Managing RHEL for Edge images] -* link:https://access.redhat.com/documentation/en-us/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-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-scripts.adoc#microshift-greenboot-workload-scripts[Greenboot workload scripts] diff --git a/microshift_updating/microshift-update-rpms-manually.adoc b/microshift_updating/microshift-update-rpms-manually.adoc index 51668a1e9720..8817cf496ec8 100644 --- a/microshift_updating/microshift-update-rpms-manually.adoc +++ b/microshift_updating/microshift-update-rpms-manually.adoc @@ -1,17 +1,14 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-update-rpms-manually"] -= About updating {product-title} RPMs manually += Updating RPMs manually + include::_attributes/attributes-microshift.adoc[] :context: microshift-update-rpms-manually toc::[] -Updating {product-title} for non-OSTree systems such as {op-system-base-full} requires downloading then updating the RPMs. For patch releases, such as 4.16.1 to 4.16.2, download and update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager. - -[IMPORTANT] -==== -{microshift-short} updates are supported with a maximum of two minor versions. For example, you can update to 4.16 from 4.14 in a single step. Updating 4.14 to 4.15 first is not required. -==== +[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. [NOTE] ==== @@ -22,7 +19,8 @@ include::modules/microshift-updating-rpms-z.adoc[leveloffset=+1] include::modules/microshift-updating-rpms-y.adoc[leveloffset=+1] -//additional resources for backup and restore +[id="additional-resources_microshift-update-rpms-manually"] [role="_additional-resources"] -.Additional resources -* xref:../microshift_backup_and_restore/microshift-backup-and-restore.adoc#microshift-backup-and-restore[Backing up and restoring {microshift-short} data] +== Additional resources + +* xref:../microshift_backup_and_restore/microshift-backup-and-restore.adoc#microshift-backup-and-restore[Backup and restore] diff --git a/microshift_updating/microshift-update-rpms-ostree.adoc b/microshift_updating/microshift-update-rpms-ostree.adoc index b7740525c8de..b77f1d8d9906 100644 --- a/microshift_updating/microshift-update-rpms-ostree.adoc +++ b/microshift_updating/microshift-update-rpms-ostree.adoc @@ -1,20 +1,20 @@ :_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. - -The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.14 to 4.16 or from 4.16.0 to 4.16.1. - -include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1] +[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. The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.16 to 4.18 or from {ocp-version}.2 to {ocp-version}.3. [NOTE] ==== Downgrades are not supported. The following procedure is for upgrades only. ==== +include::modules/microshift-updates-rpms-ostree-con.adoc[leveloffset=+1] + include::modules/microshift-updating-rpms-ostree.adoc[leveloffset=+1] diff --git a/microshift_welcome/index.adoc b/microshift_welcome/index.adoc index 09302e1e370e..c86dd314515d 100644 --- a/microshift_welcome/index.adoc +++ b/microshift_welcome/index.adoc @@ -50,7 +50,8 @@ In addition to standard Kubernetes APIs, {microshift-short} includes a small sub include::modules/microshift-k8s-apis.adoc[leveloffset=+1] +[id="additional-resources_microshift-welcome-index"] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../microshift_rest_api/index.adoc#api-index[API index] * link:https://www.redhat.com/en/technologies/cloud-computing/openshift/kubernetes-engine[{oke}] diff --git a/modules/microshift-check-journal-logs-updates.adoc b/modules/microshift-check-journal-logs-updates.adoc index 910c6ea6bef6..98c72263fa7c 100644 --- a/modules/microshift-check-journal-logs-updates.adoc +++ b/modules/microshift-check-journal-logs-updates.adoc @@ -6,12 +6,8 @@ [id="microshift-check-journal-logs-updates_{context}"] = Checking journal logs after updates -In some cases, {microshift-short} might fail to update. In these events, it is helpful to understand failure types and how to troubleshoot them. The journal logs can assist in diagnosing update failures. - -[NOTE] -==== -The default configuration of the `systemd` journal service stores data in a volatile directory. To persist system logs across system starts and restarts, enable log persistence and set limits on the maximum journal data size. -==== +[role="_abstract"] +Journal logs can assist in diagnosing {microshift-short} update failures. The default configuration of the `systemd` journal service stores data in a volatile directory. To persist system logs across system starts and restarts, enable log persistence and set limits on the maximum journal data size. .Procedure diff --git a/modules/microshift-get-rpm-release-info.adoc b/modules/microshift-get-rpm-release-info.adoc index 4886e2b3a012..fbf434aa478b 100644 --- a/modules/microshift-get-rpm-release-info.adoc +++ b/modules/microshift-get-rpm-release-info.adoc @@ -6,6 +6,7 @@ [id="microshift-get-rpm-release-info_{context}"] = Listing the contents of the {microshift-short} RPM release package +[role="_abstract"] To see the images included with a {microshift-short} release, you can list the contents of the `microshift-release-info` RPM by downloading and unpacking the RPM. .Prerequisites diff --git a/modules/microshift-greenboot-check-status.adoc b/modules/microshift-greenboot-check-status.adoc index c66c2c05b847..eb8ad4435a77 100644 --- a/modules/microshift-greenboot-check-status.adoc +++ b/modules/microshift-greenboot-check-status.adoc @@ -6,7 +6,8 @@ [id="microshift-greenboot-check-status_{context}"] = Checking the status of greenboot health checks -Check the status of greenboot health checks before making changes to the system or during troubleshooting. You can use any of the following commands to help you ensure that greenboot scripts have finished running. +[role="_abstract"] +Check the status of greenboot health checks before making changes to the system and while troubleshooting. You can use any of the following commands to help you ensure that greenboot scripts have finished running. .Procedure diff --git a/modules/microshift-manual-rpm-updates.adoc b/modules/microshift-manual-rpm-updates.adoc new file mode 100644 index 000000000000..b45a8774c3d3 --- /dev/null +++ b/modules/microshift-manual-rpm-updates.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-manual-rpm-updates_{context}"] += Manual RPM updates + +[role="_abstract"] +You can update {microshift-short} manually on {op-system-base-full} by updating the RPMs. This type of update is useful for development environments and testing. + +* To complete this update type, use the subscription manager to enable the repository that has the new RPMs. +* Use manual processes to ensure system health and complete additional system backups. +* To begin a manual RPM update, use the procedures in the following documentation: + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/updating/microshift-update-rpms-manually[About updating MicroShift RPMs manually] diff --git a/modules/microshift-rhde-updates.adoc b/modules/microshift-rhde-updates.adoc new file mode 100644 index 000000000000..0119987f16dd --- /dev/null +++ b/modules/microshift-rhde-updates.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-rhde-updates_{context}"] += {op-system-bundle} updates + +[role="_abstract"] +You can update {op-system-base-full} operating system independently of your {product-title} version if the version combination is supported. See the following table for details: + +include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1] + +include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1] diff --git a/modules/microshift-rpm-ostree-updates.adoc b/modules/microshift-rpm-ostree-updates.adoc new file mode 100644 index 000000000000..c8ee3f773904 --- /dev/null +++ b/modules/microshift-rpm-ostree-updates.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-rpm-ostree-updates_{context}"] += Updating {microshift-short} on {op-system-ostree} + +[role="_abstract"] +You can have automated backup and system rollback in case any part of the update fails by using the `rpm-ostree` update path for a new or existing {op-system-ostree} deployment. + +* 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}. +* The `rpm-ostree` image can be the same version or an updated version, but the versions of {op-system-ostree} and {microshift-short} must be compatible. + +The following features are available in the {op-system-ostree} update path: + +* The system automatically rolls back to an earlier healthy system state if the update fails. +* You do not need to reinstall applications. +* You do not need to reinstall Operators. +* You can update an application without updating {microshift-short} using this update type. +* The image you build can contain other updates as needed. + +To begin a {microshift-short} update by embedding the new version in a {op-system-ostree} image, use the procedures in the following documentation: + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/updating/microshift-update-rpms-ostree#microshift-updates-rpms-ostree_microshift-update-rpms-ostree[Applying updates on a RHEL for Edge system] + +To understand more about greenboot, see the following documentation: + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-greenboot[The greenboot health check framework] + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/microshift-greenboot-workload-health-checks[Using greenboot for application and workload health checks] diff --git a/modules/microshift-simultaneous-microshift-rhel-updates.adoc b/modules/microshift-simultaneous-microshift-rhel-updates.adoc new file mode 100644 index 000000000000..93cec9833e01 --- /dev/null +++ b/modules/microshift-simultaneous-microshift-rhel-updates.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-simultaneous-microshift-rhel-updates_{context}"] += Simultaneous {microshift-short} and {op-system-base} updates + +[role="_abstract"] +You can update your {op-system-base} operating system type and update {microshift-short} at the same time, if the final versions are a supported configuration of {op-system-bundle}. You can use following workflow to plan the general steps to take: + +. Check for compatibility before beginning an update. +. Use the {op-system-base} documentation specific to your update path to plan and update the operating system. +. 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, such as using an RPM installation or embedding {microshift-short} into an operating system image. diff --git a/modules/microshift-standalone-rhel-updates.adoc b/modules/microshift-standalone-rhel-updates.adoc new file mode 100644 index 000000000000..cf36b367e0b8 --- /dev/null +++ b/modules/microshift-standalone-rhel-updates.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-standalone-rhel-updates_{context}"] += Standalone {op-system-base} updates + +[role="_abstract"] +You can update to any {op-system-base} type without updating {microshift-short} if the two final versions in your {op-system-bundle} are compatible. Check compatibilities before beginning an update. Use the {op-system-base} documentation specific to your use case. + +For example: + +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9[Red Hat Enterprise Linux 9] +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images] +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_image_mode_for_rhel_to_build_deploy_and_manage_operating_systems/introducing-image-mode-for-rhel_using-image-mode-for-rhel-to-build-deploy-and-manage-operating-systems[Introducing image mode for RHEL] diff --git a/modules/microshift-standalone-updates.adoc b/modules/microshift-standalone-updates.adoc new file mode 100644 index 000000000000..a69bad154876 --- /dev/null +++ b/modules/microshift-standalone-updates.adoc @@ -0,0 +1,23 @@ + +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-standalone-updates_{context}"] += Standalone {microshift-short} updates + +[role="_abstract"] +You can update just your {microshift-short} version by embedding the new version in a {op-system-base} image or by installing the RPMs on a standard {op-system-base} operating system. Consider your current operating system version and deployments when planning a {microshift-short} update. + +The following factors apply to a standalone {microshift-short} version update: + +* {microshift-short} operates as an in-place update and does not require removal of the earlier version. +* Data backups beyond those required for the usual functioning of your applications are not required. +* You can potentially update {microshift-short} without reinstalling your applications and Operators. +* Only `rpm-ostree` updates include automatic rollbacks. + +[IMPORTANT] +==== +You must update {op-system-base} to update {microshift-short} if your current operating system is not compatible with the new version of {microshift-short} that you want to use. +==== diff --git a/modules/microshift-updates-rhde-config-rhel-repos.adoc b/modules/microshift-updates-rhde-config-rhel-repos.adoc new file mode 100644 index 000000000000..aa1b9ff60c44 --- /dev/null +++ b/modules/microshift-updates-rhde-config-rhel-repos.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// +//microshift_updating/microshift-update-options.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-updates-rhde-config-rhel-repos_{context}"] += Keeping {microshift-short} and {op-system-base} in a supported configuration + +[role="_abstract"] +When using RPM updates, avoid creating an unsupported configuration or breaking your node by carefully managing your {op-system-base} repositories. + +.Prerequisites + +* You understand the support status of the version of {microshift-short} you are using. +* 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]. + +.Procedure + +. Avoid unintended updates by locking your operating system version by running the following command: ++ +[source,terminal] +---- +$ sudo subscription-manager release --set= # <1> +---- +<1> Replace __ with the major and minor version of your compatible {op-system-base} system. For example, _9.4_. + +. Update both {microshift-short} and {op-system-base} versions by running the following command: ++ +[source,terminal] +---- +$ sudo subscription-manager release --set=<9.4> command. # <1> +---- +<1> Replace _<9.4>_ with the major and minor version of your compatible {op-system-base} system. + +. 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] +---- +$ sudo subscription-manager repos \ + --disable=rhel-<9>-for-x86_64-appstream-rpms \ # <1> + --disable=rhel-<9>-for-x86_64-baseos-rpms +---- +<1> Replace _<9>_ with the major version of your compatible {op-system-base} system. + +. After you disable the standard-support repositories, enable the {op-system-base} EUS repos by running the following command: ++ +[source,terminal] +---- +$ sudo subscription-manager repos \ + --enable rhel-<9>-for-x86_64-appstream-eus-rpms \ # <1> + --enable rhel-<9>-for-x86_64-baseos-eus-rpms` +---- +<1> Replace _<9>_ with the major version of your compatible {op-system-base} system. + +.Verification + +* List the repositories you have enabled for {op-system-base} by running the following command: ++ +[source,terminal] +---- +$ sudo subscription-manager repos --list-enabled +---- ++ +.Example output ++ +[source,terminal] +---- ++----------------------------------------------------------+ + Available Repositories in /etc/yum.repos.d/redhat.repo ++----------------------------------------------------------+ +Repo ID: rhel-9-for-x86_64-baseos-eus-rpms +Repo Name: Red Hat Enterprise Linux 9 for x86_64 - BaseOS - Extended Update Support (RPMs) +Repo URL: https://cdn.redhat.com/content/eus/rhel9/$releasever/x86_64/baseos/os +Enabled: 1 +Repo ID: rhel-9-for-x86_64-appstream-eus-rpms +Repo Name: Red Hat Enterprise Linux 9 for x86_64 - AppStream - Extended Update Support (RPMs) +Repo URL: https://cdn.redhat.com/content/eus/rhel9/$releasever/x86_64/appstream/os +Enabled: 1 +---- \ No newline at end of file diff --git a/modules/microshift-updates-rpms-ostree-con.adoc b/modules/microshift-updates-rpms-ostree-con.adoc new file mode 100644 index 000000000000..6c31c5cd9521 --- /dev/null +++ b/modules/microshift-updates-rpms-ostree-con.adoc @@ -0,0 +1,21 @@ +//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 + +[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. + +The procedures are the same for minor-version and patch updates. For example, use the same steps to upgrade from 4.16 to 4.17 or from 4.17.2 to 4.17.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. +* 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. +==== diff --git a/modules/microshift-updates-troubleshooting.adoc b/modules/microshift-updates-troubleshooting.adoc index bc0b5b3433b3..d8c2bc9c9079 100644 --- a/modules/microshift-updates-troubleshooting.adoc +++ b/modules/microshift-updates-troubleshooting.adoc @@ -6,23 +6,12 @@ [id="microshift-troubleshooting-updates_{context}"] = Troubleshooting {microshift-short} updates +[role="_abstract"] In some cases, {microshift-short} might fail to update. In these events, it is helpful to understand failure types and how to troubleshoot them. -//[id="microshift-update-path-blocked-by-version-sequence_{context}"] -//== Update path is blocked by {microshift-short} version sequence -//Certain versions of {microshift-short} require serial updates. Attempting to update {microshift-short} by skipping a minor version fails: - -//* For example, if your current version is `4.14.5`, but you try to update from that version to `4.16.0`, the message, `executable (4.16.0) is too recent compared to existing data (4.14.5): version difference is 2, maximum allowed difference is 1` appears and {microshift-short} fails to start. - -//In this example, you must first update `4.14.5` to a version of `4.15`, and then you can upgrade to `4.16.0`. - [id="microshift-update-path-blocked-by-version-incompatibility_{context}"] == Update path is blocked by version incompatibility -RPM dependency errors result if a {microshift-short} update is incompatible with the version of {op-system-ostree-first} or {op-system-base-full}. - -[id="microshift-compatibility-table_{context}"] -=== Compatibility table -Check the following compatibility table: +RPM dependency errors result if a {microshift-short} update is incompatible with the version of {op-system-ostree-first} or {op-system-base-full}. Check the following compatibility table: include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+2] @@ -37,10 +26,9 @@ Check the following update paths: * Generally Available Version 4.14.0 from {op-system-base} 9.2 to 4.16.0 on {op-system-base} 9.4 [id="microshift-ostree-update-failed_{context}"] -== OSTree update failed -If you updated on an OSTree system, the greenboot health check automatically logs and acts on system health. A failure can be indicated by a system rollback by greenboot. In cases where the update failed, but greenboot did not complete a system rollback, you can troubleshoot using the {op-system-ostree} documentation linked in the "Additional resources" section that follows this content. +== {op-system-ostree} update failed +If you updated on an `rpm-ostree` system, the greenboot health check automatically logs and acts on system health. A system rollback by greenboot can indicate an update failure. In cases where the update failed, but greenboot did not complete a system rollback, you can troubleshoot using the {op-system-ostree} documentation linked in the "Additional resources" section. -Checking the greenboot logs manually:: * Manually check the greenboot logs to verify system health by running the following command: + [source,terminal] @@ -50,4 +38,4 @@ $ sudo systemctl restart --no-block greenboot-healthcheck && sudo journalctl -fu [id="microshift-rpm-update-failed_{context}"] == Manual RPM update failed -If you updated by using RPMs on a non-OSTree system, an update failure can be indicated by greenboot, but the health checks are only informative. Checking the system logs is the next step in troubleshooting a manual RPM update failure. You can use greenboot and `sos report` to check both the {microshift-short} update and the host system. +If you updated by using RPMs on a non-OSTree system, greenboot can indicate an update failure, but the health checks are only informative. Checking the system logs is the next step in troubleshooting a manual RPM update failure. You can use greenboot and the `sos report` tool to check both the {microshift-short} update and the host system. diff --git a/modules/microshift-updating-rpms-ostree.adoc b/modules/microshift-updating-rpms-ostree.adoc index 6e9685bb5f0c..e6499dcd963f 100644 --- a/modules/microshift-updating-rpms-ostree.adoc +++ b/modules/microshift-updating-rpms-ostree.adoc @@ -6,12 +6,8 @@ [id="microshift-updates-rpms-ostree_{context}"] = Applying updates on an 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. 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. Back up and system rollback are automatic with this update type. - -[NOTE] -==== -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. -==== +[role="_abstract"] +To update {microshift-short} on {op-system-ostree-first}, embed the new version of {microshift-short} on a new operating system image. .Prerequisites diff --git a/modules/microshift-updating-rpms-y.adoc b/modules/microshift-updating-rpms-y.adoc index 1f298def2245..284dc37ef2e5 100644 --- a/modules/microshift-updating-rpms-y.adoc +++ b/modules/microshift-updating-rpms-y.adoc @@ -41,8 +41,8 @@ $ sudo subscription-manager repos \ [source,terminal,subs="attributes+"] ---- $ sudo subscription-manager repos \ - --enable rhel-{op-system-version-major}-for-$(uname -m)-appstream-eus-rpms \ - --enable rhel-{op-system-version-major}-for-$(uname -m)-baseos-eus-rpms + --enable rhel-{op-system-version-major}-for-$(uname -m)-appstream-eus-rpms \ + --enable rhel-{op-system-version-major}-for-$(uname -m)-baseos-eus-rpms ---- . Avoid unintended future updates into an unsupported configuration by locking your operating system version with the following command: diff --git a/modules/microshift-updating-rpms-z.adoc b/modules/microshift-updating-rpms-z.adoc index a6e4eb26bcb4..8b6dde4df7c5 100644 --- a/modules/microshift-updating-rpms-z.adoc +++ b/modules/microshift-updating-rpms-z.adoc @@ -6,7 +6,10 @@ [id="microshift-applying-patch-updates-rpms_{context}"] = Applying patch updates using RPMs -Updating {microshift-short} on non `rpm-ostree` systems such as {op-system-base-full} requires downloading then updating the RPMs. A system reboot is not required for patch updates. For example, use the following procedure to upgrade from 4.14.0 to 4.14.1. +[role="_abstract"] +Updating {microshift-short} on non `rpm-ostree` systems such as {op-system-base-full} requires downloading then updating the RPMs. For example, use the following procedure to upgrade from {ocp-version}.1 to {ocp-version}.2. + +include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1] .Prerequisites * The system requirements for installing {microshift-short} have been met. diff --git a/snippets/microshift-healthy-pods-snip.adoc b/snippets/microshift-healthy-pods-snip.adoc index 05d284597b45..9587dced96a7 100644 --- a/snippets/microshift-healthy-pods-snip.adoc +++ b/snippets/microshift-healthy-pods-snip.adoc @@ -1,6 +1,6 @@ // Snippet for healthy MicroShift output with oc get pods -a // -//* microshift_troubleshooting/microshift-troubleshoot-cluster +//* microshift_troubleshooting/microshift-troubleshoot-node :_mod-docs-content-type: SNIPPET @@ -27,5 +27,5 @@ openshift-storage topolvm-node-rht2m [NOTE] ==== -This example output shows basic {microshift-short}. If you have installed optional RPMs, the status of pods running those services is also expected to be shown in your output. +This example output shows a basic {microshift-short} installation. If you installed optional RPMs, the status of pods running those services is also expected in your output. ==== \ No newline at end of file diff --git a/snippets/microshift-rhde-compatibility-table-snip.adoc b/snippets/microshift-rhde-compatibility-table-snip.adoc index 81da7b50ae59..66c8b7bcca27 100644 --- a/snippets/microshift-rhde-compatibility-table-snip.adoc +++ b/snippets/microshift-rhde-compatibility-table-snip.adoc @@ -7,7 +7,7 @@ .{op-system-bundle} release compatibility matrix -{op-system-base-full} and {microshift-short} work together as a single solution for device-edge computing. You can update each component separately, but the product versions must be compatible. For example, an update of {microshift-short} from 4.14 to 4.16 requires a {op-system} update. Supported configurations of {op-system-bundle} use verified releases for each together as listed in the following table: +{op-system-base-full} and {microshift-short} work together as a single solution for device-edge computing. You can update each component separately, but the product versions must be compatible. Supported configurations of {op-system-bundle} use verified releases for each together as listed in the following table: [cols="4",%autowidth] |=== diff --git a/snippets/microshift-unsupported-config-warn.adoc b/snippets/microshift-unsupported-config-warn.adoc index 644bf8823635..5e277bdb78ea 100644 --- a/snippets/microshift-unsupported-config-warn.adoc +++ b/snippets/microshift-unsupported-config-warn.adoc @@ -9,7 +9,5 @@ [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 cluster, or both. For more information, see the link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.16/html/installing/microshift-install-rpm#microshift-install-rpm-rhde-compatibility-table[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 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]. ==== - -//This snippet is specifically for the 4.16 branch due to refactors in 4.17. \ No newline at end of file