containers-registries.d(5)

1CONTAINERS-REGISTRIES.D(5)(Registries.dC)ONTAINERS-REGISTRIES.D(5)(Registries.d)
2
3
4
5Miloslav Trmač August 2016
6
7

NAME

9       containers-registries.d  -  Directory for various registries configura‐
10       tions
11
12
13

DESCRIPTION

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
21
22       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
27

Directory Structure

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
33
34       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
41
42       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
47

Registries, Scopes and Search Order

49       Each  YAML  file  must contain a “YAML mapping” (key-value pairs).  Two
50       top-level keys are defined:
51
52
53              • default-docker is the configuration section (as documented be‐
54                low)  for  registries  implementing  "Docker Registry HTTP API
55                V2".
56
57
58
59       This key is optional.
60
61
62              • 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
67
68
69       This key is optional.
70
71
72       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
77
78       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
83
84       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
88
89       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
96
97   Built-in Defaults
98       If  no  docker section can be found for the container image, and no de‐
99       fault-docker   section   is   configured,   the   default    directory,
100       /var/lib/containers/sigstore  for  root and $HOME/.local/share/contain‐
101       ers/sigstore for unprivileged user,  will be used for reading and writ‐
102       ing signatures.
103
104

Individual Configuration Sections

106       A  single configuration section is selected for a container image using
107       the process described above.  The configuration section is a YAML  map‐
108       ping, with the following keys:
109
110
111              • sigstore-staging  defines  an URL of of the signature storage,
112                used for editing it (adding or deleting signatures).
113
114
115
116       This key is optional; if it is missing, sigstore below is used.
117
118
119              • sigstore defines an URL of the signature storage.  This URL is
120                used  for reading existing signatures, and if sigstore-staging
121                does not exist, also for adding or removing them.
122
123
124
125       This key is optional; if it is missing, no signature storage is defined
126       (no signatures
127          are  download  along  with images, adding new signatures is possible
128       only if sigstore-staging is defined).
129
130

Examples

132   Using Containers from Various Origins
133       The following demonstrates how to to consume and run images from  vari‐
134       ous registries and namespaces:
135
136
137              docker:
138                  registry.database-supplier.com:
139                      sigstore: https://sigstore.database-supplier.com
140                  distribution.great-middleware.org:
141                      sigstore: https://security-team.great-middleware.org/sigstore
142                  docker.io/web-framework:
143                      sigstore: https://sigstore.web-framework.io:8080
144
145
146
147   Developing and Signing Containers, Staging Signatures
148       For developers in example.com:
149
150
151              • Consume  most  container  images using the public servers also
152                used by clients.
153
154              • Use a separate signature storage for an container images in  a
155                namespace  corresponding to the developers' department, with a
156                staging storage used before publishing signatures.
157
158              • Craft an individual exception for a single branch  a  specific
159                developer is working on locally.
160
161
162
163              docker:
164                  registry.example.com:
165                      sigstore: https://registry-sigstore.example.com
166                  registry.example.com/mydepartment:
167                      sigstore: https://sigstore.mydepartment.example.com
168                      sigstore-staging: file:///mnt/mydepartment/sigstore-staging
169                  registry.example.com/mydepartment/myproject:mybranch:
170                      sigstore: http://localhost:4242/sigstore
171                      sigstore-staging: file:///home/useraccount/webroot/sigstore
172
173
174
175   A Global Default
176       If  a company publishes its products using a different domain, and dif‐
177       ferent registry hostname for each of them, it is still possible to  use
178       a single signature storage server without listing each domain individu‐
179       ally. This is expected to rarely happen, usually only for  staging  new
180       signatures.
181
182
183              default-docker:
184                  sigstore-staging: file:///mnt/company/common-sigstore-staging
185
186
187
188

AUTHORS

190       Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩
191
192
193
194Page                                  MCaOnNTAINERS-REGISTRIES.D(5)(Registries.d)