1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00

Reorganize Image configuration resources topic

This commit is contained in:
Michael Burke
2020-12-21 12:14:52 -05:00
committed by openshift-cherrypick-robot
parent 9c039df6d6
commit 3861dfa80a
8 changed files with 302 additions and 76 deletions

View File

@@ -0,0 +1,130 @@
// Module included in the following assemblies:
//
// * openshift_images/image-configuration.adoc
// * post_installation_configuration/preparing-for-users.adoc
[id="images-configuration-allowed_{context}"]
= Adding specific registries
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.
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.
[WARNING]
====
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.
====
.Procedure
. Edit the `image.config.openshift.io/cluster` CR:
+
[source,terminal]
----
$ oc edit image.config.openshift.io/cluster
----
+
The following is an example `image.config.openshift.io/cluster` CR with an allowed list:
+
[source,yaml]
----
apiVersion: config.openshift.io/v1
kind: Image
metadata:
annotations:
release.openshift.io/create-only: "true"
creationTimestamp: "2019-05-17T13:44:26Z"
generation: 1
name: cluster
resourceVersion: "8302"
selfLink: /apis/config.openshift.io/v1/images/cluster
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
spec:
registrySources: <1>
allowedRegistries: <2>
- example.com
- quay.io
- registry.redhat.io
status:
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
----
<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.
<2> `allowedRegistries`: Registries to use for image pull and push actions. All other registries are blocked.
+
[NOTE]
====
Either the `allowedRegistries` parameter or the `blockedRegistries` parameter can be set, but not both.
====
+
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.
. To check that the registries have been added to the policy file, use the following command on a node:
+
[source,terminal]
----
$ cat /host/etc/containers/policy.json
----
+
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:
+
.Example image signature policy file
[%collapsible]
====
[source,terminal]
----
{
"default": [{
"type": "reject"
}],
"transports": {
"atomic": {
"example.com": [{
"type": "insecureAcceptAnything"
}],
"quay.io": [{
"type": "insecureAcceptAnything"
}],
"registry.redhat.io": [{
"type": "insecureAcceptAnything"
}]
},
"docker": {
"example.com": [{
"type": "insecureAcceptAnything"
}],
"quay.io": [{
"type": "insecureAcceptAnything"
}],
"registry.redhat.io": [{
"type": "insecureAcceptAnything"
}]
},
"docker-daemon": {
"": [{
"type": "insecureAcceptAnything"
}]
}
}
}
----
====
[NOTE]
====
If your cluster uses the `registrySources.insecureRegistries` parameter, ensure that any insecure registries are included in the allowed list.
For example:
[source,yml]
----
spec:
registrySources:
insecureRegistries:
- insecure.com
allowedRegistries:
- example.com
- quay.io
- registry.redhat.io
- insecure.com
----
====

View File

@@ -0,0 +1,72 @@
// Module included in the following assemblies:
//
// * openshift_images/image-configuration.adoc
// * post_installation_configuration/preparing-for-users.adoc
[id="images-configuration-blocked_{context}"]
= Blocking specific registries
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.
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.
.Procedure
. Edit the `image.config.openshift.io/cluster` CR:
+
[source,terminal]
----
$ oc edit image.config.openshift.io/cluster
----
+
The following is an example `image.config.openshift.io/cluster` CR with a blocked list:
+
[source,yaml]
----
apiVersion: config.openshift.io/v1
kind: Image
metadata:
annotations:
release.openshift.io/create-only: "true"
creationTimestamp: "2019-05-17T13:44:26Z"
generation: 1
name: cluster
resourceVersion: "8302"
selfLink: /apis/config.openshift.io/v1/images/cluster
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
spec:
registrySources: <1>
blockedRegistries: <2>
- untrusted.com
status:
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
----
<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.
<2> Specify registries that should not be used for image pull and push actions. All other registries are allowed.
+
[NOTE]
====
Either the `blockedRegistries` registry or the `allowedRegistries` registry can be set, but not both.
====
+
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.
. To check that the registries have been added to the policy file, use the following command on a node:
+
[source,terminal]
----
$ cat /host/etc/containers/registries.conf
----
+
The following example indicates that images from the `untrusted.com` registry are prevented for image pulls and pushes:
+
.Example output
[source,terminal]
----
unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
[[registry]]
prefix = ""
location = "untrusted.com"
blocked = true
----

