diff --git a/_topic_map.yml b/_topic_map.yml index e0d9575ab20c..006e32516996 100644 --- a/_topic_map.yml +++ b/_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 --- diff --git a/modules/cli-installing-cli.adoc b/modules/cli-installing-cli.adoc index 684e36ef4866..2daa9a87282c 100644 --- a/modules/cli-installing-cli.adoc +++ b/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 ---- + + +ifeval::["{context}" == "updating-restricted-network-cluster"] +:!restricted: +endif::[] diff --git a/modules/installation-adding-registry-pull-secret.adoc b/modules/installation-adding-registry-pull-secret.adoc index 210016aa543a..983e80587ac8 100644 --- a/modules/installation-adding-registry-pull-secret.adoc +++ b/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::[] diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc index e1f73d8358a0..6bbdf3a86c5f 100644 --- a/modules/installation-mirror-repository.adoc +++ b/modules/installation-mirror-repository.adoc @@ -38,9 +38,10 @@ $ export LOCAL_REPOSITORY='' <3> $ export PRODUCT_REPO='openshift-release-dev' <4> $ export LOCAL_SECRET_JSON='' <5> $ export RELEASE_NAME="ocp-release" <6> +$ export ARCHITECTURE= <7> ---- <1> For ``, 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 ``, specify the registry domain name for your mirror repository, and for ``, 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] diff --git a/modules/update-configuring-image-signature.adoc b/modules/update-configuring-image-signature.adoc new file mode 100644 index 000000000000..f4d94b5f0940 --- /dev/null +++ b/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= <1> +---- +<1> For ``, 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= <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 < # <1> +$ LOCAL_REGISTRY=':' # <2> +$ LOCAL_REPOSITORY='' # <3> +$ PRODUCT_REPO='openshift-release-dev' # <4> +$ LOCAL_SECRET_JSON='' # <5> +$ RELEASE_NAME='ocp-release' # <6> +$ ARCHITECTURE= # <7> +$ REMOVABLE_MEDIA_PATH= <8> +---- +<1> For ``, specify the tag that corresponds to the version of {product-title} to which you want to upgrade, such as `4.5.0`. +<2> For ``, specify the registry domain name for your mirror +repository, and for ``, specify the port that it +serves content on. +<3> For ``, 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 ``, 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 ``, specify the architecture of the server, such as `x86_64`. +<8> For ``, 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. +==== diff --git a/modules/update-oc-configmap-signature-verification.adoc b/modules/update-oc-configmap-signature-verification.adoc new file mode 100644 index 000000000000..57dd1ef5b99e --- /dev/null +++ b/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 <1> +---- +<1> For ``, specify the path and name of the file, for example, `mirror/config/signature-sha256-81154f5c03294534.yaml`. diff --git a/modules/update-restricted.adoc b/modules/update-restricted.adoc new file mode 100644 index 000000000000..8f1bf525dd61 --- /dev/null +++ b/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} <1> +---- +<1> The `` 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`. diff --git a/updating/updating-disconnected-cluster.adoc b/updating/updating-disconnected-cluster.adoc deleted file mode 100644 index c5b7163f0d80..000000000000 --- a/updating/updating-disconnected-cluster.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="updating-disconnected-cluster"] -= Updating a disconnected cluster to a minor version -include::modules/common-attributes.adoc[] -:context: updating-disconnected-cluster - -toc::[] - -You can update, or upgrade, an {product-title} cluster that you installed in a -restricted network to a minor version by using the web console. - -.Prerequisites - -* Have access to the cluster as a user with `admin` privileges. -See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. -* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. - -//mirror module - -include::modules/update-service-overview.adoc[leveloffset=+1] - -include::modules/understanding-upgrade-channels.adoc[leveloffset=+1] - -include::modules/update-upgrading-web.adoc[leveloffset=+1] diff --git a/updating/updating-restricted-network-cluster.adoc b/updating/updating-restricted-network-cluster.adoc new file mode 100644 index 000000000000..390980b6e6b5 --- /dev/null +++ b/updating/updating-restricted-network-cluster.adoc @@ -0,0 +1,50 @@ +[id="updating-restricted-network-cluster"] += Updating a restricted network cluster +include::modules/common-attributes.adoc[] +:context: updating-restricted-network-cluster + +toc::[] + +You can upgrade a restricted network {product-title} cluster by using the `oc` command-line interface (CLI). + +A restricted network environment is the one in which your cluster nodes cannot access the internet. For this reason, you must populate a registry with the installation images. If your registry host cannot access both the internet and the cluster, you can mirror the images to a file system that disconnected from that environment and then bring that host or removable media across that gap. If the local container registry and the cluster are connected to the mirror registry's host, you can directly push the release images to the local registry. + +If multiple clusters are present within the restricted network, mirror the required release images to a single container image registry and use that registry to update all the clusters. + +.Prerequisites + +* Have access to the internet to obtain the necessary container images. +* Have write access to a container registry in the restricted-network environment to push and pull images. The container registry must be compatible with Docker registry API v2. +* You must have the `oc` command-line interface (CLI) tool installed. +* Have access to the cluster as a user with `admin` privileges. +See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. +* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. + +[id="updating-restricted-network-mirror-host"] +== Preparing your mirror host + +Before you perform the mirror procedure, you must prepare the host to retrieve content +and push it to the remote location. + +include::modules/cli-installing-cli.adoc[leveloffset=+2] + +// 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=+1] + +include::modules/update-mirror-repository.adoc[leveloffset=+1] + +[id="updating-restricted-network-image-configmap"] +== Creating the image ConfigMap + +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. + +If you are upgrading from version 4.4.8 or later, you can use the `oc` CLI to create the ConfigMap. If you are upgrading from an earlier version, you must use the manual method. + +include::modules/update-oc-configmap-signature-verification.adoc[leveloffset=+2] + +include::modules/update-configuring-image-signature.adoc[leveloffset=+2] + +include::modules/update-restricted.adoc[leveloffset=+1] + +include::modules/images-configuration-registry-mirror.adoc[leveloffset=+1]