Skip to content

Commit 0894709

Browse files
bergerhofferbergerhoffer
committed
OSDOCS-5773: Adding and updating example oc-mirror image set configs
1 parent 39fc206 commit 0894709

File tree

2 files changed

+163
-88
lines changed

2 files changed

+163
-88
lines changed

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

Lines changed: 157 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -9,46 +9,72 @@
99

1010
The following `ImageSetConfiguration` file examples show the configuration for various mirroring use cases.
1111

12+
// Moved to first; unchanged
1213
[discrete]
13-
[id="oc-mirror-image-set-examples-helm_{context}"]
14-
== Use case: Including arbitrary images and helm charts
14+
[id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
15+
== Use case: Including the shortest {product-title} upgrade path
1516

16-
The following `ImageSetConfiguration` file uses a registry storage backend and includes helm charts and an additional Red Hat Universal Base Image (UBI).
17+
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`.
1718

1819
.Example `ImageSetConfiguration` file
1920
[source,yaml]
2021
----
2122
apiVersion: mirror.openshift.io/v1alpha2
2223
kind: ImageSetConfiguration
23-
archiveSize: 4
2424
storageConfig:
25-
registry:
26-
imageURL: example.com/mirror/oc-mirror-metadata
27-
skipTLS: false
25+
local:
26+
path: /home/user/metadata
2827
mirror:
29-
platform:
30-
architectures:
31-
- "s390x"
32-
channels:
33-
- name: stable-4.13
34-
operators:
35-
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
36-
helm:
37-
repositories:
38-
- name: redhat-helm-charts
39-
url: https://raw.githubusercontent.com/redhat-developer/redhat-helm-charts/master
40-
charts:
41-
- name: ibm-mongodb-enterprise-helm
42-
version: 0.2.0
43-
additionalImages:
44-
- name: registry.redhat.io/ubi9/ubi:latest
28+
platform:
29+
channels:
30+
- name: stable-4.12
31+
minVersion: 4.11.37
32+
maxVersion: 4.12.15
33+
shortestPath: true
34+
----
35+
36+
// Moved to second; unchanged
37+
[discrete]
38+
[id="oc-mirror-image-set-examples-minimum-to-latest_{context}"]
39+
== Use case: Including all versions of {product-title} from a minimum to the latest
40+
41+
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.
42+
43+
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.
44+
45+
.Example `ImageSetConfiguration` file
46+
[source,yaml]
47+
----
48+
apiVersion: mirror.openshift.io/v1alpha2
49+
kind: ImageSetConfiguration
50+
storageConfig:
51+
registry:
52+
imageURL: example.com/mirror/oc-mirror-metadata
53+
skipTLS: false
54+
mirror:
55+
platform:
56+
channels:
57+
- name: stable-4.10
58+
minVersion: 4.10.10
4559
----
4660

61+
// Updated:
62+
// - Added a note below about the maxVersion
63+
// - Added a note about not necessarily getting all versions in the range
4764
[discrete]
4865
[id="oc-mirror-image-set-examples-operator-versions_{context}"]
4966
== Use case: Including Operator versions from a minimum to the latest
5067

51-
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.
68+
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.
69+
70+
[NOTE]
71+
====
72+
When you specify a minimum or maximum version range, you might not receive all Operator versions in that range.
73+
74+
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].
75+
76+
To receive all Operator versions in a specified range, you can set the `mirror.operators.full` field to `true`.
77+
====
5278

5379
.Example `ImageSetConfiguration` file
5480
[source,yaml]
@@ -64,110 +90,157 @@ mirror:
6490
packages:
6591
- name: rhacs-operator
6692
channels:
67-
- name: latest
68-
minVersion: 3.68.0
93+
- name: stable
94+
minVersion: 4.0.1
6995
----
7096

71-
[discrete]
72-
[id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
73-
== Use case: Including the shortest {product-title} upgrade path
97+
[NOTE]
98+
====
99+
To specify a maximum version instead of the latest, set the `mirror.operators.packages.channels.maxVersion` field.
100+
====
74101

75-
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`.
102+
[discrete]
103+
[id="oc-mirror-image-set-examples-nutanix-operator_{context}"]
104+
== Use case: Including the Nutanix CSI Operator
105+
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).
76106

