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/images-configuration-allowed.adoc
+24-17Lines changed: 24 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,20 +5,23 @@
5
5
6
6
:_mod-docs-content-type: PROCEDURE
7
7
[id="images-configuration-allowed_{context}"]
8
-
= Adding specific registries
8
+
= Adding specific registries to an allowlist
9
9
10
-
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.
10
+
[role="_abstract"]
11
+
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
12
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.
13
+
{product-title} applies the changes to this CR to all nodes in the cluster.
13
14
15
+
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.
16
+
//false positive vale example block
14
17
[WARNING]
15
18
====
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.
19
+
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. To prevent pod failure when you use the parameter, add both the `registry.redhat.io` and `quay.io` registries and the `internalRegistryHostname` to the `allowedRegistries` list. Payload images within your environment require access to these registries. For disconnected clusters, you must also add mirror registries to the allowlist.
17
20
====
18
21
19
22
.Procedure
20
23
21
-
* Edit the `image.config.openshift.io/cluster` custom resource:
24
+
* 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.
55
-
<2> Specify registries, and optionally a repository in that registry, to use for image pull and push actions. All other registries are blocked.
57
+
+
58
+
where::
59
+
`registrySources:` 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.
60
+
`registrySources.allowedRegistries:` Specify registries, and optionally a repository in that registry, to use for image pull and push actions. All other registries are blocked.
56
61
+
57
62
[NOTE]
58
63
====
@@ -62,9 +67,7 @@ Either the `allowedRegistries` parameter or the `blockedRegistries` parameter ca
62
67
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
68
64
69
ifndef::openshift-rosa,openshift-dedicated[]
65
-
.Verification
66
-
67
-
* Enter the following command to obtain a list of your nodes:
70
+
. After you have made your configuration updates, list your nodes by running the following command:
. Run the following command to enter debug mode on the node:
85
+
. Enter debug mode on the node by running the following command:
83
86
+
84
-
[source,terminal]
87
+
[source,terminal,subs="+quotes"]
85
88
----
86
-
$ oc debug node/<node_name>
89
+
$ oc debug node/_<node_name>_
87
90
----
91
+
+
92
+
Replace _<node-name>_ with the name of your node.
88
93
89
94
. When prompted, enter `chroot /host` into the terminal:
90
95
+
@@ -93,14 +98,16 @@ $ oc debug node/<node_name>
93
98
sh-4.4# chroot /host
94
99
----
95
100
96
-
. Enter the following command to check that the registries have been added to the policy file:
101
+
.Verification
102
+
103
+
. Check that the registries are added to the policy file by running the following command:
97
104
+
98
105
[source,terminal]
99
106
----
100
107
sh-5.1# cat /etc/containers/policy.json | jq '.'
101
108
----
102
109
+
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:
110
+
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:
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.
Copy file name to clipboardExpand all lines: modules/images-configuration-blocked.adoc
+22-15Lines changed: 22 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,18 +7,21 @@
7
7
[id="images-configuration-blocked_{context}"]
8
8
= Blocking specific registries
9
9
10
-
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.
10
+
[role="_abstract"]
11
+
You can block any registry, or an individual repository, within a registry by editing the `image.config.openshift.io/cluster` custom resource (CR).
12
+
13
+
{product-title} applies the changes to this CR to all nodes in the cluster.
11
14
12
15
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
16
14
17
[WARNING]
15
18
====
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.
19
+
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
20
====
18
-
21
+
//how does this work for mirror registries?
19
22
.Procedure
20
23
21
-
* Edit the `image.config.openshift.io/cluster` custom resource:
24
+
* 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.
54
+
+
55
+
where::
56
+
`registrySources:` 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.
57
+
`registrySources.blockedRegistries:` 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
58
+
54
59
[NOTE]
55
60
====
56
-
Either the `blockedRegistries`registry or the `allowedRegistries`registry can be set, but not both.
61
+
You cannot set both the `blockedRegistries`and `allowedRegistries`parameters. You must choose one or the other.
57
62
====
58
63
+
59
64
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.
60
65
61
66
ifndef::openshift-rosa,openshift-dedicated[]
62
-
.Verification
63
-
64
-
* Enter the following command to obtain a list of your nodes:
67
+
. Get a list of your nodes by running the following command:
65
68
+
66
69
[source,terminal]
67
70
----
@@ -78,10 +81,12 @@ NAME STATUS ROLES AGE VERSION
78
81
79
82
. Run the following command to enter debug mode on the node:
80
83
+
81
-
[source,terminal]
84
+
[source,terminal,subs="quotes+"]
82
85
----
83
-
$ oc debug node/<node_name>
86
+
$ oc debug node/_<node_name>_
84
87
----
88
+
+
89
+
Replace _<node_name>_ with the name of the node you want details about.
85
90
86
91
. When prompted, enter `chroot /host` into the terminal:
87
92
+
@@ -90,7 +95,9 @@ $ oc debug node/<node_name>
90
95
sh-4.4# chroot /host
91
96
----
92
97
93
-
. Enter the following command to check that the registries have been added to the policy file:
98
+
.Verification
99
+
100
+
. Verify that the registries are added to the policy file by running the following command:
Copy file name to clipboardExpand all lines: modules/images-configuration-cas.adoc
+13-11Lines changed: 13 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,17 +7,17 @@
7
7
[id="images-configuration-cas_{context}"]
8
8
= Configuring additional trust stores for image registry access
9
9
10
-
The `image.config.openshift.io/cluster` custom resource can contain a reference to a config map that contains additional certificate authorities to be trusted during image registry access.
10
+
[role="_abstract"]
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).
11
12
12
13
.Prerequisites
13
-
* The certificate authorities (CA) must be PEM-encoded.
14
14
15
-
.Procedure
16
-
17
-
You can create a config map in the `openshift-config` namespace and use its name in `AdditionalTrustedCA` in the `image.config.openshift.io` custom resource to provide additional CAs that should be trusted when contacting external registries.
15
+
* The certificate authorities (CAs) must be PEM-encoded.
18
16
19
-
The config map key is the hostname of a registry with the port for which this CA is to be trusted, and the PEM certificate content is the value, for each additional registry CA to trust.
17
+
.Procedure
20
18
19
+
. Create a config map in the `openshift-config` namespace, then and use the config mao 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
+
+
21
21
.Image registry CA config map example
22
22
[source,yaml]
23
23
----
@@ -30,16 +30,18 @@ data:
30
30
-----BEGIN CERTIFICATE-----
31
31
...
32
32
-----END CERTIFICATE-----
33
-
registry-with-port.example.com..5000: | <1>
33
+
registry-with-port.example.com..5000: |
34
34
-----BEGIN CERTIFICATE-----
35
35
...
36
36
-----END CERTIFICATE-----
37
37
----
38
-
<1> If the registry has the port, such as `registry-with-port.example.com:5000`, `:` should be replaced with `..`.
39
-
40
-
You can configure additional CAs with the following procedure.
38
+
+
39
+
where::
40
+
`data:registry.example.com:` An example hostname of a registry for which this CA is to be trusted.
41
+
`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`, `:` should be replaced with `..`.
42
+
The PEM certificate content is the value for each additional registry CA to trust.
41
43
42
-
* To configure an additional CA:
44
+
. Optional. Configure an additional CA by running the following command:
0 commit comments