containers-registries.conf man page
Brent Baude Aug 2017
containers-registries.conf — Syntax of System Registry Configuration File 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 VERSION 2 is the latest format of the An array of host[ The bulk of the configuration is represented as an array of Given an image name, a single A prefix of the user-specified image name, i.e. using one of the following formats: The user-specified image name must start with the specified 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 Accepts the same format as the requests for the image An array of TOML tables specifying (possibly-partial) mirrors for the Note: Redirection and mirrors are currently processed only when reading images, not when pushing to a registry; that may change in the future. Given the above, a pull of in order, and use the first one that exists. VERSION 1 can be used as alternative to the Version 2, but it does not support using registry mirrors, longest-prefix matches, or location rewriting. The TOML format is used to build a simple list of registries under three categories: 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 that insecure registries can be used for any registry, not just the registries listed under search. The The following example configuration defines two searchable registries, one insecure registry, and two blocked registries. Mar 2019, Added additional configuration format by Sascha Grunert sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩ Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩ Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩ Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com ⟨mailto:bbaude@redhat.com⟩ buildah(1), containers-transports(5), podman(1), podman-build(1), podman-info(1), podman-pull(1), podman-search(1).Description
/etc/containers/registries.conf
.Formats
Version 2
registries.conf
and is currently in beta. This means in general Version 1 should be used in production environments for now.Global Settings
unqualified-search-registries
:
port] registries to try when pulling an unqualified image, in order.NAMESPACED [[registry]] SETTINGS
[[registry]]
TOML tables; the settings may therefore differ among different registries as well as among different namespaces/repositories within a registry.Choosing a [[registry]] TOML table
[[registry]]
TOML table is chosen based on its prefix
field.prefix
:
port]:
port]/
namespace[/
_namespace_…]:
port]/
namespace[/
_namespace_…]/
repo:
port]/
namespace[/
_namespace_…]/
repo(:
_tag|@
digest)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).Per-namespace settings
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.Remapping and mirroring registries
Dockerfile
s, or to add redundancy).location
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: Givenprefix = "example.com/foo"
location = "internal-registry-for-example.net/bar"
example.com/foo/myimage:latest
will actually work with the internal-registry-for-example.net/bar/myimage:latest
image.mirror
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.Example
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
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/myimage:latest
Version 1
registries.search
, registries.insecure
, and registries.block
. You can list multiple registries using a comma separated list.registries.insecure
and registries.block
lists have the same meaning as the insecure
and blocked
fields in Version 2.Example
[registries.search]
registries = ['registry1.com', 'registry2.com']
[registries.insecure]
registries = ['registry3.com']
[registries.block]
registries = ['registry.untrusted.com', 'registry.unsafe.com']
History
Referenced By