// Module included in the following assemblies:
//
// * openshift_images/image-configuration.adoc

:_mod-docs-content-type: REFERENCE
[id="images-configuration-parameters_{context}"]
= Image controller 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.

[NOTE]
====
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"]
|===
|Field name |Description

|`kind.Image`
|Holds cluster-wide information about how to handle images. The canonical, and only valid name for this CR is `cluster`.

|`allowedRegistriesForImport`
|Limits the container image registries from which normal users can 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.

Every element of this list contains a location of the registry specified by the registry domain name.

`domainName`: Specifies a domain name for the registry. If the registry uses a non-standard `80` or `443` port, the port should be included in the domain name as well.

`insecure`: Insecure indicates whether the registry is secure or insecure. By default, if not otherwise specified, the registry is assumed to be secure.

|`additionalTrustedCA`
|A reference to a config map containing additional CAs that should be 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-encoded certificate as the value, for each additional registry CA to trust.

|`externalRegistryHostnames`
|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 example, whether or not to allow insecure access. It does not contain configuration for the internal cluster registry.

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

`allowedRegistries`: Registries for which image pull and push actions are allowed. 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 blocked.

`containerRuntimeSearchRegistries`: Registries for which image pull and push actions are allowed using image short names. All other registries are blocked.

You can set either `blockedRegistries` or `allowedRegistries`, but not both.

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

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:

* The single architecture payload implies that the `Legacy` mode is applicable.
* The multi payload implies that the `PreserveOriginal` mode is applicable.

For information about importing manifest lists, see "Working with manifest lists".

:FeatureName: `imageStreamImportMode`
include::snippets/technology-preview.adoc[]

endif::openshift-rosa,openshift-dedicated[]
|===

include::snippets/allowed-registries-warning.adoc[leveloffset=+1]

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

|`internalRegistryHostname`
|Set by the Image Registry Operator, which controls the `internalRegistryHostname`. It sets the hostname for the default {product-registry}. The value must be in `hostname[:port]` format. For backward compatibility, you can still use the `OPENSHIFT_DEFAULT_REGISTRY` environment variable, but this setting overrides the environment variable.

|`externalRegistryHostnames`
|Set by the Image Registry Operator, provides the external hostnames for the image registry when it is exposed externally. The first value is used in `publicDockerImageRepository` field in image streams. The values must be in `hostname[:port]` format.
|===
