Merge pull request #58552 from bergerhoffer/OSDOCS-4906

OSDOCS-4906: Updating oc-mirror docs for OCI FBC GA

Author: bergerhoffer

installing/disconnected_install/installing-mirroring-disconnected.adoc

@@ -124,13 +124,14 @@ include::modules/oc-mirror-differential-updates.adoc[leveloffset=+2]
 // Performing a dry run
 include::modules/oc-mirror-dry-run.adoc[leveloffset=+1]
 
-// Mirroring Operator images in OCI format
+// Including local OCI Operator catalogs
 include::modules/oc-mirror-oci-format.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-fb[File-based catalogs]
+// TODO: This title might need to update per sebastian's PR
+* xref:../../installing/disconnected_install/installing-mirroring-disconnected.html#oc-mirror-updating-cluster-manifests_installing-mirroring-disconnected[Configuring your cluster to use the resources generated by oc-mirror]
 
 // Image set configuration parameters
 include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+1]
@@ -145,4 +146,4 @@ include::modules/oc-mirror-command-reference.adoc[leveloffset=+1]
 [id="additional-resources_installing-mirroring-disconnected"]
 == Additional resources
 
-* xref:../../updating/updating-restricted-network-cluster/index.adoc#about-restricted-network-updates[About cluster updates in a disconnected environment]
+* xref:../../updating/updating-restricted-network-cluster/index.adoc#about-restricted-network-updates[About cluster updates in a disconnected environment]

modules/oc-mirror-command-reference.adoc

@@ -65,6 +65,9 @@ The following tables describe the `oc mirror` subcommands and flags:
 |`--ignore-history`
 |Ignore past mirrors when downloading images and packing layers. Disables incremental mirroring and might download more data.
 
+|`--include-local-oci-catalogs`
+|Enable mirroring for local OCI catalogs on disk to the target mirror registry.
+
 |`--manifests-only`
 |Generate manifests for `ImageContentSourcePolicy` objects to configure a cluster to use the mirror registry, but do not actually mirror any images.
 
@@ -74,14 +77,11 @@ The following tables describe the `oc mirror` subcommands and flags:
 |`--max-per-registry <int>`
 |Specify the number of concurrent requests allowed per registry. The default is `6`.
 
-|`--oci-feature-action`
-|The action to perform when using the Technology Preview OCI feature. The options are `copy` or `mirror`.
-
 |`--oci-insecure-signature-policy`
-|Do not push signatures when using the Technology Preview OCI feature.
+|Do not push signatures when mirroring local OCI catalogs (with `--include-local-oci-catalogs`).
 
 |`--oci-registries-config`
-|Provide a registries configuration file to specify an alternative registry location to copy from when using the Technology Preview OCI feature.
+|Provide a registries configuration file to specify an alternative registry location to copy from when mirroring local OCI catalogs (with `--include-local-oci-catalogs`).
 
 |`--skip-cleanup`
 |Skip removal of artifact directories.
@@ -108,7 +108,9 @@ The following tables describe the `oc mirror` subcommands and flags:
 |Use plain HTTP for the source registry.
 
 |`--use-oci-feature`
-|Use the Technology Preview OCI feature for copying OCI-formatted images.
+|Enable mirroring for local OCI catalogs on disk to the target mirror registry.
+
+The `--use-oci-feature` flag is deprecated. Use the `--include-local-oci-catalogs` flag instead.
 
 |`-v`, `--verbose` `<int>`
 |Specify the number for the log level verbosity. Valid values are `0` - `9`. The default is `0`.

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

@@ -58,7 +58,7 @@ mirror:
   helm: {}
 ----
 <1> Add `archiveSize` to set the maximum size, in GiB, of each file within the image set.
-<2> Set the back-end location to save the image set metadata to. This location can be a registry or local directory. It is required to specify `storageConfig` values, unless you are using the Technology Preview OCI feature.
+<2> Set the back-end location to save the image set metadata to. This location can be a registry or local directory. It is required to specify `storageConfig` values.
 <3> Set the registry URL for the storage backend.
 <4> Set the channel to retrieve the {product-title} images from.
 <5> 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) applications. The `graph: true` field also generates the `UpdateService` CR manifest. The `oc` command-line interface (CLI) can use the `UpdateService` CR manifest to create OSUS applications. For more information, see _About the OpenShift Update Service_.

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

