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
Copy file name to clipboardExpand all lines: modules/builds-image-source.adoc
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,7 +45,7 @@ source:
45
45
+
46
46
[NOTE]
47
47
====
48
-
If your cluster uses an `ImageContentSourcePolicy` object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project.
48
+
If your cluster uses an `ImageDigestMirrorSet` or `ImageTagMirrorSet` object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project.
= Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring
10
+
11
+
Using an `ImageContentSourcePolicy` (ICSP) object to configure repository mirroring is a deprecated feature. This 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.
12
+
13
+
ICSP objects are being replaced by `ImageDigestMirrorSet` and `ImageTagMirrorSet` objects to configure repository mirroring. 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. The command updates the API to the current version, changes the `kind` value to `ImageDigestMirrorSet`, and changes `spec.repositoryDigestMirrors` to `spec.imageDigestMirrors`. The rest of the file is not changed.
14
+
15
+
For more information about `ImageDigestMirrorSet` or `ImageTagMirrorSet` objects, see "Configuring image registry repository mirroring" in the previous section.
16
+
17
+
.Prerequisites
18
+
19
+
* Ensure that you have access to the cluster as a user with the `cluster-admin` role.
20
+
21
+
* Ensure that you have `ImageContentSourcePolicy` objects on your cluster.
22
+
23
+
.Procedure
24
+
25
+
. Use the following command to convert one or more `ImageContentSourcePolicy` YAML files to an `ImageDigestMirrorSet` YAML file:
Setting up container registry repository mirroring enables you to do the following:
11
+
Setting up container registry repository mirroring enables you to perform the following tasks:
12
12
13
13
* Configure your {product-title} cluster to redirect requests to pull images from a repository on a source image registry and have it resolved by a repository on a mirrored image registry.
14
14
* Identify multiple mirrored repositories for each target repository, to make sure that if one mirror is down, another can be used.
15
15
16
-
The attributes of repository mirroring in {product-title}include:
16
+
Repository mirroring in {product-title}includes the following attributes:
17
17
18
18
* Image pulls are resilient to registry downtimes.
19
19
* 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.
@@ -29,9 +29,20 @@ By pulling container images needed by {product-title} and then bringing those im
29
29
30
30
* After {product-title} installation:
31
31
+
32
-
Even if you don't configure mirroring during {product-title} installation, you can do so later using the `ImageContentSourcePolicy` object.
32
+
If you did not configure mirroring during {product-title} installation, you can do so post-installation by using one of the following custom resource (CR) objects:
33
+
+
34
+
--
35
+
**`ImageDigestMirrorSet`. This CR allows you to pull images from a mirrored registry by using digest specifications.
36
+
+
37
+
**`ImageTagMirrorSet`. This CR allows you to pull images from a mirrored registry by using image tags.
38
+
--
39
+
+
40
+
[IMPORTANT]
41
+
====
42
+
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.
43
+
====
33
44
34
-
The following procedure provides a post-installation mirror configuration, where you create an `ImageContentSourcePolicy` object that identifies:
45
+
Both of these custom resource objects identify the following information:
35
46
--
36
47
* The source of the container image repository you want to mirror.
37
48
* A separate entry for each mirror repository you want to offer the content
@@ -40,11 +51,26 @@ requested from the source repository.
40
51
41
52
[NOTE]
42
53
====
43
-
You can only configure global pull secrets for clusters that have an `ImageContentSourcePolicy` object. You cannot add a pull secret to a project.
54
+
If your cluster uses an `ImageDigestMirrorSet` or `ImageTagMirrorSet` object to configure repository mirroring, you can use only global pull secrets for mirrored registries. You cannot add a pull secret to a project.
44
55
====
45
56
57
+
The following procedure creates a post-installation mirror configuration, where you create an `ImageDigestMirrorSet` object.
58
+
46
59
.Prerequisites
47
-
* Access to the cluster as a user with the `cluster-admin` role.
60
+
* Ensure that you have access to the cluster as a user with the `cluster-admin` role.
61
+
62
+
* Ensure that there are no `ImageContentSourcePolicy` objects on your cluster. For example, you can use the following command:
63
+
+
64
+
[source, terminal]
65
+
----
66
+
$ oc get ImageContentSourcePolicy
67
+
----
68
+
+
69
+
.Example output
70
+
[source, terminal]
71
+
----
72
+
No resources found
73
+
----
48
74
49
75
.Procedure
50
76
@@ -66,55 +92,71 @@ In this example, you have a container image registry that is named `example.io`
66
92
67
93
. Log in to your {product-title} cluster.
68
94
69
-
. Create an `ImageContentSourcePolicy` file (for example, `registryrepomirror.yaml`), replacing the source and mirrors with your own registry and repository pairs and images:
95
+
. 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 name of the image registry and repository.
100
-
<2> Indicates multiple mirror repositories for each target repository. If one mirror is down, the target repository can use another mirror.
101
-
<3> Indicates the registry and repository containing the content that is mirrored.
102
-
<4> You can configure a namespace inside a registry to use any image in that namespace. If you use a registry domain as a source, the `ImageContentSourcePolicy` resource is applied to all repositories from the registry.
103
-
<5> If you configure the registry name, the `ImageContentSourcePolicy` resource is applied to all repositories from a source registry to a mirror registry.
104
-
<6> Pulls the image `mirror.example.net/image@sha256:...`.
105
-
<7> Pulls the image `myimage` in the source registry namespace from the mirror `mirror.example.net/myimage@sha256:...`.
106
-
<8> Pulls the image `registry.example.com/example/myimage` from the mirror registry `mirror.example.net/registry-example-com/example/myimage@sha256:...`. The `ImageContentSourcePolicy` resource is applied to all repositories from a source registry to a mirror registry `mirror.example.net/registry-example-com`.
107
-
108
-
. Create the new `ImageContentSourcePolicy` object:
131
+
<1> Indicates the API to use with this CR. This must be `config.openshift.io/v1`.
132
+
<2> Indicates the kind of object according to the pull type:
133
+
**`ImageDigestMirrorSet`: Pulls a digest reference image.
134
+
**`ImageTagMirrorSet`: Pulls a tag reference image.
135
+
<3> Indicates the type of image pull method, either:
136
+
**`imageDigestMirrors`: Use for an `ImageDigestMirrorSet` CR.
137
+
**`imageTagMirrors`: Use for an `ImageTagMirrorSet` CR.
138
+
<4> Indicates the name of the mirrored image registry and repository.
139
+
<5> Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use another mirror.
140
+
<6> Indicates the registry and repository source, which is the repository that is referred to in image pull specifications.
141
+
<7> Optional: Indicates the fallback policy if the image pull fails:
142
+
**`AllowContactingSource`: Allows continued attempts to pull the image from the source repository. This is the default.
143
+
**`NeverContactSource`: Prevents continued attempts to pull the image from the source repository.
144
+
<8> Optional: Indicates a namespace inside a registry, which allows you to use any image in that namespace. If you use a registry domain as a source, the object is applied to all repositories from the registry.
145
+
<9> Optional: Indicates a registry, which allows you to use any image in that registry. If you specify a registry name, the object is applied to all repositories from a source registry to a mirror registry.
146
+
<10> Pulls the image `registry.example.com/example/myimage@sha256:...` from the mirror `mirror.example.net/image@sha256:..`.
147
+
<11> Pulls the image `registry.example.com/example/image@sha256:...` in the source registry namespace from the mirror `mirror.example.net/image@sha256:...`.
148
+
<12> Pulls the image `registry.example.com/myimage@sha256` from the mirror registry `example.net/registry-example-com/myimage@sha256:...`. The `ImageContentSourcePolicy` resource is applied to all repositories from a source registry to a mirror registry `mirror.example.net/registry-example-com`.
149
+
150
+
. Create the new object:
109
151
+
110
152
[source,terminal]
111
153
----
112
154
$ oc create -f registryrepomirror.yaml
113
155
----
114
156
+
115
-
After the `ImageContentSourcePolicy`object is created, the new settings are deployed to each node and the cluster starts using the mirrored repository for requests to the source repository.
157
+
After the object is created, the Machine Config Operator (MCO) cordons the nodes as the new settings are deployed to each node. The MCO restarts the nodes for an `ImageTagMirrorSet` object only. The MCO does not restart the nodes for `ImageDigestMirrorSet` objects. When the nodes are uncordoned, the cluster starts using the mirrored repository for requests to the source repository.
116
158
117
-
. To check that the mirrored configuration settings, are applied, do the following on one of the nodes.
159
+
. To check that the mirrored configuration settings are applied, do the following on one of the nodes.
The `Imagecontentsourcepolicy` resource does not restart the nodes.
139
179
140
180
.. Start the debugging process to access the node:
141
181
+
@@ -166,6 +206,8 @@ the changes were made:
166
206
sh-4.2# cat /etc/containers/registries.conf
167
207
----
168
208
+
209
+
The following output represents a `registries.conf` file where an `ImageDigestMirrorSet` object and an `ImageTagMirrorSet` object were applied. The final two entries are marked `digest-only` and `tag-only` respectively.
<1> Indicates the repository that is referred to in a pull spec.
278
+
<2> Indicates the mirror for that repository.
279
+
<3> Indicates that the image pull from the mirror is a digest reference image.
280
+
<4> Indicates that the `NeverContactSource` parameter is set for this repository.
281
+
<5> Indicates that the image pull from the mirror is a tag reference image.
226
282
227
-
.. Pull an image digest to the node from the source and check if it is resolved by the mirror. `ImageContentSourcePolicy` objects support image digests only, not image tags.
283
+
.. Pull an image to the node from the source and check if it is resolved by the mirror.
228
284
+
229
285
[source,terminal]
230
286
----
@@ -239,3 +295,5 @@ If the repository mirroring procedure does not work as described, use the follow
239
295
* The main registry is only used if no other mirror works.
240
296
* From the system context, the `Insecure` flags are used as fallback.
241
297
* The format of the `/etc/containers/registries.conf` file has changed recently. It is now version 2 and in TOML format.
298
+
* You cannot add the same repository to both an `ImageDigestMirrorSet` and an `ImageTagMirrorSet` object.
Copy file name to clipboardExpand all lines: modules/troubleshooting-disabling-autoreboot-mco.adoc
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ The following modifications do not trigger a node reboot:
17
17
** Changes to the global pull secret or pull secret in the `openshift-config` namespace.
18
18
** Automatic rotation of the `/etc/kubernetes/kubelet-ca.crt` certificate authority (CA) by the Kubernetes API Server Operator.
19
19
20
-
* When the MCO detects changes to the `/etc/containers/registries.conf` file, such as adding or editing an `ImageContentSourcePolicy` object, it drains the corresponding nodes, applies the changes, and uncordons the nodes. The node drain does not happen when there is a mirror configuration change in the `ImageContentSourcePolicy` (ICSP) object such as a new mirror added to an existing registry or a new registry added that has the setting `mirror-by-digest-only=true`.
20
+
* When the MCO detects changes to the `/etc/containers/registries.conf` file, such as adding or editing an `ImageDigestMirrorSet` or `ImageTagMirrorSet` object, it drains the corresponding nodes, applies the changes, and uncordons the nodes. The node drain does not happen when there is a mirror configuration change in the object, such as adding a new mirror to an existing registry by using an `ImageDigestMirrorSet` object. The MCO does restart the nodes if you add a new mirror to an existing registry by uisng an`ImageTagMirrorSet` object.
21
21
====
22
22
23
23
To avoid unwanted disruptions, you can modify the machine config pool (MCP) to prevent automatic rebooting after the Operator makes changes to the machine config.
0 commit comments