Merge pull request #60093 from bergerhoffer/OSDOCS-5773

OSDOCS-5773: Adding and updating example oc-mirror image set configs
openshift · Jun 28, 2023 · 8894df2 · 8894df2
2 parents 5ec190b + 0894709
commit 8894df2
Show file tree

Hide file tree

Showing 2 changed files with 163 additions and 88 deletions.
diff --git a/modules/oc-mirror-image-set-config-examples.adoc b/modules/oc-mirror-image-set-config-examples.adoc
@@ -9,46 +9,72 @@
 
 The following `ImageSetConfiguration` file examples show the configuration for various mirroring use cases.
 
+// Moved to first; unchanged
 [discrete]
-[id="oc-mirror-image-set-examples-helm_{context}"]
-== Use case: Including arbitrary images and helm charts
+[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 registry storage backend and includes helm charts and an additional Red Hat Universal Base Image (UBI).
+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]
 ----
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
-archiveSize: 4
 storageConfig:
- registry:
-   imageURL: example.com/mirror/oc-mirror-metadata
-   skipTLS: false
+  local:
+    path: /home/user/metadata
 mirror:
- platform:
-   architectures:
-     - "s390x"
-   channels:
-     - name: stable-4.13
- operators:
-   - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
- helm:
-   repositories:
-     - name: redhat-helm-charts
-       url: https://raw.githubusercontent.com/redhat-developer/redhat-helm-charts/master
-       charts:
-         - name: ibm-mongodb-enterprise-helm
-           version: 0.2.0
- additionalImages:
-   - name: registry.redhat.io/ubi9/ubi:latest
+  platform:
+    channels:
+      - name: stable-4.12
+        minVersion: 4.11.37
+        maxVersion: 4.12.15
+        shortestPath: true
+----
+
+// Moved to second; unchanged
+[discrete]
+[id="oc-mirror-image-set-examples-minimum-to-latest_{context}"]
+== Use case: Including all versions of {product-title} from a minimum to the latest
+
+The following `ImageSetConfiguration` file uses a registry storage backend and includes all {product-title} versions starting at a minimum version of `4.10.10` to the latest version in the channel.
+
+On every invocation of oc-mirror with this image set configuration, the latest release of the `stable-4.10` channel is evaluated, so running oc-mirror at regular intervals ensures that you automatically receive the latest releases of {product-title} images.
+
+.Example `ImageSetConfiguration` file
+[source,yaml]
+----
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+storageConfig:
+  registry:
+    imageURL: example.com/mirror/oc-mirror-metadata
+    skipTLS: false
+mirror:
+  platform:
+    channels:
+      - name: stable-4.10
+        minVersion: 4.10.10
 ----
 
+// Updated:
+// - Added a note below about the maxVersion
+// - Added a note about not necessarily getting all versions in the range
 [discrete]
 [id="oc-mirror-image-set-examples-operator-versions_{context}"]
 == Use case: Including Operator versions from a minimum to the latest
 
-The following `ImageSetConfiguration` file uses a local storage backend and includes only the Red Hat Advanced Cluster Security for Kubernetes Operator, versions starting at 3.68.0 and later in the `latest` channel.
+The following `ImageSetConfiguration` file uses a local storage backend and includes only the Red Hat Advanced Cluster Security for Kubernetes Operator, versions starting at 4.0.1 and later in the `stable` channel.
+
+[NOTE]
+====
+When you specify a minimum or maximum version range, you might not receive all Operator versions in that range.
+
+By default, oc-mirror excludes any versions that are skipped or replaced by a newer version in the Operator Lifecycle Manager (OLM) specification. Operator versions that are skipped might be affected by a CVE or contain bugs. Use a newer version instead. For more information on skipped and replaced versions, see link:https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/[Creating an update graph with OLM].
+
+To receive all Operator versions in a specified range, you can set the `mirror.operators.full` field to `true`.
+====
 
 .Example `ImageSetConfiguration` file
 [source,yaml]
@@ -64,110 +90,157 @@ mirror:
       packages:
         - name: rhacs-operator
           channels:
-          - name: latest
-            minVersion: 3.68.0
+          - name: stable
+            minVersion: 4.0.1
 ----
 
-[discrete]
-[id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
-== Use case: Including the shortest {product-title} upgrade path
+[NOTE]
+====
+To specify a maximum version instead of the latest, set the `mirror.operators.packages.channels.maxVersion` field.
+====
 
-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`.
+[discrete]
+[id="oc-mirror-image-set-examples-nutanix-operator_{context}"]
+== Use case: Including the Nutanix CSI Operator
+The following `ImageSetConfiguration` file uses a local storage backend and includes the Nutanix CSI Operator, the OpenShift Update Service (OSUS) graph image, and an additional Red Hat Universal Base Image (UBI).
 
 .Example `ImageSetConfiguration` file
 [source,yaml]
 ----
-apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
+apiVersion: mirror.openshift.io/v1alpha2
 storageConfig:
-  local:
-    path: /home/user/metadata
+  registry:
+    imageURL: mylocalregistry/ocp-mirror/openshift4
+    skipTLS: false
 mirror:
   platform:
     channels:
-      - name: stable-4.10
-        minVersion: 4.11.37
-        maxVersion: 4.12.15
-        shortestPath: true
+    - name: stable-4.11
+      type: ocp
+    graph: true
+  operators:
+  - catalog: registry.redhat.io/redhat/certified-operator-index:v4.11
+    packages:
+    - name: nutanixcsioperator
+      channels:
+      - name: stable
+  additionalImages:
+  - name: registry.redhat.io/ubi9/ubi:latest
 ----
 
+// New example; including the default channel
 [discrete]
-[id="oc-mirror-image-set-examples-minimum-to-latest_{context}"]
-== Use case: Including all versions of {product-title} from a minimum to the latest
+[id="oc-mirror-image-set-examples-default-channel_{context}"]
+== Use case: Including the default Operator channel
 
-The following `ImageSetConfiguration` file uses a registry storage backend and includes all {product-title} versions starting at a minimum version of `4.10.10` to the latest version in the channel.
+The following `ImageSetConfiguration` file includes the `stable-5.7` and `stable` channels for the OpenShift Elasticsearch Operator. Even if only the packages from the `stable-5.7` channel are needed, the `stable` channel must also be included in the `ImageSetConfiguration` file, because it is the default channel for the Operator. You must always include the default channel for the Operator package even if you do not use the bundles in that channel.
 
-On every invocation of oc-mirror with this image set configuration, the latest release of the `stable-4.10` channel is evaluated, so running oc-mirror at regular intervals ensures that you automatically receive the latest releases of {product-title} images.
+[TIP]
+====
+You can find the default channel by running the following command: `oc mirror list operators --catalog=<catalog_name> --package=<package_name>`.
+====
 
 .Example `ImageSetConfiguration` file
 [source,yaml]
 ----
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
 storageConfig:
- registry:
-   imageURL: example.com/mirror/oc-mirror-metadata
-   skipTLS: false
+  registry:
+    imageURL: example.com/mirror/oc-mirror-metadata
+    skipTLS: false
 mirror:
-  platform:
-    channels:
-      - name: stable-4.10
-        minVersion: 4.10.10
+  operators:
+  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
+    packages:
+    - name: elasticsearch-operator
+      channels:
+      - name: stable-5.7
+      - name: stable
 ----
 
+// New example; Entire catalog; all versions
 [discrete]
-[id="oc-mirror-image-set-examples-operator-min-max_{context}"]
-== Use case: Including Operator versions from a minimum to a maximum
+[id="oc-mirror-image-set-examples-entire-catalog-full_{context}"]
+== Use case: Including an entire catalog (all versions)
 
-The following `ImageSetConfiguration` file uses a local storage backend and includes only an example Operator, versions starting at `1.0.0` through `2.0.0` in the `stable` channel.
+The following `ImageSetConfiguration` file sets the `mirror.operators.full` field to `true` to include all versions for an entire Operator catalog.
 
-This allows you to only mirror a specific version range of a particular Operator. As time progresses, you can use these settings to adjust the version to newer releases, for example when you no longer have version `1.0.0` running anywhere anymore. In this scenario, you can increase the `minVersion` to something newer, for example `1.5.0`. When oc-mirror runs again with the updated version range, it automatically detects that any releases older than `1.5.0` are no longer required and deletes those from the registry to conserve storage space.
+.Example `ImageSetConfiguration` file
+[source,yaml]
+----
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+storageConfig:
+  registry:
+    imageURL: example.com/mirror/oc-mirror-metadata
+    skipTLS: false
+mirror:
+  operators:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
+      full: true
+----
+
+// New example; Entire catalog; heads only
+// - Included 'targetCatalog' in example
+[discrete]
+[id="oc-mirror-image-set-examples-entire-catalog-heads_{context}"]
+== Use case: Including an entire catalog (channel heads only)
+
+The following `ImageSetConfiguration` file includes the channel heads for an entire Operator catalog.
+
+By default, for each Operator in the catalog, oc-mirror includes the latest Operator version (channel head) from the default channel. If you want to mirror all Operator versions, and not just the channel heads, you must set the `mirror.operators.full` field to `true`.
+
+This example also uses the `targetCatalog` field to specify an alternative namespace and name to mirror the catalog as.
 
 .Example `ImageSetConfiguration` file
 [source,yaml]
 ----
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
 storageConfig:
-  local:
-    path: /home/user/metadata
+  registry:
+    imageURL: example.com/mirror/oc-mirror-metadata
+    skipTLS: false
 mirror:
   operators:
-    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
-      packages:
-        - name: example-operator
-          channels:
-            - name: stable
-              minVersion: '1.0.0'
-              maxVersion: '2.0.0'
+  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
+    targetCatalog: my-namespace/my-operator-catalog
 ----
 
+// Moved to last; unchanged
 [discrete]
-[id="oc-mirror-image-set-examples-nutanix-operator_{context}"]
-== Use case: Including the Nutanix CSI Operator
-The following `ImageSetConfiguration` file uses a local storage backend and includes the Nutanix CSI Operator, the OpenShift Update Service (OSUS) graph image, and an additional Red Hat Universal Base Image (UBI).
+[id="oc-mirror-image-set-examples-helm_{context}"]
+== Use case: Including arbitrary images and helm charts
+
+The following `ImageSetConfiguration` file uses a registry storage backend and includes helm charts and an additional Red Hat Universal Base Image (UBI).
 
 .Example `ImageSetConfiguration` file
 [source,yaml]
 ----
-  kind: ImageSetConfiguration
-  apiVersion: mirror.openshift.io/v1alpha2
-  storageConfig:
-    registry:
-      imageURL: mylocalregistry/ocp-mirror/openshift4
-      skipTLS: false
-  mirror:
-    platform:
-      channels:
-      - name: stable-4.11
-        type: ocp
-      graph: true
-    operators:
-    - catalog: registry.redhat.io/redhat/certified-operator-index:v4.11
-      packages:
-      - name: nutanixcsioperator
-        channels:
-        - name: stable
-    additionalImages:
-    - name: registry.redhat.io/ubi9/ubi:latest
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+archiveSize: 4
+storageConfig:
+  registry:
+    imageURL: example.com/mirror/oc-mirror-metadata
+    skipTLS: false
+mirror:
+ platform:
+   architectures:
+     - "s390x"
+   channels:
+     - name: stable-4.13
+ operators:
+   - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
+ helm:
+   repositories:
+     - name: redhat-helm-charts
+       url: https://raw.githubusercontent.com/redhat-developer/redhat-helm-charts/master
+       charts:
+         - name: ibm-mongodb-enterprise-helm
+           version: 0.2.0
+ additionalImages:
+   - name: registry.redhat.io/ubi9/ubi:latest
 ----
diff --git a/modules/oc-mirror-oci-format.adoc b/modules/oc-mirror-oci-format.adoc
@@ -52,19 +52,21 @@ mirror:
     graph: false
   operators:
   - catalog: oci:///home/user/oc-mirror/my-oci-catalog                       <3>
+    targetCatalog: my-namespace/redhat-operator-index                        <4>
     packages:
     - name: aws-load-balancer-operator
-  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13           <4>
+  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13           <5>
     packages:
     - name: rhacs-operator
   additionalImages:
-  - name: registry.redhat.io/ubi9/ubi:latest                                 <5>
+  - name: registry.redhat.io/ubi9/ubi:latest                                 <6>
 ----
 <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.
+<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.
 
 . Run the `oc mirror` command to mirror the OCI catalog to a target mirror registry:
 +