Update containers-registries.conf.md man page for mirroring support

Update regsitries.conf file to match containers/image

containers-registries.conf.5.md

@@ -18,57 +18,127 @@ VERSION 2 is the latest format of the `registries.conf` and is currently in
 beta. This means in general VERSION 1 should be used in production environments
 for now.
 
-Every registry can have its own mirrors configured.  The mirrors will be tested
+### GLOBAL SETTINGS
-in order for the availability of the remote manifest.  This happens currently
-only during an image pull.  If the manifest is not reachable due to connectivity
-issues or the unavailability of the remote manifest, then the next mirror will
-be tested instead.  If no mirror is configured or contains the manifest to be
-pulled, then the initially provided reference will be used as fallback.  It is
-possible to set the `insecure` option per mirror, too.
 
-Furthermore it is possible to specify a `prefix` for a registry.  The `prefix`
+`unqualified-search-registries`
-is used to find the relevant target registry from where the image has to be
+: An array of _host_[`:`_port_] registries to try when pulling an unqualified image, in order.
-pulled.  During the test for the availability of the image, the prefixed
-location will be rewritten to the correct remote location.  This applies to
-mirrors as well as the fallback `location`.  If no prefix is specified, it
-defaults to the specified `location`.  For example, if
-`prefix = "example.com/foo"`, `location = "example.com"` and the image will be
-pulled from `example.com/foo/image`, then the resulting pull will be effectively
-point to `example.com/image`.
 
-By default container runtimes use TLS when retrieving images from a registry.
+### NAMESPACED `[[registry]]` SETTINGS
-If the registry is not setup with TLS, then the container runtime will fail to
-pull images from the registry. If you set `insecure = true` for a registry or a
-mirror you overwrite the `insecure` flag for that specific entry.  This means
-that the container runtime will attempt use unencrypted HTTP to pull the image.
-It also allows you to pull from a registry with self-signed certificates.
 
-If you set the `unqualified-search = true` for the registry, then it is possible
+The bulk of the configuration is represented as an array of `[[registry]]`
-to omit the registry hostname when pulling images.  This feature does not work
+TOML tables; the settings may therefore differ among different registries
-together with a specified `prefix`.
+as well as among different namespaces/repositories within a registry.
 
-If `blocked = true` then it is not allowed to pull images from that registry.
+#### Choosing a `[[registry]]` TOML table
+
+Given an image name, a single `[[registry]]` TOML table is chosen based on its `prefix` field.
+
+`prefix`
+: A prefix of the user-specified image name, i.e. using one of the following formats:
+    - _host_[`:`_port_]
+    - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]
+    - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]`/`_repo_
+    - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]`/`_repo_(`:`_tag|`@`_digest_)
+
+    The user-specified image name must start with the specified `prefix` (and continue
+    with the appropriate separator) for a particular `[[registry]]` TOML table to be
+    considered; (only) the TOML table with the longest match is used.
+
+    As a special case, the `prefix` field can be missing; if so, it defaults to the value
+    of the `location` field (described below).
+
+#### Per-namespace settings
+
+`insecure`
+: `true` or `false`.
+    By default, container runtimes require TLS when retrieving images from a registry.
+    If `insecure` is set to `true`, unencrypted HTTP as well as TLS connections with untrusted
+    certificates are allowed.
+
+`blocked`
+: `true` or `false`.
+    If `true`, pulling images with matching names is forbidden.
+
+#### Remapping and mirroring registries
+
+The user-specified image reference is, primarily, a "logical" image name, always used for naming
+the image.  By default, the image reference also directly specifies the registry and repository
+to use, but the following options can be used to redirect the underlying accesses
+to different registry servers or locations (e.g. to support configurations with no access to the
+internet without having to change `Dockerfile`s, or to add redundancy).
+
+`location`
+: Accepts the same format as the `prefix` field, and specifies the physical location
+    of the `prefix`-rooted namespace.
+
+    By default, this equal to `prefix` (in which case `prefix` can be omitted and the
+    `[[registry]]` TOML table can only specify `location`).
+
+    Example: Given
+    ```
+    prefix = "example.com/foo"
+    location = "internal-registry-for-example.net/bar"
+    ```
+    requests for the image `example.com/foo/myimage:latest` will actually work with the
+    `internal-registry-for-example.net/bar/myimage:latest` image.
+
+`mirror`
+: An array of TOML tables specifying (possibly-partial) mirrors for the
+    `prefix`-rooted namespace.
+
+    The mirrors are attempted in the specified order; the first one that can be
+    contacted and contains the image will be used (and if none of the mirrors contains the image,
+    the primary location specified by the `registry.location` field, or using the unmodified
+    user-specified reference, is tried last).
+
+    Each TOML table in the `mirror` array can contain the following fields, with the same semantics
+    as if specified in the `[[registry]]` TOML table directly:
+    - `location`
+    - `insecure`
+
+`mirror-by-digest-only`
+: `true` or `false`.
+    If `true`, mirrors will only be used during pulling if the image reference includes a digest.
+    Referencing an image by digest ensures that the same is always used
+    (whereas referencing an image by a tag may cause different registries to return
+    different images if the tag mapping is out of sync).
+
+    Note that if this is `true`, images referenced by a tag will only use the primary
+    registry, failing if that registry is not accessible.
+
+*Note*: Redirection and mirrors are currently processed only when reading images, not when pushing
+to a registry; that may change in the future.
 
 ### EXAMPLE
 
 ```
+unqualified-search-registries = ["example.com"]
+
 [[registry]]
-location = "example.com"
-insecure = false
 prefix = "example.com/foo"
-unqualified-search = false
+insecure = false
 blocked = false
-mirror = [
+location = "internal-registry-for-example.com/bar"
-    { location = "example-mirror-0.local", insecure = false },
+
-    { location = "example-mirror-1.local", insecure = true }
+[[registry.mirror]]
-]
+location = "example-mirror-0.local/mirror-for-foo"
+
+[[registry.mirror]]
+location = "example-mirror-1.local/mirrors/foo"
+insecure = true
 ```
