Image and feature digest pinning syntax inconsistency

[berkaycagir]

Hey,

I think the behavior of Dev Container CLI for digest pinning is inconsistent between the image field and feature keys. For images, it accepts the following definition without a problem:

mcr.microsoft.com/devcontainers/python:1.1.10-3.12-bookworm@sha256:c5b8bd1aa0c5c56c18de49024d2d67873612107c492ad0d8946c78c495e6ff0c

However, when it comes to feature keys, the following definition is not valid:

ghcr.io/devcontainers/features/aws-cli:1.0.7@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807

Feature keys require the following definition instead (which I've learned by digging into issues and finding #479 as I couldn't find any documentation on whether the features can be pinned), which omits the tag:

ghcr.io/devcontainers/features/aws-cli@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807

If you were to pin the feature with its tag, you get the following error:

@devcontainers/cli 0.60.0. Node.js v18.18.2. darwin 23.4.0 arm64.
Start: Run: docker buildx version
github.com/docker/buildx v0.13.1-desktop.1 2368b2ee41873b948cb607251cec573ed00f00f9
...
Resolving Feature dependencies for 'ghcr.io/devcontainers/features/aws-cli:1.0.7@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807'...
* Processing feature: ghcr.io/devcontainers/features/aws-cli:1.0.7@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807
Path 'devcontainers/features/aws-cli:1.0.7' for input 'ghcr.io/devcontainers/features/aws-cli:1.0.7@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807' failed validation.  Expected path to match regex '/^[a-z0-9]+([._-][a-z0-9]+)*(\/[a-z0-9]+([._-][a-z0-9]+)*)*$/'.
Could not resolve Feature manifest for 'ghcr.io/devcontainers/features/aws-cli:1.0.7@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807'.  If necessary, provide registry credentials with 'docker login <registry>'.

Not being able to use the tag of the image within definitions with digests makes the implementation of automatic dependency management harder (a Renovate discussion) and IMHO readability worse as you have no way of easily seeing which tag that feature is supposed to be. Would you consider changing this behavior?

Thanks! 🤗

[samruddhikhandale]

Hi 👋

From https://docs.docker.com/reference/cli/docker/image/pull/#pull-an-image-by-digest-immutable-identifier, even the Docker images have a guide to pull the image with ubuntu@sha256:xyz which doesn't contain the tag. This is likely due to the fact that Docker image references typically do not include both a tag and a digest. When a digest is present, it uniquely identifies the image, making the tag redundant.

However, as you pointed out, including the tag can improve readability and make dependency management easier. Also, I agree that using a tag and digest is currently acceptable for Docker images. Hence, we could make these changes.

However, when it comes to feature keys, the following definition is not valid:

ghcr.io/devcontainers/features/aws-cli:1.0.7@sha256:8d39e89cc98291953fb03cf7ef540dc1a7c78c3162f0eee9b61c800e4838f807

Looping in @joshspicer, wondering if you have any thoughts on this request?

[joshspicer]

👋 I didn't realize that mcr.microsoft.com/devcontainers/python:1.1.10-3.12-bookworm@sha256:c5b8bd1aa0c5c56c18de49024d2d67873612107c492ad0d8946c78c495e6ff0c was valid reference syntax! TIL

In your exploration did you find if this behavior is part of the specification that docker/OCI images adhere to (or if this syntax is an exception to the rule).

The difference here (as I think you've discovered) is that for dev container Features/Templates we implement a lot of this behavior ourselves in the CLI (as opposed to shelling out to the docker CLI when pulling an image)

What happens if a tag doesn't associate with the provided sha hash, does the look up fail?

Seems reasonable to support this syntax, especially if we're able to query registries with the entire reference+version+hash.

(Beyond the CLI, this would likely need an update on the dependabot updater implementation)