Merge pull request #58739 from skopacz1/OSDOCS-5460

OSDOCS-5460: disconnected update workflows

Author: mburke5678

modules/update-mirror-repository.adoc

@@ -130,6 +130,12 @@ $ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}
 ----
 $ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
 ----
++
+[NOTE]
+====
+This command also generates and saves the mirrored release image signature config map onto the removable media.
+====
+
 ... Take the media to the disconnected environment and upload the images to the local container registry.
 +
 [source,terminal]

modules/update-restricted.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: PROCEDURE
 [id="update-restricted_{context}"]
-= Upgrading the disconnected cluster
+= Updating the disconnected cluster
 
 Update the disconnected cluster to the {product-title} version that you downloaded the release images for.
 

modules/update-service-configure-cvo.adoc

@@ -10,7 +10,7 @@ After the OpenShift Update Service Operator has been installed and the OpenShift
 .Prerequisites
 
 * The OpenShift Update Service Operator has been installed.
-* The OpenShift Update Service graph-data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
+* The OpenShift Update Service graph data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
 * The current release and update target releases have been mirrored to a locally accessible registry.
 * The OpenShift Update Service application has been created.
 

modules/update-service-create-service-cli.adoc

@@ -10,7 +10,7 @@ You can use the OpenShift CLI (`oc`) to create an OpenShift Update Service appli
 .Prerequisites
 
 * The OpenShift Update Service Operator has been installed.
-* The OpenShift Update Service graph-data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
+* The OpenShift Update Service graph data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
 * The current release and update target releases have been mirrored to a locally accessible registry.
 
 .Procedure
@@ -39,7 +39,7 @@ $ NAME=service
 $ RELEASE_IMAGES=registry.example.com/ocp4/openshift4-release-images
 ----
 
-. Set the local pullspec for the graph-data image to the graph-data container image created in "Creating the OpenShift Update Service graph data container image", for example, `registry.example.com/openshift/graph-data:latest`:
+. Set the local pullspec for the graph data image to the graph data container image created in "Creating the OpenShift Update Service graph data container image", for example, `registry.example.com/openshift/graph-data:latest`:
 //TODO: Add xref to the preceding step when allowed.
 +
 [source,terminal]

modules/update-service-create-service-web-console.adoc

@@ -10,7 +10,7 @@ You can use the {product-title} web console to create an OpenShift Update Servic
 .Prerequisites
 
 * The OpenShift Update Service Operator has been installed.
-* The OpenShift Update Service graph-data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
+* The OpenShift Update Service graph data container image has been created and pushed to a repository that is accessible to the OpenShift Update Service.
 * The current release and update target releases have been mirrored to a locally accessible registry.
 
 .Procedure
@@ -25,7 +25,7 @@ You can use the {product-title} web console to create an OpenShift Update Servic
 
 . Enter a name in the *Name* field, for example, `service`.
 
-. Enter the local pullspec in the *Graph Data Image* field to the graph-data container image created in "Creating the OpenShift Update Service graph data container image", for example, `registry.example.com/openshift/graph-data:latest`.
+. Enter the local pullspec in the *Graph Data Image* field to the graph data container image created in "Creating the OpenShift Update Service graph data container image", for example, `registry.example.com/openshift/graph-data:latest`.
 //TODO: Add xref to preceding step when allowed.
 
 . In the *Releases* field, enter the local registry and repository created to contain the release images in "Mirroring the OpenShift Container Platform image repository", for example, `registry.example.com/ocp4/openshift4-release-images`.

modules/update-service-graph-data.adoc

@@ -5,7 +5,12 @@
 [id="update-service-graph-data_{context}"]
 = Creating the OpenShift Update Service graph data container image
 
