You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can create postinstallation mirror configuration custom resources (CR) to redirect image pull requests from a source image registry to a mirrored image registry.
11
16
17
+
ifdef::winc[]
18
+
[IMPORTANT]
19
+
====
20
+
Windows images mirrored through `ImageDigestMirrorSet` and `ImageTagMirrorSet` objects have specific naming requirements. The final portion of the namespace and the image name of the mirror image must match the image being mirrored. For example, when mirroring the `mcr.microsoft.com/oss/kubernetes/pause:3.9` image, the mirror image must have the `<mirror_registry>/<optional_namespaces>/oss/kubernetes/pause:3.9` format. The `optional_namespaces` can be any number of leading repository namespaces.
21
+
====
22
+
endif::winc[]
23
+
12
24
.Prerequisites
13
25
ifndef::openshift-rosa,openshift-dedicated[]
14
26
* Access to the cluster as a user with the `cluster-admin` role.
* Setting up a mirrored repository with Red Hat Quay, as described in link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/manage_red_hat_quay/repo-mirroring-in-red-hat-quay[Red Hat Quay Repository Mirroring]. Using Red Hat Quay allows you to copy images from one repository to another and also automatically sync those repositories repeatedly over time.
25
38
26
39
* Using a tool such as `skopeo` to copy images manually from the source repository to the mirrored repository.
@@ -29,15 +42,30 @@ For example, after installing the skopeo RPM package on a Red Hat Enterprise Lin
In this example, you have a container image registry that is named `example.io` with an image repository named `example` to which you want to copy the `ubi9/ubi-minimal` image from `registry.access.redhat.com`. After you create the mirrored registry, you can configure your {product-title} cluster to redirect requests made of the source repository to the mirrored repository.
51
+
--
52
+
+
53
+
ifdef::winc[]
54
+
[IMPORTANT]
55
+
====
56
+
You must mirror the `mcr.microsoft.com/oss/kubernetes/pause:3.9` image. For example, you could use the following `skopeo` command to mirror the image:
. Create a postinstallation mirror configuration CR, by using one of the following examples:
42
70
43
71
* Create an `ImageDigestMirrorSet` or `ImageTagMirrorSet` CR, as needed, replacing the source and mirrors with your own registry and repository pairs and images:
@@ -84,8 +112,8 @@ spec:
84
112
** `imageDigestMirrors`: Use for an `ImageDigestMirrorSet` CR.
85
113
** `imageTagMirrors`: Use for an `ImageTagMirrorSet` CR.
86
114
<4> Indicates the name of the mirrored image registry and repository.
87
-
<5> Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use another mirror.
88
-
<6> Indicates the registry and repository source, which is the repository that is referred to in image pull specifications.
115
+
<5> Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use the secondary mirror.
116
+
<6> Indicates the registry and repository source, which is the repository that is referred to in an image pull specification.
89
117
<7> Optional: Indicates the fallback policy if the image pull fails:
90
118
** `AllowContactingSource`: Allows continued attempts to pull the image from the source repository. This is the default.
91
119
** `NeverContactSource`: Prevents continued attempts to pull the image from the source repository.
@@ -114,6 +142,46 @@ spec:
114
142
----
115
143
<1> Specifies the name of the mirror image registry and repository.
116
144
<2> Specifies the online registry and repository containing the content that is mirrored.
145
+
endif::winc[]
146
+
ifdef::winc[]
147
+
. Create an `ImageDigestMirrorSet` or `ImageTagMirrorSet` CR, as needed, replacing the source and mirrors with your own registry and repository pairs and images:
<1> Indicates the API to use with this CR. This must be `config.openshift.io/v1`.
172
+
<2> Indicates the kind of object according to the pull type:
173
+
** `ImageDigestMirrorSet`: Pulls a digest reference image.
174
+
** `ImageTagMirrorSet`: Pulls a tag reference image.
175
+
<3> Indicates the type of image pull method, either:
176
+
** `imageDigestMirrors`: Use for an `ImageDigestMirrorSet` CR.
177
+
** `imageTagMirrors`: Use for an `ImageTagMirrorSet` CR.
178
+
<4> Indicates the name of the mirrored image registry and repository.
179
+
<5> Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use another mirror.
180
+
<6> Indicates the registry and repository source, which is the repository that is referred to in image pull specifications.
181
+
<7> Optional: Indicates the fallback policy if the image pull fails:
182
+
** `AllowContactingSource`: Allows continued attempts to pull the image from the source repository. This is the default.
183
+
** `NeverContactSource`: Prevents continued attempts to pull the image from the source repository.
184
+
endif::winc[]
117
185
118
186
. Create the new object:
119
187
+
@@ -122,7 +190,9 @@ spec:
122
190
$ oc create -f registryrepomirror.yaml
123
191
----
124
192
+
193
+
ifndef::winc[]
125
194
After the object is created, the Machine Config Operator (MCO) drains the nodes for `ImageTagMirrorSet` objects only. The MCO does not drain the nodes for `ImageDigestMirrorSet` and `ImageContentSourcePolicy` objects.
195
+
endif::winc[]
126
196
127
197
. To check that the mirrored configuration settings are applied, do the following on one of the nodes.
128
198
@@ -166,6 +236,7 @@ To use host binaries, run `chroot /host`
166
236
sh-4.2# chroot /host
167
237
----
168
238
239
+
ifndef::winc[]
169
240
.. Check the `/etc/containers/registries.conf` file to make sure the changes were made:
170
241
+
171
242
[source,terminal]
@@ -246,6 +317,56 @@ short-name-mode = ""
246
317
<3> Indicates that the image pull from the mirror is a digest reference image.
247
318
<4> Indicates that the `NeverContactSource` parameter is set for this repository.
248
319
<5> Indicates that the image pull from the mirror is a tag reference image.
320
+
endif::winc[]
321
+
ifdef::winc[]
322
+
.. Check that the WMCO generated a `hosts.toml` file for each registry on each Windows instance. For the previous example IDMS object, there should be three files in the following file structure:
323
+
+
324
+
[source,terminal]
325
+
----
326
+
$ tree $config_path
327
+
----
328
+
+
329
+
[source,terminal]
330
+
.Example output
331
+
----
332
+
C:/k/containerd/registries/
333
+
|── registry.access.redhat.com
334
+
| └── hosts.toml
335
+
|── mirror.example.com
336
+
| └── hosts.toml
337
+
└── docker.io
338
+
└── hosts.toml:
339
+
----
340
+
+
341
+
The following output represents a `hosts.toml` containerd configuration file where the previous example IDMS object was applied.
@@ -17,7 +22,12 @@ Repository mirroring in {product-title} includes the following attributes:
17
22
* Image pulls are resilient to registry downtimes.
18
23
* Clusters in disconnected environments can pull images from critical locations, such as quay.io, and have registries behind a company firewall provide the requested images.
19
24
* A particular order of registries is tried when an image pull request is made, with the permanent registry typically being the last one tried.
25
+
ifndef::winc[]
20
26
* The mirror information you enter is added to the `/etc/containers/registries.conf` file on every node in the {product-title} cluster.
27
+
endif::winc[]
28
+
ifdef::winc[]
29
+
* The mirror information you enter is added to the appropriate `hosts.toml` containerd configuration file(s) on every Windows node in the {product-title} cluster.
30
+
endif::winc[]
21
31
* When a node makes a request for an image from the source repository, it tries each mirrored repository in turn until it finds the requested content. If all mirrors fail, the cluster tries the source repository. If successful, the image is pulled to the node.
22
32
23
33
Setting up repository mirroring can be done in the following ways:
@@ -34,14 +44,19 @@ If you did not configure mirroring during {product-title} installation, you can
34
44
**`ImageDigestMirrorSet` (IDMS). This object allows you to pull images from a mirrored registry by using digest specifications. The IDMS CR enables you to set a fall back policy that allows or stops continued attempts to pull from the source registry if the image pull fails.
35
45
+
36
46
**`ImageTagMirrorSet` (ITMS). This object allows you to pull images from a mirrored registry by using image tags. The ITMS CR enables you to set a fall back policy that allows or stops continued attempts to pull from the source registry if the image pull fails.
47
+
// Hiding ICSP as it is not supported in WINC
48
+
ifndef::winc[]
37
49
+
38
50
**`ImageContentSourcePolicy` (ICSP). This object allows you to pull images from a mirrored registry by using digest specifications. The ICSP CR always falls back to the source registry if the mirrors do not work.
51
+
endif::winc[]
39
52
--
53
+
ifndef::winc[]
40
54
+
41
55
[IMPORTANT]
42
56
====
43
57
Using an `ImageContentSourcePolicy` (ICSP) object to configure repository mirroring is a deprecated feature. Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. If you have existing YAML files that you used to create `ImageContentSourcePolicy` objects, you can use the `oc adm migrate icsp` command to convert those files to an `ImageDigestMirrorSet` YAML file. For more information, see "Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring" in the following section.
44
58
====
59
+
endif::winc[]
45
60
46
61
Each of these custom resource objects identify the following information:
47
62
--
@@ -50,8 +65,22 @@ Each of these custom resource objects identify the following information:
50
65
requested from the source repository.
51
66
--
52
67
68
+
ifndef::winc[]
53
69
For new clusters, you can use IDMS, ITMS, and ICSP CRs objects as desired. However, using IDMS and ITMS is recommended.
54
70
55
71
If you upgraded a cluster, any existing ICSP objects remain stable, and both IDMS and ICSP objects are supported. Workloads using ICSP objects continue to function as expected. However, if you want to take advantage of the fallback policies introduced in the IDMS CRs, you can migrate current workloads to IDMS objects by using the `oc adm migrate icsp` command as shown in the *Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring* section that follows. Migrating to IDMS objects does not require a cluster reboot.
The Windows Machine Config Operator (WMCO) watches for changes to the IDMS and ITMS resources and generates a set of `hosts.toml` containerd configuration files, one file for each source registry, with those changes. The WMCO then updates any existing Windows nodes to use the new registry configuration.
77
+
78
+
[NOTE]
79
+
====
80
+
The IDMS and ITMS objects must be created before you can add Windows nodes using a mirrored registry.
Copy file name to clipboardExpand all lines: modules/machineset-creating.adoc
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,6 +59,9 @@ endif::vsphere[]
59
59
ifdef::ash[]
60
60
* Create an availability set in which to deploy Azure Stack Hub compute machines.
61
61
endif::ash[]
62
+
ifdef::win[]
63
+
* In disconnected environments, the image specified in the `MachineSet` custom resource (CR) must have the link:https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=powershell#install-openssh-for-windows[OpenSSH server v0.0.1.0 installed].
The Windows Machine Config Operator (WMCO) can pull images from a registry mirror rather than from a public registry by using an `ImageDigestMirrorSet` (IDMS) or `ImageTagMirrorSet` (ITMS) object to configure your cluster to pull images from the mirror registry.
10
+
11
+
A mirror registry has the following benefits:
12
+
13
+
* Avoids public registry outages
14
+
* Speeds up node and pod creation
15
+
* Pulls images from behind your organization's firewall
16
+
17
+
A mirror registry can also be used with a {product-title} cluster in a disconnected, or air-gapped, network. A _disconnected network_ is a restricted network without direct internet connectivity. Because the cluster does not have access to the internet, any external container images cannot be referenced.
18
+
19
+
Using a mirror registry requires the following general steps:
20
+
21
+
* Create the mirror registry, using a tool such as Red Hat Quay.
22
+
* Create a container image registry credentials file.
23
+
* Copy the images from your online image repository to your mirror registry.
24
+
25
+
For information about these steps, see "About disconnected installation mirroring."
26
+
27
+
After creating the mirror registry and mirroring the images, you can use an `ImageDigestMirrorSet` (IDMS) or `ImageTagMirrorSet` (ITMS) object to configure your cluster to pull images from the mirror registry without needing to update each of your pod specs. The IDMS and ITMS objects redirect requests to pull images from a repository on a source image registry and have it resolved by the mirror repository instead.
28
+
29
+
If changes are made to the IDMS or ITMS object, the WMCO automatically updates the appropriate `hosts.toml` file on your Windows nodes with the new information. Note that the WMCO sequentially updates each Windows node when mirror settings are changed. As such, the time required for these updates increases with the number of Windows nodes in the cluster.
30
+
31
+
Also, because Windows nodes configured by the WMCO rely on containerd container runtime, the WMCO ensures that the containerd config files are up-to-date with the registry settings. For new nodes, these files are copied to the instances upon creation. For existing nodes, after activating the mirror registry, the registry controller uses SSH to access each node and copy the generated config files, replacing any existing files.
32
+
33
+
You can use a mirror registry with machine set or Bring-Your-Own-Host (BYOH) Windows nodes.
Copy file name to clipboardExpand all lines: windows_containers/enabling-windows-container-workloads.adoc
+10-1Lines changed: 10 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ Dual NIC is not supported on WMCO-managed Windows instances.
28
28
29
29
[NOTE]
30
30
====
31
-
Windows instances deployed by the WMCO are configured with the containerd container runtime. Because WMCO installs and manages the runtime, it is recommanded that you do not manually install containerd on nodes.
31
+
Windows instances deployed by the WMCO are configured with the containerd container runtime. Because WMCO installs and manages the runtime, it is recommended that you do not manually install containerd on nodes.
0 commit comments