Skip to content

Commit 77a7a46

Browse files
kalexand-rhkalexand-rh
authored
Merge pull request #21993 from LalatenduMohanty/OTA-102
Adding documentation for updating a disconnected cluster
2 parents 66c21ad + 8a31e17 commit 77a7a46

10 files changed

+298
-29
lines changed

‎_topic_map.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -283,8 +283,9 @@ Topics:
283283
- Name: Updating a cluster that includes RHEL compute machines
284284
File: updating-cluster-rhel-compute
285285
Distros: openshift-enterprise,openshift-webscale
286-
#- Name: Updating a disconnected cluster
287-
# File: updating-disconnected-cluster
286+
- Name: Updating a restricted network cluster
287+
File: updating-restricted-network-cluster
288+
Distros: openshift-enterprise,openshift-webscale
288289
# - Name: Troubleshooting an update
289290
# File: updating-troubleshooting
290291
---

‎modules/cli-installing-cli.adoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,14 @@
2424
// * openshift_images/samples-operator-alt-registry.adoc
2525
// * installing/installing_rhv/installing-rhv-customizations.adoc
2626
// * installing/installing_rhv/installing-rhv-default.adoc
27+
// * updating/updating-restricted-network-cluster.adoc
2728
//
2829
// AMQ docs link to this; do not change anchor
2930

31+
ifeval::["{context}" == "updating-restricted-network-cluster"]
32+
:restricted:
33+
endif::[]
34+
3035
[id="cli-installing-cli_{context}"]
3136
= Installing the CLI by downloading the binary
3237

@@ -38,6 +43,9 @@ command-line interface. You can install `oc` on Linux, Windows, or macOS.
3843
If you installed an earlier version of `oc`, you cannot use it to complete all
3944
of the commands in {product-title} {product-version}. Download and
4045
install the new version of `oc`.
46+
ifdef::restricted[]
47+
If you are upgrading a cluster in a restricted network, install the `oc` version that you plan to upgrade to.
48+
endif::restricted[]
4149
====
4250

4351
[id="cli-installing-cli-on-linux_{context}"]
@@ -136,3 +144,8 @@ After you install the CLI, it is available using the `oc` command:
136144
----
137145
$ oc <command>
138146
----
147+
148+
149+
ifeval::["{context}" == "updating-restricted-network-cluster"]
150+
:!restricted:
151+
endif::[]

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
// Module included in the following assemblies:
22
//
33
// * openshift_images/samples-operator-alt-registry.adoc
4+
// * updating/updating-restricted-network-cluster.adoc
5+
6+
ifeval::["{context}" == "updating-restricted-network-cluster"]
7+
:restricted:
8+
endif::[]
49

510
[id="installation-adding-registry-pull-secret_{context}"]
611
= Adding the registry to your pull secret
@@ -9,6 +14,18 @@ Modify your the pull secret for your {product-title} cluster to describe
914
your local registry before you install an {product-title} cluster in a
1015
restricted network.
1116

17+
ifdef::restricted[]
18+
[WARNING]
19+
====
20+
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.
21+
====
22+
23+
[IMPORTANT]
24+
====
25+
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.
26+
====
27+
endif::restricted[]
28+
1229
.Prerequisites
1330

1431
* You configured a mirror registry to use in your restricted network.
@@ -111,3 +128,8 @@ The file resembles the following example:
111128
}
112129
}
113130
----
131+
132+
133+
ifeval::["{context}" == "updating-restricted-network-cluster"]
134+
:!restricted:
135+
endif::[]

‎modules/installation-mirror-repository.adoc‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,10 @@ $ export LOCAL_REPOSITORY='<repository_name>' <3>
3838
$ export PRODUCT_REPO='openshift-release-dev' <4>
3939
$ export LOCAL_SECRET_JSON='<path_to_pull_secret>' <5>
4040
$ export RELEASE_NAME="ocp-release" <6>
41+
$ export ARCHITECTURE=<server_architecture> <7>
4142
----
4243
<1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} to
43-
install for your architecture, such as `4.4.0-x86_64`.
44+
install, such as `4.5.0`.
4445
<2> For `<local_registry_host_name>`, specify the registry domain name for your mirror
4546
repository, and for `<local_registry_host_port>`, specify the port that it
4647
serves content on.
@@ -52,14 +53,16 @@ registry, such as `ocp4/openshift4`.
5253
the pull secret for your mirror registry that you created.
5354
<6> The release mirror. For a production release, you must specify
5455
`ocp-release`.
56+
<7> For `server_architecture`, specify the architecture of the server, such as `x86_64`.
57+
5558

