Adding documentation for updating a disconnected cluster

_topic_map.yml

@@ -283,8 +283,9 @@ Topics:
 - Name: Updating a cluster that includes RHEL compute machines
   File: updating-cluster-rhel-compute
   Distros: openshift-enterprise,openshift-webscale
-#- Name: Updating a disconnected cluster
-#  File: updating-disconnected-cluster
+- Name: Updating a restricted network cluster
+  File: updating-restricted-network-cluster
+  Distros: openshift-enterprise,openshift-webscale
 # - Name: Troubleshooting an update
 #  File: updating-troubleshooting
 ---

modules/cli-installing-cli.adoc

@@ -24,9 +24,14 @@
 // * openshift_images/samples-operator-alt-registry.adoc
 // * installing/installing_rhv/installing-rhv-customizations.adoc
 // * installing/installing_rhv/installing-rhv-default.adoc
+// * updating/updating-restricted-network-cluster.adoc
 //
 // AMQ docs link to this; do not change anchor
 
+ifeval::["{context}" == "updating-restricted-network-cluster"]
+:restricted:
+endif::[]
+
 [id="cli-installing-cli_{context}"]
 = Installing the CLI by downloading the binary
 
@@ -38,6 +43,9 @@ command-line interface. You can install `oc` on Linux, Windows, or macOS.
 If you installed an earlier version of `oc`, you cannot use it to complete all
 of the commands in {product-title} {product-version}. Download and
 install the new version of `oc`.
+ifdef::restricted[]
+If you are upgrading a cluster in a restricted network, install the `oc` version that you plan to upgrade to.
+endif::restricted[]
 ====
 
 [id="cli-installing-cli-on-linux_{context}"]
@@ -136,3 +144,8 @@ After you install the CLI, it is available using the `oc` command:
 ----
 $ oc <command>
 ----
+
+
+ifeval::["{context}" == "updating-restricted-network-cluster"]
+:!restricted:
+endif::[]

modules/installation-adding-registry-pull-secret.adoc

@@ -1,6 +1,11 @@
 // Module included in the following assemblies:
 //
 // * openshift_images/samples-operator-alt-registry.adoc
+// * updating/updating-restricted-network-cluster.adoc
+
+ifeval::["{context}" == "updating-restricted-network-cluster"]
+:restricted:
+endif::[]
 
 [id="installation-adding-registry-pull-secret_{context}"]
 = Adding the registry to your pull secret
@@ -9,6 +14,18 @@ Modify your the pull secret for your {product-title} cluster to describe
 your local registry before you install an {product-title} cluster in a
 restricted network.
 
+ifdef::restricted[]
+[WARNING]
+====
+This process requires that you have write access to a container image registry on the mirror registry and adds the credentials to a registry pull secret.
+====
+
+[IMPORTANT]
+====
+Do not use this image registry credentials file as the pull secret when you install a cluster. If you provide this file when you install cluster, all of the machines in the cluster will have write access to your mirror registry.
+====
+endif::restricted[]
+
 .Prerequisites
 
 * You configured a mirror registry to use in your restricted network.
@@ -111,3 +128,8 @@ The file resembles the following example:
   }
 }
 ----
+
+
+ifeval::["{context}" == "updating-restricted-network-cluster"]
+:!restricted:
+endif::[]

modules/installation-mirror-repository.adoc

@@ -38,9 +38,10 @@ $ export LOCAL_REPOSITORY='<repository_name>' <3>
 $ export PRODUCT_REPO='openshift-release-dev' <4>
 $ export LOCAL_SECRET_JSON='<path_to_pull_secret>' <5>
 $ export RELEASE_NAME="ocp-release" <6>
+$ export ARCHITECTURE=<server_architecture> <7>
 ----
 <1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} to
-install for your architecture, such as `4.4.0-x86_64`.
+install, such as `4.5.0`.
 <2> For `<local_registry_host_name>`, specify the registry domain name for your mirror
 repository, and for `<local_registry_host_port>`, specify the port that it
 serves content on.
@@ -52,14 +53,16 @@ registry, such as `ocp4/openshift4`.
 the pull secret for your mirror registry that you created.
 <6> The release mirror. For a production release, you must specify
 `ocp-release`.