77107
.Example `ImageSetConfiguration` file
78108
[source,yaml]
79109
----
80-
apiVersion: mirror.openshift.io/v1alpha2
81110
kind: ImageSetConfiguration
111+
apiVersion: mirror.openshift.io/v1alpha2
82112
storageConfig:
83-
local:
84-
path: /home/user/metadata
113+
registry:
114+
imageURL: mylocalregistry/ocp-mirror/openshift4
115+
skipTLS: false
85116
mirror:
86117
platform:
87118
channels:
88-
- name: stable-4.10
89-
minVersion: 4.11.37
90-
maxVersion: 4.12.15
91-
shortestPath: true
119+
- name: stable-4.11
120+
type: ocp
121+
graph: true
122+
operators:
123+
- catalog: registry.redhat.io/redhat/certified-operator-index:v4.11
124+
packages:
125+
- name: nutanixcsioperator
126+
channels:
127+
- name: stable
128+
additionalImages:
129+
- name: registry.redhat.io/ubi9/ubi:latest
92130
----
93131

132+
// New example; including the default channel
94133
[discrete]
95-
[id="oc-mirror-image-set-examples-minimum-to-latest_{context}"]
96-
== Use case: Including all versions of {product-title} from a minimum to the latest
134+
[id="oc-mirror-image-set-examples-default-channel_{context}"]
135+
== Use case: Including the default Operator channel
97136

98-
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.
137+
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.
99138

100-
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.
139+
[TIP]
140+
====
141+
You can find the default channel by running the following command: `oc mirror list operators --catalog=<catalog_name> --package=<package_name>`.
142+
====
101143

102144
.Example `ImageSetConfiguration` file
103145
[source,yaml]
104146
----
105147
apiVersion: mirror.openshift.io/v1alpha2
106148
kind: ImageSetConfiguration
107149
storageConfig:
108-
registry:
109-
imageURL: example.com/mirror/oc-mirror-metadata
110-
skipTLS: false
150+
registry:
151+
imageURL: example.com/mirror/oc-mirror-metadata
152+
skipTLS: false
111153
mirror:
112-
platform:
113-
channels:
114-
- name: stable-4.10
115-
minVersion: 4.10.10
154+
operators:
155+
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
156+
packages:
157+
- name: elasticsearch-operator
158+
channels:
159+
- name: stable-5.7
160+
- name: stable
116161
----
117162

163+
// New example; Entire catalog; all versions
118164
[discrete]
119-
[id="oc-mirror-image-set-examples-operator-min-max_{context}"]
120-
== Use case: Including Operator versions from a minimum to a maximum
165+
[id="oc-mirror-image-set-examples-entire-catalog-full_{context}"]
166+
== Use case: Including an entire catalog (all versions)
121167

122-
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.
168+
The following `ImageSetConfiguration` file sets the `mirror.operators.full` field to `true` to include all versions for an entire Operator catalog.
123169

