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