+<7> For `server_architecture`, specify the architecture of the server, such as `x86_64`.
+
 
 . Mirror the repository:
 +
 ----
 $ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
-     --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \
+     --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
      --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
-     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}
+     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
 ----
 +
 This command pulls the release information as a digest, and its output includes
@@ -72,7 +75,7 @@ command. The information about your mirrors is unique to your mirrored repositor
 mirrored, extract it and pin it to the release:
 +
 ----
-$ oc adm -a ${LOCAL_SECRET_JSON} release extract --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}"
+$ oc adm -a ${LOCAL_SECRET_JSON} release extract --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}"
 ----
 +
 [IMPORTANT]

modules/update-configuring-image-signature.adoc

@@ -0,0 +1,78 @@
+// Module included in the following assemblies:
+//
+// * updating/updating-restricted-network-cluster.adoc
+
+[id="update-configuring-image-signature"]
+= Creating an image signature ConfigMap manually
+
+Create and apply the image signature ConfigMap to the cluster that you want to update.
+
+[NOTE]
+====
+You must perform following steps each time that you update a cluster.
+====
+
+.Procedure
+
+. Review the link:https://access.redhat.com/solutions/4583231[{product-title} upgrade paths] knowledge base article to determine a valid upgrade path for your cluster.
+
+. Add the version to the `OCP_RELEASE_NUMBER` environment variable:
++
+----
+$ OCP_RELEASE_NUMBER=<release_version> <1>
+----
+<1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} you want
+to update the cluster, such as `4.4.0`.
+
+. Add the system architecture for your cluster to `ARCHITECTURE` environment variable:
++
+----
+$ ARCHITECTURE=<server_architecture> <11>
+----
+<1> For `server_architecture`, specify the architecture of the server, such as `x86_64`.
+
+. Get the release image digest from link:https://quay.io/[Quay]:
++
+----
+$ DIGEST="$(oc adm release info quay.io/openshift-release-dev/ocp-release:${OCP_RELEASE_NUMBER}-${ARCHITECTURE} | sed -n 's/Pull From: .*@//p')"
+----
+
+. Set the digest algorithm:
++
+----
+$ DIGEST_ALGO="${DIGEST%%:*}"
+----
+
+. Set the digest signature:
++
+----
+$ DIGEST_ENCODED="${DIGEST#*:}"
+----
+
+. Get the image signature from link:https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release[mirror.openshift.com] website.
++
+----
+$ SIGNATURE_BASE64=$(curl -s "https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release/${DIGEST_ALGO}=${DIGEST_ENCODED}/signature-1" | base64 -w0 && echo)
+----
+
+. Create the ConfigMap:
++
+----
+$ cat >checksum-${OCP_RELEASE_NUMBER}.yaml <<EOF
+ apiVersion: v1
+ kind: ConfigMap
+ metadata:
+   name: release-image-${OCP_RELEASE_NUMBER}
+   namespace: openshift-config-managed
+   labels:
+     release.openshift.io/verification-signatures: ""
+ binaryData:
+   ${DIGEST_ALGO}-${DIGEST_ENCODED}: ${SIGNATURE_BASE64}
+ EOF
+----
+
+. Apply the ConfigMap to the cluster to update:
++
+----
+$ oc apply -f checksum-${OCP_RELEASE_NUMBER}.yaml
+----

