Merge pull request #84069 from skopacz1/OSDOCS-12410

OSDOCS#12410: first pass of oc-mirror v2 improvements

Author: skopacz1

disconnected/mirroring/about-installing-oc-mirror-v2.adoc

@@ -6,51 +6,33 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can run your cluster in a restricted network without direct internet connectivity if you install the cluster from a mirrored set of {product-title} container images in a private registry. This registry must be running whenever your cluster is running.
+You can run your cluster in a disconnected environment if you install the cluster from a mirrored set of {product-title} container images in a private registry. This registry must be running whenever your cluster is running.
 
-Just as you can use the `oc-mirror` OpenShift CLI (`oc`) plugin, you can also use oc-mirror plugin v2 to mirror images to a mirror registry in your fully or partially disconnected environments. To download the required images from the official Red Hat registries, you must run oc-mirror plugin v2 from a system with internet connectivity.
+Just as you can use the `oc-mirror` OpenShift CLI (`oc`) plugin, you can also use oc-mirror plugin v2 to mirror images to a mirror registry in your fully or partially disconnected environments. To download the required images from the official Red{nbsp}Hat registries, you must run oc-mirror plugin v2 from a system with internet connectivity.
 
 :FeatureName: oc-mirror plugin v2
 include::snippets/technology-preview.adoc[]
 
+// About oc-mirror plugin v2
+include::modules/oc-mirror-v2-about.adoc[leveloffset=+1]
+
+// oc-mirror compatibility and support
+include::modules/oc-mirror-v2-support.adoc[leveloffset=+2]
+
 [id="prerequisites_oc-mirror-v2_{context}"]
 == Prerequisites
 
 * You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker V2-2] in the location that hosts the {product-title} cluster, such as {quay}.
 +
 [NOTE]
 ====
-If you use {quay}, use version 3.6 or later with the oc-mirror plugin. See the documentation on link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying the Red Hat Quay Operator on OpenShift Container Platform (Red Hat Quay documentation)]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support.
-====
+* If you use {quay}, use version 3.6 or later with the oc-mirror plugin. See link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying the Red{nbsp}Hat Quay Operator on {product-title} (Red{nbsp}Hat Quay documentation)]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red{nbsp}Hat Support.
 
-[Optional]
-* If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry. You can use this registry to mirror the necessary container images of {product-title} for disconnected installations.
+* If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red{nbsp}Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry. You can use this registry to mirror the necessary container images of {product-title} for disconnected installations.
+====
 
 * Every machine in the provisioned clusters must have access to the mirror registry. If the registry is unreachable, tasks like installation, updating, or routine operations such as workload relocation, might fail. Mirror registries must be operated in a highly available manner, ensuring their availability aligns with the production availability of your {product-title} clusters.
 
-.High level workflow
-
-The following steps outline the high-level workflow on how to mirror images to a mirror registry by using the oc-mirror plugin v2:
-
-. Create an image set configuration file.
-
-. Mirror the image set to the target mirror registry by using one of the following workflows:
-
-* Mirror an image set directly to the target mirror registry (mirror to mirror).
-
-** Mirror an image set to disk (Mirror-to-Disk), transfer the `tar` file to the target environment, then mirror the image set to the target mirror registry (Disk-to-Mirror).
-
-. Configure your cluster to use the resources generated by the oc-mirror plugin v2.
-
-. Repeat these steps to update your target mirror registry as necessary.
-
-
-// About oc-mirror plugin v2
-include::modules/oc-mirror-v2-about.adoc[leveloffset=+1]
-
-// oc-mirror compatibility and support
-include::modules/oc-mirror-v2-support.adoc[leveloffset=+2]
-
 //Preparing your mirror hosts
 include::modules/oc-mirror-preparing-mirror-hosts.adoc[leveloffset=+1]
 
@@ -65,28 +47,37 @@ include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+2]
 
 Mirroring an image set to a mirror registry ensures that the required images are available in a secure and controlled environment, facilitating smoother deployments, updates, and maintenance tasks.
 
-//Building the image set configuration
+//Creating the image set configuration
 include::modules/oc-mirror-building-image-set-config-v2.adoc[leveloffset=+2]
 