5659
. Mirror the repository:
5760
+
5861
----
5962
$ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
60-
--from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \
63+
--from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
6164
--to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \
62-
--to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}
65+
--to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
6366
----
6467
+
6568
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
7275
mirrored, extract it and pin it to the release:
7376
+
7477
----
75-
$ oc adm -a ${LOCAL_SECRET_JSON} release extract --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}"
78+
$ oc adm -a ${LOCAL_SECRET_JSON} release extract --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}"
7679
----
7780
+
7881
[IMPORTANT]

‎modules/update-configuring-image-signature.adoc‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-restricted-network-cluster.adoc
4+
5+
[id="update-configuring-image-signature"]
6+
= Creating an image signature ConfigMap manually
7+
8+
Create and apply the image signature ConfigMap to the cluster that you want to update.
9+
10+
[NOTE]
11+
====
12+
You must perform following steps each time that you update a cluster.
13+
====
14+
15+
.Procedure
16+
17+
. 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.
18+
19+
. Add the version to the `OCP_RELEASE_NUMBER` environment variable:
20+
+
21+
----
22+
$ OCP_RELEASE_NUMBER=<release_version> <1>
23+
----
24+
<1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} you want
25+
to update the cluster, such as `4.4.0`.
26+
27+
. Add the system architecture for your cluster to `ARCHITECTURE` environment variable:
28+
+
29+
----
30+
$ ARCHITECTURE=<server_architecture> <11>
31+
----
32+
<1> For `server_architecture`, specify the architecture of the server, such as `x86_64`.
33+
34+
. Get the release image digest from link:https://quay.io/[Quay]:
35+
+
36+
----
37+
$ DIGEST="$(oc adm release info quay.io/openshift-release-dev/ocp-release:${OCP_RELEASE_NUMBER}-${ARCHITECTURE} | sed -n 's/Pull From: .*@//p')"
38+
----
39+
40+
. Set the digest algorithm:
41+
+
42+
----
43+
$ DIGEST_ALGO="${DIGEST%%:*}"
44+
----
45+
46+
. Set the digest signature:
47+
+
48+
----
49+
$ DIGEST_ENCODED="${DIGEST#*:}"
50+
----
51+
52+
. Get the image signature from link:https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release[mirror.openshift.com] website.
53+
+
54+
----
55+
$ SIGNATURE_BASE64=$(curl -s "https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release/${DIGEST_ALGO}=${DIGEST_ENCODED}/signature-1" | base64 -w0 && echo)
56+
----
57+
58+
. Create the ConfigMap:
59+
+
60+
----
61+
$ cat >checksum-${OCP_RELEASE_NUMBER}.yaml <<EOF
62+
apiVersion: v1
63+
kind: ConfigMap
64+
metadata:
65+
name: release-image-${OCP_RELEASE_NUMBER}
66+
namespace: openshift-config-managed
67+
labels:
68+
release.openshift.io/verification-signatures: ""
69+
binaryData:
70+
${DIGEST_ALGO}-${DIGEST_ENCODED}: ${SIGNATURE_BASE64}
71+
EOF
72+
----
73+
74+
. Apply the ConfigMap to the cluster to update:
75+
+
76+
----
77+
$ oc apply -f checksum-${OCP_RELEASE_NUMBER}.yaml
78+
----