-The OpenShift Update Service requires a graph-data container image, from which the OpenShift Update Service retrieves information about channel membership and blocked update edges. Graph data is typically fetched directly from the upgrade graph data repository. In environments where an internet connection is unavailable, loading this information from an init container is another way to make the graph data available to the OpenShift Update Service. The role of the init container is to provide a local copy of the graph data, and during pod initialization, the init container copies the data to a volume that is accessible by the service.
+The OpenShift Update Service requires a graph data container image, from which the OpenShift Update Service retrieves information about channel membership and blocked update edges. Graph data is typically fetched directly from the upgrade graph data repository. In environments where an internet connection is unavailable, loading this information from an init container is another way to make the graph data available to the OpenShift Update Service. The role of the init container is to provide a local copy of the graph data, and during pod initialization, the init container copies the data to a volume that is accessible by the service.
+
+[NOTE]
+====
+The oc-mirror OpenShift CLI (`oc`) plugin creates this graph data container image in addition to mirroring release images. If you used the oc-mirror plugin to mirror your release images, you can skip this procedure.
+====
 
 .Procedure
 
@@ -22,14 +27,14 @@ RUN mkdir -p /var/lib/cincinnati-graph-data && tar xvzf cincinnati-graph-data.ta
 CMD ["/bin/bash", "-c" ,"exec cp -rp /var/lib/cincinnati-graph-data/* /var/lib/cincinnati/graph-data"]
 ----
 
-. Use the docker file created in the above step to build a graph-data container image, for example, `registry.example.com/openshift/graph-data:latest`:
+. Use the docker file created in the above step to build a graph data container image, for example, `registry.example.com/openshift/graph-data:latest`:
 +
 [source,terminal]
 ----
 $ podman build -f ./Dockerfile -t registry.example.com/openshift/graph-data:latest
 ----
 
-. Push the graph-data container image created in the previous step to a repository that is accessible to the OpenShift Update Service, for example, `registry.example.com/openshift/graph-data:latest`:
+. Push the graph data container image created in the previous step to a repository that is accessible to the OpenShift Update Service, for example, `registry.example.com/openshift/graph-data:latest`:
 +
 [source,terminal]
 ----
@@ -38,5 +43,5 @@ $ podman push registry.example.com/openshift/graph-data:latest
 +
 [NOTE]
 ====
-To push a graph data image to a local registry in a disconnected environment, copy the graph-data container image created in the previous step to a repository that is accessible to the OpenShift Update Service. Run `oc image mirror --help` for available options.
+To push a graph data image to a local registry in a disconnected environment, copy the graph data container image created in the previous step to a repository that is accessible to the OpenShift Update Service. Run `oc image mirror --help` for available options.
 ====

updating/updating-restricted-network-cluster/mirroring-image-repository.adoc

@@ -13,19 +13,39 @@ You must mirror container images onto a mirror registry before you can update a
 Your mirror registry must be running at all times while the cluster is running.
 ====
 
-There are two methods for mirroring images onto a mirror registry:
+The following steps outline the high-level workflow on how to mirror images to a mirror registry:
 
-* xref:../../updating/updating-restricted-network-cluster/mirroring-image-repository.adoc#mirroring-ocp-resources-ocmirror[Using the oc-mirror OpenShift CLI (`oc`) plugin]
+. Install the OpenShift CLI (`oc`) on all devices being used to retrieve and push release images.
 
-* xref:../../updating/updating-restricted-network-cluster/mirroring-image-repository.adoc#update-mirror-repository-adm-release-mirror_mirroring-ocp-image-repository[Using the `oc adm release mirror` command]
+. Download the registry pull secret and add it to your cluster.
 
-Compared to using the `oc adm release mirror`command, the oc-mirror plugin has the following advantages:
+. If you use the xref:../../updating/updating-restricted-network-cluster/mirroring-image-repository.adoc#mirroring-ocp-resources-ocmirror[oc-mirror OpenShift CLI (`oc`) plugin]:
+
+.. Install the oc-mirror plugin on all devices being used to retrieve and push release images.
+
+.. Create an image set configuration file for the plugin to use when determining which release images to mirror. You can edit this configuration file later to change which release images that the plugin mirrors.
+
+.. Mirror your targeted release images directly to a mirror registry, or to removable media and then to a mirror registry.
+
+.. Install the `ImageContentSourcePolicy` and `CatalogSource` resources that oc-mirror generated into the cluster.
+
+.. Repeat these steps as needed to update your mirror registry.
+
+. If you use the xref:../../updating/updating-restricted-network-cluster/mirroring-image-repository.adoc#update-mirror-repository-adm-release-mirror_mirroring-ocp-image-repository[`oc adm release mirror` command]:
+
+.. Set environment variables that correspond to your environment and the release images you want to mirror.
+
+.. Mirror your targeted release images directly to a mirror registry, or to removable media and then to a mirror registry.
+
+.. Repeat these steps as needed to update your mirror registry.
+
+Compared to using the `oc adm release mirror` command, the oc-mirror plugin has the following advantages:
 
 * It can mirror content other than container images.
 
 * After mirroring images for the first time, it is easier to update images in the registry.
 