+Given the above, a pull of `example.com/foo/image:latest` will try:
+    1. `example-mirror-0.local/mirror-for-foo/image:latest`
+    2. `example-mirror-1.local/mirrors/foo/image:latest`
+    3. `internal-registry-for-example.net/bar/myimage:latest`
+
+in order, and use the first one that exists.
 
 ## VERSION 1
-VERSION 1 can be used as alternative to the VERSION 2, but it is not capable in
+VERSION 1 can be used as alternative to the VERSION 2, but it does not support
-using registry mirrors or a prefix.
+using registry mirrors, longest-prefix matches, or location rewriting.
 
-The TOML_format is used to build a simple list for registries under three
+The TOML format is used to build a simple list of registries under three
 categories: `registries.search`, `registries.insecure`, and `registries.block`.
 You can list multiple registries using a comma separated list.
 
@@ -76,11 +146,11 @@ Search registries are used when the caller of a container runtime does not fully
 container image that they want to execute.  These registries are prepended onto the front
 of the specified container image until the named image is found at a registry.
 
-Note insecure registries can be used for any registry, not just the registries listed
+Note that insecure registries can be used for any registry, not just the registries listed
 under search.
 
-The fields `registries.insecure` and `registries.block` work as like as the
+The `registries.insecure` and `registries.block` lists have the same meaning as the
-`insecure` and `blocked` from VERSION 2.
+`insecure` and `blocked` fields in VERSION 2.
 
 ### EXAMPLE
 The following example configuration defines two searchable registries, one

registries.conf

@@ -1,25 +1,82 @@
-# This is a system-wide configuration file used to
+# For more information on this configuration file, see containers-registries.conf(5).
-# keep track of registries for various container backends.
+#
-# It adheres to TOML format and does not support recursive
+# There are multiple versions of the configuration syntax available, where the
-# lists of registries.
+# second iteration is backwards compatible to the first one. Mixing up both
-
+# formats will result in an runtime error.
-# The default location for this configuration file is /etc/containers/registries.conf.
+#
-
+# The initial configuration format looks like this:
-# The only valid categories are: 'registries.search', 'registries.insecure', 
+#
-# and 'registries.block'.
+# Registries to search for images that are not fully-qualified.
-
+# i.e. foobar.com/my_image:latest vs my_image:latest
 [registries.search]
 registries = ['docker.io', 'registry.fedoraproject.org', 'quay.io', 'registry.access.redhat.com', 'registry.centos.org']
 
