docker-credential-gcr

Introduction

docker-credential-gcr is Google Container Registry's standalone, gcloud SDK-independent Docker credential helper. It allows for v18.03+ Docker clients to easily make authenticated requests to GCR's repositories (gcr.io, eu.gcr.io, etc.).

Note: docker-credential-gcr is primarily intended for users wishing to authenticate with GCR in the absence of gcloud, though they are not mutually exclusive. For normal development setups, users are encouraged to use gcloud auth configure-docker, instead.

The helper implements the Docker Credential Store API, but enables more advanced authentication schemes for GCR's users. In particular, it respects Application Default Credentials and is capable of generating credentials automatically (without an explicit login operation) when running in App Engine or Compute Engine.

For even more authentication options, see GCR's documentation on advanced authentication methods.

Installation

Download latest release.

Install manually:

go install github.com/GoogleCloudPlatform/docker-credential-gcr/v2@latest

Configuration and Usage

• Configure the Docker CLI to use docker-credential-gcr as a credential helper for the default set of GCR registries:

  shell docker-credential-gcr configure-docker

To speed up docker builds, you can instead configure a minimal set of registries:

shell docker-credential-gcr configure-docker --registries="gcr.io,us-west1-docker.pkg.dev,docker.europe-west3.rep.pkg.dev"

• Alternatively, use the manual configuration instructions below to configure your version of the Docker client.

• Log in to GCR (or don't! See the GCR Credentials section)

  shell docker-credential-gcr gcr-login

• Use Docker!

  shell docker pull gcr.io/project-id/neato-container

• Log out from GCR

  shell docker-credential-gcr gcr-logout

GCR Credentials

By default, the helper searches for GCR credentials in the following order:

1. In the helper's private credential store (i.e. those stored via docker-credential-gcr gcr-login)
2. In a JSON file whose path is specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
3. In a JSON file in a location known to the helper:
   • On Windows, this is %APPDATA%/gcloud/application_default_credentials.json.
   • On other systems, $HOME/.config/gcloud/application_default_credentials.json.
4. On Google App Engine, it uses the appengine.AccessToken function.
5. On Google Compute Engine, Kubernetes Engine, and App Engine Managed VMs, it fetches the credentials of the service account associated with the VM from the metadata server (if available).

Users may limit, re-order how the helper searches for GCR credentials using docker-credential-gcr config --token-source. Number 1 above is designated by store and 2-5 by env (which cannot be individually restricted or re-ordered). Multiple sources are separated by commas, and the default is "store, env".

While it is recommended to use gcloud auth configure-docker in gcloud-based work flows, you may optionally configure docker-credential-gcr to use gcloud as a token source (see example below).

Examples:

To use only the gcloud SDK's access token:

docker-credential-gcr config --token-source="gcloud"

To search the environment, followed by the private store:

docker-credential-gcr config --token-source="env, store"

To verify that credentials are being returned for a given registry, e.g. for https://gcr.io:

echo "https://gcr.io" | docker-credential-gcr get

Other Credentials

As of the 2.0 release, docker-credential-gcr no longer supports generalized credsStore functionality.

Manual Docker Client Configuration

Add a credHelpers entry in the Docker config file (usually ~/.docker/config.json on OSX and Linux, %USERPROFILE%\.docker\config.json on Windows) for each GCR registry that you care about. The key should be the domain of the registry (without the "https://") and the value should be the suffix of the credential helper binary (everything after "docker-credential-").

e.g. for `docker-credential-gcr`:

    {
      "auths" : {
            ...
      },
      "credHelpers": {
            "coolregistry.com": ... ,
            "gcr.io": "gcr",
            "asia.gcr.io": "gcr",
            ...
      },
      "HttpHeaders": ...
      "psFormat": ...
      "imagesFormat": ...
      "detachKeys": ...
    }
  

License

Apache 2.0. See LICENSE for more information.