Skip to content

Commit 1399be7

Browse files
mburke5678mburke5678
authored
Merge pull request #28268 from mburke5678/image-registry-reorg
Reorganize Image configuration resources topic
2 parents 56edc2c + e6a745f commit 1399be7

8 files changed

+302
-76
lines changed

‎modules/images-configuration-allowed.adoc‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * openshift_images/image-configuration.adoc
4+
// * post_installation_configuration/preparing-for-users.adoc
5+
6+
[id="images-configuration-allowed_{context}"]
7+
= Adding specific registries
8+
9+
You can add a list of registries that are permitted for image pull and push actions by 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+
11+
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+
13+
[WARNING]
14+
====
15+
When the `allowedRegistries` parameter is defined, all registries including the registry.redhat.io and quay.io registries are blocked unless explicitly listed. If you use the parameter, to prevent pod failure, add `registry.redhat.io` and `quay.io` to the `allowedRegistries` list, as they are required by payload images within your environment. For disconnected clusters, mirror registries should also be added.
16+
====
17+
18+
.Procedure
19+
20+
. Edit the `image.config.openshift.io/cluster` CR:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc edit image.config.openshift.io/cluster
25+
----
26+
+
27+
The following is an example `image.config.openshift.io/cluster` CR with an allowed list:
28+
+
29+
[source,yaml]
30+
----
31+
apiVersion: config.openshift.io/v1
32+
kind: Image
33+
metadata:
34+
annotations:
35+
release.openshift.io/create-only: "true"
36+
creationTimestamp: "2019-05-17T13:44:26Z"
37+
generation: 1
38+
name: cluster
39+
resourceVersion: "8302"
40+
selfLink: /apis/config.openshift.io/v1/images/cluster
41+
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
42+
spec:
43+
registrySources: <1>
44+
allowedRegistries: <2>
45+
- example.com
46+
- quay.io
47+
- registry.redhat.io
48+
status:
49+
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
50+
----
51+
<1> `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.
52+
<2> `allowedRegistries`: Registries to use for image pull and push actions. All other registries are blocked.
53+
+
54+
[NOTE]
55+
====
56+
Either the `allowedRegistries` parameter or the `blockedRegistries` parameter can be set, but not both.
57+
====
58+
+
59+
The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` CR for any changes to registries and reboots the nodes when it detects changes. Changes to the allowed registries creates or updates the image signature policy in the `/host/etc/containers/policy.json` file on each node.
60+
61+
. To check that the registries have been added to the policy file, use the following command on a node:
62+
+
63+
[source,terminal]
64+
----
65+
$ cat /host/etc/containers/policy.json
66+
----
67+
+
68+
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:
69+
+
70+
.Example image signature policy file
71+
[%collapsible]
72+
====
73+
[source,terminal]
74+
----
75+
{
76+
"default": [{
77+
"type": "reject"
78+
}],
79+
"transports": {
80+
"atomic": {
81+
"example.com": [{
82+
"type": "insecureAcceptAnything"
83+
}],
84+
"quay.io": [{
85+
"type": "insecureAcceptAnything"
86+
}],
87+
"registry.redhat.io": [{
88+
"type": "insecureAcceptAnything"
89+
}]
90+
},
91+
"docker": {
92+
"example.com": [{
93+
"type": "insecureAcceptAnything"
94+
}],
95+
"quay.io": [{
96+
"type": "insecureAcceptAnything"
97+
}],
98+
"registry.redhat.io": [{
99+
"type": "insecureAcceptAnything"
100+
}]
101+
},
102+
"docker-daemon": {
103+
"": [{
104+
"type": "insecureAcceptAnything"
105+
}]
106+
}
107+
}
108+
}
109+
----
110+
====
111+
112+
[NOTE]
113+
====
114+
If your cluster uses the `registrySources.insecureRegistries` parameter, ensure that any insecure registries are included in the allowed list.
115+
116+
For example:
117+
118+
[source,yml]
119+
----
120+
spec:
121+
registrySources:
122+
insecureRegistries:
123+
- insecure.com
124+
allowedRegistries:
125+
- example.com
126+
- quay.io
127+
- registry.redhat.io
128+
- insecure.com
129+
----
130+
====

‎modules/images-configuration-blocked.adoc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * openshift_images/image-configuration.adoc
4+
// * post_installation_configuration/preparing-for-users.adoc
5+
6+
[id="images-configuration-blocked_{context}"]
7+
= Blocking specific registries
8+
9+
You can block any 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+
11+
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.
12+
13+
.Procedure
14+
15+
. Edit the `image.config.openshift.io/cluster` CR:
16+
+
17+
[source,terminal]
18+
----
19+
$ oc edit image.config.openshift.io/cluster
20+
----
21+
+
22+
The following is an example `image.config.openshift.io/cluster` CR with a blocked list:
23+
+
24+
[source,yaml]
25+
----
26+
apiVersion: config.openshift.io/v1
27+
kind: Image
28+
metadata:
29+
annotations:
30+
release.openshift.io/create-only: "true"
31+
creationTimestamp: "2019-05-17T13:44:26Z"
32+
generation: 1
33+
name: cluster
34+
resourceVersion: "8302"
35+
selfLink: /apis/config.openshift.io/v1/images/cluster
36+
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
37+
spec:
38+
registrySources: <1>
39+
blockedRegistries: <2>
40+
- untrusted.com
41+
status:
42+
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
43+
----
44+
<1> `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.
45+
<2> Specify registries that should not be used for image pull and push actions. All other registries are allowed.
46+
+
47+
[NOTE]
48+
====
49+
Either the `blockedRegistries` registry or the `allowedRegistries` registry can be set, but not both.
50+
====
51+
+
52+
The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` CR for any changes to registries and reboots the nodes when it detects changes. Changes to the blocked registries appear in the `/etc/containers/registries.conf` file on each node.
53+
54+
. To check that the registries have been added to the policy file, use the following command on a node:
55+
+
56+
[source,terminal]
57+
----
58+
$ cat /host/etc/containers/registries.conf
59+
----
60+
+
61+
The following example indicates that images from the `untrusted.com` registry are prevented for image pulls and pushes:
62+
+
63+
.Example output
64+
[source,terminal]
65+
----
66+
unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
67+
68+
[[registry]]
69+
prefix = ""
70+
location = "untrusted.com"
71+
blocked = true
72+
----