-* The oc-mirror plugin provides an automated way to mirror the release payload from Quay, and also builds the latest graph-data image for the OpenShift Update Service running in the disconnected environment.
+* The oc-mirror plugin provides an automated way to mirror the release payload from Quay, and also builds the latest graph data image for the OpenShift Update Service running in the disconnected environment.
 
 [id="prerequisites_updating-mirroring-disconnected"]
 == Prerequisites
@@ -51,24 +71,13 @@ include::modules/cli-installing-cli.adoc[leveloffset=+2]
 
 * xref:../../cli_reference/openshift_cli/extending-cli-plugins.adoc#cli-installing-plugins_cli-extend-plugins[Installing and using CLI plugins]
 
-// this file doesn't exist, so I'm including the one that should pick up more changes from Clayton's PR - modules/installation-adding-mirror-registry-pull-secret.adoc[leveloffset=+1]
-
 include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+2]
 
 [id=mirroring-ocp-resources-ocmirror]
 == Mirroring resources using the oc-mirror plugin
 
 You can use the oc-mirror OpenShift CLI (`oc`) plugin to mirror images to a mirror registry in your fully or partially disconnected environments. You must run oc-mirror from a system with internet connectivity to download the required images from the official Red Hat registries.
 
-The following steps outline the high-level workflow on how to use the oc-mirror plugin to mirror images to a mirror registry:
-
-. Create an image set configuration file.
-. Mirror the image set to the mirror registry by using one of the following methods:
-** Mirror an image set directly to the mirror registry.
-** Mirror an image set to disk, transfer the image set to the target environment, and then upload the image set to the target mirror registry.
-. Install the `ImageContentSourcePolicy` and `CatalogSource` resources that were generated by oc-mirror into the cluster.
-. Repeat these steps to update your mirror registry as necessary.
-
 // About the oc-mirror plugin
 include::modules/oc-mirror-about.adoc[leveloffset=+2]
 

updating/updating-restricted-network-cluster/restricted-network-update-osus.adoc

@@ -6,7 +6,21 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-To get an update experience similar to connected clusters, you can use the following procedures to install and configure the OpenShift Update Service in a disconnected environment.
+To get an update experience similar to connected clusters, you can use the following procedures to install and configure the OpenShift Update Service (OSUS) in a disconnected environment.
+
+The following steps outline the high-level workflow on how to update a cluster in a disconnected environment using OSUS:
+
+. Configure access to a secured registry.
+
+. Update the global cluster pull secret to access your mirror registry.
+
+. Install the OSUS Operator.
+
+. Create a graph data container image for the OpenShift Update Service.
+
+. Install the OSUS application and configure your clusters to use the local OpenShift Update Service.
+
+. Perform a supported update procedure from the documentation as you would with a connected cluster.
 
 include::modules/disconnected-osus-overview.adoc[leveloffset=+1]
 

updating/updating-restricted-network-cluster/restricted-network-update.adoc

@@ -19,7 +19,11 @@ See xref:../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define an
 * If your cluster uses manually maintained credentials, you must ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP].
 //STS is not currently supported in a disconnected environment, but the following bullet can be uncommented when that changes.
 //* If your cluster uses manually maintained credentials with the AWS Security Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_].
-* If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the upgrade process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain.
+
+[NOTE]
+====
+If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the upgrade process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain.
+====
 
 include::modules/machine-health-checks-pausing.adoc[leveloffset=+1]