Skip to content

OSDOCS-16880-2: CQA-IMG-2: image config and adv features #102644

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+333 −230
Open

OSDOCS-16880-2: CQA-IMG-2: image config and adv features #102644

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions _attributes/attributes-openshift-dedicated.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
41 changes: 24 additions & 17 deletions modules/images-configuration-allowed.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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
Expand All @@ -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]
====
Expand All @@ -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]
----
Expand All @@ -79,12 +82,14 @@ NAME STATUS ROLES AGE VERSION
<node_name> 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/<node_name>
$ oc debug node/_<node_name>_
----
+
Replace _<node-name>_ with the name of your node.

. When prompted, enter `chroot /host` into the terminal:
+
Expand All @@ -93,14 +98,16 @@ $ oc debug node/<node_name>
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]
Expand Down
21 changes: 14 additions & 7 deletions modules/images-configuration-blocked-payload.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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]
Expand All @@ -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]
----
Expand All @@ -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
Copy link
Collaborator

@ocpdocs-vale-bot ocpdocs-vale-bot Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 [error] AsciiDocDITA.BlockTitle: Block titles can only be assigned to examples, figures, and tables in DITA.

[source,terminal]
----
[[registry]]
Expand Down
37 changes: 22 additions & 15 deletions modules/images-configuration-blocked.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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]
----
Expand All @@ -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/<node_name>
$ oc debug node/_<node_name>_
----
+
Replace _<node_name>_ with the name of the node you want details about.

. When prompted, enter `chroot /host` into the terminal:
+
Expand All @@ -90,7 +95,9 @@ $ oc debug node/<node_name>
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]
----
Expand Down
24 changes: 13 additions & 11 deletions modules/images-configuration-cas.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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]
----
Expand Down
Loading