-//oc-mirror-workflows: mirroring in partially disconnected environment
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../updating/understanding_updates/intro-to-updates.adoc#update-service-about_understanding-openshift-updates[About the OpenShift Update Service]
+
+//Mirroring an image set in a partially disconnected environment
 include::modules/oc-mirror-workflows-partially-disconnected-v2.adoc[leveloffset=+2]
 
 //Mirroring an image set in a fully disconnected environment:
 include::modules/oc-mirror-workflows-fully-disconnected-v2.adoc[leveloffset=+2]
 include::modules/oc-mirror-mirror-to-disk-v2.adoc[leveloffset=+2]
 include::modules/oc-mirror-disk-to-mirror-v2.adoc[leveloffset=+2]
 
-[id="additional-resources_{context}"]
-== Additional resources
-
-* xref:../../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
-
 // About custom resources generated by v2
 include::modules/oc-mirror-IDMS-ITMS-about.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../rest_api/config_apis/imagedigestmirrorset-config-openshift-io-v1.adoc#imagedigestmirrorset-config-openshift-io-v1[ImageDigestMirrorSet]
+
+* xref:../../rest_api/config_apis/imagetagmirrorset-config-openshift-io-v1.adoc#imagetagmirrorset-config-openshift-io-v1[ImageTagMirrorSet]
+
 // Configuring your cluster to use the resources generated by oc-mirror
 include::modules/oc-mirror-updating-cluster-manifests-v2.adoc[leveloffset=+2]
 
+Once your cluster is configured to use the resources generated by oc-mirror plugin v2, see xref:../../disconnected/mirroring/about-installing-oc-mirror-v2.adoc#next-steps_about-installing-oc-mirror-v2[Next Steps] for information about tasks that you can perform using your mirrored images.
+
 //Delete Feature
 // workflows of delete feature
 include::modules/oc-mirror-workflows-delete-v2.adoc[leveloffset=+1]
@@ -109,6 +100,10 @@ include::modules//oc-mirror-enclave-support-about.adoc[leveloffset=+1]
 // How to mirror to an Enclave
 include::modules/oc-mirror-enclave-support.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
+
 //operator catalog filtering
 include::modules/oc-mirror-operator-catalog-filtering.adoc[leveloffset=+1]
 
@@ -118,3 +113,14 @@ include::modules/oc-mirror-imageset-config-parameters-v2.adoc[leveloffset=+1]
 // Command reference for oc-mirror v2
 include::modules/oc-mirror-command-reference-v2.adoc[leveloffset=+1]
 * xref:../../disconnected/mirroring/about-installing-oc-mirror-v2.adoc#oc-mirror-updating-cluster-manifests-v2_about-installing-oc-mirror-v2[Configuring your cluster to use the resources generated by oc-mirror]
+
+[id="next-steps_{context}"]
+== Next steps
+
+After you mirror images to your disconnected environment using oc-mirror plugin v2, you can perform any of the following actions:
+
+* xref:../../disconnected/installing.adoc#installing-disconnected-environments[Installing a cluster in a disconnected environment]
+* xref:../../disconnected/using-olm.adoc#olm-restricted-networks[Using Operator Lifecycle Manager in disconnected environments]
+* xref:../../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
+
+// Intentionally linking to the OSUS update procedure since we probably want to steer users to do that workflow as much as possible. But I can change to the index of the update section if I shouldn't be as prescriptive.

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

@@ -22,13 +22,14 @@ endif::[]
 
 ifeval::["{context}" == "about-installing-oc-mirror-v2"]
 :oc-mirror-v2:
