diff --git a/modules/images-configuration-allowed.adoc b/modules/images-configuration-allowed.adoc new file mode 100644 index 000000000000..b32aa5b76650 --- /dev/null +++ b/modules/images-configuration-allowed.adoc @@ -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 +---- +==== diff --git a/modules/images-configuration-blocked.adoc b/modules/images-configuration-blocked.adoc new file mode 100644 index 000000000000..a4aa07bfab64 --- /dev/null +++ b/modules/images-configuration-blocked.adoc @@ -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 +---- diff --git a/modules/images-configuration-cas.adoc b/modules/images-configuration-cas.adoc index 8b6aace914d3..2f17244285f9 100644 --- a/modules/images-configuration-cas.adoc +++ b/modules/images-configuration-cas.adoc @@ -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 diff --git a/modules/images-configuration-file.adoc b/modules/images-configuration-file.adoc index 5778dd148a4b..ebc89dd022ce 100644 --- a/modules/images-configuration-file.adoc +++ b/modules/images-configuration-file.adoc @@ -7,7 +7,7 @@ = 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` for any changes to registries and reboots the nodes when it detects changes. @@ -21,12 +21,12 @@ and reboots the nodes when it detects changes. $ 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" @@ -37,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 ---- @@ -67,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 +---- diff --git a/modules/images-configuration-insecure.adoc b/modules/images-configuration-insecure.adoc index 16686aa38318..f9931c80bbed 100644 --- a/modules/images-configuration-insecure.adoc +++ b/modules/images-configuration-insecure.adoc @@ -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,43 +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. +<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. + -The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` -for any changes to registries and reboots the nodes when it detects changes. -Changes to the registries appear in the `/host/etc/containers/registries.conf` file on each node. +[NOTE] +==== +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 ---- + diff --git a/modules/images-configuration-parameters.adoc b/modules/images-configuration-parameters.adoc index 3efc21696d4a..028db8c8bb88 100644 --- a/modules/images-configuration-parameters.adoc +++ b/modules/images-configuration-parameters.adoc @@ -65,13 +65,13 @@ registries are allowed. `allowedRegistries`: Allowlisted for image pull and push actions. All other registries are blocked. -Only one of `blockedRegistries` or `allowedRegistries` may be set +Either `blockedRegistries` or `allowedRegistries` can be set, but not both. |=== [WARNING] ==== -When the `allowedRegistries` parameter is defined, all registries including `registry.redhat.io` and `quay.io` are blocked unless explicitly listed. If using the parameter, declare source registries `registry.redhat.io` and `quay.io` as required by payload images within your environment, to prevent Pod failure. For disconnected clusters, mirror registries should also be added. +When the `allowedRegistries` parameter is defined, all registries including `registry.redhat.io` and `quay.io` are blocked unless explicitly listed. If using the parameter, declare source registries `registry.redhat.io` and `quay.io` as required by payload images within your environment, to prevent pod failure. For disconnected clusters, mirror registries should also be added. ==== The `status` field of the `image.config.openshift.io/cluster` resource holds diff --git a/modules/images-configuration-registry-mirror.adoc b/modules/images-configuration-registry-mirror.adoc index c09856992b5a..71525b72271b 100644 --- a/modules/images-configuration-registry-mirror.adoc +++ b/modules/images-configuration-registry-mirror.adoc @@ -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.18.3 + 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. \ No newline at end of file +changed recently. It is now version 2 and in TOML format. diff --git a/openshift_images/image-configuration.adoc b/openshift_images/image-configuration.adoc index 4b8b02df4025..9a1130cbf2dd 100644 --- a/openshift_images/image-configuration.adoc +++ b/openshift_images/image-configuration.adoc @@ -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]