openshift · bergerhoffer · Dec 8, 2022 · Oct 10, 2022
diff --git a/installing/disconnected_install/installing-mirroring-disconnected.adoc b/installing/disconnected_install/installing-mirroring-disconnected.adoc
@@ -124,6 +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
+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]
+
 // Image set configuration parameters
 include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+1]
 

diff --git a/modules/oc-mirror-command-reference.adoc b/modules/oc-mirror-command-reference.adoc
@@ -70,6 +70,15 @@ 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.
+
+|`--oci-registries-config`
+|Provide a registries configuration file to specify an alternative registry location to copy from when using the Technology Preview OCI feature.
+
 |`--skip-cleanup`
 |Skip removal of artifact directories.
 
@@ -91,6 +100,9 @@ The following tables describe the `oc mirror` subcommands and flags:
 |`--source-use-http`
 |Use plain HTTP for the source registry.
 
+|`--use-oci-feature`
+|Use the Technology Preview OCI feature for copying OCI-formatted images.
+
 |`-v`, `--verbose` `<int>`
 |Specify the number for the log level verbosity. Valid values are `0` - `9`. The default is `0`.
 

diff --git a/modules/oc-mirror-creating-image-set-config.adoc b/modules/oc-mirror-creating-image-set-config.adoc
@@ -57,7 +57,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.
+<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.
 <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 generate the OpenShift Update Service (OSUS) graph image to allow for an improved cluster update experience when using the web console. For more information, see _About the OpenShift Update Service_.

diff --git a/modules/oc-mirror-oci-format.adoc b/modules/oc-mirror-oci-format.adoc
@@ -0,0 +1,128 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected.adoc
+
+:_content-type: PROCEDURE
+[id="oc-mirror-oci-format_{context}"]
+= Mirroring Operator images in OCI format
+
+You can use the oc-mirror plug-in 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.
+
+:FeatureName: Using the oc-mirror plug-in to mirror Operator images in OCI format
+include::snippets/technology-preview.adoc[]
+
+.Prerequisites
+
+* You have access to the internet to obtain the necessary container images.
+* You have installed the OpenShift CLI (`oc`).
+* You have installed the `oc-mirror` CLI plug-in.
+
+.Procedure
+
+. Create the image set configuration file to retrieve the catalogs and images that you require.
++
+.Example image set configuration file for copying to disk
+[source,yaml]
+----
+kind: ImageSetConfiguration
+apiVersion: mirror.openshift.io/v1alpha2
+mirror:
+ operators:
+ - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.12
+   packages:
+   - name: aws-load-balancer-operator
+----
++
+[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.
+====
+
+. Run the `oc mirror` command to mirror the images from the specified image set configuration to disk:
++
+[source,terminal]
+----
+$ oc mirror --config=./imageset-config.yaml \ <1>
+  --use-oci-feature \                         <2>
+  --oci-feature-action=copy \                 <3>
+  oci:///home/user/oc-mirror/my-oci-catalog   <4>
+----
+<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 the full path to a directory on disk where you want to output the catalog. The path must start with `oci://`. This procedure assumes that the directory is named `my-oci-catalog`.
++
+[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]
+----
+[[registry]]
+ location = "registry.redhat.io:5000"
+ insecure = false
+ blocked = false
+ mirror-by-digest-only = true
+ prefix = ""
+ [[registry.mirror]]
+    location = "preprod-registry.example.com"
+    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.
+====