Store Helm charts in Artifact Registry

Helm is the package manager for Kubernetes. It uses charts that define a set of Kubernetes resources to deploy.

This quickstart shows you how to:

  • Create a private repository in Artifact Registry
  • Create a sample chart
  • Authenticate with the repository
  • Push the chart to the repository
  • Deploy the chart

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Enable the APIs

Choose a shell

To complete this quickstart, use either Cloud Shell or your local shell.

Cloud Shell
Cloud Shell is a shell environment for managing resources hosted on Google Cloud. It comes preinstalled with Docker, Helm, and the Google Cloud CLI, the primary command-line interface for Google Cloud.
Local shell
If you prefer using your local shell, you must install Docker and gcloud CLI in your environment.

Starting Cloud Shell

To launch Cloud Shell, perform the following steps:

  1. Go to Google Cloud console.

    Google Cloud console

  2. Click the Activate Cloud Shell button:  .

    A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

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

Setting up a local shell

To install gcloud CLI and Helm, perform the following steps:

  1. Install the gcloud CLI. To update an existing installation, run the command gcloud components update.

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

Create a repository

Create a Docker repository to store the sample chart for this quickstart.

Console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. Click Create Repository.

  3. Specify quickstart-helm-repo as the repository name.

  4. Choose Docker as the format.

  5. Under Location Type, select Region and then choose the location us-west1.

  6. Click Create.

The repository is added to the repository list.

gcloud

  1. Run the following command to create a new Docker repository named quickstart-helm-repo in the location us-west1 with the description "docker repository".

    gcloud artifacts repositories create quickstart-helm-repo --repository-format=docker \
    --location=us-west1 --description="Helm repository"
    
  2. Run the following command to verify that your repository was created.

    gcloud artifacts repositories list
    

For more information about Artifact Registry commands, run the command gcloud artifacts.

Create a chart

For this quickstart, you will create a sample chart named hello-chart.

  1. Change to a directory where you want to create the chart.
  2. Run the following command to create the chart:

    helm create hello-chart
    

    Helm creates a directory named hello-chart with a default set of chart files. One of the files is Chart.yaml, which includes information about the chart.

  3. Package the chart an archive.

    helm package hello-chart/
    

    Helm creates an archive named hello-chart-0.1.0.tgz using the chart name and version number in Chart.yaml.

Authenticate with the repository

Before you can push or install images, Helm must authenticate to Artifact Registry.

Helm can use existing registry settings a Docker configuration file. If you haven't already configured Docker for use with Artifact Registry, you can authenticate with an access token for this quickstart.

See Setting up authentication for Helm for more information about authentication.

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

Authenticate with an access token

To authenticate with an access token:

  1. Obtain an access token as credentials when you authenticate to Artifact Registry with Helm.

    Linux / macOS

    Run the following command:

    gcloud auth print-access-token | helm registry login -u oauth2accesstoken \
    --password-stdin https://us-west1-docker.pkg.dev
    

    Windows

    Run the following command:

    gcloud auth print-access-token
    ya29.8QEQIfY_...
    
    helm registry login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
    https://us-west1-docker.pkg.dev/PROJECT-ID/REPOSITORY
    

    Where

    • oauth2accesstoken is the user name to use when authenticating with an access token.
    • gcloud auth print-access-token is the gcloud command to obtain the access token. Your access token is the password for authentication.

Helm is now authenticated with Artifact Registry. You're ready to push the chart to the repository.

Push the chart to Artifact Registry

After you have created your chart archive and authenticated to the Artifact Registry repository, you can push the chart to the repository.

To push the chart, run the following command:

helm push hello-chart-0.1.0.tgz oci://us-west1-docker.pkg.dev/PROJECT/quickstart-helm-repo

Replace PROJECT with your Google Cloud project ID.

Helm uses values from Chart.yaml for the image:

  • The chart name is the image name: hello-chart
  • The chart version is the image tag: 0.1.0

Helm returns output similar to the following example:

Login Succeeded
Pushed: us-west1-docker.pkg.dev/my-project/quickstart-helm-repo/hello-chart:0.1.0
Digest: sha256:67a72...

Run the following command to verify that the chart is now stored in the repository:

gcloud artifacts docker images list us-west1-docker.pkg.dev/PROJECT/quickstart-helm-repo

The command output looks similar to the following example:

Listing items under project my-project, location us-west1, repository quickstart-helm-repo.

IMAGE: us-west1-docker.pkg.dev/my-project/quickstart-helm-repo/hello-chart
DIGEST: sha256:67a72...
CREATE_TIME: 2021-11-08T22:59:57
UPDATE_TIME: 2021-11-08T22:59:57

You can now deploy a release using the chart stored in Artifact Registry.

Deploy the chart

In Helm, a deployed instance of your application is called a release. After you have added your repository to the Helm configuration, you can deploy a release of your chart.

  1. Create a cluster named chart-cluster for your deployment with the command:

    gcloud container clusters create --zone us-west1-a chart-cluster
    

    When the cluster is created, the command returns a summary similar to the following example:

    kubeconfig entry generated for chart-cluster.
    NAME: chart-cluster
    LOCATION: us-west1-a
    MASTER_VERSION: 1.20.10-gke.1600
    MASTER_IP: 34.66.36.211
    MACHINE_TYPE: e2-medium
    NODE_VERSION: 1.20.10-gke.1600
    NUM_NODES: 3
    STATUS: RUNNING
    
  2. Get the cluster credentials so that kubectl can access the cluster:

    gcloud container clusters get-credentials --zone us-west1-a chart-cluster
    
  3. Run the following command to deploy a release of hello-chart using the locally extracted chart files:

    helm install hello-chart oci://us-west1-docker.pkg.dev/PROJECT/quickstart-helm-repo/hello-chart --version 0.1.0
    

    The command returns a summary of the deployment:

    NAME: hello-chart
    LAST DEPLOYED: Mon Nov  8 23:15:13 2021
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    

You have successfully deployed a release using the chart that you created and pushed to Artifact Registry.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

  1. Delete the repository you created with the following command:

    gcloud artifacts repositories delete quickstart-helm-repo --location=us-west1
    
  2. Delete the cluster you created:

    gcloud container clusters delete --zone=us-west1-a chart-cluster
    

What's next