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