@@ -72,7 +72,7 @@ mirror:
 [id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
 == Use case: Including the shortest {product-title} upgrade path
 
-The following `ImageSetConfiguration` file uses a local storage backend and includes all {product-title} versions along the shortest upgrade path from the minimum version of `4.9.37` to the maximum version of `4.10.22`.
+The following `ImageSetConfiguration` file uses a local storage backend and includes all {product-title} versions along the shortest upgrade path from the minimum version of `4.11.37` to the maximum version of `4.12.15`.
 
 .Example `ImageSetConfiguration` file
 [source,yaml]
@@ -86,8 +86,8 @@ mirror:
   platform:
     channels:
       - name: stable-4.10
-        minVersion: 4.9.37
-        maxVersion: 4.10.22
+        minVersion: 4.11.37
+        maxVersion: 4.12.15
         shortestPath: true
 ----
 

modules/oc-mirror-imageset-config-params.adoc

@@ -175,12 +175,19 @@ operators:
 |If `true`, dependencies of bundles are not included.
 |Boolean. The default value is `false`.
 
+|`mirror.operators.targetCatalog`
+|An alternative name and optional namespace hierarchy to mirror the referenced catalog as.
+|String. For example: `my-namespace/my-operator-catalog`
+
 |`mirror.operators.targetName`
-|Optional alternative name to mirror the referenced catalog as.
+|An alternative name to mirror the referenced catalog as.
+
+The `targetName` parameter is deprecated. Use the `targetCatalog` parameter instead.
+
 |String. For example: `my-operator-catalog`
 
 |`mirror.operators.targetTag`
-|Optional alternative tag to append to the `targetName`.
+|An alternative tag to append to the `targetName` or `targetCatalog`.
 |String. For example: `v1`
 
 |`mirror.platform`
@@ -219,7 +226,7 @@ channels:
 
 |`mirror.platform.channels.minVersion`
 |The minimum version of the referenced platform to be mirrored.
-|String. For example: `4.9.6`
+|String. For example: `4.12.6`
 
 |`mirror.platform.channels.maxVersion`
 |The highest version of the referenced platform to be mirrored.

modules/oc-mirror-oci-format.adoc

@@ -5,12 +5,25 @@
 
 :_content-type: PROCEDURE
 [id="oc-mirror-oci-format_{context}"]
-= Mirroring file-based catalog Operator images in OCI format
+= Including local OCI Operator catalogs
 
-You can use the oc-mirror plugin to mirror Operators in the Open Container Initiative (OCI) image format, instead of Docker v2 format. You can copy Operator images to a file-based catalog on disk in OCI format. Then you can copy local OCI images to your target mirror registry.
+While mirroring {product-title} releases, Operator catalogs, and additional images from a registry to a partially disconnected cluster, you can include Operator catalog images from a local file-based catalog on disk. The local catalog must be in the Open Container Initiative (OCI) format.
 
-:FeatureName: Using the oc-mirror plugin to mirror Operator images in OCI format
-include::snippets/technology-preview.adoc[]
+The local catalog and its contents are mirrored to your target mirror registry based on the filtering information in the image set configuration file.
+
+[IMPORTANT]
+====
+When mirroring local OCI catalogs, any {product-title} releases or additional images that you want to mirror along with the local OCI-formatted catalog must be pulled from a registry.
+
+You cannot mirror OCI catalogs along with an oc-mirror image set file on disk.
+====
+
+One example use case for using the OCI feature is if you have a CI/CD system building an OCI catalog to a location on disk, and you want to mirror that OCI catalog along with an {product-title} release to your mirror registry.
+
+[NOTE]
+====
+If you used the Technology Preview OCI local catalogs feature for the oc-mirror plugin for {product-title} 4.12, you can no longer use the OCI local catalogs feature of the oc-mirror plugin to copy a catalog locally and convert it to OCI format as a first step to mirroring to a fully disconnected cluster.
+====
 
 .Prerequisites
 
@@ -20,47 +33,57 @@ include::snippets/technology-preview.adoc[]
 
 .Procedure
 
-. Optional: Retrieve the catalogs and images that you require and save them to disk. If you already have the catalog image in OCI format on disk, you can skip this step.
-
-.. Create the image set configuration file:
+. Create the image set configuration file and adjust the settings as necessary.
++
+The following example image set configuration mirrors an OCI catalog on disk along with an {product-title} release and a UBI image from `registry.redhat.io`.
 +
-.Example image set configuration file for copying to disk
 [source,yaml]
 ----
 kind: ImageSetConfiguration
 apiVersion: mirror.openshift.io/v1alpha2
+storageConfig:
+  local:
+    path: /home/user/metadata                                                <1>
 mirror:
- operators:
- - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
-   packages:
-   - name: aws-load-balancer-operator
+  platform:
+    channels:
+    - name: stable-4.13                                                      <2>
+      type: ocp
+    graph: false
+  operators:
+  - catalog: oci:///home/user/oc-mirror/my-oci-catalog                       <3>
+    packages:
+    - name: aws-load-balancer-operator
+  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13           <4>
+    packages:
+    - name: rhacs-operator
+  additionalImages:
+  - name: registry.redhat.io/ubi8/ubi:latest                                 <5>
 ----
-+
-[NOTE]
-====
-When using the OCI feature, only the `mirror.operators.catalog` setting is available for use.
-
-The `storageConfig` setting is ignored in favor of the location passed in to the `oc mirror` command.
-====
+<1> Set the back-end location to save the image set metadata to. This location can be a registry or local directory. It is required to specify `storageConfig` values.
+<2> Optionally, include an {product-title} release to mirror from `registry.redhat.io`.
+<3> Specify the absolute path to the location of the OCI catalog on disk. The path must start with `oci://` when using the OCI feature.
+<4> Optionally, specify additional Operator catalogs to pull from a registry.
+<5> Optionally, specify additional images to pull from a registry.
 
-.. Run the `oc mirror` command to mirror the images from the specified image set configuration to disk:
+. Run the `oc mirror` command to mirror the OCI catalog to a target mirror registry:
 +
 [source,terminal]
 ----
 $ oc mirror --config=./imageset-config.yaml \ <1>
-  --use-oci-feature \                         <2>
-  --oci-feature-action=copy \                 <3>
-  oci://my-oci-catalog                        <4>
+  --include-local-oci-catalogs                <2>
+  docker://registry.example:5000              <3>
 ----
 <1> Pass in the image set configuration file. This procedure assumes that it is named `imageset-config.yaml`.
-<2> Use the `--use-oci-feature` flag to enable the OCI feature.
-<3> To copy the catalog to disk, set the `--oci-feature-action` flag to `copy`.
-<4> Specify a directory on disk where you want to output the catalog. This procedure assumes that it is named `my-oci-catalog`. The path must start with `oci://`. If the specified directory is not a full path, the directory is created in the current working directory where the `oc mirror` command is run.
+<2> Use the `--include-local-oci-catalogs` flag to enable mirroring local OCI catalogs along with other remote content.
+<3> Specify the registry to mirror the content to. The registry must start with `docker://`. If you specify a top-level namespace for the mirror registry, you must also use this same namespace on subsequent executions.
++
+Optionally, you can specify other flags to adjust the behavior of the OCI feature:
++
+`--oci-insecure-signature-policy`:: Do not push signatures to the target mirror registry.
++
+`--oci-registries-config`:: Specify the path to a TOML-formatted `registries.conf` file. You can use this to mirror from a different registry, such as a pre-production location for testing, without having to change the image set configuration file. This flag only affects local OCI catalogs, not any other mirrored content.
 +
-[NOTE]
-====
-You can optionally use the `--oci-registries-config` flag to specify the path to a TOML-formatted `registries.conf` file. You can use this to mirror from a different registry, such as a pre-production location for testing, without having to change the image set configuration file.
-
 .Example registries.conf file
 [source,toml]
 ----
@@ -75,61 +98,6 @@ You can optionally use the `--oci-registries-config` flag to specify the path to
     insecure = false
 ----
 
-Set the `location` field in the `registry.mirror` section to an alternative registry location that you want to pull images from. The `location` field in the `registry` section must be the same registry location as the one you specify in the image set configuration file.
-====
-
-.. List your directory contents and verify that the following directories were created:
-+
-[source,terminal]
-----
-$ ls -l
-----
-+
-.Example output
-[source,terminal]
-----
-my-oci-catalog      <1>
-oc-mirror-workspace <2>
-olm_artifacts       <3>
-----
-<1> Directory that contains the OCI catalog. This procedure assumes that it is named `my-oci-catalog`.
-<2> Directory that contains each image in the catalog in its original format.
-<3> Directory that contains the files that describe the Operator bundles that this catalog references.
-
-. Update the image set configuration file to specify the location of the catalog on disk to mirror to the target mirror registry:
-+
-.Example image set configuration file for mirroring to mirror registry
-[source,yaml]
-----
-kind: ImageSetConfiguration
-apiVersion: mirror.openshift.io/v1alpha2
-mirror:
- operators:
- - catalog: oci:///home/user/oc-mirror/my-oci-catalog/redhat-operator-index <1>
-   packages:
-   - name: aws-load-balancer-operator
-----
-<1> Specify the absolute path to the location of the OCI catalog on disk. This procedure assumes that you used `my-oci-catalog` as the directory and mirrored the `redhat-operator-index` catalog. The path must start with `oci://`.
-
-. Run the oc mirror command to process the image set file on disk and mirror the contents to a target mirror registry:
-+
-[source,terminal]
-----
-$ oc mirror --config=./imageset-config.yaml \ <1>
-  --use-oci-feature \                         <2>
-  --oci-feature-action=mirror \               <3>
-  docker://registry.example:5000              <4>
-----
-<1> Pass in the updated image set configuration file. This procedure assumes that it is named `imageset-config.yaml`.
-<2> Use the `--use-oci-feature` flag to enable the OCI feature.
-<3> To mirror the catalog to the target mirror registry, set the `--oci-feature-action` flag to `mirror`.
-<4> Specify the registry to mirror the image set file to. The registry must start with `docker://`. If you specify a top-level namespace for the mirror registry, you must also use this same namespace on subsequent executions.
-+
-[NOTE]
-====
-You can optionally use the `--oci-insecure-signature-policy` flag to not push signatures to the target mirror registry.
-====
-
 .Next steps
 
 * Configure your cluster to use the resources generated by oc-mirror.

modules/oc-mirror-support.adoc

@@ -7,6 +7,12 @@
 [id="oc-mirror-support_{context}"]
 = oc-mirror compatibility and support
 
-The oc-mirror plugin supports mirroring {product-title} payload images and Operator catalogs for {product-title} versions 4.9 and later.
+The oc-mirror plugin supports mirroring {product-title} payload images and Operator catalogs for {product-title} versions 4.10 and later.
 
 Use the latest available version of the oc-mirror plugin regardless of which versions of {product-title} you need to mirror.
+
+// TODO: Remove this in 4.14
+[IMPORTANT]
+====
+If you used the Technology Preview OCI local catalogs feature for the oc-mirror plugin for {product-title} 4.12, you can no longer use the OCI local catalogs feature of the oc-mirror plugin to copy a catalog locally and convert it to OCI format as a first step to mirroring to a fully disconnected cluster.
+====

modules/preparing-an-inital-cluster-deployment-for-mce-disconnected.adoc

@@ -48,7 +48,7 @@ To mirror your {product-title} image repository to your mirror registry, you can
 ----
 +
 <1> Specify the maximum size, in GiB, of each file within the image set.
-<2> Set the back-end location to receive the image set metadata. This location can be a registry or local directory. You must specify `storageConfig` values unless you are using the Technology Preview OCI feature.
+<2> Set the back-end location to receive the image set metadata. This location can be a registry or local directory. It is required to specify `storageConfig` values.
 <3> Set the registry URL for the storage backend.
 <4> Set the channel that contains the {product-title} images for the version you are installing.
 <5> Set the Operator catalog that contains the {product-title} images that you are installing.