1. Home
  2. Google Cloud
  3. GCR(Container Registry) Authentication methods

GCR(Container Registry) Authentication methods

https://cloud.google.com/container-registry/docs/advanced-authentication

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.Warning: You should use a Docker credential helper only for versions 18.03 or above. A bug in earlier versions of the Docker client slows down docker builds dramatically when credential helpers are configured.

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

Warning:gcloud docker is only recommended for Docker client versions older than 1.13, which do not support the use of credential helpers.

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

WINDOWS

  • 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]

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

WINDOWS

  • 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]

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.

Leave a Comment

LEAVE A COMMENT