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
  3. (Optional) Configure defaults for gcloud 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.

Service accounts are not associated with a specific user, and Google Cloud applications can use an Application Default Credentials strategy to obtain credentials automatically.

The service accounts for applications that typically integrate with Artifact Registry, such as Cloud Build or Cloud Run, are configured by default permissions for repositories in the same project. You do not need to configure Docker authentication for these applications.

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

  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 user name to use when authenticating with an access token.
    • gcloud auth application-default print-access-token is the gcloud 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

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

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

  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 file name 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 where the image is stored.

Helm is now authenticated with Artifact Registry.

What's next