OSDOCS-5773: Adding and updating example oc-mirror image set configs

openshift · May 18, 2023 · 058ba41 · 058ba41
1 parent 0d5e25d
commit 058ba41
Show file tree

Hide file tree

Showing 2 changed files with 100 additions and 72 deletions.
diff --git a/modules/oc-mirror-image-set-config-examples.adoc b/modules/oc-mirror-image-set-config-examples.adoc
@@ -9,65 +9,7 @@
 
 The following `ImageSetConfiguration` file examples show the configuration for various mirroring use cases.
 
-[discrete]
-[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]
-----
-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
-----
-
-[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.
-
-.Example `ImageSetConfiguration` file
-[source,yaml]
-----
-apiVersion: mirror.openshift.io/v1alpha2
-kind: ImageSetConfiguration
-storageConfig:
-  local:
-    path: /home/user/metadata
-mirror:
-  operators:
-    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
-      packages:
-        - name: rhacs-operator
-          channels:
-          - name: latest
-            minVersion: 3.68.0
-----
-
+// Moved to first; unchanged
 [discrete]
 [id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
 == Use case: Including the shortest {product-title} upgrade path
@@ -91,6 +33,7 @@ mirror:
         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
@@ -115,13 +58,24 @@ mirror:
         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-min-max_{context}"]
-== Use case: Including Operator versions from a minimum to a maximum
+[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 an example Operator, versions starting at `1.0.0` through `2.0.0` in the `stable` 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 3.68.0 and later in the `latest` channel.
+
+// TODO: Include a note like this in the sections that specify ranges?
+[NOTE]
+====
+When you specify a minimum or maximum version range, you might not receive all Operator versions in that range.
 
-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.
+By default, oc-mirror excludes any versions that are marked skipped or replaced in the Operator Lifecycle Manager (OLM) specification. Operator versions that are skipped might be affected by a CVE or contain bugs and a newer version should be used 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]
@@ -133,15 +87,19 @@ storageConfig:
     path: /home/user/metadata
 mirror:
   operators:
-    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
       packages:
-        - name: example-operator
+        - name: rhacs-operator
           channels:
-            - name: stable
-              minVersion: '1.0.0'
-              maxVersion: '2.0.0'
+          - name: latest
+            minVersion: 3.68.0
 ----
 
+[NOTE]
+====
+To specify a maximum version instead of the latest, set the `mirror.operators.packages.channels.maxVersion` field.
+====
+
 [discrete]
 [id="oc-mirror-image-set-examples-nutanix-operator_{context}"]
 == Use case: Including the Nutanix CSI Operator
@@ -171,3 +129,71 @@ The following `ImageSetConfiguration` file uses a local storage backend and incl
     additionalImages:
     - name: registry.redhat.io/ubi9/ubi:latest
 ----
+
+// TODO: New example: Use case: default channel has to be included
+// ^ can this one just be incorporated into an existing example?
+
+// TODO: New example: Use case: full for entire package
+
+// New example; Entire catalog; heads only
+// - Included 'targetCatalog' in example
+[discrete]
+[id="oc-mirror-image-set-examples-entire-catalog_{context}"]
+== Use case: Including an entire catalog (channel heads only)
+
+The following `ImageSetConfiguration` file uses a registry storage backend and includes an entire Operator catalog.
+
+By default, only versions that are required in order to upgrade to the channel head are included. Any Operator versions that are marked to replace or skip are not included. 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:
+   registry:
+     imageURL: example.com/mirror/oc-mirror-metadata
+     skipTLS: false
+  mirror:
+    operators:
+    - 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-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]
+----
+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:
 +