modules/update-mirror-repository.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * updating/updating-restricted-network-cluster.adoc
+
+[id="update-mirror-repository_{context}"]
+= Mirroring the {product-title} image repository
+
+Before you upgrade a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. You can also use this procedure in unrestricted networks to ensure your clusters only use container images that have satisfied your organizational controls on external content.
+
+.Procedure
+
+. Review the link:https://access.redhat.com/solutions/4583231[{product-title} upgrade paths] to confirm that there is an upgrade path between your current and intended cluster versions.
+
+. Set the required environment variables:
++
+----
+$ OCP_RELEASE=<release_version> # <1>
+$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>' # <2>
+$ LOCAL_REPOSITORY='<repository_name>' # <3>
+$ PRODUCT_REPO='openshift-release-dev' # <4>
+$ LOCAL_SECRET_JSON='<path_to_pull_secret>' # <5>
+$ RELEASE_NAME='ocp-release' # <6>
+$ ARCHITECTURE=<server_architecture> # <7>
+$ REMOVABLE_MEDIA_PATH=<path> <8>
+----
+<1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} to which you want to upgrade, such as `4.5.0`.
+<2> For `<local_registry_host_name>`, specify the registry domain name for your mirror
+repository, and for `<local_registry_host_port>`, specify the port that it
+serves content on.
+<3> For `<repository_name>`, specify the name of the repository to create in your
+registry, such as `ocp4/openshift4`.
+<4> The repository to mirror. For a production release, you must specify
+`openshift-release-dev`.
+<5> For `<path_to_pull_secret>`, specify the absolute path to and file name of
+the pull secret for your mirror registry that you created.
+<6> For a production release, you must specify
+`ocp-release`.
+<7> For `<server_architecture>`, specify the architecture of the server, such as `x86_64`.
+<8> For `<path>`, specify the path to the directory to host the mirrored images.
+
+. Review the images and configuration manifests to mirror:
++
+----
+$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run
+----
+. Mirror the version images to the internal container registry.
+** If your mirror host does not have internet access, take the following actions:
+... Connect the removable media to a system that is connected to the internet.
+... Mirror the images and configuration manifests to a directory on the removable media:
++
+----
+$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
+----
+... Take the media to the restricted network environment and upload the images to the local container registry.
++
+----
+$ oc image mirror  -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror 'file://openshift/release:${OCP_RELEASE}*' ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
+----
+** If the local container registry and the cluster are connected to the mirror host, directly push the release images to the local registry and apply the ConfigMap to the cluster by using following command:
++
+----
+$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
+  --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} --apply-release-image-signature
+----
++
+[NOTE]
+====
+If you include the `--apply-release-image-signature` option, do not create the ConfigMap for image signature verification.
+====

modules/update-oc-configmap-signature-verification.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * updating/updating-restricted-network-cluster.adoc
+
+[id="update-oc-configmap-signature-verification_{context}"]
+= Creating the ConfigMap for image signature verification by using the `oc` CLI
+
+Before you update your cluster, you must manually create a ConfigMap that contains the signatures of the release images that you use. This signature allows the Cluster Version Operator (CVO) to verify that the release images have not been modified by comparing the expected and actual image signatures.
+
+[NOTE]
+====
+If you are upgrading from a release prior to version 4.4.8, you must use the manual method for creating the ConfigMap instead of this procedure. The commands that this procedure uses are not in earlier versions of the `oc` command-line interface (CLI).
+====
+
+.Prerequisites
+
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`, version 4.4.8 or later.
+
+.Procedure
+
+. Obtain the image signature for the version that you are upgrading to from either link:https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release[mirror.openshift.com] or link:https://storage.googleapis.com/openshift-release/official/signatures[Google Cloud Storage (GCS)].
+
+. Use `oc` command-line interface (CLI) to log into the cluster that you are upgrading.
+
+. Apply the the mirrored release image signature ConfigMap to the connected cluster:
++
+----
+$ oc apply -f <image_signature_file> <1>
+----
+<1> For `<image_signature_file>`, specify the path and name of the file, for example, `mirror/config/signature-sha256-81154f5c03294534.yaml`.

modules/update-restricted.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * updating/updating-restricted-network-cluster.adoc
+
+[id="update-restricted_{context}"]
+= Upgrading the restricted network cluster
+
+Update the restricted network cluster to the {product-title} version that you downloaded the release images for.
+
+.Prerequisites
+
+* You mirrored the images for the new release to your registry.
+* You applied the release image signature ConfigMap for the new release to your cluster.
+* You obtained the sha256 sum value for the release from the image signature ConfigMap.
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`, version 4.4.8 or later.
+
+.Procedure
+
+* Update the cluster:
++
+----
+$ oc adm upgrade --allow-explicit-upgrade --to-image ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}<sha256_sum_value> <1>
+----
+<1> The `<sha256_sum_value>` value is the sha256 sum value for the release from the image signature ConfigMap, for example, `@sha256:81154f5c03294534e1eaf0319bef7a601134f891689ccede5d705ef659aa8c92`
++
+If you use an `ImageContentSourcePolicy` for the mirror registry, you can use the canonical registry name instead of `LOCAL_REGISTRY`.