diff --git a/_topic_map.yml b/_topic_map.yml index 829a6f3f44b8..023416523672 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -181,8 +181,8 @@ Topics: File: updating-cluster-cli - Name: Updating a cluster that includes RHEL compute machines File: updating-cluster-rhel-compute -#- Name: Updating a disconnected cluster -# File: updating-disconnected-cluster +- Name: Updating a restricted network cluster + File: updating-restricted-network # - Name: Troubleshooting an update # File: updating-troubleshooting --- diff --git a/installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc b/installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc index 29b437c21742..f1c171faafbe 100644 --- a/installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc +++ b/installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc @@ -27,9 +27,9 @@ include::modules/cli-installing-cli.adoc[leveloffset=+2] include::modules/installation-creating-mirror-registry.adoc[leveloffset=+1] -include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1] +//include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1] -//include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1] +include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1] include::modules/installation-mirror-repository.adoc[leveloffset=+1] diff --git a/modules/installation-adding-registry-pull-secret.adoc b/modules/installation-adding-registry-pull-secret.adoc index 72bd6e8ec693..b12eeae6251f 100644 --- a/modules/installation-adding-registry-pull-secret.adoc +++ b/modules/installation-adding-registry-pull-secret.adoc @@ -17,21 +17,30 @@ restricted network. Complete the following steps on the bastion host: -. Download your `registry.redhat.io` pull secret from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. +. Generate the pull secret for your registry: ++ +---- +$ podman login --authfile ~/pullsecret_config.json : <1> +---- +<1> For ``, specify the registry domain name +for your mirror registry, such as `registry.example.com`. For +``, specify the port that your mirror registry uses to +serve content. ++ +Provide your credentials for the mirror registry at the prompts. -. Generate the base64-encoded user name and password or token for your mirror -registry: +. View the pull secret that you created and record the pull secret value: + ---- -$ echo -n ':' | base64 -w0 <1> +# cat ~/pullsecret_config.json -BGVtbYk3ZHAtqXs= +{ "auths": { ":": { "auth": "ZHVtbXk6ZHVtbXk=" } } } ---- -<1> For `` and ``, specify the user name and password that -you configured for your registry. -. Make a copy of your pull secret in JSON format: +. Download your pull secret from the +link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. + +. Make a copy of the {cloud-redhat-com} link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] that you downloaded in JSON format: + ---- $ cat ./pull-secret.text | jq . > /<1> @@ -64,10 +73,10 @@ The contents of the file resemble the following example: } ---- -. Edit the new file and add a section that describes your registry to it: +. Edit the {cloud-redhat-com} link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] file and add a section that describes your registry to it: + ---- - "auths": { + "auths": { <1> ... ":": { <1> "auth": "", <2> @@ -75,11 +84,7 @@ The contents of the file resemble the following example: }, ... ---- -<1> For `bastion_host_name`, specify the registry domain name -that you specified in your certificate, and for ``, -specify the port that your mirror registry uses to serve content. -<2> For ``, specify the base64-encoded user name and password for -the mirror registry that you generated. +<1> Paste the contents of the `pullsecret_config.json` file that you created. + The file resembles the following example: + diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc index 65de2a3e7f64..e340bf00ebfe 100644 --- a/modules/installation-mirror-repository.adoc +++ b/modules/installation-mirror-repository.adoc @@ -1,12 +1,22 @@ // Module included in the following assemblies: // // * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc +// * updating/updating-restricted-network.adoc +ifeval::["{context}" == "installing-restricted-networks-preparations"] +:restricted: +:install: +endif::[] +ifeval::["{context}" == "updating-restricted-network"] +:restricted: +:update: +endif::[] + +ifdef::install[] [id="installation-mirror-repository_{context}"] = Mirroring the {product-title} image repository -Mirror the {product-title} image repository to use during cluster installation -or upgrade. +Mirror the {product-title} image repository to use during cluster installation. .Prerequisites @@ -14,6 +24,21 @@ or upgrade. can access the certificate and credentials that you configured. * You downloaded the pull secret from the link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site and modified it to include authentication to your mirror repository. +endif::install[] + +ifdef::update[] +[id="update-mirror-image-repository_{context}"] += Update the contents of the {product-title} image repository + +Update the contents of the image repository that hosts the mirrored content that +you require for installing {product-title}. You must update the mirror registry +to update {product-title} to a new version. + +.Prerequisites + +* You have access to the mirror registry that you used to store the images that +you used to install {product-title}. +endif::update[] .Procedure @@ -21,7 +46,13 @@ Complete the following steps on the bastion 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. +to determine the version of {product-title} that you want to +ifdef::install[] +install. +endif::install[] +ifdef::update[] +update to. +endif::update[] . Set the required environment variables: + @@ -34,7 +65,11 @@ $ export LOCAL_SECRET_JSON='' <5> $ export RELEASE_NAME="ocp-release" <6> ---- <1> For ``, specify the version number of {product-title} to -install, such as `4.2.0`. +install, such as `4.2.1`. +ifdef::update[] +When you update {product-title}, you must specify a version number that is +higher than the version that is installed. +endif::update[] <2> For ``, specify the registry domain name for your mirror repository, and for ``, specify the port that it serves content on. @@ -57,11 +92,105 @@ $ oc adm -a ${LOCAL_SECRET_JSON} release mirror \ ---- + This command pulls the release information as a digest, and its output includes -the `imageContentSources` data that you require when you install your cluster. +text that resembles the following sample: + +. Record the +ifdef::install[] +`imageContentSources` +endif::install[] +ifdef::update[] +`ImageContentSourcePolicy` +endif::update[] +section from the output of the previous +command. This information is required +ifdef::install[] +during {product-title} installation. +endif::install[] +ifdef::update[] +when you update your {product-title} cluster. +endif::update[] + +. Build the signature for the content that you mirrored and verify that it is +signed by an official Red Hat key: +.. Set the digest for the version to +ifdef::install[] +install: +endif::install[] +ifdef::update[] +update to: +endif::update[] ++ +---- +$ DIGEST="$(oc adm release info quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} | sed -n 's/Pull From: .*@//p')" <1> +---- +<1> For ``, specify the version number of {product-title} to +that you mirrored content for. + +.. Build a signature URI: ++ +---- +$ URI="https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release/${DIGEST/:/=}/signature-" <1> +---- +<1> Specify the name of the signature to store. The signature name must be in the format of `signature-`, where `` is a sequential series of numbers that starts with `1`. The signature verification process checks all valid signatures by incrementing `` until it finds a valid signature or the requested `signature-` does not exist. -. 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. +.. Download the signature: ++ +---- +$ wget "${URI}" +---- + +.. Download the keys that were used to sign the signature: ++ +---- +$ wget https://www.redhat.com/security/data/f21541eb.txt +$ wget https://www.redhat.com/security/data/fd431d51.txt +---- + +.. Import the keys: ++ +---- +$ gpg --no-default-keyring --keyring ./temp.keyring --import ./f21541eb.txt +$ gpg --no-default-keyring --keyring ./temp.keyring --import ./fd431d51.txt +---- + +.. Verify the signature: ++ +---- +$ gpg --no-default-keyring --keyring ./temp.keyring --verify <1> +gpg: Signature made Tue 24 Sep 2019 09:38:24 AM PDT using RSA key ID F21541EB +gpg: Good signature from "Red Hat, Inc. (beta key 2) " +gpg: aka "Mark Cox Internal RSA 4096 test key " +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: B08B 659E E86A F623 BC90 E8DB 938A 80CA F215 41EB +---- +<1> Specify the name of the signature that you stored, which is in the format `signature-`. + +.. Confirm that the `Primary key fingerprint` value from the signature output is +is listed on the +link:https://access.redhat.com/security/team/key[Product Signing Keys] +page on the Red Hat Customer Portal. + +.. If you cannot verify the signature, repeat this process to create another one. Name the new signature `signature-`, where `` is the number that you used in the last signature name. + +. Mirror the repository: ++ +---- +$ oc adm -a ${LOCAL_SECRET_JSON} release mirror \ + --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \ + --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ + --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE} +---- ++ +This command pulls the release information as a digest, and its output includes the +ifdef::install[] +`imageContentSources` data that you require when you install your cluster. +endif::install[] +ifdef::update[] +`ImageContentSourcePolicy` data that you require when you update your cluster. +endif::update[] +ifdef::install[] . To create the installation program that is based on the content that you mirrored, extract it and pin it to the release: + @@ -75,3 +204,4 @@ To ensure that you use the correct images for the version of {product-title} that you selected, you must extract the installation program from the mirrored content. ==== +endif::install[] diff --git a/modules/update-restricted-network-cli.adoc b/modules/update-restricted-network-cli.adoc new file mode 100644 index 000000000000..c84676d0e875 --- /dev/null +++ b/modules/update-restricted-network-cli.adoc @@ -0,0 +1,164 @@ +// Module included in the following assemblies: +// +// * updating/updating-restricted-network.adoc + +[id="update-restricted-network-cli_{context}"] += Update the restricted network cluster + +After you update the contents of the mirror registry, you can update your +restricted network cluster. + +.Prerequisites + +* You have access to the mirror registry that you used to store the images that +you used to install {product-title}. +* You have the `ImageContentSourcePolicy` information for the content that you +mirrored. +* The the OpenShift Command-line Interface (CLI), commonly known as `oc`, is +installed. +* The `jq` package is installed. + +.Procedure + +Complete the following steps on the bastion host: + +. Review the `ImageContentSourcePolicy` resource for your cluster: ++ +---- +$ oc get ImageContentSourcePolicy -o yaml + +apiVersion: operator.openshift.io/v1alpha1 +kind: ImageContentSourcePolicy +metadata: + name: example +spec: + repositoryDigestMirrors: <1> + - mirrors: + - ://release + source: quay.io/openshift-release-dev/ocp-release + - mirrors: + - ://release + source: quay.io/openshift-release-dev/ocp-v4.0-art-dev +---- +<1> The `repositoryDigestMirrors` section must contain the `mirrors` data that +is in the output of the `oc adm mirror release` command from when you mirrored +the images for this release. + +. If the `repositoryDigestMirrors` section of the `ImageContentSourcePolicy` does not contain the `mirrors` for this release, create another `ImageContentSourcePolicy` resource: +.. Record the name of the current `ImageContentSourcePolicy`. You will delete this resource after you complete the update. +.. Define the `ImageContentSourcePolicy` resource for your cluster: ++ +---- +$ cat test.yaml +apiVersion: operator.openshift.io/v1alpha1 <1> +kind: ImageContentSourcePolicy +metadata: + name: example +spec: + repositoryDigestMirrors: + - mirrors: + - ://release + source: quay.io/openshift-release-dev/ocp-release + - mirrors: + - ://release + source: quay.io/openshift-release-dev/ocp-v4.0-art-dev +---- +<1> Specify the entire specification that was shown in the output of the +`oc adm mirror release` command that mirrored the images for this release. +.. Create the `ImageContentSourcePolicy` resource that you defined: ++ +---- +$ oc create -f test.yaml +---- +.. Wait a few minutes, and then confirm that the new `ImageContentSoucePolicy` is in effect by reviewing the node status: ++ +---- +$ oc describe node | grep machineconfig + machineconfiguration.openshift.io/currentConfig: rendered-master-9194b32791755030dcce887c66024113 + machineconfiguration.openshift.io/desiredConfig: rendered-master-9194b32791755030dcce887c66024113 + machineconfiguration.openshift.io/reason: + machineconfiguration.openshift.io/state: Done + machineconfiguration.openshift.io/currentConfig: rendered-worker-a0f873210ec70fb117835a9c9527db29 + machineconfiguration.openshift.io/desiredConfig: rendered-worker-a0f873210ec70fb117835a9c9527db29 + machineconfiguration.openshift.io/state: Done + machineconfiguration.openshift.io/currentConfig: rendered-master-9194b32791755030dcce887c66024113 + machineconfiguration.openshift.io/desiredConfig: rendered-master-9194b32791755030dcce887c66024113 + machineconfiguration.openshift.io/reason: + machineconfiguration.openshift.io/state: Done + machineconfiguration.openshift.io/currentConfig: rendered-worker-a0f873210ec70fb117835a9c9527db29 + machineconfiguration.openshift.io/desiredConfig: rendered-worker-a0f873210ec70fb117835a9c9527db29 + machineconfiguration.openshift.io/state: Done + machineconfiguration.openshift.io/currentConfig: rendered-worker-a0f873210ec70fb117835a9c9527db29 + machineconfiguration.openshift.io/desiredConfig: rendered-worker-a0f873210ec70fb117835a9c9527db29 + machineconfiguration.openshift.io/state: Done + machineconfiguration.openshift.io/currentConfig: rendered-master-9194b32791755030dcce887c66024113 + machineconfiguration.openshift.io/desiredConfig: rendered-master-9194b32791755030dcce887c66024113 + machineconfiguration.openshift.io/state: Done + +---- ++ +For each machine, the `machineconfiguration.openshift.io/state` must be `Done` before you begin the update. + +. Start the cluster update: ++ +---- +$ oc adm upgrade --allow-explicit-upgrade --to-image :/ocp/release@${DIGEST} <1> +---- +<1> For `` and ``, specify +the values that describe your mirror registry host name and port. For +``, specify the version that you want to upgrade to. + +. Review the cluster version status history to monitor the status of the update. +It might take some time for all the objects to finish updating. ++ +---- +$ oc get clusterversion -o json|jq ".items[0].status.history" + +[ + { + "completionTime": null, + "image": "quay.io/openshift-release-dev/ocp-release@sha256:9c5f0df8b192a0d7b46cd5f6a4da2289c155fd5302dec7954f8f06c878160b8b", + "startedTime": "2019-06-19T20:30:50Z", + "state": "Partial", + "verified": true, + "version": "4.2.1" + }, + { + "completionTime": "2019-06-19T20:30:50Z", + "image": "quay.io/openshift-release-dev/ocp-release@sha256:b8307ac0f3ec4ac86c3f3b52846425205022da52c16f56ec31cbe428501001d6", + "startedTime": "2019-06-19T17:38:10Z", + "state": "Completed", + "verified": false, + "version": "4.2.0" + } +] +---- ++ +The history contains a list of the most recent versions applied to the cluster. +This value is updated when the CVO applies an update. The list is ordered by +date, where the newest update is first in the list. Updates in the history have +state `Completed` if the rollout completed and `Partial` if the update failed +or did not complete. ++ +[IMPORTANT] +==== +If an upgrade fails, the cluster version reports a condition that explains the +failure. Contact Red Hat support. +==== + +. After the update completes, you can confirm that the cluster version has +updated to the new version: ++ +---- +$ oc get clusterversion + +NAME VERSION AVAILABLE PROGRESSING SINCE STATUS +version 4.2.1 True False 2m Cluster version is 4.2.1 +---- + +. Optional: Delete the original `ImageContentSourcePolicy` resource, if one existed: ++ +---- +$ oc delete ImageContentSourcePolicy <1> +---- +<1> For ``, specify the name of the original `ImageContentSourcePolicy` resource. diff --git a/modules/update-upgrading-cli.adoc b/modules/update-upgrading-cli.adoc index a2134b936e08..72df67d4094b 100644 --- a/modules/update-upgrading-cli.adoc +++ b/modules/update-upgrading-cli.adoc @@ -131,9 +131,8 @@ or did not complete. + [IMPORTANT] ==== -If an upgrade fails, the Operator stops and reports the status of the failing -component. Rolling your cluster back to a previous version is not supported. -If your upgrade fails, contact Red Hat support. +If an upgrade fails, the cluster version reports a condition that explains the +failure. Contact Red Hat support. ==== . After the update completes, you can confirm that the cluster version has diff --git a/updating/updating-restricted-network.adoc b/updating/updating-restricted-network.adoc new file mode 100644 index 000000000000..f4585120a821 --- /dev/null +++ b/updating/updating-restricted-network.adoc @@ -0,0 +1,25 @@ +[id="updating-restricted-network"] += Updating a restricted network cluster +include::modules/common-attributes.adoc[] +:context: updating-restricted-network + +toc::[] + +You can update, or upgrade, an {product-title} cluster that you installed in a +restricted network by using the web console. + +.Prerequisites + +* Access to the cluster as a user with `admin` privileges. +See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. +* Access to the mirror registry that you used to store the images +that you used to install {product-title}. + +include::modules/update-service-overview.adoc[leveloffset=+1] + +//This file has the right if statements to apply to upgrade and install. +include::modules/installation-mirror-repository.adoc[leveloffset=+1] + +//You can only update through the CLI for disconnected, for now, but using the +//web console is still the best user experience in all other instances. +include::modules/update-restricted-network-cli.adoc[leveloffset=+1]