1CONTAINERS-REGISTRIES.CONF(5)(System-CwfOiiNdlTeeA)INERS-REGISTRIES.CONF(5)(System-wide)
2Brent Baude Aug 2017
6
9 containers-registries.conf - Syntax of System Registry Configuration
10 File
11
15 The CONTAINERS-REGISTRIES configuration file is a system-wide configu‐
16 ration file for container image registries. The file format is TOML.
17 Container engines will use the $HOME/.config/containers/registries.conf
20 if it exists, otherwise they will use /etc/containers/registries.conf
21
26 VERSION 2 is the latest format of the registries.conf and is currently
27 in beta. This means in general VERSION 1 should be used in production
28 environments for now.
29 GLOBAL SETTINGS
32 unqualified-search-registries
33 An array of host[:port] registries to try when pulling an
34 unqualified image, in order.
35 NAMESPACED [[registry]] SETTINGS
38 The bulk of the configuration is represented as an array of [[reg‐
39 istry]] TOML tables; the settings may therefore differ among different
40 registries as well as among different namespaces/repositories within a
41 registry.
42 Choosing a [[registry]] TOML table
45 Given an image name, a single [[registry]] TOML table is chosen based
46 on its prefix field.
47 prefix A prefix of the user-specified image name, i.e. using one of the
50 following formats:
51 · host[:port]
53 · host[:port]/namespace[/_namespace_…]
55 · host[:port]/namespace[/_namespace_…]/repo
57 · host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)
59 The user-specified image name must start with the specified prefix (and
61 continue with the appropriate separator) for a particular [[registry]]
62 TOML table to be considered; (only) the TOML table with the longest
63 match is used.As a special case, the prefix field can be missing; if
64 so, it defaults to the value of the location field (described below).
65 Per-namespace settings
68 insecure
69 true or false. By default, container runtimes require TLS when
70 retrieving images from a registry. If insecure is set to true,
71 unencrypted HTTP as well as TLS connections with untrusted cer‐
72 tificates are allowed.
73 blocked
76 true or false. If true, pulling images with matching names is
77 forbidden.
78 Remapping and mirroring registries
81 The user-specified image reference is, primarily, a "logical" image
82 name, always used for naming the image. By default, the image refer‐
83 ence also directly specifies the registry and repository to use, but
84 the following options can be used to redirect the underlying accesses
85 to different registry servers or locations (e.g. to support configura‐
86 tions with no access to the internet without having to change Docker‐
87 files, or to add redundancy).
88 location
91 Accepts the same format as the prefix field, and specifies the
92 physical location of the prefix-rooted namespace.By default,
93 this equal to prefix (in which case prefix can be omitted and
94 the [[registry]] TOML table can only specify location).Example:
95 Given
96 prefix = "example.com/foo"
98 location = "internal-registry-for-example.net/bar"
99 requests for the image example.com/foo/myimage:latest will actually
101 work with the internal-registry-for-example.net/bar/myimage:latest
102 image.
103 mirror An array of TOML tables specifying (possibly-partial) mirrors
106 for the prefix-rooted namespace.The mirrors are attempted in the
107 specified order; the first one that can be contacted and con‐
108 tains the image will be used (and if none of the mirrors con‐
109 tains the image, the primary location specified by the reg‐
110 istry.location field, or using the unmodified user-specified
111 reference, is tried last).Each TOML table in the mirror array
112 can contain the following fields, with the same semantics as if
113 specified in the [[registry]] TOML table directly:
114 · location
116 · insecure
118 mirror-by-digest-only
123 true or false. If true, mirrors will only be used during
124 pulling if the image reference includes a digest. Referencing
125 an image by digest ensures that the same is always used (whereas
126 referencing an image by a tag may cause different registries to
127 return different images if the tag mapping is out of sync).Note
128 that if this is true, images referenced by a tag will only use
129 the primary registry, failing if that registry is not accessi‐
130 ble.
131 Note: Redirection and mirrors are currently processed only when reading
134 images, not when pushing to a registry; that may change in the future.
135 Normalization of docker.io references
138 The Docker Hub docker.io is handled in a special way: every push and
139 pull operation gets internally normalized with /library if no other
140 specific namespace is defined (for example on docker.io/names‐
141 pace/image).
142 (Note that the above-described normalization happens to match the
145 behavior of Docker.)
146 This means that a pull of docker.io/alpine will be internally trans‐
149 lated to docker.io/library/alpine. A pull of docker.io/user/alpine will
150 not be rewritten because this is already the correct remote path.
151 Therefore, to remap or mirror the docker.io images in the (implied)
154 /library namespace (or that whole namespace), the prefix and location
155 fields in this configuration file must explicitly include that /library
156 namespace. For example prefix = "docker.io/library/alpine" and not pre‐
157 fix = "docker.io/alpine". The latter would match the docker.io/alpine/*
158 repositories but not the docker.io/[library/]alpine image).
159 EXAMPLE
162 unqualified-search-registries = ["example.com"]
163 [[registry]]
165 prefix = "example.com/foo"
166 insecure = false
167 blocked = false
168 location = "internal-registry-for-example.com/bar"
169 [[registry.mirror]]
171 location = "example-mirror-0.local/mirror-for-foo"
172 [[registry.mirror]]
174 location = "example-mirror-1.local/mirrors/foo"
175 insecure = true
176 Given the above, a pull of example.com/foo/image:latest will try:
180 1. example-mirror-0.local/mirror-for-foo/image:latest
181 2. example-mirror-1.local/mirrors/foo/image:latest
182 3. internal-registry-for-example.net/bar/image:latest
183 in order, and use the first one that exists.
186
189 VERSION 1 can be used as alternative to the VERSION 2, but it does not
190 support using registry mirrors, longest-prefix matches, or location
191 rewriting.
192 The TOML format is used to build a simple list of registries under
195 three categories: registries.search, registries.insecure, and reg‐
196 istries.block. You can list multiple registries using a comma sepa‐
197 rated list.
198 Search registries are used when the caller of a container runtime does
201 not fully specify the container image that they want to execute. These
202 registries are prepended onto the front of the specified container
203 image until the named image is found at a registry.
204 Note that insecure registries can be used for any registry, not just
207 the registries listed under search.
208 The registries.insecure and registries.block lists have the same mean‐
211 ing as the insecure and blocked fields in VERSION 2.
212 EXAMPLE
215 The following example configuration defines two searchable registries,
216 one insecure registry, and two blocked registries.
217 [registries.search]
220 registries = ['registry1.com', 'registry2.com']
221 [registries.insecure]
223 registries = ['registry3.com']
224 [registries.block]
226 registries = ['registry.untrusted.com', 'registry.unsafe.com']
227
232 We recommend always using fully qualified image names including the
233 registry server (full dns name), namespace, image name, and tag (e.g.,
234 registry.redhat.io/ubi8/ubi:latest). When using short names, there is
235 always an inherent risk that the image being pulled could be spoofed.
236 For example, a user wants to pull an image named foobar from a registry
237 and expects it to come from myregistry.com. If myregistry.com is not
238 first in the search list, an attacker could place a different foobar
239 image at a registry earlier in the search list. The user would acciden‐
240 tally pull and run the attacker's image and code rather than the
241 intended content. We recommend only adding registries which are com‐
242 pletely trusted, i.e. registries which don't allow unknown or anonymous
243 users to create accounts with arbitrary names. This will prevent an
244 image from being spoofed, squatted or otherwise made insecure. If it
245 is necessary to use one of these registries, it should be added at the
246 end of the list.
247 It is recommended to use fully-qualified images for pulling as the des‐
250 tination registry is unambiguous. Pulling by digest (i.e.,
251 quay.io/repository/name@digest) further eliminates the ambiguity of
252 tags.
253
257 containers-certs.d(5)
258
262 Dec 2019, Warning added for unqualified image names by Tom Sweeney
263 tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩
264 Mar 2019, Added additional configuration format by Sascha Grunert
267 sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
268 Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
271 vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
272 Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com
275 ⟨mailto:tsweeney@redhat.com⟩
276 Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com
279 ⟨mailto:bbaude@redhat.com⟩
280configuration reCgOiNsTtArIyNERS-REGISTRIES.CONF(5)(System-wide)