Chapter 9. Image configuration resources

Procedure

• Edit the image.config.openshift.io/cluster custom resource:

  $ oc edit image.config.openshift.io/cluster

  The following is an example image.config.openshift.io/cluster CR with an allowed list:

  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
      - reg1.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 registries, and optionally a repository in that registry, 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 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.

Verification

• Enter the following command to obtain a list of your nodes:

  $ oc get nodes

  Example output

  NAME               STATUS   ROLES                  AGE   VERSION
  <node_name>        Ready    control-plane,master   37m   v1.27.8+4fab27b

  1. Run the following command to enter debug mode on the node:

     $ oc debug node/<node_name>

  2. When prompted, enter chroot /host into the terminal:

     sh-4.4# chroot /host

  3. Enter the following command to check that the registries have been added to the policy file:

     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:

     Example 9.1. Example image signature policy file

     {
        "default":[
           {
              "type":"reject"
           }
        ],
        "transports":{
           "atomic":{
              "example.com":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "image-registry.openshift-image-registry.svc:5000":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "insecure.com":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "quay.io":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "reg4.io/myrepo/myapp:latest":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "registry.redhat.io":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ]
           },
           "docker":{
              "example.com":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "image-registry.openshift-image-registry.svc:5000":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "insecure.com":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "quay.io":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "reg4.io/myrepo/myapp:latest":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ],
              "registry.redhat.io":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ]
           },
           "docker-daemon":{
              "":[
                 {
                    "type":"insecureAcceptAnything"
                 }
              ]
           }
        }
     }

Procedure

• Edit the image.config.openshift.io/cluster custom resource:

  $ oc edit image.config.openshift.io/cluster

  The following is an example image.config.openshift.io/cluster CR with a blocked list:

  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
      - 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.

  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 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.

Verification

• Enter the following command to obtain a list of your nodes:

  $ oc get nodes

  Example output

  NAME                STATUS   ROLES                  AGE   VERSION
  <node_name>         Ready    control-plane,master   37m   v1.27.8+4fab27b

  1. Run the following command to enter debug mode on the node:

     $ oc debug node/<node_name>

  2. When prompted, enter chroot /host into the terminal:

     sh-4.4# chroot /host

  3. Enter the following command to check that the registries have been added to the policy file:

     sh-5.1# cat etc/containers/registries.conf

     The following example indicates that images from the untrusted.com registry are prevented for image pulls and pushes:

     Example output

     unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
     
     [[registry]]
       prefix = ""
       location = "untrusted.com"
       blocked = true

Procedure

• Edit the image.config.openshift.io/cluster custom resource:

  $ oc edit image.config.openshift.io/cluster

  The following is an example image.config.openshift.io/cluster CR with an insecure registries list:

  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
      insecureRegistries: 2
      - insecure.com
      - reg4.io/myrepo/myapp:latest
      allowedRegistries:
      - example.com
      - quay.io
      - registry.redhat.io
      - insecure.com 3
      - 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.

  Note

  When the allowedRegistries parameter is defined, all registries, including the registry.redhat.io and quay.io registries and the default OpenShift image registry, are blocked unless explicitly listed. If you use the parameter, to prevent pod failure, add all registries including 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.

  The Machine Config Operator (MCO) watches the image.config.openshift.io/cluster CR for any changes to the registries, then drains and uncordons the nodes when it detects changes. After the nodes return to the Ready state, changes to the insecure and blocked registries appear in the /etc/containers/registries.conf file on each node.

Verification

• To check that the registries have been added to the policy file, use the following command on a node:

  $ 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.

  Example output

  unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
  
  [[registry]]
    prefix = ""
    location = "insecure.com"
    insecure = true

Procedure

• Edit the image.config.openshift.io/cluster custom resource:

  $ oc edit image.config.openshift.io/cluster

  The following is an example image.config.openshift.io/cluster CR:

  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:
    allowedRegistriesForImport:
      - domainName: quay.io
        insecure: false
    additionalTrustedCA:
      name: myconfigmap
    registrySources:
      containerRuntimeSearchRegistries: 1
      - reg1.io
      - reg2.io
      - reg3.io
      allowedRegistries: 2
      - example.com
      - quay.io
      - registry.redhat.io
      - reg1.io
      - reg2.io
      - reg3.io
      - image-registry.openshift-image-registry.svc:5000
  ...
  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.

  Note

  When the allowedRegistries parameter is defined, all registries, including the registry.redhat.io and quay.io registries and the default OpenShift image registry, are blocked unless explicitly listed. If you use this parameter, to prevent pod failure, add all registries including 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.

Verification

• Enter the following command to obtain a list of your nodes:

  $ oc get nodes

  Example output

  NAME                STATUS   ROLES                  AGE   VERSION
  <node_name>         Ready    control-plane,master   37m   v1.27.8+4fab27b

  1. Run the following command to enter debug mode on the node:

     $ oc debug node/<node_name>

  2. When prompted, enter chroot /host into the terminal:

     sh-4.4# chroot /host

  3. Enter the following command to check that the registries have been added to the policy file:

     sh-5.1# cat /etc/containers/registries.conf.d/01-image-searchRegistries.conf

     Example output

     unqualified-search-registries = ['reg1.io', 'reg2.io', 'reg3.io']

Prerequisites

• The certificate authorities (CA) must be PEM-encoded.

• To configure an additional CA:

  $ oc create configmap registry-config --from-file=<external_registry_address>=ca.crt -n openshift-config

  $ oc edit image.config.openshift.io cluster

  spec:
    additionalTrustedCA:
      name: registry-config

Prerequisites

• Access to the cluster as a user with the cluster-admin role.

• The first working mirror is used to supply the pulled image.
• The main registry is only used if no other mirror works.
• From the system context, the Insecure flags are used as fallback.
• The format of the /etc/containers/registries.conf file has changed recently. It is now version 2 and in TOML format.

Prerequisites

• Access to the cluster as a user with the cluster-admin role.
• Ensure that you have ImageContentSourcePolicy objects on your cluster.