Merge pull request #102851 from ShaunaDiaz/OSDOCS-16880-3

OSDOCS-16880-3: CQA IMG-2: Image Configuration and Advanced Features

Author: dfitzmau

modules/images-registry-mirroring.adoc

@@ -1,8 +1,8 @@
 // Module included in the following assemblies:
 //
 // * openshift_images/image-configuration-hcp.adoc
-:_mod-docs-content-type: CONCEPT
 
+:_mod-docs-content-type: CONCEPT
 [id="images-registry-mirroring_{context}"]
 =  Image registry mirroring for {product-title}
 

modules/installation-about-mirror-registry.adoc

@@ -17,6 +17,9 @@ endif::[]
 [id="installation-about-mirror-registry_{context}"]
 = About the mirror registry
 
+[role="_abstract"]
+You must have access to the internet to obtain the necessary container images. Using an alternative registry means that you place the mirror registry on a mirror host that has access to both your network and the internet.
+
 ifndef::oc-mirror[]
 You can mirror the images that are required for {product-title} installation and subsequent product updates to a container mirror registry such as {quay}, JFrog Artifactory, Sonatype Nexus Repository, or Harbor. If you do not have access to a large-scale container registry, you can use the _mirror registry for Red{nbsp}Hat OpenShift_, a small-scale container registry included with {product-title} subscriptions.
 
@@ -41,7 +44,7 @@ For mirrored registries, to view the source of pulled images, you must review th
 
 [NOTE]
 ====
-Red Hat does not test third party registries with {product-title}.
+Red{nbsp}Hat does not test third party registries with {product-title}.
 ====
 
 ifeval::["{context}" == "installing-mirroring-disconnected"]

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

@@ -29,7 +29,8 @@ endif::[]
 [id="installation-adding-registry-pull-secret_{context}"]
 = Configuring credentials that allow images to be mirrored
 
-Create a container image registry credentials file that enables you to mirror images from Red{nbsp}Hat to your mirror.
+[role="_abstract"]
+Create a container image registry credentials file so that you can mirror images from Red{nbsp}Hat to your mirror. Complete the following steps on the installation host.
 
 ifdef::restricted[]
 [WARNING]
@@ -54,19 +55,17 @@ ifdef::restricted[]
 endif::restricted[]
 
 .Procedure
-
-Complete the following steps on the installation host:
-
 ifndef::openshift-origin[]
 . Download your `registry.redhat.io` {cluster-manager-url-pull}.
 
 . Make a copy of your pull secret in JSON format by running the following command:
 +
 [source,terminal]
 ----
-$ cat ./pull-secret | jq . > <path>/<pull_secret_file_in_json> <1>
+$ cat ./pull-secret | jq . > <path>/<pull_secret_file_in_json>
 ----
-<1> Specify the path to the folder to store the pull secret in and a name for the JSON file that you create.
++
+Specify the path to the directory to store the pull secret in and a name for the JSON file that you create.
 +
 .Example pull secret
 [source,json]
@@ -92,9 +91,13 @@ $ cat ./pull-secret | jq . > <path>/<pull_secret_file_in_json> <1>
   }
 }
 ----
++
+--
 // An additional step for following this procedure when using oc-mirror as part of the disconnected install process.
 ifdef::oc-mirror[]
+--
 . Save the file as either `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`:
+
 .. If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command:
 +
 [source,terminal]
@@ -103,38 +106,45 @@ $ mkdir -p <directory_name>
 ----
 +
 Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`.
+
 .. Copy the pull secret to the appropriate directory by entering the following command:
 +
 [source,terminal]
 ----
 $ cp <path>/<pull_secret_file_in_json> <directory_name>/<auth_file>
 ----
 +
-Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `<auth_file>` is either `config.json` or `auth.json`.
+The `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `<auth_file>` is either `config.json` or `auth.json`
+--
 endif::oc-mirror[]
 // Similar to the additional step above, except it is framed as optional because it is included in a disconnected update page (where users may or may not use oc-mirror for their process)
 ifdef::update-oc-mirror[]
+
 . Optional: If using the oc-mirror plugin, save the file as either `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`:
-.. If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command:
+
+** If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command:
 +
 [source,terminal]
 ----
 $ mkdir -p <directory_name>
 ----
 +
 Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`.
-.. Copy the pull secret to the appropriate directory by entering the following command:
+
+** Copy the pull secret to the appropriate directory by entering the following command:
 +
 [source,terminal]
 ----
 $ cp <path>/<pull_secret_file_in_json> <directory_name>/<auth_file>
 ----
 +
 Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `<auth_file>` is either `config.json` or `auth.json`.
+
 endif::update-oc-mirror[]
 // Additional step for allowing this procedure for oc-mirror-v2
 // Should this step below also have the "if you don't have this directory, create it using this command" substeps?
 ifdef::oc-mirror-v2[]
+
 . If the `$XDG_RUNTIME_DIR/containers` directory does not exist, create one by entering the following command:
 +
 [source,terminal]
@@ -145,14 +155,15 @@ $ mkdir -p $XDG_RUNTIME_DIR/containers
 . Save the pull secret file as `$XDG_RUNTIME_DIR/containers/auth.json`.
 endif::oc-mirror-v2[]
 endif::openshift-origin[]
+--
 
 . Generate the base64-encoded user name and password or token for your mirror registry by running the following command:
 +
 [source,terminal]
 ----
-$ echo -n '<user_name>:<password>' | base64 -w0 <1>
+$ echo -n '<user_name>:<password>' | base64 -w0
 ----
-<1> For `<user_name>` and `<password>`, specify the user name and password that you configured for your registry.
+For `<user_name>` and `<password>`, specify the user name and password that you configured for your registry.
 +
 .Example output
 [source,terminal]
@@ -167,17 +178,17 @@ ifdef::openshift-origin[]
 ----
 {
   "auths": {
-    "<mirror_registry>": { <1>
-      "auth": "<credentials>", <2>
+    "<mirror_registry>": {
+      "auth": "<credentials>",
       "email": "you@example.com"
     }
   }
 }
 ----
-<1> Specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example,
-`registry.example.com` or `registry.example.com:8443`
-<2> Specify the base64-encoded user name and password for
-the mirror registry.
++
+* For the `<mirror_registry>` value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, `registry.example.com` or `registry.example.com:8443`.
++
+* For the `<credentials>` value, specify the base64-encoded user name and password for the mirror registry.
 
 endif::openshift-origin[]
 
@@ -187,16 +198,16 @@ ifndef::openshift-origin[]
 [source,json]
 ----
   "auths": {
-    "<mirror_registry>": { <1>
-      "auth": "<credentials>", <2>
+    "<mirror_registry>": {
+      "auth": "<credentials>",
       "email": "you@example.com"
     }
   },
 ----
-<1> Specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example,
-`registry.example.com` or `registry.example.com:8443`
-<2> Specify the base64-encoded user name and password for
-the mirror registry.
++
+* For the `<mirror_registry>` value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, `registry.example.com` or `registry.example.com:8443`.
++
+* For the `<credentials>` value, specify the base64-encoded user name and password for the mirror registry.
 +
 .Example modified pull secret
 [source,json]

modules/installation-mirror-repository.adoc

@@ -7,7 +7,8 @@
 [id="installation-mirror-repository_{context}"]
 = Mirroring the {product-title} image repository
 
-Mirror the {product-title} image repository to your registry to use during cluster installation or upgrade.
+[role="_abstract"]
+Mirror the {product-title} image repository to your registry to use during cluster installation or upgrade. Complete the following steps on the mirror host.
 
 .Prerequisites
 
@@ -25,13 +26,10 @@ endif::[]
 ifdef::openshift-origin[]
 * You have created a pull secret for your mirror repository.
 endif::[]
-
 * If you use self-signed certificates, you have specified a Subject Alternative Name in the certificates.
 
 .Procedure
 
-Complete the following steps on the mirror host:
-
 . Review the
 ifndef::openshift-origin[]
 link:https://access.redhat.com/downloads/content/290/[Download {product-title}] 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.
@@ -41,16 +39,16 @@ link:https://github.com/okd-project/okd/releases/[{product-title} releases page]
 to determine the version and tag of {product-title} that you want to install.
 endif::[]
 
-. Set the required environment variables:
+. Set the following required environment variables:
+
 .. Export the release version:
 +
 [source,terminal]
 ----
 $ OCP_RELEASE=<release_version>
 ----
 +
-For `<release_version>`, specify the tag that corresponds to the version of {product-title} to
-install, such as `4.5.4`.
+For `<release_version>`, specify the tag that corresponds to the version of {product-title} to install, such as `4.20.1`.
 
 .. Export the local registry name and host port:
 +
@@ -59,9 +57,7 @@ install, such as `4.5.4`.
 $ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>'
 ----
 +
-For `<local_registry_host_name>`, specify the registry domain name for your mirror
-repository, and for `<local_registry_host_port>`, specify the port that it
-serves content on.
+For `<local_registry_host_name>`, specify the registry domain name for your mirror repository, and for `<local_registry_host_port>`, specify the port that it serves content on.
 
 .. Export the local repository name:
 +
@@ -70,8 +66,7 @@ serves content on.
 $ LOCAL_REPOSITORY='<local_repository_name>'
 ----
 +
-For `<local_repository_name>`, specify the name of the repository to create in your
-registry, such as `ocp4/openshift4`.
+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:
 +
@@ -121,19 +116,20 @@ ifndef::openshift-origin[]
 +
 [source,terminal]
 ----
-$ ARCHITECTURE=<cluster_architecture> <1>
+$ ARCHITECTURE=<cluster_architecture>
 ----
-<1> Specify the architecture of the cluster, such as `x86_64`, `aarch64`, `s390x`, or `ppc64le`.
-
++
+Specify the architecture of the cluster, such as `x86_64`, `aarch64`, `s390x`, or `ppc64le`.
 endif::[]
 
 .. Export the path to the directory to host the mirrored images:
 +
 [source,terminal]
 ----
-$ REMOVABLE_MEDIA_PATH=<path> <1>
+$ REMOVABLE_MEDIA_PATH=<path>
 ----
-<1> Specify the full path, including the initial forward slash (/) character.
++
+Specify the full path, including the initial forward slash (/) character.
 
 ifndef::openshift-rosa,openshift-dedicated[]
 . Mirror the version images to the mirror registry:
@@ -181,14 +177,14 @@ endif::[]
 +
 [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:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
 ----
 +
-<1> For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images.
+For the `REMOVABLE_MEDIA_PATH` variable, you must use the same path that you specified when you mirrored the images.
 +
 [IMPORTANT]
 ====
-Running `oc image mirror` might result in the following error: `error: unable to retrieve source image`. This error occurs when image indexes include references to images that no longer exist on the image registry. Image indexes might retain older references to allow users running those images an upgrade path to newer points on the upgrade graph. As a temporary workaround, you can use the `--skip-missing` option to bypass the error and continue downloading the image index. For more information, see link:https://access.redhat.com/solutions/6975305[Service Mesh Operator mirroring failed].
+Running the `oc image mirror` command might result in the following error: `error: unable to retrieve source image`. This error occurs when image indexes include references to images that no longer exist on the image registry. Image indexes might retain older references to allow users running those images an upgrade path to newer points on the upgrade graph. As a temporary workaround, you can use the `--skip-missing` option to bypass the error and continue downloading the image index. For more information, see link:https://access.redhat.com/solutions/6975305[Service Mesh Operator mirroring failed].
 ====
 
 ** If the local container registry is connected to the mirror host, take the following actions:
@@ -213,15 +209,14 @@ $ oc adm release mirror -a ${LOCAL_SECRET_JSON}  \
 ----
 endif::[]
 +
-This command pulls the release information as a digest, and its output includes
-the `imageContentSources` data that you require when you install your cluster.
+This command pulls the release information as a digest, and its output includes the `imageContentSources` data that you require when you install your cluster.
 
 ... 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.
 +
 [NOTE]
 ====
-The image name gets patched to Quay.io during the mirroring process, and the podman images will show Quay.io in the registry on the bootstrap virtual machine.
+The image name gets patched to Quay.io during the mirroring process, and the Podman images will show Quay.io in the registry on the bootstrap virtual machine.
 ====
 
 . To create the installation program that is based on the content that you
@@ -231,9 +226,10 @@ mirrored, extract it and pin it to the release:
 [source,terminal]
 ----
 $ oc adm release extract -a ${LOCAL_SECRET_JSON} --icsp-file=<file> --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}" \
---insecure=true <1>
+--insecure=true
 ----
-<1> Optional: If you do not want to configure trust for the target registry, add the `--insecure=true` flag.
++
+Optional: If you do not want to configure trust for the target registry, add the `--insecure=true` flag.
 
 ** If the local container registry is connected to the mirror host, run the following command:
 +
@@ -252,9 +248,7 @@ endif::[]
 +
 [IMPORTANT]
 ====
-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.
+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.
 
 You must perform this step on a machine with an active internet connection.
 ====
@@ -281,19 +275,16 @@ $ oc adm release mirror -a ${LOCAL_SECRET_JSON}  \
      --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}
 ----
 +
-This command pulls the release information as a digest, and its output includes
-the `imageContentSources` data that you require when you install your cluster.
+This command pulls the release information as a digest, and its output includes the `imageContentSources` data that you require when you install your cluster.
 
-.. 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.
+.. 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.
 +
 [NOTE]
 ====
-The image name gets patched to Quay.io during the mirroring process, and the podman images will show Quay.io in the registry on the bootstrap virtual machine.
+The image name gets patched to Quay.io during the mirroring process, and the Podman images show `quay.io` in the registry on the bootstrap virtual machine.
 ====
 
-. To create the installation program that is based on the content that you
-mirrored, extract it and pin it to the release by running the following command:
+. To create the installation program that is based on the content that you mirrored, extract it and pin it to the release by running the following command:
 +
 [source,terminal]
 ----
@@ -302,9 +293,7 @@ $ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${
 +
 [IMPORTANT]
 ====
-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.
+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.
 
 You must perform this step on a machine with an active internet connection.
 ====