Skip to content

Commit c2a42cf

Browse files
mletaliemletalie
committed
IDMS
1 parent 428c588 commit c2a42cf

11 files changed

+690
-75
lines changed

‎modules/images-registry-mirroring.adoc‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * openshift_images/image-configuration-hcp.adoc
4+
:_mod-docs-content-type: CONCEPT
5+
6+
[id="images-registry-mirroring_{context}"]
7+
= Image registry mirroring for {product-title}
8+
9+
You can configure an existing {product-title} cluster to pull images from a mirrored registry by using the `ImageDigestMirrorSet (IDMS)` object.
10+
11+
[IMPORTANT]
12+
====
13+
The image mirror configuration feature operates exclusively with image references by digest, meaning that image mirroring will only activate when an image is pulled using its unique and immutable ID. Any image references using a mutable tag are currently not supported by this functionality.
14+
====
15+
16+
IDMS defines a set of cluster-wide policies for registry mirroring that makes image downloads faster, more reliable and more secure. It works by intercepting any image pull request that identifies an image by its unique, content-addressable digest. Based on these policies, the IDMS transparently redirects the pull operation from its specified source registry to one or more designated mirror registries. For the developer, this means their request—still pointing to the original source—is automatically fulfilled by a faster, closer mirror, significantly improving deployment speed without requiring any changes to their workflow.
17+
18+
.Prerequisites
19+
20+
To configure an existing {product-title} cluster to pull images from a mirrored registry by using the `ImageDigestMirrorSet (IDMS)` object, you must meet the following prerequisites:
21+
22+
** You have installed and configured the latest {rosa-cli-first} on your installation host.
23+
** You have installed a {product-title} cluster.
24+
** The {product-title} cluster must be in a **Ready** state to create, edit, list, or delete image mirrors.
25+
** You have access to the mirror registries you want to configure.
26+
** You have the required IAM permissions to manage cluster configurations. For more information, see "About IAM resources" in the _Additional resources_ section.
27+
28+
The benefits of configuring your {product-title} cluster to pull images from a mirrored registry using IDMS include:
29+
30+
** *Enhanced Security*: By forcing image pulls from a private, mirrored registry, you can scan and approve all images for vulnerabilities before they ever enter your cluster.
31+
32+
** *Improved Cluster Reliability*: A local mirror guarantees stable and predictable cluster performance by eliminating reliance on public internet pathways.
33+
34+
** *Guaranteed Image Consistency*: IDMS uses image digests to reference images, which ensures that every node in the cluster pulls the same version of an image, preventing inconsistencies which could lead to deployment failures.
35+
36+
[id="create-image-mirroring_{context}"]
37+
== Creating an image mirror configuration
38+
39+
.Procedure
40+
41+
To create an image mirror configuration for a {product-title} cluster, run the following command:
42+
43+
[IMPORTANT]
44+
====
45+
The source registry cannot be modified after creation. You must delete and recreate the image mirror to change the source.
46+
====
47+
48+
.Syntax
49+
[source,terminal]
50+
----
51+
$ rosa create image-mirror [arguments]
52+
----
53+
54+
.Arguments
55+
[cols="30,70"]
56+
|===
57+
|Option |Definition
58+
59+
a|--cluster
60+
|Required: The name or ID of the cluster the mirror configuration will be applied to.
61+
62+
|--source
63+
|Required: The source registry that will be mirrored.
64+
65+
|--mirrors
66+
|Required: List of mirror registries. Mirror registries must be comma-separated.
67+
68+
|--type=digest
69+
|Optional: Type of image mirror. The `digest` type is set by default and the only available `type` option.
70+
71+
|--profile
72+
|Optional: Specifies an AWS profile (string) from your credentials file.
73+
74+
|--region
75+
|Optional:Specifies an AWS region, overriding the AWS_REGION environment variable.
76+
|===
77+
78+
.Examples
79+
Creates an image mirror configuration for a cluster named `mycluster`.
80+
81+
82+
[source,terminal]
83+
----
84+
$ rosa create image-mirror --cluster=mycluster \
85+
--source=registry.example.com/team \
86+
--mirrors=mirror.corp.com/team,backup.corp.com/team
87+
----
88+
.Example Output
89+
90+
[source,terminal]
91+
----
92+
I: Image mirror with ID 'abc123def456' has been created on cluster 'mycluster'
93+
I: Source: registry.example.com/team
94+
I: Mirrors: [mirror.corp.com/team backup.corp.com/team]
95+
----
96+
[NOTE]
97+
====
98+
An ID is automatically generated and assigned to an image mirror during image mirror configuration creation.
99+
====
100+
101+
Creates an image mirror configuration with a specific type.
102+
103+
[NOTE]
104+
====
105+
The `digest` type is set by default and the only available `type` option.
106+
====
107+
108+
[source,terminal]
109+
----
110+
$ rosa create image-mirror --cluster=mycluster \
111+
--type=digest --source=docker.io/library \
112+
--mirrors=internal-registry.company.com/dockerhub
113+
----
114+
115+
Creating a single image mirror configuration with multiple mirrors for a cluster.
116+
117+
[source,terminal]
118+
----
119+
$ rosa create image-mirror --cluster=mycluster \
120+
--source=quay.io/openshift \
121+
--mirrors=mirror1.company.com/openshift,mirror2.company.com/openshift,mirror3.company.com/openshift
122+
----
123+
124+
[id="edit-image-mirroring_{context}"]
125+
== Editing an image mirroring configuration
126+
127+
.Procedure
128+
129+
To edit an image mirror configuration for a {product-title} cluster, run the following command:
130+
131+
[NOTE]
132+
====
133+
When editing an image mirror configuration, the new mirrors list completely replaces the existing mirrors list.
134+
====
135+
136+
.Syntax
137+
[source,terminal]
138+
----
139+
$ rosa edit image-mirror [arguments]
140+
----
141+
.Arguments
142+
[cols="30,70"]
143+
|===
144+
|Option |Definition
145+
146+
|--cluster
147+
|Required: The name or ID (string) of the cluster to which the image mirror configuration applies.
148+
149+
|--mirrors
150+
|Required: New list of mirror registries that replaces current mirror registries. Mirror registries must be comma-separated.
151+
152+
|--id
153+
|Required: ID of the image mirror configuration to edit.
154+
155+
|--profile
156+
|Optional: Use a specific AWS profile from your credential file.
157+
158+
|--region
159+
|Optional: Use a specific AWS region, overriding the AWS_REGION environment variable.
160+
|===
161+
162+
.Examples
163+
// Based on conversation with PM, these are not necessary b/c we are going to include examples only with the ID to keep things unambiguous.
164+
// Edits an image mirror configuration with a positional argument.
165+
166+
// [source,terminal]
167+
// ----
168+
// $ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
169+
// --mirrors=mirror.corp.com/team,backup.corp.com/team,new-mirror.corp.com/team
170+
// ----
171+
172+
// Edits an image mirror configuration using the `--id` flag.
173+
174+
// [source,terminal]
175+
// ----
176+
// $ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
177+
// --mirrors=mirror.corp.com/team,backup.corp.com/team,new-mirror.corp.com/team
178+
// ----
179+
180+
Replaces a single mirror on an image mirror configuration.
181+
182+
[source,terminal]
183+
----
184+
$ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
185+
--mirrors=single-mirror.company.com/team
186+
----
187+
.Example Output
188+
[source,terminal]
189+
----
190+
I: Image mirror 'abc123def456' has been updated on cluster 'mycluster'
191+
I: Source: registry.example.com/team
192+
I: Updated mirrors: [mirror.corp.com/team backup.corp.com/team new-mirror.corp.com/team]
193+
----
194+
195+
Replaces all mirrors on an image mirror configuration.
196+
197+
[source,terminal]
198+
----
199+
$ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
200+
--mirrors=new-primary.company.com/team,new-secondary.company.com/team
201+
----
202+
203+
204+
[id="list-image-mirroring_{context}"]
205+
== Listing all image mirror configurations
206+
.Procedure
207+
208+
To list all image mirror configurations for a {product-title} cluster, run the following command:
209+
210+
.Syntax
211+
[source,terminal]
212+
----
213+
$ rosa list image-mirrors [arguments]
214+
----
215+
216+
.Arguments
217+
[cols="30,70"]
218+
|===
219+
|Option |Definition
220+
221+
|--cluster
222+
|Required: Name or ID of the cluster.
223+
|--output
224+
|Optional: Output format. Allowed formats are `json`, `yaml`
225+
|--profile
226+
|Optional: Use a specific AWS profile from your credential file.
227+
|--region
228+
|Optional: Use a specific AWS region, overriding the AWS_REGION environment variable.
229+
|===
230+
231+
.Example
232+
233+
Lists all image mirror configurations for a cluster.
234+
235+
[source,terminal]
236+
----
237+
$ rosa list image-mirrors --cluster=mycluster
238+
----
239+
.Example Outputs
240+
[source,terminal]
241+
----
242+
ID TYPE SOURCE MIRRORS
243+
abc123def456 digest registry.example.com/team mirror.corp.com/team, backup.corp.com/
244+
----
245+
246+
[id="delete-image-mirroring_{context}"]
247+
== Deleting an image mirror configuration
248+
[NOTE]
249+
====
250+
Delete operations require confirmation unless the `--yes` or `--y` argument is used.
251+
====
252+
253+
.Procedure
254+
255+
To delete an image mirror configuration from a {product-title} cluster, run the following command:
256+
257+
.Syntax
258+
[source,terminal]
259+
----
260+
$ rosa delete image-mirror [arguments]
261+
----
262+
263+
.Arguments
264+
[cols="30,70"]
265+
|===
266+
|Option |Definition
267+
268+
|--cluster
269+
|Required: The name or ID (string) of the cluster that the image mirror configuration will be deleted from.
270+
|--id
271+
|Required: ID of the image mirror configuration to delete.
272+
|`--yes`, `-y`
273+
|Optional: Automatically answers "yes" to confirm deletion.
274+
|--profile
275+
|Optional: Use a specific AWS profile from your credential file.
276+
|--region
277+
|Optional: Use a specific AWS region, overriding the AWS_REGION environment variable.
278+
279+
|===
280+
.Examples
281+
Deletes an image mirror configuration without a confirmation prompt.
282+
283+
[source,terminal]
284+
----
285+
$ rosa delete image-mirror --cluster=mycluster abc123def456 --yes
286+
----
287+
288+
.Example Output
289+
[source,terminal]
290+
----
291+
I: Image mirror 'abc123def456' has been deleted from cluster 'mycluster'
292+
----
293+
294+
Deletes an image mirror configuration with a confirmation prompt.
295+
296+
[source,terminal]
297+
----
298+
$ rosa delete image-mirror --cluster=mycluster --id=abc123def456
299+
----
300+

0 commit comments

Comments
 (0)