Using a dynamic registry reference

You can follow this tutorial to learn how to use a dynamic registry reference in the contract.

Explicit registry reference

Typically, the docker registry is referenced through the full docker URL in the compose file. See the following example:

services:
  helloworld:
    image: docker.io/library/hello-world@sha256:53f1bbee2f52c39e41682ee1d388285290c5c8a76cc92b42687eecf38e0af3f0

In the example, docker.io/library/ is the registry prefix, hello-world is the identifier of the OCI image in that registry, and sha256:53f1bbee2f52c39e41682ee1d388285290c5c8a76cc92b42687eecf38e0af3f0 is the unique identifier of the version of the image.

In such a case, the workload provider role decides about the registry (and the associated pull credentials), since both the registry reference and the pull credentials are part of the workload section of the contract.

Dynamic registry reference

In certain use cases, the registry is not known when the workload section is pre-encrypted. For example, when the workload provider wants to allow the deployer to use a registry mirror or a private container registry.

In that case, it's possible to dynamically override the registry and the pull credentials. This effort has to be coordinated between the workload provider and the deployer.

The templating approach works only for a compose-based workload, and only for images that are referenced through a digest. DCT-based workloads are not supported.

Workload provider

The workload provider marks the registry as dynamic by using a replacement variable in the docker compose file:

services:
  helloworld:
    image: ${REGISTRY}/hpse-docker-hello-world-s390x@sha256:43c500c5f85fc450060b804851992314778e35cadff03cb63042f593687b7347

The digest of the image is identical across registries, so the workload provider can lock down a specific version of the image by setting the key, independent of the registry being used. Using tokens in the compose file is a native feature of the compose specification.

Now the workload provider can prepare (encrypt) the workload section without specifying the pull secrets for that registry.

Deployer

The deployer enters the missing information about the registry and the associated pull secrets.

The registry is set as an environment variable. Both the deployer and the workload provider can provide pieces to the overall environment and these pieces are overlaid with workload taking precedence.

The pull credentials are passed in through an auth section in the environment part of the contract. Just as environment variables, these auth sections are overlaid with the workload section taking precedence.

---
  ---
  env:
    type: env
    auths:
      de.icr.io:
        username: xxx
        password: yyy
    env:
      REGISTRY: de.icr.io