This page describes how to configure a third-party client to authenticate with Container Registry.
Google Cloud services that integrate with Container Registry are preconfigured with permissions to access repositories in the same project. You do not need to configure authentication for these services, but you should verify that permissions are appropriately configured.
Before you begin
- Verify that you have enabled the Container Registry API and installed Cloud SDK. See Enabling and disabling service for instructions.
Verify that the account you are using for authentication has permissions to access Container Registry. We recommend using a service account rather than a user account.
Install Docker if it is not already installed. Docker is included in Cloud Shell.
Docker requires privileged access to interact with registries. On Linux or Windows, add the user that you use to run Docker commands to the Docker security group. This step is not required on MacOS since Docker Desktop runs on a virtual machine as the root user.
Linux
The Docker security group is called
docker
. To add your username, run the following command:sudo usermod -a -G docker ${USER}
Windows
The Docker security group is called
docker-users
. To add a user from the Administrator command prompt, run the following command:net localgroup docker-users DOMAIN\USERNAME /add
Where
- DOMAIN is your Windows domain.
- USERNAME is your user name.
Log out and log back in for group membership changes to take effect. If you are using a virtual machine, you may need to restart the virtual machine for membership changes to take effect.
Authentication methods
You must configure any third-party clients that need to access Container Registry.
The following authentication methods are available:
gcloud
credential helper (Recommended)- Configure your Container Registry credentials for use with Docker directly in gcloud. Use this method when possible for secure, short-lived access to your project resources. This option only supports Docker versions 18.03 or above.
- Standalone credential helper
- This option is primarily for configuring your credentials for use with Docker in the absence of Cloud SDK. This option only supports Docker versions 18.03 or above.
- Access token
- Application Default Credentials
provide short-lived access tokens that a
service account uses to access your Google Cloud resources.
It is the safest of the alternatives to using
gcloud
as a credential helper. - JSON key file
A user-managed key-pair that you can use as a credential for a service account. Because the credential is long-lived, it is the least secure option of all the available authentication methods.
When possible, use an access token or another available authentication method to reduce the risk of unauthorized access to your artifacts. If you must use a service account key, ensure that you follow best practices for managing credentials.
Some tools or workflows do not provide good support for using gcloud
as
a credential helper. If you use one of the alternative options, ensure that you understand security implications.
gcloud credential helper
We strongly recommend that you use this method when possible. It provides secure,short-lived access to your project resources.
Use the gcloud
tool to configure authentication
in Cloud Shell or any
environment where the Cloud SDK is installed. Cloud Shell
includes a current version of Docker.
To configure authentication:
Log in to gcloud as the user that will run Docker commands.
To configure authentication with user credentials, run the following command:
gcloud auth login
To configure authentication with service account credentials, run the following command:
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
Where
- ACCOUNT is the service account name in the format
[USERNAME]@[PROJECT-ID].iam.gserviceaccount.com
. You can view existing service accounts on the Service Accounts page of Cloud Console or with the commandgcloud iam service-accounts list
- KEY-FILE is the service account key file. See the Identity and Access Management (IAM) documentation for information about creating a key.
- ACCOUNT is the service account name in the format
Configure Docker with the following command:
gcloud auth configure-docker
Your credentials are saved in your user home directory.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Docker is now configured to authenticate with Container Registry. To push and pull images, make sure that permissions are correctly configured.
Standalone credential helper
The standalone Docker credential helper configures Docker to authenticate to Container Registry on a system where Cloud SDK is not available.
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 configure authentication:
Log on to the machine as the user who will run Docker commands.
Download
docker-credential-gcr
from GitHub releases:You may optionally using the
curl
command-line utility. For example:VERSION=2.0.0 OS=linux # or "darwin" for OSX, "windows" for Windows. ARCH=amd64 # or "386" for 32-bit OSs, "arm64" for ARM 64. 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/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
Configure Docker with the following command:
docker-credential-gcr configure-docker
Your credentials are saved in your user home directory.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
See the standalone Docker credential helper documentation on GitHub for more information.
Docker is now configured to authenticate with Container Registry. To push and pull images, make sure that permissions are correctly configured.
Access token
An access token is a short-lived credential that provides access to your Google Cloud resources. Since the token is valid for 60 minutes, you should request it less than an hour before you use it to connect with Container Registry.
Google Cloud obtains an access token using Application Default Credentials. The token expires after 60 minutes.
Obtain the key for the service account that will interact with Container Registry.
Console
In Google Cloud Console, open the Create service account key page.
From the Service account list, select the service account that you want to use.
To create a new service account, choose New service account and specify the service account name, ID, and appropriate Cloud Storage role based on the permissions you want to grant to the service account.
Select JSON as the key type.
Click Create. A JSON file that contains your key downloads to your computer.
The instructions on this page use the file name
keyfile.json
for this key file.
gcloud
You can run the following commands using Cloud SDK on your local machine, or in Cloud Shell.
Create the service account. Replace NAME with a name for the service account.
gcloud iam service-accounts create NAME
Grant permissions to the service account. Replace PROJECT_ID with your project ID and ROLE with the appropriate Cloud Storage role for the service account. This role applies across repositories in the project. You can change the role later and you can also set different permissions for the service account on specific repositories.
gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
Generate the key file. The instructions on this page use the file name
keyfile.json
for the key file.gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
Run the following command to log in to Cloud SDK as a service account.
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
Where
- ACCOUNT is the service account name in the format
[USERNAME]@[PROJECT-ID].iam.gserviceaccount.com
. - KEY-FILE is the service account key file. See the IAM documentation for information about creating a key.
- ACCOUNT is the service account name in the format
Verify that permissions are correctly configured for the service account. If you are using the Compute Engine service account, you must correctly configure both permissions and access scopes.
Obtain an access token for the service account. Since the token is short-lived, request it less than an hour before you use it to connect with Container Registry.
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
, orasia.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
- Get the access token
gcloud auth print-access-token
The returned string is the access token that you use as your password. In this example,
ya29.8QEQIfY_...
represents the returned access token.ya29.8QEQIfY_...
- Log in with the access token
docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://HOSTNAME
where HOSTNAME is
gcr.io
,us.gcr.io
,eu.gcr.io
, orasia.gcr.io
.- Username is
Docker is now authenticated with Container Registry.
JSON key file
A service account key is a long-lived key-pair that you can use as a credential for a service account. You are responsible for security of the private key and other key management operations, such as key rotation.
Anyone who has access to a valid private key for a service account will be able
to access resources through the service account. For example, some
service accounts automatically created by Google Cloud, 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.
In addition, the lifecycle of the key's access to the service account (and thus, the data the service account has access to) is independent of the lifecycle of the user who has downloaded the key.
Use the following guidelines to limit access to your container images:
- Create dedicated service accounts that are only used to interact with Container Registry.
- Grant the specific role for the least amount of access that the service account requires.
- Follow best practices for managing credentials.
To create a new service account and a service account key for use with Container Registry repositories only:
Create the service account for interacting with repositories:
Console
In Google Cloud Console, open the Create service account key page.
From the Service account list, select New service account.
In the Service account name field, enter a name.
From the Role list, select the appropriate Cloud Storage role for the service account.
Click Create. A JSON file that contains your key downloads to your computer.
The instructions on this page use the file name
keyfile.json
for this key file.
gcloud
You can run the following commands using Cloud SDK on your local machine, or in Cloud Shell.
Create the service account. Replace NAME with a name for the service account.
gcloud iam service-accounts create NAME
Grant permissions to the service account. Replace PROJECT_ID with your project ID and ROLE with the appropriate role for the service account.
gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
Generate the key file. In this example, the output key file name is
keyfile.json
gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
Verify that permissions are correctly configured for the service account. If you are using the Compute Engine service account, you must correctly configure both permissions and access scopes.
Use the service account key as your password to authenticate with Docker.
Linux / macOS
- Username is
_json_key
(NOT the name of your service account) keyfile.json
is the service account key you created
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
, orasia.gcr.io
.Or, for older Docker clients which don't support
--password-stdin
:docker login -u _json_key -p "$(cat keyfile.json)" https://HOSTNAME
where HOSTNAME is
gcr.io
,us.gcr.io
,eu.gcr.io
, orasia.gcr.io
.Windows
- Username is
_json_key
(NOT the name of your service account). keyfile.json
contains the service account JSON key.
For example:
docker login -u _json_key --password-stdin https://HOSTNAME < keyfile.json
where HOSTNAME is
gcr.io
,us.gcr.io
,eu.gcr.io
, orasia.gcr.io
.Or, for older Docker clients which don't support
--password-stdin
: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
, orasia.gcr.io
.- Username is
Docker is now authenticated with Container Registry.