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 add a list of registries, and optionally an individual repository within a registry, that are permitted for image pull and push actions by editing the `image.config.openshift.io/cluster` custom resource (CR). {product-title} applies the changes to this CR to all nodes in the cluster.
9
+
[role="_abstract"]
10
+
You can add an allowlist of registries, or an individual repository, within a registry for image pull and push actions by editing the `image.config.openshift.io/cluster` custom resource (CR).
11
11
12
-
When pulling or pushing images, the container runtime searches the registries listed under the `registrySources` parameter in the `image.config.openshift.io/cluster` CR. If you created a list of registries under the `allowedRegistries` parameter, the container runtime searches only those registries. Registries not in the list are blocked.
12
+
{product-title} applies the changes to this CR to all nodes in the cluster.
13
13
14
-
[WARNING]
15
-
====
16
-
When the `allowedRegistries` parameter is defined, all registries, including the `registry.redhat.io` and `quay.io` registries and the default {product-registry}, are blocked unless explicitly listed. If you use the parameter, to prevent pod failure, add the `registry.redhat.io` and `quay.io` registries and the `internalRegistryHostname` to the `allowedRegistries` list, as they are required by payload images within your environment. For disconnected clusters, mirror registries should also be added.
17
-
====
14
+
When pulling or pushing images, the container runtime searches the registries listed under the `registrySources` parameter in the `image.config.openshift.io/cluster` CR. If you created a list of registries under the `allowedRegistries` parameter, the container runtime searches only those registries. Registries not in your allowlist are blocked.
<1> Contains configurations that determine how the container runtime should treat individual registries when accessing images for builds and pods. It does not contain configuration for the internal cluster registry.
55
-
<2> Specify registries, and optionally a repository in that registry, to use for image pull and push actions. All other registries are blocked.
56
-
+
57
-
[NOTE]
58
-
====
59
-
Either the `allowedRegistries` parameter or the `blockedRegistries` parameter can be set, but not both.
60
-
====
61
-
+
62
-
The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it triggers a rollout on nodes in machine config pool (MCP). The allowed registries list is used to update the image signature policy in the `/etc/containers/policy.json` file on each node. Changes to the `/etc/containers/policy.json` file do not require the node to drain.
63
54
64
55
ifndef::openshift-rosa,openshift-dedicated[]
65
-
.Verification
66
-
67
-
* Enter the following command to obtain a list of your nodes:
56
+
. After you make your configuration updates, list your nodes by running the following command:
. Run the following command to enter debug mode on the node:
71
+
. Enter debug mode on the node by running the following command:
83
72
+
84
73
[source,terminal]
85
74
----
86
75
$ oc debug node/<node_name>
87
76
----
77
+
+
78
+
Replace <node_name> with the name of your node.
88
79
89
80
. When prompted, enter `chroot /host` into the terminal:
90
81
+
@@ -93,18 +84,18 @@ $ oc debug node/<node_name>
93
84
sh-4.4# chroot /host
94
85
----
95
86
96
-
. Enter the following command to check that the registries have been added to the policy file:
87
+
.Verification
88
+
89
+
. Check that the registries are in the policy file by running the following command:
97
90
+
98
91
[source,terminal]
99
92
----
100
93
sh-5.1# cat /etc/containers/policy.json | jq '.'
101
94
----
102
95
+
103
-
The following policy indicates that only images from the example.com, quay.io, and registry.redhat.io registries are permitted for image pulls and pushes:
96
+
The following policy indicates that only images from the `example.com`, `quay.io`, and `registry.redhat.io` registries are accessible for image pulls and pushes:
104
97
+
105
98
.Example image signature policy file
106
-
[%collapsible]
107
-
====
108
99
[source,text]
109
100
----
110
101
{
@@ -188,9 +179,9 @@ The following policy indicates that only images from the example.com, quay.io, a
188
179
}
189
180
}
190
181
----
191
-
====
192
182
endif::openshift-rosa,openshift-dedicated[]
193
-
183
+
+
184
+
--
194
185
[NOTE]
195
186
====
196
187
If your cluster uses the `registrySources.insecureRegistries` parameter, ensure that any insecure registries are included in the allowed list.
In a mirroring configuration, you can block upstream payload registries in a disconnected environment using a `ImageContentSourcePolicy` (ICSP) object. The following example procedure demonstrates how to block the `quay.io/openshift-payload` payload registry.
9
+
[role="_abstract"]
10
+
In a mirroring configuration, you can block upstream payload registries in a disconnected environment by using a `ImageContentSourcePolicy` (ICSP) object.
11
+
//oc mirror v2 does not support ICSP; this content needs an update or a note
12
+
The following example procedure demonstrates how to block the `quay.io/openshift-payload` payload registry.
11
13
12
14
.Procedure
15
+
13
16
. Create the mirror configuration using an `ImageContentSourcePolicy` (ICSP) object to mirror the payload to a registry in your instance. The following example ICSP file mirrors the payload `internal-mirror.io/openshift-payload`:
14
17
+
15
18
[source,yaml]
@@ -24,7 +27,8 @@ spec:
24
27
- internal-mirror.io/openshift-payload
25
28
source: quay.io/openshift-payload
26
29
----
27
-
. After the object deploys onto your nodes, verify that the mirror configuration is set by checking the `/etc/containers/registries.conf` file:
30
+
31
+
. After the object deploys onto your nodes, verify that the mirror configuration is set by checking the `/etc/containers/registries.conf` custom resource (CR):
28
32
+
29
33
.Example output
30
34
[source,terminal]
@@ -37,13 +41,15 @@ spec:
37
41
[[registry.mirror]]
38
42
location = "internal-mirror.io/openshift-payload"
39
43
----
40
-
. Use the following command to edit the `image.config.openshift.io` custom resource file:
44
+
45
+
. Use the following command to edit the `image.config.openshift.io` CR:
41
46
+
42
47
[source,terminal]
43
48
----
44
49
$ oc edit image.config.openshift.io cluster
45
50
----
46
-
. To block the payload registry, add the following configuration to the `image.config.openshift.io` custom resource file:
51
+
52
+
. To block the payload registry, add the following configuration to the `image.config.openshift.io` CR:
47
53
+
48
54
[source,yaml]
49
55
----
@@ -54,9 +60,10 @@ spec:
54
60
----
55
61
56
62
.Verification
63
+
//can we run a command such as an oc debug or oc edit to look at this file?
57
64
* Verify that the upstream payload registry is blocked by checking the `/etc/containers/registries.conf` file on the node.
You can block any registry, and optionally an individual repository within a registry, by editing the `image.config.openshift.io/cluster` custom resource (CR). {product-title} applies the changes to this CR to all nodes in the cluster.
9
+
[role="_abstract"]
10
+
You can block any registry, or an individual repository, within a registry by editing the `image.config.openshift.io/cluster` custom resource (CR).
11
+
12
+
{product-title} applies the changes to this CR to all nodes in the cluster.
11
13
12
14
When pulling or pushing images, the container runtime searches the registries listed under the `registrySources` parameter in the `image.config.openshift.io/cluster` CR. If you created a list of registries under the `blockedRegistries` parameter, the container runtime does not search those registries. All other registries are allowed.
13
15
14
16
[WARNING]
15
17
====
16
-
To prevent pod failure, do not add the `registry.redhat.io` and `quay.io` registries to the `blockedRegistries` list, as they are required by payload images within your environment.
18
+
To prevent pod failure, do not add the `registry.redhat.io` and `quay.io` registries to the `blockedRegistries` list. Payload images within your environment require access to these registries.
17
19
====
18
-
20
+
//how does this work for mirror registries?
19
21
.Procedure
20
22
21
-
* Edit the `image.config.openshift.io/cluster` custom resource:
23
+
* Edit the `image.config.openshift.io/cluster` custom resource by running the following command:
<1> Contains configurations that determine how the container runtime should treat individual registries when accessing images for builds and pods. It does not contain configuration for the internal cluster registry.
52
-
<2> Specify registries, and optionally a repository in that registry, that should not be used for image pull and push actions. All other registries are allowed.
53
-
+
54
-
[NOTE]
55
-
====
56
-
Either the `blockedRegistries` registry or the `allowedRegistries` registry can be set, but not both.
57
-
====
58
53
+
59
-
The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it drains the nodes, applies the change, and uncordons the nodes. After the nodes return to the `Ready` state, changes to the blocked registries appear in the `/etc/containers/registries.conf` file on each node. During this period, you might experience service unavailability.
54
+
You cannot set both the `blockedRegistries`and `allowedRegistries` parameters. You must select one or the other.
60
55
61
56
ifndef::openshift-rosa,openshift-dedicated[]
62
-
.Verification
63
-
64
-
* Enter the following command to obtain a list of your nodes:
57
+
. Get a list of your nodes by running the following command:
65
58
+
66
59
[source,terminal]
67
60
----
@@ -82,6 +75,8 @@ NAME STATUS ROLES AGE VERSION
82
75
----
83
76
$ oc debug node/<node_name>
84
77
----
78
+
+
79
+
Replace <node_name> with the name of the node you want details about.
85
80
86
81
. When prompted, enter `chroot /host` into the terminal:
87
82
+
@@ -90,14 +85,16 @@ $ oc debug node/<node_name>
90
85
sh-4.4# chroot /host
91
86
----
92
87
93
-
. Enter the following command to check that the registries have been added to the policy file:
88
+
.Verification
89
+
90
+
. Verify that the registries are in the policy file by running the following command:
94
91
+
95
92
[source,terminal]
96
93
----
97
94
sh-5.1# cat etc/containers/registries.conf
98
95
----
99
96
+
100
-
The following example indicates that images from the `untrusted.com` registry are prevented for image pulls and pushes:
97
+
The following example indicates that images from the `untrusted.com` registry are blocked for image pulls and pushes:
Copy file name to clipboardExpand all lines: modules/images-configuration-cas.adoc
+9-5Lines changed: 9 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,16 +8,17 @@
8
8
= Configuring additional trust stores for image registry access
9
9
10
10
[role="_abstract"]
11
-
You can update an `image.config.openshift.io/cluster` custom resource (CR) to include a reference to a config map that includes additional certificate authorities (CAs). You must ensure that these CAs are trusted during image registry access. The config map key is the hostname of a registry with the port for which this CA is to be trusted. The Privacy-Enhanced Mail (PEM) certificate content is the value, for each additional registry CA to trust.
11
+
You can add references to a config map that has additional certificate authorities (CAs) to be trusted during image registry access to the `image.config.openshift.io/cluster` custom resource (CR).
12
12
13
13
.Prerequisites
14
14
15
-
* Ensure that a CA is PEM-encoded.
15
+
* The certificate authorities (CAs) must be PEM-encoded.
16
16
17
17
.Procedure
18
18
19
-
. Create a config map in the `openshift-config` namespace. The following example configurations show defined image registry CA that exists in a config map:
19
+
. Create a config map in the `openshift-config` namespace, then and use the config map name in the `AdditionalTrustedCA` parameter of the `image.config.openshift.io` CR. This adds CAs that should be trusted when the cluster contacts external image registries.
20
20
+
21
+
.Image registry CA config map example
21
22
[source,yaml]
22
23
----
23
24
apiVersion: v1
@@ -37,9 +38,12 @@ data:
37
38
+
38
39
where:
39
40
+
40
-
`registry-with-port.example.com..5000`:: If the registry has the port, `:` should be replaced with `..`.
41
+
`data:registry.example.com:`:: An example hostname of a registry for which this CA is to be trusted.
42
+
`data:registry-with-port.example.com..5000:`:: An example hostname of a registry with the port for which this CA is to be trusted. If the registry has a port, such as `registry-with-port.example.com:5000`, `:` must be replaced with `..`.
43
+
+
44
+
The PEM certificate content is the value for each additional registry CA to trust.
41
45
42
-
. Configure an additional CA. Ensure that you specify the name of the CA in the AdditionalTrustedCA` parameter of the `image.config.openshift.io` CR. You can then provide additional CAs that must be trusted when contacting external registries.
46
+
. Optional. Configure an additional CA by running the following command:
Copy file name to clipboardExpand all lines: modules/images-configuration-file.adoc
+12-24Lines changed: 12 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,21 +6,12 @@
6
6
[id="images-configuration-file_{context}"]
7
7
= Configuring image registry settings
8
8
9
+
[role="_abstract"]
9
10
You can configure image registry settings by editing the `image.config.openshift.io/cluster` custom resource (CR).
10
-
When changes to the registry are applied to the `image.config.openshift.io/cluster` CR, the Machine Config Operator (MCO) performs the following sequential actions:
11
-
12
-
. Cordons the node
13
-
. Applies changes by restarting CRI-O
14
-
. Uncordons the node
15
-
+
16
-
[NOTE]
17
-
====
18
-
The MCO does not restart nodes when it detects changes.
19
-
====
20
11
21
12
.Procedure
22
13
23
-
. Edit the `image.config.openshift.io/cluster`custom resource:
14
+
. Edit the `image.config.openshift.io/cluster`CR by running the following command:
24
15
+
25
16
[source,terminal]
26
17
----
@@ -32,7 +23,7 @@ The following is an example `image.config.openshift.io/cluster` CR:
<1> `Image`: Holds cluster-wide information about how to handle images. The canonical, and only valid name is `cluster`.
64
-
<2> `allowedRegistriesForImport`: Limits the container image registries from which normal users may import images. Set this list to the registries that you trust to contain valid images, and that you want applications to be able to import from. Users with permission to create images or `ImageStreamMappings` from the API are not affected by this policy. Typically only cluster administrators have the appropriate permissions.
65
-
<3> `additionalTrustedCA`: A reference to a config map containing additional certificate authorities (CA) that are trusted during image stream import, pod image pull, `openshift-image-registry` pullthrough, and builds. The namespace for this config map is `openshift-config`. The format of the config map is to use the registry hostname as the key, and the PEM certificate as the value, for each additional registry CA to trust.
66
-
<4> `registrySources`: Contains configuration that determines whether the container runtime allows or blocks individual registries when accessing images for builds and pods. Either the `allowedRegistries` parameter or the `blockedRegistries` parameter can be set, but not both. You can also define whether or not to allow access to insecure registries or registries that allow registries that use image short names. This example uses the `allowedRegistries` parameter, which defines the registries that are allowed to be used. The insecure registry `insecure.com` is also allowed. The `registrySources` parameter does not contain configuration for the internal cluster registry.
67
54
+
68
55
[NOTE]
69
56
====
70
-
When the `allowedRegistries` parameter is defined, all registries, including the registry.redhat.io and quay.io registries and the default {product-registry}, are blocked unless explicitly listed. If you use the parameter, to prevent pod failure, you must add the `registry.redhat.io` and `quay.io` registries and the `internalRegistryHostname` to the `allowedRegistries` list, as they are required by payload images within your environment. Do not add the `registry.redhat.io` and `quay.io` registries to the `blockedRegistries` list.
71
-
72
-
When using the `allowedRegistries`, `blockedRegistries`, or `insecureRegistries` parameter, you can specify an individual repository within a registry. For example: `reg1.io/myrepo/myapp:latest`.
57
+
When you use the `allowedRegistries`, `blockedRegistries`, or `insecureRegistries` parameter, you can specify an individual repository within a registry. For example: `reg1.io/myrepo/myapp:latest`.
73
58
74
-
Insecure external registries should be avoided to reduce possible security risks.
59
+
Avoid insecure external registries to reduce possible security risks.
75
60
====
61
+
//moved footnotes to reference table
62
+
63
+
.Verification
76
64
77
-
. To check that the changes are applied, list your nodes:
65
+
. To verify your changes, list your nodes by running the following command:
0 commit comments