`docker_environment` cannot pull images from private registries — does not inherit `[docker]` credential configuration

[mfairley]

Problem

docker_environment fails to pull its image from a private Docker registry with a credentials error, even though the [docker] subsystem is correctly configured with credential helpers and environment variables.

For example, with Google Artifact Registry configured via docker-credential-gcloud:

Permission "artifactregistry.repositories.downloadArtifacts" denied on resource

This affects any goal that uses the environment — pants package, pants test, etc. — whenever the image isn't already cached locally.

The [docker] subsystem config is provably correct: pants publish of images to the same registry works fine using the same credential helpers. The issue is that docker_environment does not appear to use the [docker] subsystem's env_vars or tools configuration when pulling its image.

Reproduction

Minimal reproduction repo: https://github.com/mfairley/pants-docker-issue

Setup:

• A docker_environment referencing an image from a private Google Artifact Registry
• [docker] configured with docker-credential-gcloud in tools and CLOUDSDK_CONFIG/DOCKER_CONFIG in env_vars

# /BUILD
docker_environment(
    name="python",
    platform=env("ENVIRONMENT_PLATFORM"),
    image=env("DOCKER_REGISTRY_ADDRESS")
    + "/"
    + env("CLOUDSDK_CORE_PROJECT")
    + "/docker/python",
)

# pants.toml
[docker]
use_buildx = true
env_vars = [
  "DOCKER_CONFIG=%(env.DOCKER_CONFIG)s",
  "CLOUDSDK_CONFIG=%(env.CLOUDSDK_CONFIG)s",
]
tools = [
  "docker-credential-gcloud",
  "docker-credential-osxkeychain",
  "docker-credential-desktop",
  "dirname",
  "readlink",
  "python",
]

Steps:

1. Ensure the image is not cached locally (e.g. docker rmi or use a fresh machine)
2. Run any goal that uses the environment, e.g. pants package company/server:pex
3. Fails with a permission denied error pulling the environment image

Meanwhile, pants publish docker/python:base to the same registry with the same credentials works, and docker pull outside of Pants works — confirming the credential configuration is correct.

Why this goes unnoticed

This bug is easy to miss because if you publish the image first, Docker caches it locally. Everything works until someone on a different machine (or after pruning images) tries to use the environment for the first time and the pull fails.

Expected behavior

docker_environment should use the [docker] subsystem's env_vars and tools configuration (or have its own equivalent) when pulling its image, so that credential helpers like docker-credential-gcloud can authenticate to private registries.

Related discussion

• Slack thread in #general

Environment

• Pants 2.29.0
• macOS (Apple Silicon)
• Google Cloud Artifact Registry
• docker-credential-gcloud