Set up authentication for Helm

This page describes how to configure Helm to authenticate with Artifact Registry repositories.

Before you begin

1. If a repository for your charts does not exist, create a new repository. Choose Docker as the repository format.

2. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
3. (Optional) Configure defaults for Google Cloud CLI commands.

4. 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:

1. 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.

   Go to the Service Accounts page

   Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

2. Grant the appropriate Artifact Registry role to the service account to provide repository access.

3. 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.

4. 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.

Helm is now authenticated with Artifact Registry.

Using a JSON key file

Note: When possible, use an access token or to reduce the risk of unauthorized access to your artifacts. Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

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:

1. 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.

   Go to the Service Accounts page

   Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

2. 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.

3. Grant the appropriate Artifact Registry role to the service account to provide repository access.

4. 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.

Helm is now authenticated with Artifact Registry.

What's next

• Learn about managing Helm charts saved as images