This page describes how to configure Helm to authenticate with Artifact Registry repositories.
Before you begin
- If a repository for your charts does not exist, create a new repository. Choose Docker as the repository format.
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- (Optional) Configure defaults for Google Cloud CLI commands.
Install Helm 3.8.0 or later. In previous versions of Helm, support for charts in OCI format is an experimental feature.
Run
helm version
to verify your version.
Choosing an authentication method
In most situations, we recommend using a service account for authenticating to Artifact Registry.
The following authentication methods are available:
- Use Artifact Registry credentials configured for Docker
- By default, Helm can authenticate with the same credentials that you use for Docker.
- Access token
- Application Default Credentials provide short-lived access tokens that a service account uses to access your Google Cloud resources.
- 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 to reduce the risk of unauthorized access to your artifacts.
Using your Docker configuration
By default, Helm supports registry settings in the Docker configuration file config.json. Helm finds registry settings in either the default location or the location specified by the DOCKER_CONFIG environment variable.
If you configured Docker with a credential helper to authenticate with Artifact Registry, Helm uses your existing configuration for Artifact Registry Docker repositories.
Using an access token
Access tokens are short-lived tokens that provide access to your Google Cloud resources. Since the token is short-lived, you should request it less than an hour before you use it to connect with Artifact Registry repositories.
Google Cloud obtains an access token using Application Default Credentials.
To use an access token:
Create a service account to act on behalf of your application, or choose an existing service account that you use for automation.
You will need the location of the service account key file to set up authentication with Artifact Registry. For existing accounts, you can view keys and create new keys on the Service Accounts page.
Grant the appropriate Artifact Registry role to the service account to provide repository access.
Assign the service account key file location to the variable
GOOGLE_APPLICATION_CREDENTIALS
so that the Artifact Registry credential helper can obtain your key when connecting with repositories.export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
Where KEY-FILE is path to the service account key file.
Obtain an access token as credentials when you authenticate to Artifact Registry with Docker.
Linux / macOS
Run the following command:
gcloud auth application-default print-access-token | helm registry login -u oauth2accesstoken \ --password-stdin https://LOCATION-docker.pkg.dev
Windows
Run the following command:
gcloud auth application-default print-access-token ya29.8QEQIfY_... helm registry login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \ https://LOCATION-docker.pkg.dev
Where
oauth2accesstoken
is the username to use when authenticating with an access token.gcloud auth application-default print-access-token
is the Google Cloud CLI command to obtain the access token for the service account. Your access token is the password for authentication.- LOCATION is the regional or multi-regional location of the repository where the image is stored.
Helm is now authenticated with Artifact Registry.
Using a JSON key file
Anyone who has access to a valid private key for a service account will be able to access resources through the service account. Note that 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 repositories:
- Create dedicated service accounts that are only used to interact with repositories.
- Grant the specific Artifact Registry role for the access required by the service account. For example, a service account that only downloads artifacts only requires the Artifact Registry Reader role.
- Configure the permissions for your dedicated service accounts on each repository rather than at the project level. You can then specify access based on the repository context. For example, a service account for development builds might have the Artifact Registry Reader role for a production repository and the Artifact Registry Writer role for a staging repository.
- Follow best practices for managing service account keys.
To create a new service account and a service account key for use with Artifact Registry repositories only:
Create a service account to act on behalf of your application, or choose an existing service account that you use for automation.
You will need the location of the service account key file to set up authentication with Artifact Registry. For existing accounts, you can view keys and create new keys on the Service Accounts page.
You can optionally base64-encode all the contents of the key file.
Linux
base64 FILE-NAME > NEW-FILE-NAME
macOS
base64 -i FILE-NAME -o NEW-FILE-NAME
Windows
Base64.exe -e FILE-NAME > NEW-FILE-NAME
Where FILE-NAME is the original key filename and NEW-FILE-NAME is your base64-encoded key file.
Grant the appropriate Artifact Registry role to the service account to provide repository access.
Use the service account key to authenticate:
Linux / macOS
Run the following command:
cat KEY-FILE | helm registry login -u KEY-TYPE --password-stdin \ https://LOCATION-docker.pkg.dev
Windows
Run the following command:
helm registry login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev < KEY-FILE
Where
- KEY-TYPE is one of the following:
_json_key
if you are using the service account key in JSON format as it was provided when you created the file._json_key_base64
if you base64-encoded the all contents of the file.
- KEY-FILE is the name of the service account key file in JSON format.
- LOCATION is the regional or multi-regional location of the repository where the image is stored.
- KEY-TYPE is one of the following:
Helm is now authenticated with Artifact Registry.