Skip to content

Commit f8bffcb

Browse files
bergerhofferbergerhoffer
authored
Merge pull request #53150 from bergerhoffer/OSDOCS-4298
OSDOCS-4298: Updating oc-mirror docs for OCI feature
2 parents 68cfca2 + 551940a commit f8bffcb

File tree

4 files changed

+149
-1
lines changed

4 files changed

+149
-1
lines changed

‎installing/disconnected_install/installing-mirroring-disconnected.adoc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,14 @@ include::modules/oc-mirror-differential-updates.adoc[leveloffset=+2]
124124
// Performing a dry run
125125
include::modules/oc-mirror-dry-run.adoc[leveloffset=+1]
126126

127+
// Mirroring Operator images in OCI format
128+
include::modules/oc-mirror-oci-format.adoc[leveloffset=+1]
129+
130+
[role="_additional-resources"]
131+
.Additional resources
132+
133+
* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-fb[File-based catalogs]
134+
127135
// Image set configuration parameters
128136
include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+1]
129137

‎modules/oc-mirror-command-reference.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,15 @@ The following tables describe the `oc mirror` subcommands and flags:
7070
|`--max-per-registry <int>`
7171
|Specify the number of concurrent requests allowed per registry. The default is `6`.
7272

73+
|`--oci-feature-action`
74+
|The action to perform when using the Technology Preview OCI feature. The options are `copy` or `mirror`.
75+
76+
|`--oci-insecure-signature-policy`
77+
|Do not push signatures when using the Technology Preview OCI feature.
78+
79+
|`--oci-registries-config`
80+
|Provide a registries configuration file to specify an alternative registry location to copy from when using the Technology Preview OCI feature.
81+
7382
|`--skip-cleanup`
7483
|Skip removal of artifact directories.
7584

@@ -91,6 +100,9 @@ The following tables describe the `oc mirror` subcommands and flags:
91100
|`--source-use-http`
92101
|Use plain HTTP for the source registry.
93102

103+
|`--use-oci-feature`
104+
|Use the Technology Preview OCI feature for copying OCI-formatted images.
105+
94106
|`-v`, `--verbose` `<int>`
95107
|Specify the number for the log level verbosity. Valid values are `0` - `9`. The default is `0`.
96108

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ mirror:
5757
helm: {}
5858
----
5959
<1> Add `archiveSize` to set the maximum size, in GiB, of each file within the image set.
60-
<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.
60+
<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.
6161
<3> Set the registry URL for the storage backend.
6262
<4> Set the channel to retrieve the {product-title} images from.
6363
<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_.

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

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="oc-mirror-oci-format_{context}"]
7+
= Mirroring Operator images in OCI format
8+
9+
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.
10+
11+
:FeatureName: Using the oc-mirror plug-in to mirror Operator images in OCI format
12+
include::snippets/technology-preview.adoc[]
13+
14+
.Prerequisites
15+
16+
* You have access to the internet to obtain the necessary container images.
17+
* You have installed the OpenShift CLI (`oc`).
18+
* You have installed the `oc-mirror` CLI plug-in.
19+
20+
.Procedure
21+
22+
. Create the image set configuration file to retrieve the catalogs and images that you require.
23+
+
24+
.Example image set configuration file for copying to disk
25+
[source,yaml]
26+
----
27+
kind: ImageSetConfiguration
28+
apiVersion: mirror.openshift.io/v1alpha2
29+
mirror:
30+
operators:
31+
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.12
32+
packages:
33+
- name: aws-load-balancer-operator
34+
----
35+
+
36+
[NOTE]
37+
====
38+
When using the OCI feature, only the `mirror.operators.catalog` setting is available for use.
39+
40+
The `storageConfig` setting is ignored in favor of the location passed in to the `oc mirror` command.
41+
====
42+
43+
. Run the `oc mirror` command to mirror the images from the specified image set configuration to disk:
44+
+
45+
[source,terminal]
46+
----
47+
$ oc mirror --config=./imageset-config.yaml \ <1>
48+
--use-oci-feature \ <2>
49+
--oci-feature-action=copy \ <3>
50+
oci:///home/user/oc-mirror/my-oci-catalog <4>
51+
----
52+
<1> Pass in the image set configuration file. This procedure assumes that it is named `imageset-config.yaml`.
53+
<2> Use the `--use-oci-feature` flag to enable the OCI feature.
54+
<3> To copy the catalog to disk, set the `--oci-feature-action` flag to `copy`.
55+
<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`.
56+
+
57+
[NOTE]
58+
====
59+
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.
60+
61+
.Example registries.conf file
62+
[source,toml]
63+
----
64+
[[registry]]
65+
location = "registry.redhat.io:5000"
66+
insecure = false
67+
blocked = false
68+
mirror-by-digest-only = true
69+
prefix = ""
70+
[[registry.mirror]]
71+
location = "preprod-registry.example.com"
72+
insecure = false
73+
----
74+
75+
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.
76+
====
77+
78+
. List your directory contents and verify that the following directories were created:
79+
+
80+
[source,terminal]
81+
----
82+
$ ls -l
83+
----
84+
+
85+
.Example output
86+
[source,terminal]
87+
----
88+
my-oci-catalog <1>
89+
oc-mirror-workspace <2>
90+
olm_artifacts <3>
91+
----
92+
<1> Directory that contains the OCI catalog. This procedure assumes that it is named `my-oci-catalog`.
93+
<2> Directory that contains each image in the catalog in its original format.
94+
<3> Directory that contains the files that describe the Operator bundles that this catalog references.
95+
96+
. Update the image set configuration file to specify the location of the catalog on disk to mirror to the target mirror registry:
97+
+
98+
.Example image set configuration file for mirroring to mirror registry
99+
[source,yaml]
100+
----
101+
kind: ImageSetConfiguration
102+
apiVersion: mirror.openshift.io/v1alpha2
103+
mirror:
104+
operators:
105+
- catalog: oci:///home/user/oc-mirror/my-oci-catalog/redhat-operator-index <1>
106+
packages:
107+
- name: aws-load-balancer-operator
108+
----
109+
<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://`.
110+
111+
. Run the oc mirror command to process the image set file on disk and mirror the contents to a target mirror registry:
112+
+
113+
[source,terminal]
114+
----
115+
$ oc mirror --config=./imageset-config.yaml \ <1>
116+
--use-oci-feature \ <2>
117+
--oci-feature-action=mirror \ <3>
118+
docker://registry.example:5000 <4>
119+
----
120+
<1> Pass in the updated image set configuration file. This procedure assumes that it is named `imageset-config.yaml`.
121+
<2> Use the `--use-oci-feature` flag to enable the OCI feature.
122+
<3> To mirror the catalog to the target mirror registry, set the `--oci-feature-action` flag to `mirror`.
123+
<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.
124+
+
125+
[NOTE]
126+
====
127+
You can optionally use the `--oci-insecure-signature-policy` flag to not push signatures to the target mirror registry.
128+
====

0 commit comments

Comments
 (0)