1CONTAINERS-REGISTRIES.CONF(5)(System-CwfOiiNdlTeeA)INERS-REGISTRIES.CONF(5)(System-wide)
2
3
4
5Brent Baude Aug 2017
6
7

NAME

9       containers-registries.conf  -  Syntax  of System Registry Configuration
10       File
11
12
13

DESCRIPTION

15       The CONTAINERS-REGISTRIES configuration file is a system-wide  configu‐
16       ration file for container image registries. The file format is TOML.
17
18
19       By  default,  the configuration file is located at /etc/containers/reg‐
20       istries.conf.
21
22
23

FORMATS

VERSION 2

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
30
31   GLOBAL SETTINGS
32       unqualified-search-registries
33              An array of  host[:port]  registries  to  try  when  pulling  an
34              unqualified image, in order.
35
36
37   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
43
44   Choosing a [[registry]] TOML table
45       Given an image name, a single [[registry]] TOML table is  chosen  based
46       on its prefix field.
47
48
49       prefix A prefix of the user-specified image name, i.e. using one of the
50              following formats:
51
52              · host[:port]
53
54              · host[:port]/namespace[/_namespace_…]
55
56              · host[:port]/namespace[/_namespace_…]/repo
57
58              · host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)
59
60       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
66
67   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
74
75       blocked
76              true  or  false.  If true, pulling images with matching names is
77              forbidden.
78
79
80   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
89
90       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
97              prefix = "example.com/foo"
98              location = "internal-registry-for-example.net/bar"
99
100       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
104
105       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
115              · location
116
117              · insecure
118
119
120
121
122       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
132
133       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
136
137   EXAMPLE
138              unqualified-search-registries = ["example.com"]
139
140              [[registry]]
141              prefix = "example.com/foo"
142              insecure = false
143              blocked = false
144              location = "internal-registry-for-example.com/bar"
145
146              [[registry.mirror]]
147              location = "example-mirror-0.local/mirror-for-foo"
148
149              [[registry.mirror]]
150              location = "example-mirror-1.local/mirrors/foo"
151              insecure = true
152
153
154
155       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
160
161       in order, and use the first one that exists.
162
163

VERSION 1

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
169
170       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
175
176       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
181
182       Note that insecure registries can be used for any  registry,  not  just
183       the registries listed under search.
184
185
186       The  registries.insecure and registries.block lists have the same mean‐
187       ing as the insecure and blocked fields in VERSION 2.
188
189
190   EXAMPLE
191       The following example configuration defines two searchable  registries,
192       one insecure registry, and two blocked registries.
193
194
195              [registries.search]
196              registries = ['registry1.com', 'registry2.com']
197
198              [registries.insecure]
199              registries = ['registry3.com']
200
201              [registries.block]
202              registries = ['registry.untrusted.com', 'registry.unsafe.com']
203
204
205
206

HISTORY

208       Mar  2019,  Added  additional  configuration  format  by Sascha Grunert
209       sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
210
211
212       Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
213       vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
214
215
216       Jun     2018,    Updated    by    Tom    Sweeney    tsweeney@redhat.com
217       ⟨mailto:tsweeney@redhat.com⟩
218
219
220       Aug  2017,  Originally  compiled  by  Brent   Baude   bbaude@redhat.com
221       ⟨mailto:bbaude@redhat.com⟩
222
223
224
225configuration                      reCgOiNsTtArIyNERS-REGISTRIES.CONF(5)(System-wide)
Impressum