1CONTAINERS-REGISTRIES.D(5)(Registries.dC)ONTAINERS-REGISTRIES.D(5)(Registries.d)
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
54 below) 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
98 A single configuration section is selected for a container image using
99 the process described above. The configuration section is a YAML map‐
100 ping, with the following keys:
101 · sigstore-staging defines an URL of of the signature storage,
104 used for editing it (adding or deleting signatures).
105 This key is optional; if it is missing, sigstore below is used.
109 · sigstore defines an URL of the signature storage. This URL is
112 used for reading existing signatures, and if sigstore-staging
113 does not exist, also for adding or removing them.
114 This key is optional; if it is missing, no signature storage is defined
118 (no signatures
119 are download along with images, adding new signatures is possible
120 only if sigstore-staging is defined).
121
124 Using Containers from Various Origins
125 The following demonstrates how to to consume and run images from vari‐
126 ous registries and namespaces:
127 docker:
130 registry.database-supplier.com:
131 sigstore: https://sigstore.database-supplier.com
132 distribution.great-middleware.org:
133 sigstore: https://security-team.great-middleware.org/sigstore
134 docker.io/web-framework:
135 sigstore: https://sigstore.web-framework.io:8080
136 Developing and Signing Containers, Staging Signatures
140 For developers in example.com:
141 · Consume most container images using the public servers also
144 used by clients.
145 · Use a separate signature storage for an container images in a
147 namespace corresponding to the developers' department, with a
148 staging storage used before publishing signatures.
149 · Craft an individual exception for a single branch a specific
151 developer is working on locally.
152 docker:
156 registry.example.com:
157 sigstore: https://registry-sigstore.example.com
158 registry.example.com/mydepartment:
159 sigstore: https://sigstore.mydepartment.example.com
160 sigstore-staging: file:///mnt/mydepartment/sigstore-staging
161 registry.example.com/mydepartment/myproject:mybranch:
162 sigstore: http://localhost:4242/sigstore
163 sigstore-staging: file:///home/useraccount/webroot/sigstore
164 A Global Default
168 If a company publishes its products using a different domain, and dif‐
169 ferent registry hostname for each of them, it is still possible to use
170 a single signature storage server without listing each domain individu‐
171 ally. This is expected to rarely happen, usually only for staging new
172 signatures.
173 default-docker:
176 sigstore-staging: file:///mnt/company/common-sigstore-staging
177
182 Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩
183Page MCaOnNTAINERS-REGISTRIES.D(5)(Registries.d)