1containers-registries.d(5) Page containers-registries.d(5)
2Miloslav Trmač August 2016
6
9 containers-registries.d - Directory for various registries configura‐
10 tions
11
15 The registries configuration directory contains configuration for vari‐
16 ous registries (servers storing remote container images), and for con‐
17 tent stored in them, so that the configuration does not have to be pro‐
18 vided in command-line options over and over for every command, and so
19 that it can be shared by all users of containers/image.
20 By default, the registries configuration directory is $HOME/.con‐
23 fig/containers/registries.d if it exists, otherwise /etc/contain‐
24 ers/registries.d (unless overridden at compile-time); applications may
25 allow using a different directory instead.
26
29 The directory may contain any number of files with the extension .yaml,
30 each using the YAML format. Other than the mandatory extension, names
31 of the files don’t matter.
32 The contents of these files are merged together; to have a well-defined
35 and easy to understand behavior, there can be only one configuration
36 section describing a single namespace within a registry (in particular
37 there can be at most one one default-docker section across all files,
38 and there can be at most one instance of any key under the docker sec‐
39 tion; these sections are documented later).
40 Thus, it is forbidden to have two conflicting configurations for a sin‐
43 gle registry or scope, and it is also forbidden to split a configura‐
44 tion for a single registry or scope across more than one file (even if
45 they are not semantically in conflict).
46
49 Each YAML file must contain a “YAML mapping” (key-value pairs). Two
50 top-level keys are defined:
51 • default-docker is the configuration section (as documented be‐
54 low) for registries implementing "Docker Registry HTTP API
55 V2".
56 This key is optional.
60 • docker is a mapping, using individual registries implementing
63 "Docker Registry HTTP API V2", or namespaces and individual
64 images within these registries, as keys; the value assigned to
65 any such key is a configuration section.
66 This key is optional.
70 Scopes matching individual images are named Docker references in the
73 fully expanded form, either
74 using a tag or digest. For example, docker.io/library/busybox:latest
75 (not busybox:latest).
76 More general scopes are prefixes of individual-image scopes, and spec‐
79 ify a repository (by omitting the tag or digest),
80 a repository namespace, or a registry host (and a port if it differs
81 from the default).
82 Note that if a registry is accessed using a hostname+port configura‐
85 tion, the port-less hostname
86 is not used as parent scope.
87 When searching for a configuration to apply for an individual container
90 image, only the configuration for the most-precisely matching scope is
91 used; configuration using more general scopes is ignored. For example,
92 if any configuration exists for docker.io/library/busybox, the configu‐
93 ration for docker.io is ignored (even if some element of the configura‐
94 tion is defined for docker.io and not for docker.io/library/busybox).
95 Built-in Defaults
98 If no docker section can be found for the container image, and no de‐
99 fault-docker section is configured:
100 • The default directory, /var/lib/containers/sigstore for root
103 and $HOME/.local/share/containers/sigstore for unprivileged
104 user, will be used for reading and writing signatures.
105 • Sigstore attachments will not be read/written.
107
111 A single configuration section is selected for a container image using
112 the process described above. The configuration section is a YAML map‐
113 ping, with the following keys:
114 • lookaside-staging defines an URL of of the signature storage,
117 used for editing it (adding or deleting signatures).
118 This key is optional; if it is missing, lookaside below is used.
122 • lookaside defines an URL of the signature storage. This URL
125 is used for reading existing signatures, and if lookaside-
126 staging does not exist, also for adding or removing them.
127 This key is optional; if it is missing, no signature storage is defined
131 (no signatures
132 are download along with images, adding new signatures is possible
133 only if lookaside-staging is defined).
134 • use-sigstore-attachments specifies whether sigstore image at‐
137 tachments (signatures, attestations and the like) are going to
138 be read/written along with the image. If disabled, the images
139 are treated as if no attachments exist; attempts to write at‐
140 tachments fail.
141
145 Using Containers from Various Origins
146 The following demonstrates how to to consume and run images from vari‐
147 ous registries and namespaces:
148 docker:
151 registry.database-supplier.com:
152 lookaside: https://lookaside.database-supplier.com
153 distribution.great-middleware.org:
154 lookaside: https://security-team.great-middleware.org/lookaside
155 docker.io/web-framework:
156 lookaside: https://lookaside.web-framework.io:8080
157 Developing and Signing Containers, Staging Signatures
161 For developers in example.com:
162 • Consume most container images using the public servers also
165 used by clients.
166 • Use a separate signature storage for an container images in a
168 namespace corresponding to the developers' department, with a
169 staging storage used before publishing signatures.
170 • Craft an individual exception for a single branch a specific
172 developer is working on locally.
173 docker:
177 registry.example.com:
178 lookaside: https://registry-lookaside.example.com
179 registry.example.com/mydepartment:
180 lookaside: https://lookaside.mydepartment.example.com
181 lookaside-staging: file:///mnt/mydepartment/lookaside-staging
182 registry.example.com/mydepartment/myproject:mybranch:
183 lookaside: http://localhost:4242/lookaside
184 lookaside-staging: file:///home/useraccount/webroot/lookaside
185 A Global Default
189 If a company publishes its products using a different domain, and dif‐
190 ferent registry hostname for each of them, it is still possible to use
191 a single signature storage server without listing each domain individu‐
192 ally. This is expected to rarely happen, usually only for staging new
193 signatures.
194 default-docker:
197 lookaside-staging: file:///mnt/company/common-lookaside-staging
198
203 Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩
204Man Registries.d containers-registries.d(5)