‎modules/update-mirror-repository.adoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-restricted-network-cluster.adoc
4+
5+
[id="update-mirror-repository_{context}"]
6+
= Mirroring the {product-title} image repository
7+
8+
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.
9+
10+
.Procedure
11+
12+
. 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.
13+
14+
. Set the required environment variables:
15+
+
16+
----
17+
$ OCP_RELEASE=<release_version> # <1>
18+
$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>' # <2>
19+
$ LOCAL_REPOSITORY='<repository_name>' # <3>
20+
$ PRODUCT_REPO='openshift-release-dev' # <4>
21+
$ LOCAL_SECRET_JSON='<path_to_pull_secret>' # <5>
22+
$ RELEASE_NAME='ocp-release' # <6>
23+
$ ARCHITECTURE=<server_architecture> # <7>
24+
$ REMOVABLE_MEDIA_PATH=<path> <8>
25+
----
26+
<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`.
27+
<2> For `<local_registry_host_name>`, specify the registry domain name for your mirror
28+
repository, and for `<local_registry_host_port>`, specify the port that it
29+
serves content on.
30+
<3> For `<repository_name>`, specify the name of the repository to create in your
31+
registry, such as `ocp4/openshift4`.
32+
<4> The repository to mirror. For a production release, you must specify
33+
`openshift-release-dev`.
34+
<5> For `<path_to_pull_secret>`, specify the absolute path to and file name of
35+
the pull secret for your mirror registry that you created.
36+
<6> For a production release, you must specify
37+
`ocp-release`.
38+
<7> For `<server_architecture>`, specify the architecture of the server, such as `x86_64`.
39+
<8> For `<path>`, specify the path to the directory to host the mirrored images.
40+
41+
. Review the images and configuration manifests to mirror:
42+
+
43+
----
44+
$ 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
45+
----
46+
. Mirror the version images to the internal container registry.
47+
** If your mirror host does not have internet access, take the following actions:
48+
... Connect the removable media to a system that is connected to the internet.
49+
... Mirror the images and configuration manifests to a directory on the removable media:
50+
+
51+
----
52+
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
53+
----
54+
... Take the media to the restricted network environment and upload the images to the local container registry.
55+
+
56+
----
57+
$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror 'file://openshift/release:${OCP_RELEASE}*' ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
58+
----
59+
** 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:
60+
+
61+
----
62+
$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \
63+
--to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} --apply-release-image-signature
64+
----
65+
+
66+
[NOTE]
67+
====
68+
If you include the `--apply-release-image-signature` option, do not create the ConfigMap for image signature verification.
69+
====

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-restricted-network-cluster.adoc
4+
5+
[id="update-oc-configmap-signature-verification_{context}"]
6+
= Creating the ConfigMap for image signature verification by using the `oc` CLI
7+
8+
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.
9+
10+
[NOTE]
11+
====
12+
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).
13+
====
14+
15+
.Prerequisites
16+
17+
* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`, version 4.4.8 or later.
18+
19+
.Procedure
20+
21+
. 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)].
22+
23+
. Use `oc` command-line interface (CLI) to log into the cluster that you are upgrading.
24+
25+
. Apply the the mirrored release image signature ConfigMap to the connected cluster:
26+
+
27+
----
28+
$ oc apply -f <image_signature_file> <1>
29+
----
30+
<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‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-restricted-network-cluster.adoc
4+
5+
[id="update-restricted_{context}"]
6+
= Upgrading the restricted network cluster
7+
8+
Update the restricted network cluster to the {product-title} version that you downloaded the release images for.
9+
10+
.Prerequisites
11+
12+
* You mirrored the images for the new release to your registry.
13+
* You applied the release image signature ConfigMap for the new release to your cluster.
14+
* You obtained the sha256 sum value for the release from the image signature ConfigMap.
15+
* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`, version 4.4.8 or later.
16+
17+
.Procedure
18+
19+
* Update the cluster:
20+
+
21+
----
22+
$ oc adm upgrade --allow-explicit-upgrade --to-image ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}<sha256_sum_value> <1>
23+
----
24+
<1> The `<sha256_sum_value>` value is the sha256 sum value for the release from the image signature ConfigMap, for example, `@sha256:81154f5c03294534e1eaf0319bef7a601134f891689ccede5d705ef659aa8c92`
25+
+
26+
If you use an `ImageContentSourcePolicy` for the mirror registry, you can use the canonical registry name instead of `LOCAL_REGISTRY`.

‎updating/updating-disconnected-cluster.adoc‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

0 commit comments

Comments
 (0)