Merge pull request #103511 from xenolinux/oc-mir-host

[enterprise-4.16] OCPBUGS#63555: oc-mirror v2 requires explict registry hostnames

Author: xenolinux

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

@@ -15,18 +15,31 @@ kind: ImageSetConfiguration
 apiVersion: mirror.openshift.io/v2alpha1
 mirror:
   platform:
-    channels:
+    channels: # <1>
     - name: stable-4.13
       minVersion: 4.13.10
       maxVersion: 4.13.10
-    graph: true
+    graph: true  # <2>
   operators:
-    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15
-      packages:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 # <3>
+      packages:     # <4>
        - name: aws-load-balancer-operator
        - name: 3scale-operator
        - name: node-observability-operator
-  additionalImages: 
+  additionalImages: # <5>
    - name: registry.redhat.io/ubi8/ubi:latest
    - name: registry.redhat.io/ubi9/ubi@sha256:20f695d2a91352d4eaa25107535126727b5945bff38ed36a3e59590f495046f0
-----
+----
+<1> Set the channel to retrieve {product-title} images from.
+<2> Add `graph: true` to build and push the graph-data image to the mirror registry. The graph-data image is required to create OpenShift Update Service (OSUS). The `graph: true` field also generates the `UpdateService` custom resource manifest. The `oc` command-line interface (CLI) can use the `UpdateService` custom resource manifest to create OSUS. For more information, see _About the OpenShift Update Service_.
+<3> Set the Operator catalog to retrieve the {product-title} images from.
+<4> Specify only certain Operator packages to include in the image set. Remove this field to retrieve all packages in the catalog.
+<5> Specify any additional images to include in image set.
++
+[NOTE]
+====
+In oc-mirror plugin v2, you must use explicit registry hostnames for all images listed under `additionalImages`. Otherwise, images are mirrored to incorrect target paths.
+====
+
+// Are there more relevant example version numbers we can use in the example above?
+// Also, are there any other callouts that would be helpful for users here?

modules/oc-mirror-oci-format.adoc

@@ -67,6 +67,11 @@ mirror:
 <4> Optionally, specify an alternative namespace and name to mirror the catalog as.
 <5> Optionally, specify additional Operator catalogs to pull from a registry.
 <6> Optionally, specify additional images to pull from a registry.
++
+[NOTE]
+====
+In oc-mirror plugin v2, you must use explicit registry hostnames for all images listed under `additionalImages`. Otherwise, images are mirrored to incorrect target paths. 
+====
 
 . Run the `oc mirror` command to mirror the OCI catalog to a target mirror registry:
 +

modules/oc-mirror-workflows-delete-v2.adoc

@@ -26,7 +26,7 @@ kind: DeleteImageSetConfiguration
 delete:
   platform:
     channels:
-      - name: stable-4.13 
+      - name: stable-4.13
         minVersion: 4.13.3
         maxVersion: 4.13.3
   operators:
@@ -35,23 +35,25 @@ delete:
       - name: aws-load-balancer-operator
          minVersion: 0.0.1
          maxVersion: 0.0.1
-  additionalImages: 
+  additionalImages:
     - name: registry.redhat.io/ubi8/ubi@sha256:bce7e9f69fb7d4533447232478fd825811c760288f87a35699f9c8f030f2c1a6
     - name: registry.redhat.io/ubi8/ubi-minimal@sha256:8bedbe742f140108897fb3532068e8316900d9814f399d676ac78b46e740e34e
 ----
 
 [IMPORTANT]
 ====
-Consider using the mirror-to-disk and disk-to-mirror workflows to reduce mirroring issues.
+* Consider using the mirror-to-disk and disk-to-mirror workflows to reduce deletion issues.
+
+* In oc-mirror plugin v2, you must use explicit registry hostnames for all images listed under `additionalImages`. Otherwise, images are mirrored to incorrect target paths.
 ====
 
 In the image delete workflow, oc-mirror plugin v2 deletes only the manifests of the images, which does not reduce the storage occupied in the registry.
 
-To free up storage space from unnecessary images, such as those with deleted manifests, you must enable the garbage collector on your container registry. With the garbage collector enabled, the registry will delete the image blobs that no longer have references to any manifests, thereby reducing the storage previously occupied by the deleted blobs. Enabling the garbage collector differs depending on your container registry. 
+To free up storage space from unnecessary images, such as those with deleted manifests, you must enable the garbage collector on your container registry. With the garbage collector enabled, the registry will delete the image blobs that no longer have references to any manifests, thereby reducing the storage previously occupied by the deleted blobs. Enabling the garbage collector differs depending on your container registry.
 
 [IMPORTANT]
 ====
 To skip deleting the Operator catalog image when deleting images, you must list the specific Operators under the Operator catalog image in the `DeleteImageSetConfiguration` file. This ensures that only the specified Operators are deleted, not the catalog image.
 
 If only the Operator catalog image is specified, all Operators within that catalog, as well as the catalog image itself, will be deleted.
-====
+====