Description of problem:

The current implementation of registries.conf support is not working as expected. This bug report will outline the expectations of how we believe this should work.

Background

The containers/image project defines a configuration file called registries.conf, which controls how image pulls can be redirected to another registry. Effectively the pull request for a given registry is redirected to another registry which can satisfy the image pull request instead. The specification for the registries.conf file is located here. For tools such as podman and skopeo, this configuration file allows those tools to indicate where images should be pulled from, and the containers/image project rewrites the image reference on the fly and tries to get the image from the first location it can, preferring these "alternate locations" and then falling back to the original location if one of the alternate locations can't satisfy the image request.

An important aspect of this redirection mechanism is it allows the "host:port" and "namespace" portions of the image reference to be redirected. To be clear on the nomenclature used in the registries.conf specification, a namespace refers to zero or more slash separated sections leading up to the image name (which is called repo in the specification and has the tag or digest after it. See repo(:_tag|@digest) below) and the host[:port] refers to the domain where the image registry is being hosted.

Example:

host[:port]/namespace[/namespace…]/repo(:_tag|@digest)

For example, if we have an image called myimage@sha:1234 the and the image normally resides in quay.io/foo/myimage@sha:1234 you could redirect the image pull request to my registry.com/bar/baz/myimage@sha:1234. Note that in this example the alternate registry location is in a different host, and the namespace "path" is different too.

Use Case

In a typical development scenario, image references within an OLM catalog should always point to a production location where the image is intended to be pulled from when a catalog is published publicly. Doing this prevents publishing a catalog which contains image references to internal repositories, which would never be accessible by a customer. By using the registries.conf redirection mechanism, we can perform testing even before the images are officially published to public locations, and we can redirect the image reference from a production location to an internal repository for testing purposes. Below is a simple example of a registries.conf file that redirects image pull requests away from prodlocation.io to preprodlocation.com:

[[registry]]
 location = "prodlocation.io/xx"
 insecure = false
 blocked = false
 mirror-by-digest-only = true
 prefix = ""
 [[registry.mirror]]
  location = "preprodlocation.com/xx"
  insecure = false

Other Considerations

• We only care about redirection of images during image pull. Image redirection on push is out of scope.
• We would like to see as much support for the fields and TOML tables defined in the spec as possible. That being said, there are some items we don't really care about.
  • supported:
    • support multiple [[registry]] TOML tables
    • support multiple [[registry.mirror]] TOML tables for a given [[registry]] TOML table
    • if all entires of [[registry.mirror]] for a given [[registry]] TOML table do not resolve an image, the original [[registry]] TOML locations should be used as the final fallback (this is consistent with how the specification is written, but want to make this point clear. See the specification example which describes how things should work.
    • prefix and location
      • These fields work together, so refer to the specification for how this works. If necessary, we could simplify this to only use location since we are unlikely to use the prefix option.
    • insecure
      • this should be supported for the [[registry]] and [[registry.mirror]] TOML tables so you know how to access registries. If this is not needed by oc mirror then we can forgo this field.
  • fields that require discussion:
    • we assume that digests and tags can be supplied for an image reference, but in the end digests are required for oc mirror to keep track of the image in the workspace. It's not clear if we need to support these configuration options or not:
      • mirror-by-digest-only
        • we assume this is always false since we don't need to prevent an image from being pulled if it is using a tag
      • pull-from-mirror
        • we assume this is always all since we don't need to prevent an image from being pulled if it is using a tag
  • does not need to be supported:
    • unqualified-search-registries
    • credential-helpers
    • blocked
    • aliases
• we are not interested in supporting version 1 of registries.conf since it is deprecated

Version-Release number of selected component (if applicable):

4.12

How reproducible:

Always

Steps to Reproduce:

oc mirror -c ImageSetConfiguration.yaml --use-oci-feature --oci-feature-action mirror --oci-insecure-signature-policy --oci-registries-config registries.conf --dest-skip-tls docker://localhost:5000/example/test

Example registries.conf

[[registry]]
  prefix = ""
  insecure = false
  blocked = false
  location = "prod.com/abc"
  mirror-by-digest-only = true
  [[registry.mirror]]
    location = "internal.exmaple.io/cp"
    insecure = false
[[registry]]
  prefix = ""
  insecure = false
  blocked = false
  location = "quay.io"
  mirror-by-digest-only = true
  [[registry.mirror]]
    location = "internal.exmaple.io/abcd"
    insecure = false

Actual results:

images are not pulled from "internal" registry

Expected results:

images should be pulled from "internal" registry

Additional info:

The current implementation in oc mirror creates its own structs to approximate the ones provided by the containers/image project, but it might not be necessary to do that. Since the oc mirror project already uses containers/image as a dependency, it could leverage the FindRegistry function, which takes a image reference, loads the registries.conf information and returns the most appropriate [[registry]] reference (in the form of Registry struct) or nil if no match was found. Obviously custom processing will be necessary to do something useful with the Registry instance. Using this code is not a requirement, just a suggestion of another possible path to load the configuration.