‎modules/images-configuration-cas.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
[id="images-configuration-cas_{context}"]
88
= Configuring additional trust stores for image registry access
99

10-
The `image.config.openshift.io/cluster` resource can contain a reference
10+
The `image.config.openshift.io/cluster` custom resource can contain a reference
1111
to a ConfigMap that contains additional certificate authorities to be trusted
1212
during image registry access.
1313

@@ -17,7 +17,7 @@ during image registry access.
1717
.Procedure
1818

1919
You can create a ConfigMap in the `openshift-config` namespace and use its name
20-
in `AdditionalTrustedCA` in the `image.config.openshift.io` resource to provide
20+
in `AdditionalTrustedCA` in the `image.config.openshift.io` custom resource to provide
2121
additional CAs that should be trusted when contacting external registries.
2222

2323
The ConfigMap key is the host name of a registry with the port for which this CA is to be

‎modules/images-configuration-file.adoc‎

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,10 @@
77
= Configuring image settings
88

99
You can configure image registry settings by editing the
10-
`image.config.openshift.io/cluster` resource. The
10+
`image.config.openshift.io/cluster` custom resource (CR). The
1111
Machine Config Operator (MCO) watches the
12-
`image.config.openshift.io/cluster` resource for any changes to the registries.
13-
When the MCO detects a change, it drains the nodes, applies the change,
14-
and uncordons the nodes.
12+
`image.config.openshift.io/cluster` CR for any changes
13+
to the registries and reboots the nodes when it detects changes.
1514

1615
.Procedure
1716

@@ -22,12 +21,12 @@ and uncordons the nodes.
2221
$ oc edit image.config.openshift.io/cluster
2322
----
2423
+
25-
The following is an example `image.config.openshift.io/cluster` resource:
24+
The following is an example `image.config.openshift.io/cluster` CR:
2625
+
2726
[source,yaml]
2827
----
2928
apiVersion: config.openshift.io/v1
30-
kind: Image<1>
29+
kind: Image <1>
3130
metadata:
3231
annotations:
3332
release.openshift.io/create-only: "true"
@@ -38,16 +37,18 @@ metadata:
3837
selfLink: /apis/config.openshift.io/v1/images/cluster
3938
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
4039
spec:
41-
allowedRegistriesForImport:<2>
40+
allowedRegistriesForImport: <2>
4241
- domainName: quay.io
4342
insecure: false
44-
additionalTrustedCA:<3>
43+
additionalTrustedCA: <3>
4544
name: myconfigmap
4645
registrySources:<4>
47-
insecureRegistries:<5>
46+
allowedRegistries:
47+
- example.com
48+
- quay.io
49+
- registry.redhat.io
50+
insecureRegistries:
4851
- insecure.com
49-
blockedRegistries:<6>
50-
- untrusted.com
5152
status:
5253
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
5354
----
@@ -68,8 +69,25 @@ trust.
6869
<4> `registrySources`: Contains configuration that determines how the container
6970
runtime should treat individual registries when accessing images for builds and
7071
pods. For instance, whether or not to allow insecure access. It does not contain
71-
configuration for the internal cluster registry.
72-
<5> `insecureRegistries`: Registries which do not have a valid TLS certificate or
73-
only support HTTP connections.
74-
<6> `blockedRegistries`: Denylisted for image pull and push actions. All other
75-
registries are allowed.
72+
configuration for the internal cluster registry. This example lists `allowedRegistries`,
73+
which defines the registries that are allowed to be used. One of the registries listed
74+
is insecure.
75+
76+
. To check that the changes are applied, list your nodes:
77+
+
78+
[source,terminal]
79+
----
80+
$ oc get nodes
81+
----
82+
+
83+
.Example output
84+
[source,terminal]
85+
----
86+
NAME STATUS ROLES AGE VERSION
87+
ci-ln-j5cd0qt-f76d1-vfj5x-master-0 Ready master 98m v1.19.0+7070803
88+
ci-ln-j5cd0qt-f76d1-vfj5x-master-1 Ready,SchedulingDisabled master 99m v1.19.0+7070803
89+
ci-ln-j5cd0qt-f76d1-vfj5x-master-2 Ready master 98m v1.19.0+7070803
90+
ci-ln-j5cd0qt-f76d1-vfj5x-worker-b-nsnd4 Ready worker 90m v1.19.0+7070803
91+
ci-ln-j5cd0qt-f76d1-vfj5x-worker-c-5z2gz NotReady,SchedulingDisabled worker 90m v1.19.0+7070803
92+
ci-ln-j5cd0qt-f76d1-vfj5x-worker-d-stsjv Ready worker 90m v1.19.0+7070803
93+
----

0 commit comments

Comments
 (0)