openshift · wking · Jan 23, 2020
diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc
@@ -27,18 +27,28 @@ Complete the following steps on the mirror host:
 
 . Review the
 link:https://access.redhat.com/downloads/content/290/[{product-title} downloads page]
-to determine the version of {product-title} that you want to install and determine the corresponding tag on the link:https://quay.io/repository/openshift-release-dev/ocp-release?tab=tags[Repository Tags] page.
+to determine the version of {product-title} that you want to install.
+The image release advisory includes the pullspec repository and digest. For example, link:https://access.redhat.com/errata/product/290/ver=4.5/rhel---8/x86_64/RHBA-2020:3719[the 4.5.11 Bug Fix Advisory] uses `quay.io/openshift-release-dev/ocp-release` for the pullspec repository and  `sha256:4d048ae1274d11c49f9b7e70713a072315431598b2ddbb512aee4027c422fe3e` for the x86-64 4.5.11 release image digest.
 
 . Set the required environment variables:
-.. Export the release version:
+.. Export the image repository from the image release advisory:
 +
 [source,terminal]
 ----
-$ OCP_RELEASE=<release_version>
+$ OCP_RELEASE_REPOSITORY=quay.io/openshift-release-dev/ocp-release
+----
+
+.. Export the release digest from the image release advisory:
++
+[source,terminal]
+----
+$ OCP_RELEASE_DIGEST=<release_digest>
 ----
 +
-For `<release_version>`, specify the tag that corresponds to the version of {product-title} to
-install, such as `4.5.4`.
+For `<release_digest>`, specify the digest from the release image advisory, such as
+`sha256:4d048ae1274d11c49f9b7e70713a072315431598b2ddbb512aee4027c422fe3e`.
++
+If you want to inspect a particular release image, use `oc adm release info "${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}`.
 
 .. Export the local registry name and host port:
 +
@@ -61,14 +71,16 @@ $ LOCAL_REPOSITORY='<local_repository_name>'
 For `<local_repository_name>`, specify the name of the repository to create in your
 registry, such as `ocp4/openshift4`.
 
-.. Export the name of the repository to mirror:
+.. Export a tag name for the mirrored release image:
 +
 [source,terminal]
 ----
-$ PRODUCT_REPO='openshift-release-dev'
+$ LOCAL_TAG=<local_tag>
 ----
 +
-For a production release, you must specify `openshift-release-dev`.
+For `<local_tag>`, you may specify any tag name compatible with your local registry.
+To avoid conflicts, a safe pattern includes both the version of {product-title} to
+install, such as `4.5.11`, and the architecture for the release image, such as `x86_64`.
 
 .. Export the path to your registry pull secret:
 +
@@ -79,22 +91,6 @@ $ LOCAL_SECRET_JSON='<path_to_pull_secret>'
 +
 For `<path_to_pull_secret>`, specify the absolute path to and file name of the pull secret for your mirror registry that you created.
 
-.. Export the release mirror:
-+
-[source,terminal]
-----
-$ RELEASE_NAME="ocp-release"
-----
-+
-For a production release, you must specify `ocp-release`.
-
-.. Export the type of architecture for your server, such as `x86_64`.:
-+
-[source,terminal]
-----
-$ ARCHITECTURE=<server_architecture>
-----
-
 .. Export the path to the directory to host the mirrored images:
 +
 [source,terminal]
@@ -110,23 +106,23 @@ $ REMOVABLE_MEDIA_PATH=<path>
 [source,terminal]
 ----
 $ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
-     --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
+     --from=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} \
      --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
-     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run
+     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${LOCAL_TAG} --dry-run
 ----
 ... Record the entire `imageContentSources` section from the output of the previous
 command. The information about your mirrors is unique to your mirrored repository, and you must add the `imageContentSources` section to the `install-config.yaml` file during installation.
 ... Mirror the images to a directory on the removable media:
 +
 [source,terminal]
 ----
-$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
+$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror ${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}
 ----
 ... Take the media to the restricted network environment and upload the images to the local container registry.
 +
 [source,terminal]
 ----
-$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
+$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:4.*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
 ----
 
 ** If the local container registry is connected to the mirror host, take the following actions:
@@ -135,9 +131,9 @@ $ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mir
 [source,terminal]
 ----
 $ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
-     --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
+     --from=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} \
      --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
-     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
+     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${LOCAL_TAG}
 ----
 +
 This command pulls the release information as a digest, and its output includes
@@ -151,7 +147,7 @@ mirrored, extract it and pin it to the release:
 +
 [source,terminal]
 ----
