diff --git a/_attributes/attributes-openshift-dedicated.adoc b/_attributes/attributes-openshift-dedicated.adoc index 8f3844e3085a..38f4328611d8 100644 --- a/_attributes/attributes-openshift-dedicated.adoc +++ b/_attributes/attributes-openshift-dedicated.adoc @@ -7,6 +7,8 @@ :OCP: OpenShift Container Platform :OCP-short: OpenShift :ocp-version: 4.19 +:op-system-base: RHEL +:op-system-base-full: Red{nbsp}Hat Enterprise Linux (RHEL) :op-system-first: Red Hat Enterprise Linux CoreOS (RHCOS) :oc-first: pass:quotes[OpenShift CLI (`oc`)] :cluster-manager-first: Red Hat OpenShift Cluster Manager diff --git a/modules/images-configuration-allowed.adoc b/modules/images-configuration-allowed.adoc index 59ad9b8dba2c..c742593adc13 100644 --- a/modules/images-configuration-allowed.adoc +++ b/modules/images-configuration-allowed.adoc @@ -5,20 +5,23 @@ :_mod-docs-content-type: PROCEDURE [id="images-configuration-allowed_{context}"] -= Adding specific registries += Adding specific registries to an allowlist -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. +[role="_abstract"] +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). -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. +{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 your allowlist are blocked. +//false positive vale example block [WARNING] ==== -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. +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. ==== .Procedure -* Edit the `image.config.openshift.io/cluster` custom resource: +* Edit the `image.config.openshift.io/cluster` custom resource by running the following command: + [source,terminal] ---- @@ -41,8 +44,8 @@ metadata: selfLink: /apis/config.openshift.io/v1/images/cluster uid: e34555da-78a9-11e9-b92b-06d6c7da38dc spec: - registrySources: <1> - allowedRegistries: <2> + registrySources: + allowedRegistries: - example.com - quay.io - registry.redhat.io @@ -51,8 +54,10 @@ spec: status: internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ---- -<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. -<2> Specify registries, and optionally a repository in that registry, to use for image pull and push actions. All other registries are blocked. ++ +where:: +`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. +`registrySources.allowedRegistries:` Specify registries, and optionally a repository in that registry, to use for image pull and push actions. All other registries are blocked. + [NOTE] ==== @@ -62,9 +67,7 @@ Either the `allowedRegistries` parameter or the `blockedRegistries` parameter ca 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. ifndef::openshift-rosa,openshift-dedicated[] -.Verification - -* Enter the following command to obtain a list of your nodes: +. After you have made your configuration updates, list your nodes by running the following command: + [source,terminal] ---- @@ -79,12 +82,14 @@ NAME STATUS ROLES AGE VERSION Ready control-plane,master 37m v1.27.8+4fab27b ---- -. Run the following command to enter debug mode on the node: +. Enter debug mode on the node by running the following command: + -[source,terminal] +[source,terminal,subs="+quotes"] ---- -$ oc debug node/ +$ oc debug node/__ ---- ++ +Replace __ with the name of your node. . When prompted, enter `chroot /host` into the terminal: + @@ -93,14 +98,16 @@ $ oc debug node/ sh-4.4# chroot /host ---- -. Enter the following command to check that the registries have been added to the policy file: +.Verification + +. Check that the registries are added to the policy file by running the following command: + [source,terminal] ---- sh-5.1# cat /etc/containers/policy.json | jq '.' ---- + -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: +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: + .Example image signature policy file [%collapsible] diff --git a/modules/images-configuration-blocked-payload.adoc b/modules/images-configuration-blocked-payload.adoc index 072bdc8757ef..6d7841efbf7a 100644 --- a/modules/images-configuration-blocked-payload.adoc +++ b/modules/images-configuration-blocked-payload.adoc @@ -3,13 +3,16 @@ // * openshift_images/image-configuration.adoc :_mod-docs-content-type: PROCEDURE -[id="images-configuration-blocked-payload"] - +[id="images-configuration-blocked-payload_{context}"] = Blocking a payload registry -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. +[role="_abstract"] +In a mirroring configuration, you can block upstream payload registries in a disconnected environment by using a `ImageContentSourcePolicy` (ICSP) object. +//oc mirror v2 does not support ICSP; this content needs an update or a note +The following example procedure demonstrates how to block the `quay.io/openshift-payload` payload registry. .Procedure + . 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`: + [source,yaml] @@ -24,7 +27,8 @@ spec: - internal-mirror.io/openshift-payload source: quay.io/openshift-payload ---- -. After the object deploys onto your nodes, verify that the mirror configuration is set by checking the `/etc/containers/registries.conf` file: + +. After the object deploys onto your nodes, verify that the mirror configuration is set by checking the `/etc/containers/registries.conf` custom resource (CR): + .Example output [source,terminal] @@ -37,13 +41,15 @@ spec: [[registry.mirror]] location = "internal-mirror.io/openshift-payload" ---- -. Use the following command to edit the `image.config.openshift.io` custom resource file: + +. Use the following command to edit the `image.config.openshift.io` CR: + [source,terminal] ---- $ oc edit image.config.openshift.io cluster ---- -. To block the payload registry, add the following configuration to the `image.config.openshift.io` custom resource file: + +. To block the payload registry, add the following configuration to the `image.config.openshift.io` CR: + [source,yaml] ---- @@ -54,9 +60,10 @@ spec: ---- .Verification +//can we run a command such as an oc debug or oc edit to look at this file? * Verify that the upstream payload registry is blocked by checking the `/etc/containers/registries.conf` file on the node. + -.Example output +.Example `/etc/containers/registries.conf` file [source,terminal] ---- [[registry]] diff --git a/modules/images-configuration-blocked.adoc b/modules/images-configuration-blocked.adoc index 0bc620cc18cb..e23619dc352a 100644 --- a/modules/images-configuration-blocked.adoc +++ b/modules/images-configuration-blocked.adoc @@ -7,18 +7,21 @@ [id="images-configuration-blocked_{context}"] = Blocking specific registries -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. +[role="_abstract"] +You can block any registry, or 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. 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. [WARNING] ==== -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. +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. ==== - +//how does this work for mirror registries? .Procedure -* Edit the `image.config.openshift.io/cluster` custom resource: +* Edit the `image.config.openshift.io/cluster` custom resource by running the following command: + [source,terminal] ---- @@ -41,27 +44,27 @@ metadata: selfLink: /apis/config.openshift.io/v1/images/cluster uid: e34555da-78a9-11e9-b92b-06d6c7da38dc spec: - registrySources: <1> - blockedRegistries: <2> + registrySources: + blockedRegistries: - untrusted.com - reg1.io/myrepo/myapp:latest status: internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ---- -<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. -<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. ++ +where:: +`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. +`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. + [NOTE] ==== -Either the `blockedRegistries` registry or the `allowedRegistries` registry can be set, but not both. +You cannot set both the `blockedRegistries` and `allowedRegistries` parameters. You must choose one or the other. ==== + 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. ifndef::openshift-rosa,openshift-dedicated[] -.Verification - -* Enter the following command to obtain a list of your nodes: +. Get a list of your nodes by running the following command: + [source,terminal] ---- @@ -78,10 +81,12 @@ NAME STATUS ROLES AGE VERSION . Run the following command to enter debug mode on the node: + -[source,terminal] +[source,terminal,subs="quotes+"] ---- -$ oc debug node/ +$ oc debug node/__ ---- ++ +Replace __ with the name of the node you want details about. . When prompted, enter `chroot /host` into the terminal: + @@ -90,7 +95,9 @@ $ oc debug node/ sh-4.4# chroot /host ---- -. Enter the following command to check that the registries have been added to the policy file: +.Verification + +. Verify that the registries are added to the policy file by running the following command: + [source,terminal] ---- diff --git a/modules/images-configuration-cas.adoc b/modules/images-configuration-cas.adoc index 25067e2bdf36..77d92c77ee2e 100644 --- a/modules/images-configuration-cas.adoc +++ b/modules/images-configuration-cas.adoc @@ -7,17 +7,17 @@ [id="images-configuration-cas_{context}"] = Configuring additional trust stores for image registry access -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. +[role="_abstract"] +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). .Prerequisites -* The certificate authorities (CA) must be PEM-encoded. -.Procedure - -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. +* The certificate authorities (CAs) must be PEM-encoded. -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. +.Procedure +. 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. ++ .Image registry CA config map example [source,yaml] ---- @@ -30,16 +30,18 @@ data: -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- - registry-with-port.example.com..5000: | <1> + registry-with-port.example.com..5000: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- ---- -<1> If the registry has the port, such as `registry-with-port.example.com:5000`, `:` should be replaced with `..`. - -You can configure additional CAs with the following procedure. ++ +where:: +`data:registry.example.com:` An example hostname of a registry for which this CA is to be trusted. +`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 `..`. +The PEM certificate content is the value for each additional registry CA to trust. -* To configure an additional CA: +. Optional. Configure an additional CA by running the following command: + [source,terminal] ---- diff --git a/modules/images-configuration-file.adoc b/modules/images-configuration-file.adoc index 689997217ecd..4f8e182e3749 100644 --- a/modules/images-configuration-file.adoc +++ b/modules/images-configuration-file.adoc @@ -6,7 +6,9 @@ [id="images-configuration-file_{context}"] = Configuring image registry settings +[role="_abstract"] You can configure image registry settings by editing the `image.config.openshift.io/cluster` custom resource (CR). + 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: . Cordons the node @@ -20,7 +22,7 @@ The MCO does not restart nodes when it detects changes. .Procedure -. Edit the `image.config.openshift.io/cluster` custom resource: +. Edit the `image.config.openshift.io/cluster` CR by running the following command: + [source,terminal] ---- @@ -32,7 +34,7 @@ The following is an example `image.config.openshift.io/cluster` CR: [source,yaml] ---- apiVersion: config.openshift.io/v1 -kind: Image <1> +kind: Image metadata: annotations: release.openshift.io/create-only: "true" @@ -43,12 +45,12 @@ metadata: selfLink: /apis/config.openshift.io/v1/images/cluster uid: e34555da-78a9-11e9-b92b-06d6c7da38dc spec: - allowedRegistriesForImport: <2> + allowedRegistriesForImport: - domainName: quay.io insecure: false - additionalTrustedCA: <3> + additionalTrustedCA: name: myconfigmap - registrySources: <4> + registrySources: allowedRegistries: - example.com - quay.io @@ -60,21 +62,25 @@ spec: status: internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ---- -<1> `Image`: Holds cluster-wide information about how to handle images. The canonical, and only valid name is `cluster`. -<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. -<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. -<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. ++ +Details about parameters are as follows: ++ +* `Image`: Holds cluster-wide information about how to handle images. The canonical, and only valid name is `cluster`. +* `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. +* `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. +* `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. +* `registrySources.allowedRegistries`: When this 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. + [NOTE] ==== -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. +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`. -When using the `allowedRegistries`, `blockedRegistries`, or `insecureRegistries` parameter, you can specify an individual repository within a registry. For example: `reg1.io/myrepo/myapp:latest`. - -Insecure external registries should be avoided to reduce possible security risks. +Avoid insecure external registries to reduce possible security risks. ==== -. To check that the changes are applied, list your nodes: +.Verification + +. To verify your changes, list your nodes by running the following command: + [source,terminal] ---- diff --git a/modules/images-configuration-insecure.adoc b/modules/images-configuration-insecure.adoc index 1c63da8328c4..a7db6215b7a3 100644 --- a/modules/images-configuration-insecure.adoc +++ b/modules/images-configuration-insecure.adoc @@ -7,18 +7,19 @@ [id="images-configuration-insecure_{context}"] = Allowing insecure registries -You can add insecure registries, 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. +[role="_abstract"] +You can add insecure registries, or an individual repository, within a registry by editing the `image.config.openshift.io/cluster` custom resource (CR). -Registries that do not use valid SSL certificates or do not require HTTPS connections are considered insecure. +{product-title} applies the changes to this CR to all nodes in the cluster. 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. +Avoid insecure external registries to reduce possible security risks. ==== .Procedure -* Edit the `image.config.openshift.io/cluster` custom resource: +* Edit the `image.config.openshift.io/cluster` custom resource (CR) by running the following command: + [source,terminal] ---- @@ -41,23 +42,25 @@ metadata: selfLink: /apis/config.openshift.io/v1/images/cluster uid: e34555da-78a9-11e9-b92b-06d6c7da38dc spec: - registrySources: <1> - insecureRegistries: <2> + registrySources: + insecureRegistries: - insecure.com - reg4.io/myrepo/myapp:latest allowedRegistries: - example.com - quay.io - registry.redhat.io - - insecure.com <3> + - insecure.com - reg4.io/myrepo/myapp:latest - image-registry.openshift-image-registry.svc:5000 status: internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ---- -<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. -<2> Specify an insecure registry. You can specify a repository in that registry. -<3> Ensure that any insecure registries are included in the `allowedRegistries` list. ++ +where:: +`spec.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. +`spec.registrySources.insecureRegistries:` Specify an insecure registry. You can specify a repository in that registry. +`spec.registrySources.allowedRegistries:insecure.com` Ensure that any insecure registries are included in the `allowedRegistries` list. + [NOTE] ==== @@ -69,14 +72,14 @@ The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster ifndef::openshift-rosa,openshift-dedicated[] .Verification -* To check that the registries have been added to the policy file, use the following command on a node: +* Check that the registries are added to the policy file by running the following command on a node: + [source,terminal] ---- $ cat /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. +The following example indicates that images from the `insecure.com` registry is insecure and are allowed for image pulls and pushes. + .Example output [source,terminal] diff --git a/modules/images-configuration-parameters.adoc b/modules/images-configuration-parameters.adoc index aecabc622848..23ff5dee5bfa 100644 --- a/modules/images-configuration-parameters.adoc +++ b/modules/images-configuration-parameters.adoc @@ -6,13 +6,21 @@ [id="images-configuration-parameters_{context}"] = Image controller configuration parameters -The `image.config.openshift.io/cluster` resource holds cluster-wide information about how to handle images. The canonical, and only valid name is `cluster`. Its `spec` offers the following configuration parameters. +[role="_abstract"] +You can configure certain parameters that handle images cluster-wide in the `spec` of the `image.config.openshift.io/cluster` resource. The canonical, and only valid name is `cluster`. [NOTE] ==== -Parameters such as `DisableScheduledImport`, `MaxImagesBulkImportedPerRepository`, `MaxScheduledImportsPerMinute`, `ScheduledImageImportMinimumIntervalSeconds`, `InternalRegistryHostname` are not configurable. +The following non-configurable parameters are not listed in the table: + +* `DisableScheduledImport` +* `MaxImagesBulkImportedPerRepository` +* `MaxScheduledImportsPerMinute` +* `ScheduledImageImportMinimumIntervalSeconds` +* `InternalRegistryHostname` ==== +.Image controller configuration parameters [cols="3a,8a",options="header"] |=== |Parameter |Description @@ -35,10 +43,9 @@ The namespace for this config map is `openshift-config`. The format of the confi |Provides the hostnames for the default external image registry. The external hostname should be set only when the image registry is exposed externally. The first value is used in `publicDockerImageRepository` field in image streams. The value must be in `hostname[:port]` format. |`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. +|Contains configuration that determines how the container runtime should treat individual registries when accessing images for builds and pods. For example, whether or not to allow insecure access. It does not contain configuration for the internal cluster registry. -`insecureRegistries`: Registries which do not have a valid TLS certificate or only support HTTP connections. To specify all subdomains, add the asterisk (`\*`) wildcard character as a prefix to the domain name. For example, `*.example.com`. You can specify an individual repository within a registry. For example: `reg1.io/myrepo/myapp:latest`. +`insecureRegistries`: Registries that do not have a valid TLS certificate or only support HTTP connections. To specify all subdomains, add the asterisk (`\*`) wildcard character as a prefix to the domain name. For example, `*.example.com`. You can specify an individual repository within a registry. For example: `reg1.io/myrepo/myapp:latest`. `blockedRegistries`: Registries for which image pull and push actions are denied. To specify all subdomains, add the asterisk (`\*`) wildcard character as a prefix to the domain name. For example, `*.example.com`. You can specify an individual repository within a registry. For example: `reg1.io/myrepo/myapp:latest`. All other registries are allowed. @@ -52,20 +59,20 @@ ifndef::openshift-rosa,openshift-dedicated[] |`imageStreamImportMode` |Controls the import mode behavior of image streams. -You must enable the `TechPreviewNoUpgrade` feature set in the `FeatureGate` custom resource (CR) to enable the `imageStreamImportMode` feature. +You must enable the `TechPreviewNoUpgrade` feature set in the `FeatureGate` custom resource (CR) to enable the `imageStreamImportMode` feature. For more information about feature gates, see "Understanding feature gates". You can set the `imageStreamImportMode` field to either of the following values: -* `Legacy`: Indicates that the legacy behavior must be used. The legacy behavior discards the manifest list and imports a single sub-manifest. In this case, the platform is chosen in the following order of priority: +* `Legacy`: Indicates that the legacy behavior must be used. The legacy behavior discards the manifest list and imports a single sub-manifest. In this case, the platform is chosen in the following order of priority: . Tag annotations: Determining the platform by using the platform-specific annotations in the image tags. . Control plane architecture or the operating system: Selecting the platform based on the architecture or the operating system of the control plane. -. `linux/amd64`: If no platform is selected by the preceeding methods, the `linux/amd64` platform is selected. +. `linux/amd64`: If no platform is selected by the preceeding methods, the `linux/amd64` platform is selected. . The first manifest in the list is selected. -* `PreserveOriginal`: Indicates that the original manifest is preserved. The manifest list and its sub-manifests are imported. +* `PreserveOriginal`: Indicates that the original manifest is preserved. The manifest list and its sub-manifests are imported. -If you specify a value for this field, the value is applied to the newly created image stream tags that do not already have this value manually set. +If you specify a value for this field, the value is applied to the newly created image stream tags that do not already have this value manually set. If you do not configure this field, the behavior is decided based on the payload type advertised by the `ClusterVersion` status. In this case, the platform is chosen as follows: @@ -76,6 +83,7 @@ For information about importing manifest lists, see "Working with manifest lists :FeatureName: `imageStreamImportMode` include::snippets/technology-preview.adoc[] + endif::openshift-rosa,openshift-dedicated[] |=== @@ -86,6 +94,7 @@ When the `allowedRegistries` parameter is defined, all registries, including `re The `status` field of the `image.config.openshift.io/cluster` resource holds observed values from the cluster. +.Image controller status field parameters [cols="3a,8a",options="header"] |=== |Parameter |Description diff --git a/modules/images-configuration-registry-mirror-configuring.adoc b/modules/images-configuration-registry-mirror-configuring.adoc index 07a93710f9c1..3bc1c29e6835 100644 --- a/modules/images-configuration-registry-mirror-configuring.adoc +++ b/modules/images-configuration-registry-mirror-configuring.adoc @@ -12,6 +12,7 @@ endif::[] [id="images-configuration-registry-mirror-configuring_{context}"] = Configuring image registry repository mirroring +[role="_abstract"] You can create postinstallation mirror configuration custom resources (CR) to redirect image pull requests from a source image registry to a mirrored image registry. ifdef::winc[] @@ -34,11 +35,13 @@ endif::openshift-rosa,openshift-dedicated[] . Configure mirrored repositories, by either: + -- -* Setting up a mirrored repository with {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[{quay} Repository Mirroring]. Using {quay} allows you to copy images from one repository to another and also automatically sync those repositories repeatedly over time. +* Setting up a mirrored repository with {quay}. You can copy images from one repository to another and also automatically sync those repositories repeatedly over time by using {quay}. + +** link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/manage_red_hat_quay/repo-mirroring-in-red-hat-quay[{quay} Repository Mirroring] * Using a tool such as `skopeo` to copy images manually from the source repository to the mirrored repository. + -For example, after installing the skopeo RPM package on a Red Hat Enterprise Linux (RHEL) 7 or RHEL 8 system, use the `skopeo` command as shown in this example: +For example, after installing the skopeo RPM package on a {op-system-base-full system}, use the `skopeo` command as shown in the following example: + [source,terminal] ---- @@ -47,7 +50,7 @@ docker://registry.access.redhat.com/ubi9/ubi-minimal:latest@sha256:5cf... \ docker://example.io/example/ubi-minimal ---- + -In this example, you have a container image registry that is named `example.io` with an image repository named `example` to which you want to copy the `ubi9/ubi-minimal` image from `registry.access.redhat.com`. After you create the mirrored registry, you can configure your {product-title} cluster to redirect requests made of the source repository to the mirrored repository. +In this example, you have a container image registry named `example.io` and image repository named `example`. You want to copy the `ubi9/ubi-minimal` image from `registry.access.redhat.com` to `example.io`. After you create the mirrored registry, you can configure your {product-title} cluster to redirect requests made to the source repository to the mirrored repository. -- + ifdef::winc[] @@ -65,63 +68,46 @@ docker://example.io/oss/kubernetes/pause:3.9 . Log in to your {product-title} cluster. endif::winc[] -ifndef::winc[] -. Create a postinstallation mirror configuration CR, by using one of the following examples: +ifndef::winc[] +. Create a postinstallation mirror configuration custom resource (CR), by using one of the following examples: +//should note oc mirror v2 for users here; this set of docs contains mixed examples * Create an `ImageDigestMirrorSet` or `ImageTagMirrorSet` CR, as needed, replacing the source and mirrors with your own registry and repository pairs and images: + [source,yaml] ---- -apiVersion: config.openshift.io/v1 <1> -kind: ImageDigestMirrorSet <2> +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet metadata: name: ubi9repo spec: - imageDigestMirrors: <3> + imageDigestMirrors: - mirrors: - - example.io/example/ubi-minimal <4> - - example.com/example/ubi-minimal <5> - source: registry.access.redhat.com/ubi9/ubi-minimal <6> - mirrorSourcePolicy: AllowContactingSource <7> + - example.io/example/ubi-minimal + - example.com/example2/ubi-minimal + source: registry.access.redhat.com/ubi9/ubi-minimal + mirrorSourcePolicy: AllowContactingSource - mirrors: - mirror.example.com/redhat - source: registry.example.com/redhat <8> + source: registry.example.com/redhat mirrorSourcePolicy: AllowContactingSource - mirrors: - mirror.example.com - source: registry.example.com <9> + source: registry.example.com mirrorSourcePolicy: AllowContactingSource - mirrors: - mirror.example.net/image - source: registry.example.com/example/myimage <10> + source: registry.example.com/example/myimage mirrorSourcePolicy: AllowContactingSource - mirrors: - mirror.example.net - source: registry.example.com/example <11> + source: registry.example.com/example mirrorSourcePolicy: AllowContactingSource - mirrors: - mirror.example.net/registry-example-com - source: registry.example.com <12> + source: registry.example.com mirrorSourcePolicy: AllowContactingSource ---- -<1> Indicates the API to use with this CR. This must be `config.openshift.io/v1`. -<2> Indicates the kind of object according to the pull type: -** `ImageDigestMirrorSet`: Pulls a digest reference image. -** `ImageTagMirrorSet`: Pulls a tag reference image. -<3> Indicates the type of image pull method, either: -** `imageDigestMirrors`: Use for an `ImageDigestMirrorSet` CR. -** `imageTagMirrors`: Use for an `ImageTagMirrorSet` CR. -<4> Indicates the name of the mirrored image registry and repository. -<5> Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use the secondary mirror. -<6> Indicates the registry and repository source, which is the repository that is referred to in an image pull specification. -<7> Optional: Indicates the fallback policy if the image pull fails: -** `AllowContactingSource`: Allows continued attempts to pull the image from the source repository. This is the default. -** `NeverContactSource`: Prevents continued attempts to pull the image from the source repository. -<8> Optional: Indicates a namespace inside a registry, which allows you to use any image in that namespace. If you use a registry domain as a source, the object is applied to all repositories from the registry. -<9> Optional: Indicates a registry, which allows you to use any image in that registry. If you specify a registry name, the object is applied to all repositories from a source registry to a mirror registry. -<10> Pulls the image `registry.example.com/example/myimage@sha256:...` from the mirror `mirror.example.net/image@sha256:..`. -<11> Pulls the image `registry.example.com/example/image@sha256:...` in the source registry namespace from the mirror `mirror.example.net/image@sha256:...`. -<12> Pulls the image `registry.example.com/myimage@sha256` from the mirror registry `example.net/registry-example-com/myimage@sha256:...`. * Create an `ImageContentSourcePolicy` custom resource, replacing the source and mirrors with your own registry and repository pairs and images: + @@ -134,31 +120,34 @@ metadata: spec: repositoryDigestMirrors: - mirrors: - - mirror.registry.com:443/ocp/release <1> - source: quay.io/openshift-release-dev/ocp-release <2> + - mirror.registry.com:443/ocp/release + source: quay.io/openshift-release-dev/ocp-release - mirrors: - mirror.registry.com:443/ocp/release source: quay.io/openshift-release-dev/ocp-v4.0-art-dev ---- -<1> Specifies the name of the mirror image registry and repository. -<2> Specifies the online registry and repository containing the content that is mirrored. ++ +where:: +`- mirror.registry.com:443/ocp/release`: Specifies the name of the mirror image registry and repository. +`source: quay.io/openshift-release-dev/ocp-release`: Specifies the online registry and repository containing the content that is mirrored. endif::winc[] + ifdef::winc[] . Create an `ImageDigestMirrorSet` or `ImageTagMirrorSet` CR, as needed, replacing the source and mirrors with your own registry and repository pairs and images: + [source,yaml] ---- -apiVersion: config.openshift.io/v1 <1> -kind: ImageDigestMirrorSet <2> +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet metadata: name: ubi9repo spec: - imageDigestMirrors: <3> + imageDigestMirrors: - mirrors: - - example.io/example/ubi-minimal <4> - - example.com/example2/ubi-minimal <5> - source: registry.access.redhat.com/ubi9/ubi-minimal <6> - mirrorSourcePolicy: AllowContactingSource <7> + - example.io/example/ubi-minimal + - example.com/example2/ubi-minimal + source: registry.access.redhat.com/ubi9/ubi-minimal + mirrorSourcePolicy: AllowContactingSource - mirrors: - mirror.example.com source: registry.redhat.io @@ -168,22 +157,9 @@ spec: source: docker-mirror.internal mirrorSourcePolicy: AllowContactingSource ---- -<1> Indicates the API to use with this CR. This must be `config.openshift.io/v1`. -<2> Indicates the kind of object according to the pull type: -** `ImageDigestMirrorSet`: Pulls a digest reference image. -** `ImageTagMirrorSet`: Pulls a tag reference image. -<3> Indicates the type of image pull method, either: -** `imageDigestMirrors`: Use for an `ImageDigestMirrorSet` CR. -** `imageTagMirrors`: Use for an `ImageTagMirrorSet` CR. -<4> Indicates the name of the mirrored image registry and repository. -<5> Optional: Indicates a secondary mirror repository for each target repository. If one mirror is down, the target repository can use another mirror. -<6> Indicates the registry and repository source, which is the repository that is referred to in image pull specifications. -<7> Optional: Indicates the fallback policy if the image pull fails: -** `AllowContactingSource`: Allows continued attempts to pull the image from the source repository. This is the default. -** `NeverContactSource`: Prevents continued attempts to pull the image from the source repository. endif::winc[] -. Create the new object: +. Create the new object by running the following command: + [source,terminal] ---- @@ -244,7 +220,7 @@ ifndef::winc[] sh-4.2# cat /etc/containers/registries.conf ---- + -The following output represents a `registries.conf` file where postinstallation mirror configuration CRs were applied. The final two entries are marked `digest-only` and `tag-only` respectively. +The following output represents a `registries.conf` file where postinstallation mirror configuration CRs are applied. + .Example output [source,terminal] @@ -254,11 +230,11 @@ short-name-mode = "" [[registry]] prefix = "" - location = "registry.access.redhat.com/ubi9/ubi-minimal" <1> + location = "registry.access.redhat.com/ubi9/ubi-minimal" [[registry.mirror]] - location = "example.io/example/ubi-minimal" <2> - pull-from-mirror = "digest-only" <3> + location = "example.io/example/ubi-minimal" + pull-from-mirror = "digest-only" [[registry.mirror]] location = "example.com/example/ubi-minimal" @@ -306,17 +282,19 @@ short-name-mode = "" [[registry]] prefix = "" location = "registry.access.redhat.com/ubi9/ubi-minimal" - blocked = true <4> + blocked = true [[registry.mirror]] location = "example.io/example/ubi-minimal-tag" - pull-from-mirror = "tag-only" <5> + pull-from-mirror = "tag-only" ---- -<1> Indicates the repository that is referred to in a pull spec. -<2> Indicates the mirror for that repository. -<3> Indicates that the image pull from the mirror is a digest reference image. -<4> Indicates that the `NeverContactSource` parameter is set for this repository. -<5> Indicates that the image pull from the mirror is a tag reference image. ++ +where:: +`\[[registry]].location = "registry.access.redhat.com/ubi9/ubi-minimal"` The repository listed in a pull spec. +`\[[registry.mirror]].location = "example.io/example/ubi-minimal"` Indicates the mirror for that repository. +`\[[registry.mirror]].pull-from-mirror = "digest-only"` Means that the image pull from the mirror is a digest reference image. +`\[[registry]].blocked = true` Indicates that the `NeverContactSource` parameter is set for this repository. +`\[[registry.mirror]].pull-from-mirror = "tag-only"` Indicates that the image pull from the mirror is a tag reference image. endif::winc[] ifdef::winc[] .. Check that the WMCO generated a `hosts.toml` file for each registry on each Windows instance. For the previous example IDMS object, there should be three files in the following file structure: @@ -375,9 +353,9 @@ endif::winc[] sh-4.2# podman pull --log-level=debug registry.access.redhat.com/ubi9/ubi-minimal@sha256:5cf... ---- -.Troubleshooting repository mirroring +.Troubleshooting -If the repository mirroring procedure does not work as described, use the following information about how repository mirroring works to help troubleshoot the problem. +If the repository mirroring procedure does not work as described, use the following information about how repository mirroring works to help troubleshoot the problem: * The first working mirror is used to supply the pulled image. * The main registry is only used if no other mirror works. @@ -389,3 +367,4 @@ endif::winc[] ifeval::["{context}" == "enabling-windows-container-workloads"] :!winc: endif::[] +//do we need this ifeval? diff --git a/modules/images-configuration-registry-mirror-convert.adoc b/modules/images-configuration-registry-mirror-convert.adoc index 8c933b4547ea..92b22ba7674a 100644 --- a/modules/images-configuration-registry-mirror-convert.adoc +++ b/modules/images-configuration-registry-mirror-convert.adoc @@ -7,7 +7,10 @@ [id="images-configuration-registry-mirror-convert_{context}"] = Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring -Using an `ImageContentSourcePolicy` (ICSP) object to configure repository mirroring is a deprecated feature. This functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. +[role="_abstract"] +Using an `ImageContentSourcePolicy` (ICSP) object to configure repository mirroring is a deprecated feature. + +This functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. ICSP objects are being replaced by `ImageDigestMirrorSet` and `ImageTagMirrorSet` objects to configure repository mirroring. If you have existing YAML files that you used to create `ImageContentSourcePolicy` objects, you can use the `oc adm migrate icsp` command to convert those files to an `ImageDigestMirrorSet` YAML file. The command updates the API to the current version, changes the `kind` value to `ImageDigestMirrorSet`, and changes `spec.repositoryDigestMirrors` to `spec.imageDigestMirrors`. The rest of the file is not changed. @@ -35,12 +38,10 @@ endif::openshift-rosa,openshift-dedicated[] $ oc adm migrate icsp .yaml .yaml .yaml --dest-dir ---- + --- where: - ++ ``:: Specifies the name of the source `ImageContentSourcePolicy` YAML. You can list multiple file names. `--dest-dir`:: Optional: Specifies a directory for the output `ImageDigestMirrorSet` YAML. If unset, the file is written to the current directory. --- + For example, the following command converts the `icsp.yaml` and `icsp-2.yaml` file and saves the new YAML files to the `idms-files` directory. + @@ -63,11 +64,9 @@ wrote ImageDigestMirrorSet to idms-files/imagedigestmirrorset_ubi9repo.645693185 $ oc create -f /.yaml ---- + --- where: - ++ ``:: Specifies the path to the directory, if you used the `--dest-dir` flag. ``:: Specifies the name of the `ImageDigestMirrorSet` YAML. --- . Remove the ICSP objects after the IDMS objects are rolled out. diff --git a/modules/images-configuration-registry-mirror.adoc b/modules/images-configuration-registry-mirror.adoc index 8fc654c3f509..743e736ccd21 100644 --- a/modules/images-configuration-registry-mirror.adoc +++ b/modules/images-configuration-registry-mirror.adoc @@ -12,7 +12,8 @@ endif::[] [id="images-configuration-registry-mirror_{context}"] = Understanding image registry repository mirroring -Setting up container registry repository mirroring enables you to perform the following tasks: +[role="_abstract"] +By setting up container registry repository mirroring, you can perform the following tasks: * 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 repository, to make sure that if one mirror is down, another can be used. @@ -20,7 +21,7 @@ Setting up container registry repository mirroring enables you to perform the fo Repository mirroring in {product-title} includes the following attributes: * Image pulls are resilient to registry downtimes. -* Clusters in disconnected environments can pull images from critical locations, such as quay.io, and have registries behind a company firewall provide the requested images. +* Clusters in disconnected environments can pull images from critical locations, such as `quay.io`, and have registries behind a company firewall provide the requested images. * A particular order of registries is tried when an image pull request is made, with the permanent registry typically being the last one tried. ifndef::winc[] * The mirror information you enter is added to the `/etc/containers/registries.conf` file on every node in the {product-title} cluster. @@ -30,7 +31,7 @@ ifdef::winc[] endif::winc[] * When a node makes a request for an image from the source repository, it tries each mirrored repository in turn until it finds the requested content. If all mirrors fail, the cluster tries the source repository. If successful, the image is pulled to the node. -Setting up repository mirroring can be done in the following ways: +You can set up repository mirroring in the following ways: * At {product-title} installation: + @@ -38,7 +39,7 @@ By pulling container images needed by {product-title} and then bringing those im * After {product-title} installation: + -If you did not configure mirroring during {product-title} installation, you can do so postinstallation by using any of the following custom resource (CR) objects: +If you did not configure mirroring during {product-title} installation, you can do so post-installation by using any of the following custom resource (CR) objects: + -- ** `ImageDigestMirrorSet` (IDMS). This object allows you to pull images from a mirrored registry by using digest specifications. The IDMS CR enables you to set a fall back policy that allows or stops continued attempts to pull from the source registry if the image pull fails. @@ -67,9 +68,9 @@ requested from the source repository. Note the following actions and how they affect node drain behavior: -* If you create an IDMS or ICSP CR object, the MCO does not drain or reboot the node. -* If you create an ITMS CR object, the MCO drains and reboots the node. -* If you delete an ITMS, IDMS, or ICSP CR object, the MCO drains and reboots the node. +* If you create an IDMS or ICSP CR object, the MCO does not drain or reboot the node. +* If you create an ITMS CR object, the MCO drains and reboots the node. +* If you delete an ITMS, IDMS, or ICSP CR object, the MCO drains and reboots the node. * If you modify an ITMS, IDMS, or ICSP CR object, the MCO drains and reboots the node. + [IMPORTANT] @@ -78,9 +79,9 @@ include::snippets/node-icsp-no-drain.adoc[] ==== ifndef::winc[] -For new clusters, you can use IDMS, ITMS, and ICSP CRs objects as desired. However, using IDMS and ITMS is recommended. +For new clusters, you can use IDMS, ITMS, and ICSP CRs objects as needed. However, using IDMS and ITMS is recommended. -If you upgraded a cluster, any existing ICSP objects remain stable, and both IDMS and ICSP objects are supported. Workloads using ICSP objects continue to function as expected. However, if you want to take advantage of the fallback policies introduced in the IDMS CRs, you can migrate current workloads to IDMS objects by using the `oc adm migrate icsp` command as shown in the *Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring* section that follows. Migrating to IDMS objects does not require a cluster reboot. +If you upgraded a cluster, any existing ICSP objects remain stable, and both IDMS and ICSP objects are supported. Workloads that use ICSP objects continue to function as expected. However, if you want to take advantage of the fallback policies introduced in the IDMS CRs, you can migrate current workloads to IDMS objects by using the `oc adm migrate icsp` command as shown in the *Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring* section that follows. Migrating to IDMS objects does not require a cluster reboot. include::snippets/idms-global-pull-secret.adoc[]endif::winc[] endif::winc[] diff --git a/modules/images-configuration-shortname.adoc b/modules/images-configuration-shortname.adoc index d24867833b23..64dd8765223b 100644 --- a/modules/images-configuration-shortname.adoc +++ b/modules/images-configuration-shortname.adoc @@ -1,40 +1,14 @@ // Module included in the following assemblies: // // * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc :_mod-docs-content-type: PROCEDURE [id="images-configuration-shortname_{context}"] = Adding registries that allow image short names +[role="_abstract"] You can add registries to search for an image short name 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. -An image short name enables you to search for images without including the fully qualified domain name in the pull spec. For example, you could use `rhel7/etcd` instead of `registry.access.redhat.com/rhe7/etcd`. - -You might use short names in situations where using the full path is not practical. For example, if your cluster references multiple internal registries whose DNS changes frequently, you would need to update the fully qualified domain names in your pull specs with each change. In this case, using an image short name might be beneficial. - -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 `containerRuntimeSearchRegistries` parameter, when pulling an image with a short name, the container runtime searches those registries. - -[WARNING] -==== -Using image short names with public registries is strongly discouraged because the image might not deploy if the public registry requires authentication. Use fully-qualified image names with public registries. - -Red Hat internal or private registries typically support the use of image short names. - -If you list public registries under the `containerRuntimeSearchRegistries` parameter (including the `registry.redhat.io`, `docker.io`, and `quay.io` registries), you expose your credentials to all the registries on the list, and you risk network and registry attacks. Because you can only have one pull secret for pulling images, as defined by the global pull secret, that secret is used to authenticate against every registry in that list. Therefore, if you include public registries in the list, you introduce a security risk. - -You cannot list multiple public registries under the `containerRuntimeSearchRegistries` parameter if each public registry requires different credentials and a cluster does not list the public registry in the global pull secret. - -For a public registry that requires authentication, you can use an image short name only if the registry has its credentials stored in the global pull secret. -//// -Potentially add the last line to the Ignoring image registry repository mirroring section. -//// -==== - -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. During this period, you might experience service unavailability. After the nodes return to the `Ready` state, if the `containerRuntimeSearchRegistries` parameter is added, the MCO creates a file in the `/etc/containers/registries.conf.d` directory on each node with the listed registries. The file overrides the default list of unqualified search registries in the `/etc/containers/registries.conf` file. There is no way to fall back to the default list of unqualified search registries. - -The `containerRuntimeSearchRegistries` parameter works only with the Podman and CRI-O container engines. The registries in the list can be used only in pod specs, not in builds and image streams. - .Procedure * Edit the `image.config.openshift.io/cluster` custom resource: @@ -66,11 +40,11 @@ spec: additionalTrustedCA: name: myconfigmap registrySources: - containerRuntimeSearchRegistries: <1> + containerRuntimeSearchRegistries: - reg1.io - reg2.io - reg3.io - allowedRegistries: <2> + allowedRegistries: - example.com - quay.io - registry.redhat.io @@ -82,8 +56,10 @@ spec: status: internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ---- -<1> Specify registries to use with image short names. You should use image short names with only internal or private registries to reduce possible security risks. -<2> Ensure that any registries listed under `containerRuntimeSearchRegistries` are included in the `allowedRegistries` list. ++ +where:: +`spec.registrySources.containerRuntimeSearchRegistries:` Specify registries to use with image short names. Use image short names with only internal or private registries to reduce possible security risks. If you list public registries under the `containerRuntimeSearchRegistries` parameter, you expose your credentials to all of the registries on the list. +`spec.registrySources.allowedRegistries:` Ensure that any registries listed under `containerRuntimeSearchRegistries` are included in the `allowedRegistries` list. + [NOTE] ==== @@ -91,9 +67,7 @@ When the `allowedRegistries` parameter is defined, all registries, including the ==== ifndef::openshift-rosa,openshift-dedicated[] -.Verification - -* Enter the following command to obtain a list of your nodes: +. Get a list of your nodes by running the following command: + [source,terminal] ---- @@ -122,7 +96,9 @@ $ oc debug node/ sh-4.4# chroot /host ---- -. Enter the following command to check that the registries have been added to the policy file: +.Verification + +. Verify that registries are added to the policy file by running the following command: + [source,terminal] ---- diff --git a/modules/images_configuration_shortname_con.adoc b/modules/images_configuration_shortname_con.adoc new file mode 100644 index 000000000000..23f8eb003bea --- /dev/null +++ b/modules/images_configuration_shortname_con.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * openshift_images/image-configuration.adoc + +:_mod-docs-content-type: CONCEPT +[id="images-configuration-shortname-con_{context}"] += About adding registries that allow image short names + +[role="_abstract"] +With an image short name, you can search for images without including the fully qualified domain name in the pull `spec` parameter. + +For example, you could use `rhel7/etcd` instead of `registry.access.redhat.com/rhe7/etcd`. You can add registries to search for an image short name by editing the `image.config.openshift.io/cluster` custom resource (CR). + +You might use short names in situations where using the full path is not practical. For example, if your cluster references multiple internal registries whose DNS changes often, you would need to update the fully qualified domain names in your pull specs with each change. In this case, using an image short name might be beneficial. + +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 `containerRuntimeSearchRegistries` parameter, when pulling an image with a short name, the container runtime searches those registries. + +[id="images-configuration-shortname-when-not-to-use_{context}"] +== When not to use image short names + +Using image short names with public registries is strongly discouraged because the image might not deploy if the public registry requires authentication. Use fully-qualified image names with public registries. + +Red{nbsp}Hat internal or private registries typically support the use of image short names. + +You cannot list multiple public registries under the `containerRuntimeSearchRegistries` parameter if each public registry requires different credentials and a cluster does not list the public registry in the global pull secret. + +For a public registry that requires authentication, you can use an image short name only if the registry has its credentials stored in the global pull secret. + +[WARNING] +==== +If you list public registries under the `containerRuntimeSearchRegistries` parameter (including the `registry.redhat.io`, `docker.io`, and `quay.io` registries), you expose your credentials to all the registries on the list, and you risk network and registry attacks. Because you can only have one pull secret for pulling images, as defined by the global pull secret, that secret is used to authenticate against every registry in that list. Therefore, if you include public registries in the list, you introduce a security risk. +==== + +[id="images-configuration-mco-and-registry-changes_{context}"] +== Machine Config Operator behavior and registry changes + +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. During this period, you might experience service unavailability. + +After the nodes return to the `Ready` state, if the `containerRuntimeSearchRegistries` parameter is added, the MCO creates a file in the `/etc/containers/registries.conf.d` directory on each node with the listed registries. The file overrides the default list of unqualified search registries in the `/etc/containers/registries.conf` file. There is no way to fall back to the default list of unqualified search registries. + +The `containerRuntimeSearchRegistries` parameter works only with the Podman and CRI-O container engines. The registries in the list can be used only in pod specs, not in builds and image streams. diff --git a/modules/images_configuring_registry_mirror_config_params.adoc b/modules/images_configuring_registry_mirror_config_params.adoc new file mode 100644 index 000000000000..fc8434cc77d8 --- /dev/null +++ b/modules/images_configuring_registry_mirror_config_params.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * openshift_images/image-configuration.adoc +// * updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update.adoc +// * windows_containers/enabling-windows-container-workloads.adoc + +ifeval::["{context}" == "enabling-windows-container-workloads"] +:winc: +endif::[] + +:_mod-docs-content-type: REFERENCE +[id="images-configuration-registry-mirror-config-params_{context}"] += Image registry repository mirroring configuration parameters + +[role="_abstract"] +You can use the following table for information about parameters when configuring your image repository for mirroring. + +[%header,cols="32",cols="1,2",options="header"] +|=== +|*Parameter* |*Values and Information* + +|`apiVersion:` +|Required. The value must be `config.openshift.io/v1` API. + +|`kind:` +|The kind of object according to the pull type. The `ImageDigestMirrorSet` type pulls a digest reference image The `ImageTagMirrorSet` type pulls a tag reference image. + +|`spec: imageDigestMirrors:` +|The type of image pull method. Use `imageDigestMirrors`for an `ImageDigestMirrorSet` CR. Use `imageTagMirrors` for an `ImageTagMirrorSet` CR. + +|`- mirrors: - example.io/example/ubi-minimal` +|The name of the mirrored image registry and repository. + +|`- mirrors: -example.com/example2/ubi-minimal` +|The value of this parameter is the name of a secondary mirror repository for each target repository. If one mirror is down the target repository can use the secondary mirror. + +|`source: registry.access.redhat.com/ubi9/ubi-minimal` +|The registry and repository source. The source is the repository that is listed in an image pull specification. + +|`mirrorSourcePolicy: AllowContactingSource` +|Optional parameter that indicates the fallback policy if the image pull fails. The `AllowContactingSource` value allows continued attempts to pull the image from the source repository. Default value. `NeverContactSource` prevents continued attempts to pull the image from the source repository. +ifndef::winc[] +|`source: registry.example.com/redhat`: An optional parameter that indicates a namespace inside a registry. Setting a namespace inside a registry allows use of any image in that namespace. If you use a registry domain as a source, the object applies to all of the repositories from the registry. + +|`source: registry.example.com` +|Optional parameter that indicates a registry. Allows us of any image in that registry. If you specify a registry name, the object applies to all repositories from a source registry to a mirror registry. + +|`source: registry.example.com/example/myimage` +|Pulls the image `registry.example.com/example/myimage@sha256:...` from the mirror `mirror.example.net/image@sha256:..`. + +|`source: registry.example.com/example` +|Pulls the image `registry.example.com/example/image@sha256:...` in the source registry namespace from the mirror `mirror.example.net/image@sha256:...`. + +|`source: registry.example.com` +|Pulls the image `registry.example.com/myimage@sha256` from the mirror registry `example.net/registry-example-com/myimage@sha256:...`. +endif::winc[] +|=== + +ifeval::["{context}" == "enabling-windows-container-workloads"] +:winc: +endif::[] diff --git a/openshift_images/image-configuration.adoc b/openshift_images/image-configuration.adoc index 84862e32e7ba..e0203eea2cbd 100644 --- a/openshift_images/image-configuration.adoc +++ b/openshift_images/image-configuration.adoc @@ -6,45 +6,46 @@ include::_attributes/common-attributes.adoc[] toc::[] -Use the following procedure to configure image registries. +[role="_abstract"] +You can configure an image registry to store and serve container images. include::modules/images-configuration-parameters.adoc[leveloffset=+1] -ifndef::openshift-rosa,openshift-dedicated[] -[role="_additional-resources"] -.Additional resources - -* xref:../openshift_images/image-streams-manage.adoc#images-imagestream-import-import-mode_image-streams-managing[Working with manifest lists] - -* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features-about_nodes-cluster-enabling[Understanding feature gates] -endif::openshift-rosa,openshift-dedicated[] - include::modules/images-configuration-file.adoc[leveloffset=+1] include::modules/images-configuration-allowed.adoc[leveloffset=+2] include::modules/images-configuration-blocked.adoc[leveloffset=+2] -// Managed OpenShift customers may not create ImageContentSourcePolicy +// Managed OpenShift customers cannot create ImageContentSourcePolicy ifndef::openshift-rosa,openshift-dedicated[] -include::modules/images-configuration-blocked-payload.adoc[leveloffset=+3] +include::modules/images-configuration-blocked-payload.adoc[leveloffset=+2] + endif::openshift-rosa,openshift-dedicated[] +//adds blank line after module include include::modules/images-configuration-insecure.adoc[leveloffset=+2] +include::modules/images_configuration_shortname_con.adoc[leveloffset=+2] + include::modules/images-configuration-shortname.adoc[leveloffset=+2] include::modules/images-configuration-cas.adoc[leveloffset=+2] include::modules/images-configuration-registry-mirror.adoc[leveloffset=+1] +include::modules/images-configuration-registry-mirror-configuring.adoc[leveloffset=+2] + +include::modules/images_configuring_registry_mirror_config_params.adoc[leveloffset=+2] + +include::modules/images-configuration-registry-mirror-convert.adoc[leveloffset=+2] + ifndef::openshift-rosa,openshift-dedicated[] +[id="additional-resources_image-configuration"] [role="_additional-resources"] -.Additional resources +== Additional resources -* For more information about global pull secrets, see xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#images-update-global-pull-secret_using-image-pull-secrets[Updating the global cluster pull secret]. +* xref:../openshift_images/image-streams-manage.adoc#images-imagestream-import-import-mode_image-streams-managing[Working with manifest lists] +* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features-about_nodes-cluster-enabling[Understanding feature gates] +* xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#images-update-global-pull-secret_using-image-pull-secrets[Updating the global cluster pull secret] endif::openshift-rosa,openshift-dedicated[] - -include::modules/images-configuration-registry-mirror-configuring.adoc[leveloffset=+2] - -include::modules/images-configuration-registry-mirror-convert.adoc[leveloffset=+2] diff --git a/snippets/technology-preview.adoc b/snippets/technology-preview.adoc index 713f12719104..f2e08c01a4e8 100644 --- a/snippets/technology-preview.adoc +++ b/snippets/technology-preview.adoc @@ -8,9 +8,11 @@ [IMPORTANT] ==== [subs="attributes+"] -{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. +{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red{nbsp}Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. -For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +For more information about the support scope of Red Hat Technology Preview features, see the following link: + +* link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope] ==== // Undefine {FeatureName} attribute, so that any mistakes are easily spotted :!FeatureName: