Authentication methods

To authenticate to Container Registry, you should use gcloud as a Docker credential helper as described below.

This page also describes advanced authentication methods.

Before you begin

Make sure that you have:

  1. Installed the most recent version of the Cloud SDK, which includes the gcloud command-line tool

  2. Installed Docker

gcloud as a Docker credential helper

To authenticate to Container Registry, use gcloud as a Docker credential helper. To do so, run the following command:

gcloud auth configure-docker

You need to run this command once to authenticate to Container Registry.

We strongly recommend that you use this method when possible. It provides secure, short-lived access to your project resources.

Advanced authentication methods

The advanced methods on this page should only be used when using gcloud as a Docker credential helper is not ideal, and when you understand the security implications of the advanced method.

The advanced authentication methods are:

Standalone Docker credential helper

Docker needs access to Container Registry to push and pull images. You can use the standalone Docker credential helper tool, docker-credential-gcr, to configure your Container Registry credentials for use with Docker.

The credential helper fetches your Container Registry credentials—either automatically, or from a location specified using its --token-source flag—then writes them to Docker's configuration file. This way, you can use Docker's command-line tool, docker, to interact directly with Container Registry.

To use the Docker credential helper:

  1. Download docker-credential-gcr in one of two ways:

    • Using the gcloud command-line tool:

      gcloud components install docker-credential-gcr
      
    • From the docker-credential-gcr's GitHub releases, optionally using the curl command-line utility. For example:

      VERSION=1.5.0
      OS=linux  # or "darwin" for OSX, "windows" for Windows.
      ARCH=amd64  # or "386" for 32-bit OSs
      
      curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
        | tar xz --to-stdout ./docker-credential-gcr \
        > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
      
  2. Configure Docker to use your Container Registry credentials when interacting with Container Registry (you are only required to do this once):

    docker-credential-gcr configure-docker
    

    See docker-credential-gcr's main documentation on GitHub for more information.

  3. If you intend to use the docker command to push or pull images that are stored in a different Google Cloud Platform project, ensure that permissions and access scopes are correctly configured.

gcloud docker

Use gcloud docker to inject the Docker client with Container Registry credentials before handing the request off to Docker. For example, to push an image identified by its digest, use the command:

gcloud docker -- push [HOSTNAME]/[PROJECT-ID]/[IMAGE]@[IMAGE_DIGEST]

where:

  • [HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
  • [PROJECT-ID] is your Google Cloud Platform Console project ID). If your project ID contains a colon (:), see Domain-scoped projects.
  • [IMAGE] is the image's name in Container Registry.
  • [IMAGE_DIGEST] is the sha256 hash value of the image contents. In the console, click on the specific image to see its metadata. The digest is listed as the Image digest.

See the gcloud docker documentation for more information.

If you intend to use the docker command to push or pull images that are stored in a different Google Cloud Platform project, ensure that permissions and access scopes are correctly configured.

Access token

Access tokens are short-lived tokens that provide read/write access to your Google Cloud Platform resources.

The gcloud docker command authenticates Docker commands by passing a short-lived access token as a password to Container Registry.

  • For docker pull and docker search, the access token must use the devstorage.read_only scope.
  • For docker push, the access token must use the devstorage.read_write scope.

For more information about the required service account permissions and scopes to push and pull images, refer to the requirements for using Container Registry with Google Cloud Platform.

The authentication scheme for gcloud docker can be used in the absence of the gcloud command-line tool by creating an appropriate access token (such as Compute Engine instance metadata).

The access granted by this token is the same as what is granted when using the gcloud docker command to authenticate, making this the safest of the alternative authentication methods.

To use an access token, see the Application Default Credentials documentation. Then, use the following credentials:

Linux / macOS

  • Username is oauth2accesstoken
  • Password is your access token. For example, gcloud auth print-access-token

For example:

gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://[HOSTNAME]

where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

Or, for older Docker clients which don't support --password-stdin:

docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]

Windows

  • Username is oauth2accesstoken
  • Password is the output of gcloud auth print-access-token

For example:

gcloud auth print-access-token
ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]

where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

JSON key file

A service account JSON key file is a long-lived credential that is scoped to a specific GCP Console project and its resources.

The service account you use to push and pull images must be correctly configured with the required permissions and access scope for interaction with Container Registry.

Service accounts automatically created by GCP, such as the Container Registry service account, are granted the read-write Editor role for the parent project. The Compute Engine default service account is configured with read-only access to storage within the same project. You may wish to grant other service accounts more specific permissions. Pushing and pulling images across projects requires proper configuration of both permissions and access scopes on the service account that interacts with Container Registry.

For more information about the required service account permissions and scopes to push and pull images, refer to the requirements for using Container Registry with Google Cloud Platform.

To use a JSON key file, follow the service account instructions instructions in the Google Cloud Platform Console Help Center. Then, use the following credentials:

Linux / macOS

  • Username is _json_key (NOT the name of your service account)
  • keyfile.json contains the service account JSON key

For example:

cat keyfile.json | docker login -u _json_key --password-stdin https://[HOSTNAME]

where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

Or, for older Docker clients which don't support --password-stdin:

docker login -u _json_key -p "$(cat keyfile.json)" https://[HOSTNAME]

Windows

  • Username is _json_key (NOT the name of your service account)
  • keyfile.json contains the service account JSON key

For example:

set /p PASS=<keyfile.json
docker login -u _json_key -p "%PASS%" https://[HOSTNAME]

where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

See the service accounts documentation to learn more about configuring service accounts.

Using Container Registry with GCP

Compute Engine instances and Google Kubernetes Engine clusters can push and pull Container Registry images based on Cloud Storage scopes on the instances. Refer to Using Container Registry with GCP.

Images stored in Container Registry can be deployed to the App Engine flexible environment.

Kunde den här sidan hjälpa dig? Berätta:

Skicka feedback om ...

Container Registry