6a0200
% CONTAINERS-REGISTRIES.D(5) Registries.d Man Page
6a0200
% Miloslav Trmač
6a0200
% August 2016
6a0200
6a0200
# NAME
6a0200
containers-registries.d - Directory for various registries configurations
6a0200
6a0200
# DESCRIPTION
6a0200
6a0200
The registries configuration directory contains configuration for various registries
6a0200
(servers storing remote container images), and for content stored in them,
6a0200
so that the configuration does not have to be provided in command-line options over and over for every command,
6a0200
and so that it can be shared by all users of containers/image.
6a0200
6a0200
By default (unless overridden at compile-time), the registries configuration directory is `/etc/containers/registries.d`;
6a0200
applications may allow using a different directory instead.
6a0200
6a0200
## Directory Structure
6a0200
6a0200
The directory may contain any number of files with the extension `.yaml`,
6a0200
each using the YAML format.  Other than the mandatory extension, names of the files
6a0200
don’t matter.
6a0200
6a0200
The contents of these files are merged together; to have a well-defined and easy to understand
6a0200
behavior, there can be only one configuration section describing a single namespace within a registry
6a0200
(in particular there can be at most one one `default-docker` section across all files,
2d4258
and there can be at most one instance of any key under the `docker` section;
6a0200
these sections are documented later).
6a0200
6a0200
Thus, it is forbidden to have two conflicting configurations for a single registry or scope,
6a0200
and it is also forbidden to split a configuration for a single registry or scope across
6a0200
more than one file (even if they are not semantically in conflict).
6a0200
6a0200
## Registries, Scopes and Search Order
6a0200
6a0200
Each YAML file must contain a “YAML mapping” (key-value pairs).  Two top-level keys are defined:
6a0200
6a0200
- `default-docker` is the _configuration section_ (as documented below)
6a0200
   for registries implementing "Docker Registry HTTP API V2".
6a0200
6a0200
   This key is optional.
6a0200
6a0200
- `docker` is a mapping, using individual registries implementing "Docker Registry HTTP API V2",
6a0200
   or namespaces and individual images within these registries, as keys;
6a0200
   the value assigned to any such key is a _configuration section_.
6a0200
6a0200
   This key is optional.
6a0200
6a0200
   Scopes matching individual images are named Docker references *in the fully expanded form*, either
6a0200
   using a tag or digest. For example, `docker.io/library/busybox:latest` (*not* `busybox:latest`).
6a0200
6a0200
   More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest),
6a0200
   a repository namespace, or a registry host (and a port if it differs from the default).
6a0200
6a0200
   Note that if a registry is accessed using a hostname+port configuration, the port-less hostname
6a0200
   is _not_ used as parent scope.
6a0200
6a0200
When searching for a configuration to apply for an individual container image, only
6a0200
the configuration for the most-precisely matching scope is used; configuration using
6a0200
more general scopes is ignored.  For example, if _any_ configuration exists for
6a0200
`docker.io/library/busybox`, the configuration for `docker.io` is ignored
6a0200
(even if some element of the configuration is defined for `docker.io` and not for `docker.io/library/busybox`).
6a0200
6a0200
## Individual Configuration Sections
6a0200
6a0200
A single configuration section is selected for a container image using the process
6a0200
described above.  The configuration section is a YAML mapping, with the following keys:
6a0200
6a0200
- `sigstore-staging` defines an URL of of the signature storage, used for editing it (adding or deleting signatures).
6a0200
6a0200
   This key is optional; if it is missing, `sigstore` below is used.
6a0200
6a0200
- `sigstore` defines an URL of the signature storage.
6a0200
   This URL is used for reading existing signatures,
6a0200
   and if `sigstore-staging` does not exist, also for adding or removing them.
6a0200
6a0200
   This key is optional; if it is missing, no signature storage is defined (no signatures
6a0200
   are download along with images, adding new signatures is possible only if `sigstore-staging` is defined).
6a0200
6a0200
## Examples
6a0200
6a0200
### Using Containers from Various Origins
6a0200
6a0200
The following demonstrates how to to consume and run images from various registries and namespaces:
6a0200
6a0200
```yaml
6a0200
docker:
6a0200
    registry.database-supplier.com:
6a0200
        sigstore: https://sigstore.database-supplier.com
6a0200
    distribution.great-middleware.org:
6a0200
        sigstore: https://security-team.great-middleware.org/sigstore
6a0200
    docker.io/web-framework:
6a0200
        sigstore: https://sigstore.web-framework.io:8080
6a0200
```
6a0200
6a0200
### Developing and Signing Containers, Staging Signatures
6a0200
6a0200
For developers in `example.com`:
6a0200
6a0200
- Consume most container images using the public servers also used by clients.
2d4258
- Use a separate signature storage for an container images in a namespace corresponding to the developers' department, with a staging storage used before publishing signatures.
6a0200
- Craft an individual exception for a single branch a specific developer is working on locally.
6a0200
6a0200
```yaml
6a0200
docker:
6a0200
    registry.example.com:
6a0200
        sigstore: https://registry-sigstore.example.com
6a0200
    registry.example.com/mydepartment:
6a0200
        sigstore: https://sigstore.mydepartment.example.com
6a0200
        sigstore-staging: file:///mnt/mydepartment/sigstore-staging
6a0200
    registry.example.com/mydepartment/myproject:mybranch:
6a0200
        sigstore: http://localhost:4242/sigstore
6a0200
        sigstore-staging: file:///home/useraccount/webroot/sigstore
6a0200
```
6a0200
6a0200
### A Global Default
6a0200
6a0200
If a company publishes its products using a different domain, and different registry hostname for each of them, it is still possible to use a single signature storage server
6a0200
without listing each domain individually. This is expected to rarely happen, usually only for staging new signatures.
6a0200
6a0200
```yaml
6a0200
default-docker:
6a0200
    sigstore-staging: file:///mnt/company/common-sigstore-staging
6a0200
```
6a0200
6a0200
# AUTHORS
6a0200
6a0200
Miloslav Trmač <mitr@redhat.com>