diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc index 8ef7c8b9adda..9aa0735d9e1d 100644 --- a/modules/installation-mirror-repository.adoc +++ b/modules/installation-mirror-repository.adoc @@ -33,20 +33,36 @@ x509: certificate relies on legacy Common Name field, use SANs or temporarily en Complete the following steps on the mirror host: +[NOTE] +==== +Optionally, you can use image tag name instead of image digest in the following commands. +==== + . 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/downloads/content/290/ver={product-version}/rhel---8/[In the errata tab here], +uses `quay.io/openshift-release-dev/ocp-release` for the pullspec repository. . Set the required environment variables: -.. Export the release version: +.. Export the image repository from the image release advisory: ++ +[source,terminal] +---- +$ OCP_RELEASE_REPOSITORY=quay.io/openshift-release-dev/ocp-release +---- + +.. Export the release digest from the image release advisory: + [source,terminal] ---- -$ OCP_RELEASE= +$ OCP_RELEASE_DIGEST= ---- + -For ``, specify the tag that corresponds to the version of {product-title} to -install, such as `4.5.4`. +For ``, 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: + @@ -69,15 +85,17 @@ $ LOCAL_REPOSITORY='' For ``, 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: + ifndef::openshift-origin[] [source,terminal] ---- -$ PRODUCT_REPO='openshift-release-dev' +$ LOCAL_TAG= ---- + -For a production release, you must specify `openshift-release-dev`. +For ``, 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, and the architecture for the release image, such as `x86_64`. endif::[] ifdef::openshift-origin[] [source,terminal] @@ -95,32 +113,6 @@ $ LOCAL_SECRET_JSON='' + For ``, specify the absolute path to and file name of the pull secret for your mirror registry that you created. -.. Export the release mirror: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ RELEASE_NAME="ocp-release" ----- -+ -For a production release, you must specify `ocp-release`. -endif::[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ RELEASE_NAME="okd" ----- -endif::[] - -ifndef::openshift-origin[] -.. Export the type of architecture for your server, such as `x86_64`: -+ -[source,terminal] ----- -$ ARCHITECTURE= ----- -endif::[] - .. Export the path to the directory to host the mirrored images: + [source,terminal] @@ -147,9 +139,9 @@ ifndef::openshift-origin[] [source,terminal] ---- $ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --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=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} --dry-run ---- endif::[] @@ -160,13 +152,13 @@ command. The information about your mirrors is unique to your mirrored repositor ifdef::openshift-origin[] [source,terminal] ---- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} +$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror ${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} ---- endif::[] ifndef::openshift-origin[] [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} ---- endif::[] @@ -186,18 +178,18 @@ ifdef::openshift-origin[] [source,terminal] ---- $ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \ + --from=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} \ --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ - --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE} + --to-release-image=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} ---- endif::[] ifndef::openshift-origin[] [source,terminal] ---- $ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --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=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} ---- endif::[] + @@ -218,20 +210,20 @@ mirrored, extract it and pin it to the release: + [source,terminal] ---- -$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}" +$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}" ---- ** If the local container registry is connected to the mirror host, run the following command: + ifdef::openshift-origin[] [source,terminal] ---- -$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}" +$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}" ---- endif::[] ifndef::openshift-origin[] [source,terminal] ---- -$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}" +$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST}" ---- endif::[] + diff --git a/modules/update-mirror-repository.adoc b/modules/update-mirror-repository.adoc index cafb6388745a..279bbb5a6717 100644 --- a/modules/update-mirror-repository.adoc +++ b/modules/update-mirror-repository.adoc @@ -9,17 +9,29 @@ Before you upgrade a cluster on infrastructure that you provision in a restricte .Procedure + + . Use the link:https://access.redhat.com/labs/ocpupgradegraph/update_channel[Red Hat {product-title} Upgrade Graph visualizer and update planner] to plan an upgrade from one version to another. The OpenShift Upgrade Graph provides channel graphs and a way to confirm that there is an update path between your current and intended cluster versions. . Set the required environment variables: -.. Export the release version: +.. Export the image repository from the image release advisory: + [source,terminal] ---- -$ export OCP_RELEASE= +$ OCP_RELEASE_REPOSITORY=quay.io/openshift-release-dev/ocp-release ---- + +.. Export the release digest from the image release advisory: + -For ``, specify the tag that corresponds to the version of {product-title} to which you want to upgrade, such as `4.5.4`. +[source,terminal] +---- +$ OCP_RELEASE_DIGEST= +---- ++ +For ``, 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: + @@ -42,15 +54,6 @@ $ LOCAL_REPOSITORY='' For ``, specify the name of the repository to create in your registry, such as `ocp4/openshift4`. -.. Export the name of the repository to mirror: -+ -[source,terminal] ----- -$ PRODUCT_REPO='openshift-release-dev' ----- -+ -For a production release, you must specify `openshift-release-dev`. - .. Export the path to your registry pull secret: + [source,terminal] @@ -65,22 +68,6 @@ For ``, specify the absolute path to and file name of the p If your cluster uses an `ImageContentSourcePolicy` object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project. ==== -.. 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= ----- - .. Export the path to the directory to host the mirrored images: + [source,terminal] @@ -89,26 +76,33 @@ $ REMOVABLE_MEDIA_PATH= <1> ---- <1> Specify the full path, including the initial forward slash (/) character. -. 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 -a ${LOCAL_SECRET_JSON} release mirror \ + --from=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} \ + --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ + --to-release-image=${OCP_RELEASE_REPOSITORY}@${OCP_RELEASE_DIGEST} --dry-run $ 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: + +... 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} <1> +$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:4.*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} ---- + <1> For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images. @@ -117,11 +111,21 @@ $ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mi + [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 config map for image signature verification. ==== + +[NOTE] +==== +Optionally, you can use image tag name instead of image digest in the previous commands. +====