containers-registries.conf - Man Page

unqualified-search-registries

An array of host[:port] registries to try when pulling an unqualified image, in order.

The bulk of the configuration is represented as an array of [[registry]] TOML tables; the settings may therefore differ among different registries as well as among different namespaces/repositories within a registry.

Given an image name, a single [[registry]] TOML table is chosen based on its prefix field.

prefix

A prefix of the user-specified image name, i.e. using one of the following formats:

• host[:port]
• host[:port]/namespace[/_namespace_…]
• host[:port]/namespace[/_namespace_…]/repo
• host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)

The user-specified image name must start with the specified prefix (and continue with the appropriate separator) for a particular [[registry]] TOML table to be considered; (only) the TOML table with the longest match is used.As a special case, the prefix field can be missing; if so, it defaults to the value of the location field (described below).

insecure

true or false. By default, container runtimes require TLS when retrieving images from a registry. If insecure is set to true, unencrypted HTTP as well as TLS connections with untrusted certificates are allowed.

blocked

true or false. If true, pulling images with matching names is forbidden.

The user-specified image reference is, primarily, a "logical" image name, always used for naming the image.  By default, the image reference also directly specifies the registry and repository to use, but the following options can be used to redirect the underlying accesses to different registry servers or locations (e.g. to support configurations with no access to the internet without having to change Dockerfiles, or to add redundancy).

location

Accepts the same format as the prefix field, and specifies the physical location of the prefix-rooted namespace.By default, this equal to prefix (in which case prefix can be omitted and the [[registry]] TOML table can only specify location).Example: Given

prefix = "example.com/foo"
location = "internal-registry-for-example.net/bar"

requests for the image example.com/foo/myimage:latest will actually work with the internal-registry-for-example.net/bar/myimage:latest image.

mirror

An array of TOML tables specifying (possibly-partial) mirrors for the prefix-rooted namespace.The mirrors are attempted in the specified order; the first one that can be contacted and contains the image will be used (and if none of the mirrors contains the image, the primary location specified by the registry.location field, or using the unmodified user-specified reference, is tried last).Each TOML table in the mirror array can contain the following fields, with the same semantics as if specified in the [[registry]] TOML table directly:

• location
• insecure

mirror-by-digest-only

true or false. If true, mirrors will only be used during pulling if the image reference includes a digest. Referencing an image by digest ensures that the same is always used (whereas referencing an image by a tag may cause different registries to return different images if the tag mapping is out of sync).Note that if this is true, images referenced by a tag will only use the primary registry, failing if that registry is not accessible.

Note: Redirection and mirrors are currently processed only when reading images, not when pushing to a registry; that may change in the future.

The Docker Hub docker.io is handled in a special way: every push and pull operation gets internally normalized with /library if no other specific namespace is defined (for example on docker.io/namespace/image).

(Note that the above-described normalization happens to match the behavior of Docker.)

This means that a pull of docker.io/alpine will be internally translated to docker.io/library/alpine. A pull of docker.io/user/alpine will not be rewritten because this is already the correct remote path.

Therefore, to remap or mirror the docker.io images in the (implied) /library namespace (or that whole namespace), the prefix and location fields in this configuration file must explicitly include that /library namespace. For example prefix = "docker.io/library/alpine" and not prefix = "docker.io/alpine". The latter would match the docker.io/alpine/* repositories but not the docker.io/[library/]alpine image).

unqualified-search-registries = ["example.com"]

[[registry]]
prefix = "example.com/foo"
insecure = false
blocked = false
location = "internal-registry-for-example.com/bar"

[[registry.mirror]]
location = "example-mirror-0.local/mirror-for-foo"

[[registry.mirror]]
location = "example-mirror-1.local/mirrors/foo"
insecure = true

Given the above, a pull of example.com/foo/image:latest will try:
   1. example-mirror-0.local/mirror-for-foo/image:latest
   2. example-mirror-1.local/mirrors/foo/image:latest
   3. internal-registry-for-example.net/bar/image:latest

in order, and use the first one that exists.

The following example configuration defines two searchable registries, one insecure registry, and two blocked registries.

[registries.search]
registries = ['registry1.com', 'registry2.com']

[registries.insecure]
registries = ['registry3.com']

[registries.block]
registries = ['registry.untrusted.com', 'registry.unsafe.com']