View File

@@ -7,7 +7,7 @@
[id="images-configuration-cas_{context}"]
= Configuring additional trust stores for image registry access
The `image.config.openshift.io/cluster` resource can contain a reference
The `image.config.openshift.io/cluster` custom resource can contain a reference
to a ConfigMap that contains additional certificate authorities to be trusted
during image registry access.
@@ -17,7 +17,7 @@ during image registry access.
.Procedure
You can create a ConfigMap in the `openshift-config` namespace and use its name
in `AdditionalTrustedCA` in the `image.config.openshift.io` resource to provide
in `AdditionalTrustedCA` in the `image.config.openshift.io` custom resource to provide
additional CAs that should be trusted when contacting external registries.
The ConfigMap key is the host name of a registry with the port for which this CA is to be

View File

@@ -7,11 +7,10 @@
= Configuring image settings
You can configure image registry settings by editing the
`image.config.openshift.io/cluster` resource. The
`image.config.openshift.io/cluster` custom resource (CR). 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.
`image.config.openshift.io/cluster` CR for any changes
to the registries and reboots the nodes when it detects changes.
.Procedure
@@ -22,12 +21,12 @@ and uncordons the nodes.
$ oc edit image.config.openshift.io/cluster
----
+
The following is an example `image.config.openshift.io/cluster` resource:
The following is an example `image.config.openshift.io/cluster` CR:
+
[source,yaml]
----
apiVersion: config.openshift.io/v1
kind: Image<1>
kind: Image <1>
metadata:
annotations:
release.openshift.io/create-only: "true"
@@ -38,16 +37,18 @@ metadata:
selfLink: /apis/config.openshift.io/v1/images/cluster
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
spec:
allowedRegistriesForImport:<2>
allowedRegistriesForImport: <2>
- domainName: quay.io
insecure: false
additionalTrustedCA:<3>
additionalTrustedCA: <3>
name: myconfigmap
registrySources:<4>
insecureRegistries:<5>
allowedRegistries:
- example.com
- quay.io
- registry.redhat.io
insecureRegistries:
- insecure.com
blockedRegistries:<6>
- untrusted.com
status:
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
----
@@ -68,8 +69,25 @@ trust.
<4> `registrySources`: Contains configuration that determines how the container
runtime should treat individual registries when accessing images for builds and
pods. For instance, whether or not to allow insecure access. It does not contain
configuration for the internal cluster registry.
<5> `insecureRegistries`: Registries which do not have a valid TLS certificate or
only support HTTP connections.
<6> `blockedRegistries`: Denylisted for image pull and push actions. All other
registries are allowed.
configuration for the internal cluster registry. This example lists `allowedRegistries`,
which defines the registries that are allowed to be used. One of the registries listed
is insecure.
. To check that the changes are applied, list your nodes:
+
[source,terminal]
----
$ oc get nodes
----
+
.Example output
[source,terminal]
----
NAME STATUS ROLES AGE VERSION
ci-ln-j5cd0qt-f76d1-vfj5x-master-0 Ready master 98m v1.19.0+7070803
ci-ln-j5cd0qt-f76d1-vfj5x-master-1 Ready,SchedulingDisabled master 99m v1.19.0+7070803
ci-ln-j5cd0qt-f76d1-vfj5x-master-2 Ready master 98m v1.19.0+7070803
ci-ln-j5cd0qt-f76d1-vfj5x-worker-b-nsnd4 Ready worker 90m v1.19.0+7070803
ci-ln-j5cd0qt-f76d1-vfj5x-worker-c-5z2gz NotReady,SchedulingDisabled worker 90m v1.19.0+7070803
ci-ln-j5cd0qt-f76d1-vfj5x-worker-d-stsjv Ready worker 90m v1.19.0+7070803
----

View File