-# If you need to access insecure registries, add the registry's fully-qualified name.
+# Registries that do not use TLS when pulling images or uses self-signed
-# An insecure registry is one that does not have a valid SSL certificate or only does HTTP.
+# certificates.
 [registries.insecure]
 registries = []
 
-
+# Blocked Registries, blocks the `docker daemon` from pulling from the blocked registry.  If you specify
-# If you need to block pull access from a registry, uncomment the section below
+# "*", then the docker daemon will only be allowed to pull from registries listed above in the search
-# and add the registries fully-qualified name.
+# registries.  Blocked Registries is deprecated because other container runtimes and tools will not use it.
-#
+# It is recommended that you use the trust policy file /etc/containers/policy.json to control which
-# Docker only
+# registries you want to allow users to pull and push from.  policy.json gives greater flexibility, and
+# supports all container runtimes and tools including the docker daemon, cri-o, buildah ...
+# The atomic CLI `atomic trust` can be used to easily configure the policy.json file.
 [registries.block]
 registries = []
+
+# The second version of the configuration format allows to specify registry
+# mirrors:
+#
+# # An array of host[:port] registries to try when pulling an unqualified image, in order.
+# unqualified-search-registries = ["example.com"]
+#
+# [[registry]]
+# # The "prefix" field is used to choose the relevant [[registry]] TOML table;
+# # (only) the TOML table with the longest match for the input image name
+# # (taking into account namespace/repo/tag/digest separators) is used.
+# #
+# # If the prefix field is missing, it defaults to be the same as the "location" field.
+# prefix = "example.com/foo"
+#
+# # If true, unencrypted HTTP as well as TLS connections with untrusted
+# # certificates are allowed.
+# insecure = false
+#
+# # If true, pulling images with matching names is forbidden.
+# blocked = false
+#
+# # The physical location of the "prefix"-rooted namespace.
+# #
+# # By default, this equal to "prefix" (in which case "prefix" can be omitted
+# # and the [[registry]] TOML table can only specify "location").
+# #
+# # Example: Given
+# #   prefix = "example.com/foo"
+# #   location = "internal-registry-for-example.net/bar"
+# # requests for the image example.com/foo/myimage:latest will actually work with the
+# # internal-registry-for-example.net/bar/myimage:latest image.
+# location = internal-registry-for-example.com/bar"
+#
+# # (Possibly-partial) mirrors for the "prefix"-rooted namespace.
+# #
+# # The mirrors are attempted in the specified order; the first one that can be
+# # contacted and contains the image will be used (and if none of the mirrors contains the image,
+# # the primary location specified by the "registry.location" field, or using the unmodified
+# # user-specified reference, is tried last).
+# #
+# # Each TOML table in the "mirror" array can contain the following fields, with the same semantics
+# # as if specified in the [[registry]] TOML table directly:
+# # - location
+# # - insecure
+# [[registry.mirror]]
+# location = "example-mirror-0.local/mirror-for-foo"
+# [[registry.mirror]]
+# location = "example-mirror-1.local/mirrors/foo"
+# insecure = true
+# # Given the above, a pull of example.com/foo/image:latest will try:
+# # 1. example-mirror-0.local/mirror-for-foo/image:latest
+# # 2. example-mirror-1.local/mirrors/foo/image:latest
+# # 3. internal-registry-for-example.net/bar/myimage:latest
+# # in order, and use the first one that exists.

skopeo.spec

@@ -39,7 +39,7 @@ Epoch: 1
 Epoch: 0
 %endif
 Version: 0.1.38
-Release: 1.dev.git%{shortcommit0}%{?dist}
+Release: 2.dev.git%{shortcommit0}%{?dist}
 Summary: Inspect Docker images and repositories on registries
 License: ASL 2.0
 URL: %{git0}
@@ -399,6 +399,10 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath}
 %{_datadir}/bash-completion/completions/%{name}
 
 %changelog
+* Tue Jul 9 2019 Dan Walsh (Bot) <dwalsh+bot@fedoraproject.org> - 1:0.1.38-2.dev
+- Update containers-registries.conf.md man page for mirroring support
+- Update regsitries.conf file to match containers/image
+
 * Mon Jun 24 2019 Dan Walsh (Bot) <dwalsh+bot@fedoraproject.org> - 1:0.1.38-1.dev
 - Bump up to 1:0.1.38