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 (unless overridden at compile-time), the registries configu‐
23 ration directory is /etc/containers/registries.d; applications may
24 allow using a different directory instead.
25
28 The directory may contain any number of files with the extension .yaml,
29 each using the YAML format. Other than the mandatory extension, names
30 of the files don’t matter.
31 The contents of these files are merged together; to have a well-defined
34 and easy to understand behavior, there can be only one configuration
35 section describing a single namespace within a registry (in particular
36 there can be at most one one default-docker section across all files,
37 and there can be at most one instance of any key under the docker sec‐
38 tion; these sections are documented later).
39 Thus, it is forbidden to have two conflicting configurations for a sin‐
42 gle registry or scope, and it is also forbidden to split a configura‐
43 tion for a single registry or scope across more than one file (even if
44 they are not semantically in conflict).
45
48 Each YAML file must contain a “YAML mapping” (key-value pairs). Two
49 top-level keys are defined:
50 · default-docker is the configuration section (as documented
53 below) for registries implementing "Docker Registry HTTP API
54 V2".
55 This key is optional.
59 · docker is a mapping, using individual registries implementing
62 "Docker Registry HTTP API V2", or namespaces and individual
63 images within these registries, as keys; the value assigned to
64 any such key is a configuration section.
65 This key is optional.
69 Scopes matching individual images are named Docker references in the
72 fully expanded form, either
73 using a tag or digest. For example, docker.io/library/busybox:latest
74 (not busybox:latest).
75 More general scopes are prefixes of individual-image scopes, and spec‐
78 ify a repository (by omitting the tag or digest),
79 a repository namespace, or a registry host (and a port if it differs
80 from the default).
81 Note that if a registry is accessed using a hostname+port configura‐
84 tion, the port-less hostname
85 is not used as parent scope.
86 When searching for a configuration to apply for an individual container
89 image, only the configuration for the most-precisely matching scope is
90 used; configuration using more general scopes is ignored. For example,
91 if any configuration exists for docker.io/library/busybox, the configu‐
92 ration for docker.io is ignored (even if some element of the configura‐
93 tion is defined for docker.io and not for docker.io/library/busybox).
94
97 A single configuration section is selected for a container image using
98 the process described above. The configuration section is a YAML map‐
99 ping, with the following keys:
100 · sigstore-staging defines an URL of of the signature storage,
103 used for editing it (adding or deleting signatures).
104 This key is optional; if it is missing, sigstore below is used.
108 · sigstore defines an URL of the signature storage. This URL is
111 used for reading existing signatures, and if sigstore-staging
112 does not exist, also for adding or removing them.
113 This key is optional; if it is missing, no signature storage is defined
117 (no signatures
118 are download along with images, adding new signatures is possible
119 only if sigstore-staging is defined).
120
123 Using Containers from Various Origins
124 The following demonstrates how to to consume and run images from vari‐
125 ous registries and namespaces:
126 docker:
129 registry.database-supplier.com:
130 sigstore: https://sigstore.database-supplier.com
131 distribution.great-middleware.org:
132 sigstore: https://security-team.great-middleware.org/sigstore
133 docker.io/web-framework:
134 sigstore: https://sigstore.web-framework.io:8080
135 Developing and Signing Containers, Staging Signatures
139 For developers in example.com:
140 · Consume most container images using the public servers also
143 used by clients.
144 · Use a separate signature storage for an container images in a
146 namespace corresponding to the developers' department, with a
147 staging storage used before publishing signatures.
148 · Craft an individual exception for a single branch a specific
150 developer is working on locally.
151 docker:
155 registry.example.com:
156 sigstore: https://registry-sigstore.example.com
157 registry.example.com/mydepartment:
158 sigstore: https://sigstore.mydepartment.example.com
159 sigstore-staging: file:///mnt/mydepartment/sigstore-staging
160 registry.example.com/mydepartment/myproject:mybranch:
161 sigstore: http://localhost:4242/sigstore
162 sigstore-staging: file:///home/useraccount/webroot/sigstore
163 A Global Default
167 If a company publishes its products using a different domain, and dif‐
168 ferent registry hostname for each of them, it is still possible to use
169 a single signature storage server without listing each domain individu‐
170 ally. This is expected to rarely happen, usually only for staging new
171 signatures.
172 default-docker:
175 sigstore-staging: file:///mnt/company/common-sigstore-staging
176
181 Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩
182Page MCaOnNTAINERS-REGISTRIES.D(5)(Registries.d)