Update containers-registries.conf.md man page for mirroring support
Update regsitries.conf file to match containers/image
This commit is contained in:
Daniel J Walsh
parent
6ce0407a60
commit
22ca95d8ef
@ -18,57 +18,127 @@ 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.
|
||||
### GLOBAL SETTINGS
|
||||
|
||||
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`.
|
||||
`unqualified-search-registries`
|
||||
: An array of _host_[`:`_port_] registries to try when pulling an unqualified image, in order.
|
||||
|
||||
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.
|
||||
### NAMESPACED `[[registry]]` SETTINGS
|
||||
|
||||
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`.
|
||||
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.
|
||||
|
||||
If `blocked = true` then it is not allowed to pull images from that 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]]
|
||||
location = "example.com"
|
||||
insecure = false
|
||||
prefix = "example.com/foo"
|
||||
unqualified-search = false
|
||||
insecure = false
|
||||
blocked = false
|
||||
mirror = [
|
||||
{ location = "example-mirror-0.local", insecure = false },
|
||||
{ location = "example-mirror-1.local", insecure = true }
|
||||
]
|
||||
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 is not capable in
|
||||
using registry mirrors or a prefix.
|
||||
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 for registries under three
|
||||
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.
|
||||
|
||||
@ -76,11 +146,11 @@ Search registries are used when the caller of a container runtime does not fully
|
||||
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
|
||||
Note that 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.
|
||||
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
|
||||
|
||||
@ -1,25 +1,82 @@
|
||||
# This is a system-wide configuration file used to
|
||||
# keep track of registries for various container backends.
|
||||
# It adheres to TOML format and does not support recursive
|
||||
# lists of registries.
|
||||
|
||||
# The default location for this configuration file is /etc/containers/registries.conf.
|
||||
|
||||
# The only valid categories are: 'registries.search', 'registries.insecure',
|
||||
# and 'registries.block'.
|
||||
|
||||
# For more information on this configuration file, see containers-registries.conf(5).
|
||||
#
|
||||
# There are multiple versions of the configuration syntax available, where the
|
||||
# second iteration is backwards compatible to the first one. Mixing up both
|
||||
# formats will result in an runtime error.
|
||||
#
|
||||
# The initial configuration format looks like this:
|
||||
#
|
||||
# Registries to search for images that are not fully-qualified.
|
||||
# i.e. foobar.com/my_image:latest vs my_image:latest
|
||||
[registries.search]
|
||||
registries = ['docker.io', 'registry.fedoraproject.org', 'quay.io', 'registry.access.redhat.com', 'registry.centos.org']
|
||||
|
||||
# If you need to access insecure registries, add the registry's fully-qualified name.
|
||||
# An insecure registry is one that does not have a valid SSL certificate or only does HTTP.
|
||||
# Registries that do not use TLS when pulling images or uses self-signed
|
||||
# certificates.
|
||||
[registries.insecure]
|
||||
registries = []
|
||||
|
||||
|
||||
# If you need to block pull access from a registry, uncomment the section below
|
||||
# and add the registries fully-qualified name.
|
||||
#
|
||||
# Docker only
|
||||
# Blocked Registries, blocks the `docker daemon` from pulling from the blocked registry. If you specify
|
||||
# "*", then the docker daemon will only be allowed to pull from registries listed above in the search
|
||||
# registries. Blocked Registries is deprecated because other container runtimes and tools will not use it.
|
||||
# It is recommended that you use the trust policy file /etc/containers/policy.json to control which
|
||||
# registries you want to allow users to pull and push from. policy.json gives greater flexibility, and
|
||||
# supports all container runtimes and tools including the docker daemon, cri-o, buildah ...
|
||||
# The atomic CLI `atomic trust` can be used to easily configure the policy.json file.
|
||||
[registries.block]
|
||||
registries = []
|
||||
|
||||
# The second version of the configuration format allows to specify registry
|
||||
# mirrors:
|
||||
#
|
||||
# # An array of host[:port] registries to try when pulling an unqualified image, in order.
|
||||
# unqualified-search-registries = ["example.com"]
|
||||
#
|
||||
# [[registry]]
|
||||
# # The "prefix" field is used to choose the relevant [[registry]] TOML table;
|
||||
# # (only) the TOML table with the longest match for the input image name
|
||||
# # (taking into account namespace/repo/tag/digest separators) is used.
|
||||
# #
|
||||
# # If the prefix field is missing, it defaults to be the same as the "location" field.
|
||||
# prefix = "example.com/foo"
|
||||
#
|
||||
# # If true, unencrypted HTTP as well as TLS connections with untrusted
|
||||
# # certificates are allowed.
|
||||
# insecure = false
|
||||
#
|
||||
# # If true, pulling images with matching names is forbidden.
|
||||
# blocked = false
|
||||
#
|
||||
# # 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.
|
||||
# location = internal-registry-for-example.com/bar"
|
||||
#
|
||||
# # (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
|
||||
# [[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.
|
||||
|
||||
@ -39,7 +39,7 @@ Epoch: 1
|
||||
Epoch: 0
|
||||
%endif
|
||||
Version: 0.1.38
|
||||
Release: 1.dev.git%{shortcommit0}%{?dist}
|
||||
Release: 2.dev.git%{shortcommit0}%{?dist}
|
||||
Summary: Inspect Docker images and repositories on registries
|
||||
License: ASL 2.0
|
||||
URL: %{git0}
|
||||
@ -399,6 +399,10 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath}
|
||||
%{_datadir}/bash-completion/completions/%{name}
|
||||
|
||||
%changelog
|
||||
* Tue Jul 9 2019 Dan Walsh (Bot) <dwalsh+bot@fedoraproject.org> - 1:0.1.38-2.dev
|
||||
- Update containers-registries.conf.md man page for mirroring support
|
||||
- Update regsitries.conf file to match containers/image
|
||||
|
||||
* Mon Jun 24 2019 Dan Walsh (Bot) <dwalsh+bot@fedoraproject.org> - 1:0.1.38-1.dev
|
||||
- Bump up to 1:0.1.38
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user