178 lines
6.6 KiB
Markdown
178 lines
6.6 KiB
Markdown
% 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.
|
|
|
|
### GLOBAL SETTINGS
|
|
|
|
`unqualified-search-registries`
|
|
: An array of _host_[`:`_port_] registries to try when pulling an unqualified image, in order.
|
|
|
|
### NAMESPACED `[[registry]]` SETTINGS
|
|
|
|
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.
|
|
|
|
#### Choosing a `[[registry]]` TOML table
|
|
|
|
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).
|
|
|
|
#### 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
|
|
|
|
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 `Dockerfile`s, 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.
|
|
|
|
### 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
|
|
```
|
|
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/myimage:latest`
|
|
|
|
in order, and use the first one that exists.
|
|
|
|
## VERSION 1
|
|
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: `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 that insecure registries can be used for any registry, not just the registries listed
|
|
under search.
|
|
|
|
The `registries.insecure` and `registries.block` lists have the same meaning as the
|
|
`insecure` and `blocked` fields in 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>
|