@@ -4,24 +4,27 @@
// * post_installation_configuration/preparing-for-users.adoc
[id="images-configuration-insecure_{context}"]
= Importing insecure registries and blocking registries
= Allowing insecure registries
You can add insecure registries or block any registry by editing the `image.config.openshift.io/cluster` custom resource (CR).
You can add insecure registries 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.
Insecure external registries, such as those do not have a valid TLS certificate or
only support HTTP connections, should be avoided.
Registries that do not use valid SSL certificates or do not require HTTPS connections are considered insecure.
[WARNING]
====
Insecure external registries should be avoided to reduce possible security risks.
====
.Procedure
. Edit the `image.config.openshift.io/cluster` custom resource:
. Edit the `image.config.openshift.io/cluster` CR:
+
[source,terminal]
----
$ oc edit image.config.openshift.io/cluster
----
+
The following is an example `image.config.openshift.io/cluster` resource:
The following is an example `image.config.openshift.io/cluster` CR with an insecure registries list:
+
[source,yaml]
----
@@ -37,47 +40,45 @@ metadata:
selfLink: /apis/config.openshift.io/v1/images/cluster
uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
spec:
allowedRegistriesForImport:
- domainName: quay.io
insecure: false
additionalTrustedCA:
name: myconfigmap
registrySources:
insecureRegistries:<1>
registrySources: <1>
insecureRegistries: <2>
- insecure.com
blockedRegistries:<2>
- untrusted.com
allowedRegistries:
- quay.io <3>
- example.com
- quay.io
- registry.redhat.io
- insecure.com <3>
status:
internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
----
<1> Specify an insecure registry.
<2> Specify registries that should be denylisted for image pull and push actions. All other
registries are allowed. Either `blockedRegistries` or `allowedRegistries` can be set, but not both.
<3> Specify registries that should be permitted for image pull and push actions. All other registries are denied. Either `blockedRegistries` or `allowedRegistries` can be set, but not both.
+
The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource
for any changes to registries. When the MCO detects a change, it drains the nodes, applies the change, reloads the `crio` systemd service on the host, and uncordons the nodes. Changes to the registries appear in the `/etc/containers/registries.conf` file on each node.
<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.
<2> Specify an insecure registry.
<3> Ensure that any insecure registries are included in the `allowedRegistries` list.
+
[NOTE]
====
As of {product-title} 4.7, changes to the registries no longer trigger a reboot.
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.
====
+
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 insecure and blocked registries appear in the `/etc/containers/registries.conf` file on each node.
. To check that the registries have been added to the policy file, use the following command on a node:
+
[source,terminal]
----
$ cat /host/etc/containers/registries.conf
----
+
The following example indicates that images from the `insecure.com` registry is insecure and is allowed for image pulls and pushes.
+
.Example output
[source,terminal]
----
[registries]
[registries.search]
registries = ["registry.access.redhat.com", "docker.io"]
[registries.insecure]
registries = ["insecure.com"]
[registries.block]
registries = ["untrusted.com"]
unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
[[registry]]
prefix = ""
location = "insecure.com"
insecure = true
----

View File

@@ -65,7 +65,7 @@ registries are allowed.
`allowedRegistries`: Allowlisted for image pull and push actions. All other
registries are blocked.
Only one of `blockedRegistries` or `allowedRegistries` can be set.
Either `blockedRegistries` or `allowedRegistries` can be set, but not both.
|===

View File

