Proposal: Adding Support for Alternative Image Tags in Docker Compose

[yaroslavputria]

Description

Objective: The goal of this proposal is to enhance Docker Compose by introducing support for specifying alternative image tags for services. This feature will provide users with flexibility in specifying multiple image tags for a service, allowing Docker Compose to attempt pulling the image using alternative tags if the primary tag is not found.

Background: Currently, Docker Compose only supports specifying a single image tag for each service. If the specified tag is not found in the registry, Docker Compose fails to pull the image. This limitation can be problematic for users who rely on specific tags for their services and want to provide fallback options in case the primary tag is unavailable.

Proposal: We propose extending the Docker Compose syntax to allow specifying multiple alternative image tags for a service. The syntax will be similar to the following:

version: '3.8'

services:
  myservice:
    image: 
      - myrepo/myimage:tag1
      - myrepo/myimage:tag2
      - myrepo/myimage:tag3

In this example, Docker Compose will attempt to pull the image myrepo/myimage with the tags tag1, tag2, and tag3, in that order. If tag1 is not found, it will try tag2, and so on.

Implementation Details:

1. Modify the Docker Compose parser to recognize and handle lists of alternative image tags under the image key in service definitions.
2. Update the image pulling logic to attempt pulling images using each tag in the specified order until a match is found or all tags have been exhausted.
3. Provide appropriate error handling and logging to inform users if none of the specified tags are found in the registry.

Benefits:

1. Increased Flexibility: Users can specify multiple image tags for services, providing flexibility in handling image versions and dependencies.
2. Improved Reliability: Docker Compose will attempt to pull images using alternative tags if the primary tag is not available, reducing deployment failures due to tag mismatches.
3. Enhanced Compatibility: Existing Docker Compose files can be easily updated to take advantage of the new syntax without breaking compatibility with older versions.

[ndeloof]

I hardly imagine a scenario this would be of any benefit. Do you have any real-world example this could be useful?

[mrsarm]

I have created an open source CLI tool for this: https://github.com/mrsarm/pose

A real-world example is e2e testing of distributed apps in a CI environment: pose builds a new compose file on the fly from another, replacing tag versions with a new remote version (if available), making it possible to develop a feature across apps, tagged with a common name, e.g. "new-tracking-field", and then test them all together in a CI environment with docker compose.

Use case: in a distributed app composed of maybe 5 microservices (5 images), maybe the feature you are working on needs changes in only 2 or 3 images, so you have tagged only those images with "new-tracking-field", and in CI to run your e2e tests you want to run all services with "latest" images, except for those 2 or 3 tagged with "new-tracking-field", where you want to use the images tagged with the particular tag. So the way you know at runtime in CI which images to use is to check in the Docker registry which images from your compose file are tagged with "new-tracking-field" and set the tag if it exists, otherwise keep using the one already set in the compose.yaml file. This is basically what pose does.

[mrsarm]

I just summarized this specific use case with a simple example here: https://stackoverflow.com/questions/74140047/docker-compose-is-it-possible-to-update-all-changed-images-with-a-single-comma/78478622#78478622

More complete example, e.g. using it on Github Actions for CI environments are explained here: https://github.com/mrsarm/pose/blob/main/Run-CI-envs.md

[jhrotko]

related: https://github.com/docker/compose/issues/11743