-$ oc adm -a ${LOCAL_SECRET_JSON} release extract --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}"
+$ oc adm -a ${LOCAL_SECRET_JSON} release extract --command=openshift-install "${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}"
 ----
 +
 [IMPORTANT]

diff --git a/modules/update-mirror-repository.adoc b/modules/update-mirror-repository.adoc
@@ -10,16 +10,27 @@ Before you upgrade a cluster on infrastructure that you provision in a restricte
 .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.
+The image release advisory includes the pullspec repository and digest. For example, link:https://access.redhat.com/errata/product/290/ver=4.5/rhel---8/x86_64/RHBA-2020:3719[the 4.5.11 Bug Fix Advisory] uses `quay.io/openshift-release-dev/ocp-release` for the pullspec repository and  `sha256:4d048ae1274d11c49f9b7e70713a072315431598b2ddbb512aee4027c422fe3e` for the x86-64 4.5.11 release image digest.
 
 . Set the required environment variables:
-.. Export the release version:
+.. Export the image repository from the image release advisory:
 +
 [source,terminal]
 ----
-$ export OCP_RELEASE=<release_version>
+$ OCP_RELEASE_REPOSITORY=quay.io/openshift-release-dev/ocp-release
 ----
+
+.. Export the release digest from the image release advisory:
++
+[source,terminal]
+----
+$ OCP_RELEASE_DIGEST=<release_digest>
+----
++
+For `<release_digest>`, specify the digest from the release image advisory, such as
+`sha256:4d048ae1274d11c49f9b7e70713a072315431598b2ddbb512aee4027c422fe3e`.
 +
-For `<release_version>`, specify the tag that corresponds to the version of {product-title} to which you want to upgrade, such as `4.5.4`.
+If you want to inspect a particular release image, use `oc adm release info "${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}`.
 
 .. Export the local registry name and host port:
 +
@@ -42,14 +53,16 @@ $ LOCAL_REPOSITORY='<local_repository_name>'
 For `<local_repository_name>`, specify the name of the repository to create in your
 registry, such as `ocp4/openshift4`.
 
-.. Export the name of the repository to mirror:
+.. Export a tag name for the mirrored release image:
 +
 [source,terminal]
 ----
-$ PRODUCT_REPO='openshift-release-dev'
+$ LOCAL_TAG=<local_tag>
 ----
 +
-For a production release, you must specify `openshift-release-dev`.
+For `<local_tag>`, you may specify any tag name compatible with your local registry.
+To avoid conflicts, a safe pattern includes both the version of {product-title} to
+install, such as `4.5.11`, and the architecture for the release image, such as `x86_64`.
 
 .. Export the path to your registry pull secret:
 +
@@ -60,58 +73,53 @@ $ LOCAL_SECRET_JSON='<path_to_pull_secret>'
 +
 For `<path_to_pull_secret>`, specify the absolute path to and file name of the pull secret for your mirror registry that you created.
 
-.. Export the release mirror:
-+
-[source,terminal]
-----
-$ RELEASE_NAME="ocp-release"
-----
-+
-For a production release, you must specify `ocp-release`.
-
-.. Export the type of architecture for your server, such as `x86_64`.:
-+
-[source,terminal]
-----
-$ ARCHITECTURE=<server_architecture>
-----
-
 .. Export the path to the directory to host the mirrored images:
 +
 [source,terminal]
 ----
 $ REMOVABLE_MEDIA_PATH=<path>
 ----
 
-. Review the images and configuration manifests to mirror:
+. 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.
+... Review the images and configuration manifests to mirror:
 +
 [source,terminal]
 ----
-$ 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
+$ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
+     --from=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} \
+     --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
+     --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${LOCAL_TAG} --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:
+... Record the entire `ImageContentSourcePolicy` section from the output of the previous
+command. The information about your mirrors is unique to your mirrored repository, and you must ensure your in-cluster `ImageContentSourcePolicy` includes the entries needed for the mirrored release.
+... Mirror the images to a directory on the removable media:
 +
 [source,terminal]
 ----
-$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
+$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror ${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}
 ----
 ... Take the media to the restricted network environment and upload the images to the local container registry.
 +
 [source,terminal]
 ----
-$ oc image mirror  -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
+$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:4.*" ${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:
 +
 [source,terminal]
 ----
-$ 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
+$ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
+     --from=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} \
+     --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
+     --apply-release-image-signature
 ----
 +
+... Record the entire `ImageContentSourcePolicy` section from the output of the previous
+command. The information about your mirrors is unique to your mirrored repository, and you must ensure your in-cluster `ImageContentSourcePolicy` includes the entries needed for the mirrored release.
+
 [NOTE]
 ====
 If you include the `--apply-release-image-signature` option, do not create the ConfigMap for image signature verification.