Merge pull request #77247 from subhtk/ocm-v2-part2

OSDOCS 8197: Updated oc-mirror v2 section for partially and fully disconnected environment updates

Author: bscott-rh

installing/disconnected_install/about-installing-oc-mirror-v2.adoc

@@ -2,7 +2,7 @@
 [id="about-installing-oc-mirror-v2"]
 = Mirroring images for a disconnected installation by using the oc-mirror plugin v2
 include::_attributes/common-attributes.adoc[]
-:context: installing-mirroring-disconnected
+:context: about-installing-oc-mirror-v2
 
 toc::[]
 
@@ -36,7 +36,7 @@ The following steps outline the high-level workflow on how to mirror images to a
 
 . 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 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).
 
@@ -51,6 +51,42 @@ 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]
+
+//Installing oc-mirror plugin v2
+include::modules/oc-mirror-installing-plugin.adoc[leveloffset=+2]
+
+//Configuring credentials that enable image mirroring
+include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+2]
+
+[id="using-oc-mirror_{context}"]
+== Mirroring an image set to a mirror registry
+
+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
+include::modules/oc-mirror-building-image-set-config-v2.adoc[leveloffset=+2]
+
+//oc-mirror-workflows: mirroring in 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"]
+== Additional resources
+
+* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.html[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]
+
+// Configuring your cluster to use the resources generated by oc-mirror
+include::modules/oc-mirror-updating-cluster-manifests-v2.adoc[leveloffset=+2]
+
 //Delete Feature
 // workflows of delete feature
 include::modules/oc-mirror-workflows-delete-v2.adoc[leveloffset=+1]
@@ -70,16 +106,12 @@ 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]
 
-[id="additional-resources"]
-== Additional resources
-
-* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.html[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]
 
 //Image set configuration parameters
 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]
+include::modules/oc-mirror-command-reference-v2.adoc[leveloffset=+1]
+* xref:../../installing/disconnected_install/about-installing-oc-mirror-v2.adoc#oc-mirror-updating-cluster-manifests-v2_installing-mirroring-disconnected[Configuring your cluster to use the resources generated by oc-mirror]

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

@@ -20,12 +20,15 @@ ifeval::["{context}" == "installing-mirroring-disconnected"]
 :oc-mirror:
 endif::[]
 
+ifeval::["{context}" == "about-installing-oc-mirror-v2"]
+:oc-mirror-v2:
+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 allows mirroring
-images from Red Hat to your mirror.
+Create a container image registry credentials file that enables you to mirror images from Red Hat to your mirror.
 
 ifdef::restricted[]
 [WARNING]
@@ -98,6 +101,10 @@ The contents of the file resemble the following example:
 ifdef::oc-mirror[]
 . Save the file either as `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`.
 endif::[]
+
+ifdef::oc-mirror-v2[]
+. Save the file as `$XDG_RUNTIME_DIR/containers/auth.json`.
+endif::[]
 // 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 either as `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`.
@@ -142,10 +149,9 @@ ifdef::openshift-origin[]
 }
 endif::[]
 ----
-<1> For `<mirror_registry>`, specify the registry domain name, and optionally the
-port, that your mirror registry uses to serve content. For example,
+<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> For `<credentials>`, specify the base64-encoded user name and password for
+<2> Specify the base64-encoded user name and password for
 the mirror registry.
 +
 ifndef::openshift-origin[]
@@ -205,3 +211,8 @@ ifeval::["{context}" == "installing-mirroring-disconnected"]
 :!restricted:
 :!oc-mirror:
 endif::[]
+
+ifeval::["{context}" == "about-installing-oc-mirror-v2"]
+:!oc-mirror-v2:
+endif::[]
+

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

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
+
+:_mod-docs-content-type: CONCEPT
+[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.
+
+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.
+
+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.

modules/oc-mirror-building-image-set-config-v2.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="oc-mirror-building-image-set-config-v2_{context}"]
+= Building the image set configuration
+
+The oc-mirror plugin v2 uses the image set configuration as the input file to determine the required images for mirroring.
+
+.Example for the `ImageSetConfiguration` input file
+[source,yaml]
+----
+kind: ImageSetConfiguration
+apiVersion: mirror.openshift.io/v2alpha1
+mirror:
+  platform:
+    channels:
+    - name: stable-4.13
+      minVersion: 4.13.10
+      maxVersion: 4.13.10
+    graph: true
+  operators:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15
+      packages:
+       - name: aws-load-balancer-operator
+       - name: 3scale-operator
+       - name: node-observability-operator
+  additionalImages: 
+   - name: registry.redhat.io/ubi8/ubi:latest
+   - name: registry.redhat.io/ubi9/ubi@sha256:20f695d2a91352d4eaa25107535126727b5945bff38ed36a3e59590f495046f0
+----

modules/oc-mirror-creating-image-set-config.adoc

@@ -18,17 +18,17 @@ Do not delete or modify the metadata that is generated by the oc-mirror plugin.
 
 .Prerequisites
 
-* You have created a container image registry credentials file. For instructions, see _Configuring credentials that allow images to be mirrored_.
+* You have created a container image registry credentials file. For instructions, see "Configuring credentials that allow images to be mirrored".
 
 .Procedure
 
 . Use the `oc mirror init` command to create a template for the image set configuration and save it to a file called `imageset-config.yaml`:
 +
 [source,terminal]
 ----