@@ -5,19 +5,19 @@
[id="images-configuration-registry-mirror_{context}"]
= Configuring image registry repository mirroring
Setting up container registry repository mirroring lets you:
Setting up container registry repository mirroring enables you to:
* Configure your {product-title} cluster to redirect requests
* 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.
* Identify multiple mirrored repositories for each target
it resolved by a repository on a mirrored image registry
* identify multiple mirrored repositories for each target
repository, to make sure that if one mirror is down, another
can be used.
can be used
Here are some of the attributes of repository mirroring in {product-title}:
The attributes of repository mirroring in {product-title} include:
* Image pulls are resilient to registry downtimes
* Clusters in restricted networks can request to pull
* Image pulls are resilient to registry downtimes.
* Clusters in restricted networks can pull
images from critical locations (such as quay.io)
and have registries behind a company firewall
provide the requested images.
@@ -33,19 +33,19 @@ image is pulled to the node.
Setting up repository mirroring can be done in the following ways:
* At {product-title} installation time: By pulling container images needed
* At {product-title} installation: By pulling container images needed
by {product-title} and then bringing those images behind your company's
firewall, you can install {product-title} into a
datacenter that is in a restricted network. See
Mirroring the {product-title} image repository for details.
* After {product-title} installation time: Even if you don't configure mirroring during {product-title}
* After {product-title} installation: Even if you don't configure mirroring during {product-title}
installation, you can do so later using the `ImageContentSourcePolicy` object.
The following procedure provides a post-installation mirror configuration, where you create an `ImageContentSourcePolicy` object that identifies:
* The source of the container image repository you want to mirror
* A separate entry for each mirror repository you want to offer the content
* the source of the container image repository you want to mirror
* a separate entry for each mirror repository you want to offer the content
requested from the source repository.
.Prerequisites
@@ -54,13 +54,13 @@ requested from the source repository.
.Procedure
. Configure mirrored repositories. To do that, you can either:
. Configure mirrored repositories, by either:
+
* Set up a mirrored repository with Red Hat Quay, as
* 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.
* Use a tool such as `skopeo` to copy images manually
* Using a tool such as `skopeo` to copy images manually
from the source directory to the mirrored repository.
+
For example, after installing the skopeo RPM package
@@ -86,7 +86,7 @@ mirrored repository.
. Create an `ImageContentSourcePolicy` file (for example,
`registryrepomirror.yaml`), replacing the source and
mirrors with those of your own registry and repository pairs and images:
mirrors with your own registry and repository pairs and images:
+
[source,yaml]
@@ -98,8 +98,8 @@ metadata:
spec:
repositoryDigestMirrors:
- mirrors:
- example.io/example/ubi-minimal<1>
source: registry.access.redhat.com/ubi8/ubi-minimal<2>
- example.io/example/ubi-minimal <1>
source: registry.access.redhat.com/ubi8/ubi-minimal <2>
- mirrors:
- example.com/example/ubi-minimal
source: registry.access.redhat.com/ubi8/ubi-minimal
@@ -115,12 +115,13 @@ $ oc create -f registryrepomirror.yaml
----
+
After the `ImageContentSourcePolicy` object is created,
the new settings are deployed to each node
and shortly start using the mirrored repository
the new settings are deployed to each node and
the cluster starts using the mirrored repository
for requests to the source repository.
. To check that the mirrored configuration worked,
go to one of your nodes. For example:
. To check that the mirrored configuration settings,
are applied, do the following on one of the nodes.
.. List your nodes:
+
[source,terminal]
@@ -142,7 +143,7 @@ ip-10-0-154-10.ec2.internal Ready master 11m v1.19.0
+
You can see that scheduling on each worker node is disabled as the change is being applied.
.. Start the debugging process:
.. Start the debugging process to access the node:
+
[source,terminal]
----
@@ -191,7 +192,7 @@ unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
insecure = false
----
.. Pull an image digest to the node from the source and check if it is actually
.. 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.
+
[source,terminal]
@@ -209,4 +210,4 @@ troubleshoot the problem.
* The main registry will only be used if no other mirror works.
* From the system context, the `Insecure` flags are used as fallback.
* The format of the `/etc/containers/registries` file has
changed recently. It is now version 2 and in TOML format.
changed recently. It is now version 2 and in TOML format.

View File

@@ -10,8 +10,12 @@ include::modules/images-configuration-parameters.adoc[leveloffset=+1]
include::modules/images-configuration-file.adoc[leveloffset=+1]
include::modules/images-configuration-cas.adoc[leveloffset=+2]
include::modules/images-configuration-allowed.adoc[leveloffset=+2]
include::modules/images-configuration-blocked.adoc[leveloffset=+2]
include::modules/images-configuration-insecure.adoc[leveloffset=+2]
include::modules/images-configuration-cas.adoc[leveloffset=+2]
include::modules/images-configuration-registry-mirror.adoc[leveloffset=+2]