Blame containers-registries.d.5.md

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