Merge pull request #48412 from tshwartz/TELCODOCS-791-Upgrade

TELCODOCS-791-Upgrade: Adding KATA notes to Upgrade section

Author: EricPonvelle

_topic_maps/_topic_map.yml

@@ -2137,8 +2137,8 @@ Topics:
   File: monitoring-sandboxed-containers
 - Name: Uninstalling OpenShift sandboxed containers
   File: uninstalling-sandboxed-containers
-- Name: Upgrade OpenShift sandboxed containers
-  File: upgrade-sandboxed-containers
+- Name: Upgrading OpenShift sandboxed containers
+  File: upgrading-sandboxed-containers
 - Name: Collecting OpenShift sandboxed containers data
   File: troubleshooting-sandboxed-containers
 ---
@@ -2307,7 +2307,7 @@ Topics:
 - Name: Deploying distributed units manually on single-node OpenShift
   File: ztp-configuring-single-node-cluster-deployment-during-installation
   Distros: openshift-origin,openshift-enterprise
-- Name: Validating cluster tuning for vDU application workloads 
+- Name: Validating cluster tuning for vDU application workloads
   File: ztp-vdu-validating-cluster-tuning
   Distros: openshift-origin,openshift-enterprise
 - Name: Provisioning and deploying a distributed unit (DU)

modules/sandboxed-containers-upgrading-monitor-pods-cli.adoc

@@ -0,0 +1,28 @@
+//Module included in the following assemblies:
+//
+// *upgrading-sandboxed-containers.adoc
+
+:_content-type: PROCEDURE
+[id="sandboxed-containers-upgrading-monitor-pods-cli_{context}"]
+= Upgrading the monitor pods using the CLI
+
+You can manually patch the monitor image in the `KataConfig` CR to update the monitor pods.
+
+.Prerequisites
+
+* You have {product-title} {product-version} installed on your cluster.
+* You have installed the OpenShift CLI (`oc`).
+* You have access to the cluster as a user with the `cluster-admin` role.
+
+.Procedure
+
+* In the {product-title} CLI, run the following command:
++
+[source,terminal]
+----
+$ oc patch kataconfig <kataconfig_name> --type merge --patch
+'{"spec":{"kataMonitorImage":"registry.redhat.io/openshift-sandboxed-containers/osc-monitor-rhel8:1.3.0"}}'
+----
++
+where:
+`<kataconfig_name>`:: specifies the name of your Kata configuration file, such as `example-kataconfig`.

modules/sandboxed-containers-upgrading-monitor-pods-web.adoc

@@ -0,0 +1,32 @@
+//Module included in the following assemblies:
+//
+// *upgrading-sandboxed-containers.adoc
+
+:_content-type: PROCEDURE
+[id="sandboxed-containers-upgrading-monitor-pods-web_{context}"]
+= Upgrading the monitor pods using the web console
+
+The `KataConfig` YAML file in the {product-title} contains the version number for the monitor image. Update the version number with the correct version.
+
+.Prerequisites
+
+* You have {product-title} {product-version} installed on your cluster.
+* You have access to the cluster as a user with the `cluster-admin` role.
+
+.Procedure
+
+. From the *Administrator* perspective of {product-title}, navigate to *Operators* → *Installed Operators*.
+. Select the *{sandboxed-containers-operator}* and go to the *KataConfig* tab.
+. Search for the `KataConfig` resource using the *Search by name* field. The default name for the `KataConfig` resource is *example-kataconfig*.
+. Select the `KataConfig` resource and go to the *KataConfig* tab.
+. Modify the version number for `kataMonitorImage`:
+
++
+[source,yaml]
+----
+    checkNodeEligibility: false
+    kataConfigPoolSelector: null
+    kataMonitorImage: 'registry.redhat.io/openshift-sandboxed-containers/osc-monitor-rhel8:1.3.0'
+----
+
+. Click *Save*.

sandboxed_containers/upgrade-sandboxed-containers.adoc

@@ -0,0 +1,51 @@
+:_content-type: ASSEMBLY
+[id="upgrading-sandboxed-containers"]
+= Upgrading {sandboxed-containers-first}
+include::_attributes/common-attributes.adoc[]
+:context: upgrading-sandboxed-containers
+
+toc::[]
+
+The upgrade of the {sandboxed-containers-first} components consists of the following three steps:
+
+* Upgrading {product-title} to update the `Kata` runtime and its dependencies.
+
+* Upgrading the {sandboxed-containers-operator} to update the Operator subscription.
+
+* Manually patching the `KataConfig` custom resource (CR) to update the monitor pods.
+
+You can upgrade {product-title} before or after the {sandboxed-containers-operator} upgrade, with the one exception noted below. Always apply the `KataConfig` patch immediately after upgrading {sandboxed-containers-operator}.
+
+[IMPORTANT]
+====
+
+If you are upgrading to {product-title} 4.11 with {sandboxed-containers-first} 1.3, the recommended order is to first upgrade {sandboxed-containers-first} from 1.2 to 1.3, and then upgrade {product-title} from 4.10 to 4.11.
+====
+
+[id="sandboxed-containers-upgrade-resources"]
+== Upgrading the {sandboxed-containers-first} resources
+
+The {sandboxed-containers-first} resources are deployed onto the cluster using {op-system-first} extensions.
+
+//Update the Red Hat CoreOS extension with the updated link once PR is approved for the Understanding section.
+
+The {op-system} extension `sandboxed containers` contains the required components to run Kata Containers such as the Kata containers runtime, the hypervisor QEMU, and other dependencies. You upgrade the extension by upgrading the cluster to a new release of {product-title}.
+
+For more information about upgrading {product-title}, see xref:../updating/index.adoc#index[Updating Clusters].
+
+[id="sandboxed-containers-upgrading-operator"]
+== Upgrading the {sandboxed-containers-operator}
+
+Use Operator Lifecycle Manager (OLM) to upgrade the {sandboxed-containers-operator} either manually or automatically. Selecting between manual or automatic upgrade during the initial deployment determines the future upgrade mode. For manual upgrades, the web console shows the available updates that can be installed by the cluster administrator.
+
+For more information about upgrading the {sandboxed-containers-operator} in Operator Lifecycle Manager (OLM), see xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators].
+
+[id="sandboxed-containers-upgrading-monitor-pods"]
+== Upgrading the {sandboxed-containers-first} monitor pods
+
+After upgrading {sandboxed-containers-first}, you need to update the monitor image in the `KataConfig` CR to upgrade the monitor pods. Otherwise, the monitor pods will continue running images from the previous version.
+
+You can perform the update using the web console or the CLI.
+
+include::modules/sandboxed-containers-upgrading-monitor-pods-web.adoc[leveloffset=+2]
+include::modules/sandboxed-containers-upgrading-monitor-pods-cli.adoc[leveloffset=+2]