skopeo/containers-registries.conf.5.md

4.2 KiB

% CONTAINERS-REGISTRIES.CONF(5) System-wide registry configuration file % Brent Baude % Aug 2017

NAME

containers-registries.conf - Syntax of System Registry Configuration File

DESCRIPTION

The CONTAINERS-REGISTRIES configuration file is a system-wide configuration file for container image registries. The file format is TOML.

By default, the configuration file is located at /etc/containers/registries.conf.

FORMATS

VERSION 2

VERSION 2 is the latest format of the registries.conf and is currently in beta. This means in general VERSION 1 should be used in production environments for now.

Every registry can have its own mirrors configured. The mirrors will be tested in order for the availability of the remote manifest. This happens currently only during an image pull. If the manifest is not reachable due to connectivity issues or the unavailability of the remote manifest, then the next mirror will be tested instead. If no mirror is configured or contains the manifest to be pulled, then the initially provided reference will be used as fallback. It is possible to set the insecure option per mirror, too.

Furthermore it is possible to specify a prefix for a registry. The prefix is used to find the relevant target registry from where the image has to be pulled. During the test for the availability of the image, the prefixed location will be rewritten to the correct remote location. This applies to mirrors as well as the fallback location. If no prefix is specified, it defaults to the specified location. For example, if prefix = "example.com/foo", location = "example.com" and the image will be pulled from example.com/foo/image, then the resulting pull will be effectively point to example.com/image.

By default container runtimes use TLS when retrieving images from a registry. If the registry is not setup with TLS, then the container runtime will fail to pull images from the registry. If you set insecure = true for a registry or a mirror you overwrite the insecure flag for that specific entry. This means that the container runtime will attempt use unencrypted HTTP to pull the image. It also allows you to pull from a registry with self-signed certificates.

If you set the unqualified-search = true for the registry, then it is possible to omit the registry hostname when pulling images. This feature does not work together with a specified prefix.

If blocked = true then it is not allowed to pull images from that registry.

EXAMPLE

[[registry]]
location = "example.com"
insecure = false
prefix = "example.com/foo"
unqualified-search = false
blocked = false
mirror = [
    { location = "example-mirror-0.local", insecure = false },
    { location = "example-mirror-1.local", insecure = true }
]

VERSION 1

VERSION 1 can be used as alternative to the VERSION 2, but it is not capable in using registry mirrors or a prefix.

The TOML_format is used to build a simple list for registries under three categories: registries.search, registries.insecure, and registries.block. You can list multiple registries using a comma separated list.

Search registries are used when the caller of a container runtime does not fully specify the container image that they want to execute. These registries are prepended onto the front of the specified container image until the named image is found at a registry.

Note insecure registries can be used for any registry, not just the registries listed under search.

The fields registries.insecure and registries.block work as like as the insecure and blocked from VERSION 2.

EXAMPLE

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']

HISTORY

Mar 2019, Added additional configuration format by Sascha Grunert sgrunert@suse.com

Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg vrothberg@suse.com

Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com

Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com