From 0d4f8d563fa82c3cef5409780b553e953147685a 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-418: manual CP --- ...microshift-installing-troubleshooting.adoc | 2 +- .../microshift-troubleshoot-updates.adoc | 22 +++-- .../microshift-list-update-contents.adoc | 4 +- .../microshift-update-options.adoc | 95 ++++--------------- .../microshift-update-rpms-manually.adoc | 13 ++- .../microshift-update-rpms-ostree.adoc | 10 +- 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 | 3 +- .../microshift-updates-rpms-ostree-con.adoc | 21 ++++ .../microshift-updates-troubleshooting.adoc | 16 ++-- modules/microshift-updating-rpms-ostree.adoc | 11 +-- modules/microshift-updating-rpms-y.adoc | 5 +- modules/microshift-updating-rpms-z.adoc | 5 +- snippets/microshift-healthy-pods-snip.adoc | 4 +- .../microshift-unsupported-config-warn.adoc | 2 +- 24 files changed, 211 insertions(+), 132 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-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 ec62e4ed3c85..fcc7c09a6dc9 100644 --- a/microshift_updating/microshift-update-options.adoc +++ b/microshift_updating/microshift-update-options.adoc @@ -1,94 +1,35 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-microshift.adoc[] [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::[] -Updates are supported on {product-title} beginning with the General Availability version 4.14. - -[id="red-hat-device-edge-updates_{context}"] -== {op-system-bundle} updates -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-unsupported-config-warn.adoc[leveloffset=+1] - -[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. - -[NOTE] -==== -Only `rpm-ostree` updates include automatic rollbacks. -==== - -[id="microshift-update-options-rpm-ostree-updates_{context}"] -=== RPM-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}. -* 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. +[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. -The following features are available in the {op-system-ostree} update path: +include::modules/microshift-rhde-updates.adoc[leveloffset=+1] -* 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-standalone-updates.adoc[leveloffset=+1] -To begin a {microshift-short} update by embedding in a {op-system-ostree} image, use the procedures in the following documentation: +include::modules/microshift-rpm-ostree-updates.adoc[leveloffset=+2] -* xref:../microshift_updating/microshift-update-rpms-ostree.adoc#microshift-update-rpms-ostree[Applying updates on an OSTree system] - -To understand more about Greenboot, see the following documentation: - -* 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 updating the RPMs. - -* To complete this update type, use the subscription manager to enable the repository that contains 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: - -* xref:../microshift_updating/microshift-update-rpms-manually.adoc#microshift-update-rpms-manually[About updating MicroShift RPMs manually] +include::modules/microshift-manual-rpm-updates.adoc[leveloffset=+2] include::modules/microshift-updates-rhde-config-rhel-repos.adoc[leveloffset=+3] -[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. +include::modules/microshift-standalone-rhel-updates.adoc[leveloffset=+1] -//additional resources for updating RHEL alone -[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] - -[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. Use the following workflow: - -. Check for compatibility before beginning an update. -. Use the {op-system-ostree} and {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. +include::modules/microshift-simultaneous-microshift-rhel-updates.adoc[leveloffset=+1] -//additional resources for updating RHEL and MicroShift +[id="additional-resources_microshift-update-options"] [role="_additional-resources"] -.Additional resources +== Additional resources + * link:https://access.redhat.com/articles/rhel-eus#c5[How to Access EUS] -* 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] +* 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] + diff --git a/microshift_updating/microshift-update-rpms-manually.adoc b/microshift_updating/microshift-update-rpms-manually.adoc index 005bbc559682..8817cf496ec8 100644 --- a/microshift_updating/microshift-update-rpms-manually.adoc +++ b/microshift_updating/microshift-update-rpms-manually.adoc @@ -1,12 +1,14 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-update-rpms-manually"] -= About updating 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 updating the RPMs. For patch releases, such as 4.18.1 to 4.18.2, simply update the RPMs. For minor-version release updates, add the step of enabling the update repository using your subscription manager. +[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] ==== @@ -17,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[Backup and restore] \ No newline at end of file +== 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 06eee0f3dc9e..079b6104d665 100644 --- a/microshift_updating/microshift-update-rpms-ostree.adoc +++ b/microshift_updating/microshift-update-rpms-ostree.adoc @@ -1,18 +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.17 to 4.18 or from 4.18.2 to 4.18.3. +[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.17 to 4.18 or from {ocp-version}.2 to {ocp-version}.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] diff --git a/microshift_welcome/index.adoc b/microshift_welcome/index.adoc index 29c31dd7efc3..ad9ed487ab8e 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}] \ No newline at end of file diff --git a/modules/microshift-check-journal-logs-updates.adoc b/modules/microshift-check-journal-logs-updates.adoc index c2e12679f33e..ed4b78067442 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 e85f06a2c1a7..897c6a6d685d 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 index 4b4f382de1b4..aa1b9ff60c44 100644 --- a/modules/microshift-updates-rhde-config-rhel-repos.adoc +++ b/modules/microshift-updates-rhde-config-rhel-repos.adoc @@ -6,7 +6,8 @@ [id="microshift-updates-rhde-config-rhel-repos_{context}"] = Keeping {microshift-short} and {op-system-base} in a supported configuration -When using RPM updates, avoid creating an unsupported configuration or breaking your cluster by carefully managing your {op-system-base} repositories. +[role="_abstract"] +When using RPM updates, avoid creating an unsupported configuration or breaking your node by carefully managing your {op-system-base} repositories. .Prerequisites diff --git a/modules/microshift-updates-rpms-ostree-con.adoc b/modules/microshift-updates-rpms-ostree-con.adoc new file mode 100644 index 000000000000..29b7554b758a --- /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.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} 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 4f2f32677a14..29e4b204f40e 100644 --- a/modules/microshift-updates-troubleshooting.adoc +++ b/modules/microshift-updates-troubleshooting.adoc @@ -6,6 +6,7 @@ [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}"] @@ -14,11 +15,7 @@ Non-EUS versions of {microshift-short} require serial updates. For example, if y [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] @@ -34,11 +31,10 @@ Check the following update paths: * Generally Available Version 4.14.0 from {op-system-base} 9.2 to 4.15.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: +* Manually check the greenboot logs to verify system health by running the following command: + [source,terminal] ---- @@ -47,4 +43,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 db5c62e71d58..2b409f8b2cf9 100644 --- a/modules/microshift-updating-rpms-ostree.adoc +++ b/modules/microshift-updating-rpms-ostree.adoc @@ -6,15 +6,8 @@ [id="microshift-updates-rpms-ostree_{context}"] = Applying updates on an rpm-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. -==== +[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 81130008a135..fd95ad15a869 100644 --- a/modules/microshift-updating-rpms-y.adoc +++ b/modules/microshift-updating-rpms-y.adoc @@ -6,6 +6,7 @@ [id="microshift-updating-rpms_{context}"] = Applying minor-version updates with RPMs +[role="_abstract"] Updating a {microshift-short} minor version on non `rpm-ostree` systems such as {op-system-base-full} requires downloading then updating the RPMs. For example, use the following procedure to update from 4.16 to 4.18. include::snippets/microshift-unsupported-config-warn.adoc[leveloffset=+1] @@ -38,8 +39,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 4f8e4ea59062..b1c6fe1562d8 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. For example, use the following procedure to upgrade from 4.18.1 to 4.18.2. +[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 d6664d84625d..a866e0ccef05 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 @@ -26,5 +26,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-unsupported-config-warn.adoc b/snippets/microshift-unsupported-config-warn.adoc index 07c1d440dff7..5fc9c886dc38 100644 --- a/snippets/microshift-unsupported-config-warn.adoc +++ b/snippets/microshift-unsupported-config-warn.adoc @@ -8,5 +8,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/{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 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