124-
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.
170+
.Example `ImageSetConfiguration` file
171+
[source,yaml]
172+
----
173+
apiVersion: mirror.openshift.io/v1alpha2
174+
kind: ImageSetConfiguration
175+
storageConfig:
176+
registry:
177+
imageURL: example.com/mirror/oc-mirror-metadata
178+
skipTLS: false
179+
mirror:
180+
operators:
181+
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
182+
full: true
183+
----
184+
185+
// New example; Entire catalog; heads only
186+
// - Included 'targetCatalog' in example
187+
[discrete]
188+
[id="oc-mirror-image-set-examples-entire-catalog-heads_{context}"]
189+
== Use case: Including an entire catalog (channel heads only)
190+
191+
The following `ImageSetConfiguration` file includes the channel heads for an entire Operator catalog.
192+
193+
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`.
194+
195+
This example also uses the `targetCatalog` field to specify an alternative namespace and name to mirror the catalog as.
125196

126197
.Example `ImageSetConfiguration` file
127198
[source,yaml]
128199
----
129200
apiVersion: mirror.openshift.io/v1alpha2
130201
kind: ImageSetConfiguration
131202
storageConfig:
132-
local:
133-
path: /home/user/metadata
203+
registry:
204+
imageURL: example.com/mirror/oc-mirror-metadata
205+
skipTLS: false
134206
mirror:
135207
operators:
136-
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
137-
packages:
138-
- name: example-operator
139-
channels:
140-
- name: stable
141-
minVersion: '1.0.0'
142-
maxVersion: '2.0.0'
208+
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
209+
targetCatalog: my-namespace/my-operator-catalog
143210
----
144211

212+
// Moved to last; unchanged
145213
[discrete]
146-
[id="oc-mirror-image-set-examples-nutanix-operator_{context}"]
147-
== Use case: Including the Nutanix CSI Operator
148-
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).
214+
[id="oc-mirror-image-set-examples-helm_{context}"]
215+
== Use case: Including arbitrary images and helm charts
216+
217+
The following `ImageSetConfiguration` file uses a registry storage backend and includes helm charts and an additional Red Hat Universal Base Image (UBI).
149218

150219
.Example `ImageSetConfiguration` file
151220
[source,yaml]
152221
----
153-
kind: ImageSetConfiguration
154-
apiVersion: mirror.openshift.io/v1alpha2
155-
storageConfig:
156-
registry:
157-
imageURL: mylocalregistry/ocp-mirror/openshift4
158-
skipTLS: false
159-
mirror:
160-
platform:
161-
channels:
162-
- name: stable-4.11
163-
type: ocp
164-
graph: true
165-
operators:
166-
- catalog: registry.redhat.io/redhat/certified-operator-index:v4.11
167-
packages:
168-
- name: nutanixcsioperator
169-
channels:
170-
- name: stable
171-
additionalImages:
172-
- name: registry.redhat.io/ubi9/ubi:latest
222+
apiVersion: mirror.openshift.io/v1alpha2
223+
kind: ImageSetConfiguration
224+
archiveSize: 4
225+
storageConfig:
226+
registry:
227+
imageURL: example.com/mirror/oc-mirror-metadata
228+
skipTLS: false
229+
mirror:
230+
platform:
231+
architectures:
232+
- "s390x"
233+
channels:
234+
- name: stable-4.13
235+
operators:
236+
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13
237+
helm:
238+
repositories:
239+
- name: redhat-helm-charts
240+
url: https://raw.githubusercontent.com/redhat-developer/redhat-helm-charts/master
241+
charts:
242+
- name: ibm-mongodb-enterprise-helm
243+
version: 0.2.0
244+
additionalImages:
245+
- name: registry.redhat.io/ubi9/ubi:latest
173246
----

‎modules/oc-mirror-oci-format.adoc

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,19 +52,21 @@ mirror:
5252
graph: false
5353
operators:
5454
- catalog: oci:///home/user/oc-mirror/my-oci-catalog <3>
55+
targetCatalog: my-namespace/redhat-operator-index <4>
5556
packages:
5657
- name: aws-load-balancer-operator
57-
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13 <4>
58+
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.13 <5>
5859
packages:
5960
- name: rhacs-operator
6061
additionalImages:
61-
- name: registry.redhat.io/ubi9/ubi:latest <5>
62+
- name: registry.redhat.io/ubi9/ubi:latest <6>
6263
----
6364
<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.
6465
<2> Optionally, include an {product-title} release to mirror from `registry.redhat.io`.
6566
<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.
66-
<4> Optionally, specify additional Operator catalogs to pull from a registry.
67-
<5> Optionally, specify additional images to pull from a registry.
67+
<4> Optionally, specify an alternative namespace and name to mirror the catalog as.
68+
<5> Optionally, specify additional Operator catalogs to pull from a registry.
69+
<6> Optionally, specify additional images to pull from a registry.
6870

6971
. Run the `oc mirror` command to mirror the OCI catalog to a target mirror registry:
7072
+

0 commit comments

Comments
 (0)