-$ oc mirror init --registry example.com/mirror/oc-mirror-metadata > imageset-config.yaml <1>
+$ oc mirror init <--registry <storage_backend> > imageset-config.yaml <1>
 ----
-<1> Replace `example.com/mirror/oc-mirror-metadata` with the location of your registry for the storage backend.
+<1> Specifies the location of your storage backend, such as `example.com/mirror/oc-mirror-metadata`.
 
 . Edit the file and adjust the settings as necessary:
 +
@@ -72,7 +72,7 @@ mirror:
 The `graph: true` field also mirrors the `ubi-micro` image along with other mirrored images.
 ====
 +
-See _Image set configuration parameters_ for the full list of parameters and _Image set configuration examples_ for various mirroring use cases.
+See "Image set configuration parameters" for the full list of parameters and "Image set configuration examples" for various mirroring use cases.
 
 . Save the updated file.
 +

modules/oc-mirror-disk-to-mirror-v2.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="disk-mirror-v2_{context}"]
+== Mirroring from disk to mirror
+
+You can use the `oc-mirror` plugin v2 to mirror image sets from a disk to a target mirror registry.
+
+The `oc-mirror` plugin v2 retrieves container images from a local disk and transfers them to the specified mirror registry.
+
+.Procedure
+
+* Process the image set file on the disk and mirror the contents to a target mirror registry by running the following command:
++
+[source,terminal]
+----
+$ oc mirror -c isc.yaml --from file://<file_path> docker://<mirror_registry_url> --v2 <1>
+----
+<1> Specify the URL or address of the mirror registry where the images are stored and from which they need to be deleted.
+
+.Verification
+
+. Navigate to the `cluster-resources` directory within the `working-dir` directory that was generated in the `<file_path>` directory.
+. Verify that the YAML files are present for the `ImageDigestMirrorSet`, `ImageTagMirrorSet` and `CatalogSource` resources.
+
+.Next steps
+
+* Configure your cluster to use the resources generated by oc-mirror plugin v2.

modules/oc-mirror-dry-run-v2.adoc

@@ -7,7 +7,7 @@
 [id="oc-mirror-dry-run-v2_{context}"]
 = Performing dry run for oc-mirror plugin v2
 
-To perform a dry run and verify your image set configuration without mirroring any images, follow the procedure.
+Verify your image set configuration by performing a dry run without mirroring any images. This ensures your setup is correct and prevents unintended changes.
 
 .Procedure
 

modules/oc-mirror-installing-plugin.adoc

@@ -3,10 +3,21 @@
 // * installing/disconnected_install/installing-mirroring-disconnected.adoc
 // * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc
 
+ifeval::["{context}" == "installing-mirroring-disconnected"]
+:oc-mirror:
+endif::[]
+
+ifeval::["{context}" == "about-installing-oc-mirror-v2"]
+:oc-mirror-v2:
+:restricted:
+endif::[]
+
 :_mod-docs-content-type: PROCEDURE
 [id="installation-oc-mirror-installing-plugin_{context}"]
 = Installing the oc-mirror OpenShift CLI plugin
 
+Install the oc-mirror OpenShift CLI plugin to manage image sets in disconnected environments.
+
 .Prerequisites
 
 * You have installed the OpenShift CLI (`oc`). If you are mirroring image sets in a fully disconnected environment, ensure the following:
@@ -56,9 +67,28 @@ $ sudo mv oc-mirror /usr/local/bin/.
 
 .Verification
 
-* Run `oc mirror help` to verify that the plugin was successfully installed:
+ifdef::oc-mirror[]
+* Verify that the plugin for oc-mirror v1 is successfully installed by running the following command:
 +
 [source,terminal]
 ----
 $ oc mirror help
 ----
+endif::[]
+
+ifdef::oc-mirror-v2[]
+* Verify that the plugin for oc-mirror v2 is successfully installed by running the following command:
++
+[source,terminal]
+----
+$ oc mirror --v2 --help
+----
+endif::[]
+
+ifeval::["{context}" == "about-installing-oc-mirror-v2"]
+:!oc-mirror-v2:
+endif::[]
+
+ifeval::["{context}" == "installing-mirroring-disconnected"]
+:!oc-mirror:
+endif::[]

modules/oc-mirror-mirror-to-disk-v2.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="mirror-to-disk-v2_{context}"]
+== Mirroring from mirror to disk
+
+You can use the oc-mirror plugin v2 to generate an image set and save the content to disk. You can then transfer the generated image set can to the disconnected environment and mirrored to the target registry.
+
+oc-mirror plugin v2 retrieves the container images from the source specified in the image set configuration and packs them into a tar archive in a local directory.
+
+.Procedure
+
+* Mirror the images from the specified image set configuration to the disk by running the following command:
++
+[source,terminal]
+----
+$ oc mirror -c isc.yaml file://<file_path> --v2 <1>
+----
+<1> Add the required file path. 
+
+.Verification
+
+. Navigate to the `<file_path>` directory that was generated.
+. Verify that the archive files have been generated.
+
+.Next steps
+
+* Configure your cluster to use the resources generated by oc-mirror plugin v2.

modules/oc-mirror-preparing-mirror-hosts.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="oc-mirror-preparing-mirror-hosts_{context}"]
+= Preparing your mirror hosts
+
+To use the oc-mirror plugin v2 for image mirroring, you need to install the plugin and create a file with credentials for container images, enabling you to mirror from Red Hat to your mirror.