Setting 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. (Optional) Configure defaults for gcloud commands.
  3. Install Helm 3 if it is not already installed.

  4. Enable Helm experimental support for OCI images with the HELM_EXPERIMENTAL_OCI variable. Add the following line to ~/.bashrc (or ~/.bash_profile in macOS, or wherever your shell stores environment variables):

    export HELM_EXPERIMENTAL_OCI=1
    
  5. Run the following command to load your updated .bashrc (or .bash_profile) file:

    source ~/.bashrc
    

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 with permissions to access 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
You can configure Helm to obtain registry settings from the Docker configuration file. If you configured Docker with the gcloud or standalone credential helper to authenticate with Artifact Registry, 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

If you configured Docker with the gcloud or standalone credential helper to authenticate with Artifact Registry, Docker stores registry settings in its config.json file.

By default, Helm stores registry settings in ~/.config/helm/registry.json. Instead of maintaining registry settings in two different configuration files, you can configure Helm to authenticate with any Artifact Registry hosts that are configured for Docker.

To configure Helm to use your Docker registry settings:

Linux

  1. Add the following lines to ~/.bashrc (or ~/.bash_profile in macOS, or wherever your shell stores environment variables):

    export DOCKER_CONFIG="~/.docker"
    export HELM_REGISTRY_CONFIG="${DOCKER_CONFIG}/config.json"
    
    • DOCKER_CONFIG is the Docker environment variable for the location of the Docker client configuration file, config.json. The default location is ~/.docker.
    • HELM_REGISTRY_CONFIG is the Helm environment variable for the registry configuration file. It points to the Docker config.json file.
  2. Run the following command to load your updated .bashrc (or .bash_profile) file:

    source ~/.bashrc
    

Windows

Run the following commands to configure user environment variables for the Docker and Helm configuration files:

setx DOCKER_CONFIG %USERPROFILE%\.docker
setx HELM_REGISTRY_CONFIG %DOCKER_CONFIG%\config.json
  • DOCKER_CONFIG is the Docker environment variable for the location of the Docker client configuration file, config.json. The default location is %USERPROFILE%\.docker.
  • HELM_REGISTRY_CONFIG is the Helm environment variable for the registry configuration file. It points to the Docker config.json file.

Helm is now configured to use the same credentials that Docker uses for Artifact Registry. You can push and pull charts for Artifact Registry repositories in host locations that you configured for Docker.

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