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 By default, the configuration file is located at /etc/containers/reg‐
20 istries.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 EXAMPLE
138 unqualified-search-registries = ["example.com"]
139 [[registry]]
141 prefix = "example.com/foo"
142 insecure = false
143 blocked = false
144 location = "internal-registry-for-example.com/bar"
145 [[registry.mirror]]
147 location = "example-mirror-0.local/mirror-for-foo"
148 [[registry.mirror]]
150 location = "example-mirror-1.local/mirrors/foo"
151 insecure = true
152 Given the above, a pull of example.com/foo/image:latest will try:
156 1. example-mirror-0.local/mirror-for-foo/image:latest
157 2. example-mirror-1.local/mirrors/foo/image:latest
158 3. internal-registry-for-example.net/bar/myimage:latest
159 in order, and use the first one that exists.
162
165 VERSION 1 can be used as alternative to the VERSION 2, but it does not
166 support using registry mirrors, longest-prefix matches, or location
167 rewriting.
168 The TOML format is used to build a simple list of registries under
171 three categories: registries.search, registries.insecure, and reg‐
172 istries.block. You can list multiple registries using a comma sepa‐
173 rated list.
174 Search registries are used when the caller of a container runtime does
177 not fully specify the container image that they want to execute. These
178 registries are prepended onto the front of the specified container
179 image until the named image is found at a registry.
180 Note that insecure registries can be used for any registry, not just
183 the registries listed under search.
184 The registries.insecure and registries.block lists have the same mean‐
187 ing as the insecure and blocked fields in VERSION 2.
188 EXAMPLE
191 The following example configuration defines two searchable registries,
192 one insecure registry, and two blocked registries.
193 [registries.search]
196 registries = ['registry1.com', 'registry2.com']
197 [registries.insecure]
199 registries = ['registry3.com']
200 [registries.block]
202 registries = ['registry.untrusted.com', 'registry.unsafe.com']
203
208 Mar 2019, Added additional configuration format by Sascha Grunert
209 sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
210 Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
213 vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
214 Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com
217 ⟨mailto:tsweeney@redhat.com⟩
218 Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com
221 ⟨mailto:bbaude@redhat.com⟩
222configuration reCgOiNsTtArIyNERS-REGISTRIES.CONF(5)(System-wide)