+:restricted:
 endif::[]
 
 :_mod-docs-content-type: PROCEDURE
 [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 Hat to your mirror.
+Create a container image registry credentials file that enables you to mirror images from Red{nbsp}Hat to your mirror.
 
 ifdef::restricted[]
 [WARNING]
@@ -37,13 +38,7 @@ Do not use this image registry credentials file as the pull secret when you inst
 ====
 endif::restricted[]
 
-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.
-====
-
-endif::restricted[]
+// removed this warning since the first part is more of a prereq, and the second part seems to just describe what will happen later in the procedure. Can revert/modify as needed.
 
 .Prerequisites
 ifndef::openshift-rosa,openshift-dedicated[]
@@ -55,6 +50,7 @@ endif::openshift-rosa,openshift-dedicated[]
 ifdef::restricted[]
 * You identified an image repository location on your mirror registry to mirror images into.
 * You provisioned a mirror registry account that allows images to be uploaded to that image repository.
+* You have write access to the mirror registry.
 endif::restricted[]
 
 .Procedure
@@ -64,16 +60,15 @@ 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:
+. 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>
 ----
 <1> Specify the path to the folder to store the pull secret in and a name for the JSON file that you create.
 +
-The contents of the file resemble the following example:
-+
+.Example pull secret
 [source,json]
 ----
 {
@@ -116,7 +111,7 @@ $ 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::[]
+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`:
@@ -136,59 +131,74 @@ $ 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::[]
+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[]
-. Save the file as `$XDG_RUNTIME_DIR/containers/auth.json`.
-endif::[]
-endif::[]
- 
-. Generate the base64-encoded user name and password or token for your mirror registry:
+. If the `$XDG_RUNTIME_DIR/containers` directory does not exist, create one by entering the following command:
++
+[source,terminal]
+----
+$ 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>
-BGVtbYk3ZHAtqXs=
 ----
 <1> For `<user_name>` and `<password>`, specify the user name and password that you configured for your registry.
++
+.Example output
+[source,terminal]
+----
+BGVtbYk3ZHAtqXs=
+----
 
-ifndef::openshift-origin[]
-. Edit the JSON
-endif::[]
 ifdef::openshift-origin[]
-. Create a `.json`
-endif::[]
-file and add a section that describes your registry to it:
+. Create a `.json` file and add a section that describes your registry to it:
 +
 [source,json]
 ----
-ifndef::openshift-origin[]
+{
   "auths": {
     "<mirror_registry>": { <1>
       "auth": "<credentials>", <2>
       "email": "you@example.com"
     }
-  },
-endif::[]
-ifdef::openshift-origin[]
-{
+  }
+}
+----
+<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.
+
+endif::openshift-origin[]
+
+ifndef::openshift-origin[]
+. Edit the JSON file and add a section that describes your registry to it:
++
+[source,json]
+----
   "auths": {
     "<mirror_registry>": { <1>
       "auth": "<credentials>", <2>
       "email": "you@example.com"
     }
-  }
-}
-endif::[]
+  },
 ----
 <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.
 +
-ifndef::openshift-origin[]
-The file resembles the following example:
-+
+.Example modified pull secret
 [source,json]
 ----
 {
@@ -216,7 +226,7 @@ The file resembles the following example:
   }
 }
 ----
-endif::[]
+endif::openshift-origin[]
 
 ////
 This is not currently working as intended.
@@ -246,5 +256,6 @@ endif::[]
 
 ifeval::["{context}" == "about-installing-oc-mirror-v2"]
 :!oc-mirror-v2:
+:!restricted:
 endif::[]
 

modules/oc-mirror-IDMS-ITMS-about.adoc

@@ -6,10 +6,11 @@
 [id="oc-mirror-custom-resources-v2_{context}"]
 = About custom resources generated by v2
 
-With oc-mirror plugin v2, `ImageDigestMirrorSet` (IDMS) and `ImageTagMirrorSet` (ITMS) are generated by default if at least one image is found to which a tag refers. These sets contain mirrors for images referenced by digest or tag in releases, Operator catalogs and additional images.
+// Should sentence below say "to which a digest or tag refers"?
 
-The `ImageDigestMirrorSet` (IDMS) links the mirror registry to the source registry and forwards image pull requests using digest specifications. The `ImagetagMirrorSet` (ITMS) resource, however, redirects image pull requests by using image tags.
+With oc-mirror plugin v2, `ImageDigestMirrorSet` (IDMS) resources are generated by default if at least one image of the image set is mirrored by digest.
+`ImageTagMirrorSet` (ITMS) resources are generated if at least one image from the image set is mirrored by tag.
 
 Operator Lifecycle Manager (OLM) uses the `CatalogSource` resource to retrieve information about the available Operators in the mirror registry.
 
-The OSUS service uses the `UpdateService` resource to provide Cincinnati graph to the disconnected environment.
+The OpenShift Update Service uses the `UpdateService` resource to provide update graph data to the disconnected environment.