Manage Helm charts

This page explains how to manage Helm 3 charts saved as OCI container images, including pushing (uploading), pulling (downloading), listing, tagging, and deleting charts.

Before you begin

  1. If the target repository doesn't exist, create a new repository. Choose Docker as the repository format.
  2. Verify that you have the required permissions for the repository.
  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.

  5. Configure Helm to authenticate with Artifact Registry.

Creating or obtaining a chart

This documentation focuses on managing your chart images and assumes that you have existing charts or are familiar with creating charts. To learn more about creating charts or obtaining publicly available charts in Artifact Hub, see the following information in the Helm documentation.

  • Using Helm describes obtaining charts from the public Artifact Hub and customizing a chart before installing it.
  • Charts describes charts and creating charts.
  • Chart Best Practices Guide describes conventions and best practices.

Packaging a chart

Before you can push a chart to Artifact Registry, you must package it as a chart archive.

  1. Change to the directory that contains your chart.

  2. Package the chart.

    helm package CHART-PATH

    Replace CHART-PATH with the path to the directory that contains your Chart.yaml file.

Helm uses the chart name and version for the archive filename. For example, if you have a chart with the name my-chart and version number 0.1.0, the package name is my-chart-0.1.0.tgz.

You can now push the chart to Artifact Registry.

Pushing a chart

After you have packaged your chart, you can push it to Artifact Registry.

To push the chart, run the following command:

helm push my-chart-0.1.0.tgz oci://LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

Replace the following values:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY is the name of the repository.

Helm uses information from Chart.yaml for the OCI container image name and tag. Consider the following example command:

helm push my-chart-0.1.0.tgz oci://us-west1-docker.pkg.dev/my-project/my-repo

Helm uploads the chart archive as the image my-chart with the tag 0.1.0.

To verify that the push operation was successful, list the images in the repository.

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

Pulling charts

To pull a chart:

  1. Run the following command to pull the chart archive:

    helm pull oci://LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE \
    --version VERSION

    If you want to pull the chart archive and extract its contents, add the --untar flag.

    helm pull oci://LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE \
    --version VERSION \
    --untar

    Replace the following values:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE is the name of the image in the repository.
  • VERSION is semantic version of the chart. This flag is required. Helm does not support pulling a chart using a tag.

Installing a chart

Install a chart stored in Artifact Registry with the helm install command.

helm install RELEASE \
    oci://LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE \
    --version VERSION

The following example installs a release named release1 using version 0.1.0 of the chart us-west1-docker.pkg.dev/nyap-test/helm-repo/my-chart:

helm install release1 oci://us-west1-docker.pkg.dev/nyap-test/helm-repo/my-chart --version 0.1.0

Listing charts

You can list charts using the Google Cloud console or the command line. If you store container images and charts in the same Docker repository, then both artifact types appear in the list.

Console

To view images in a repository:

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

    Open the Repositories page

  2. Click the repository with the container image.

  3. Click an image to see its versions.

gcloud

To list all images in the default project, repository, and location when the default values are configured:

gcloud artifacts docker images list

To list images in a repository in a specific location, run the command:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

To list all digests and tags for a specific image, run the command:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE \
--include-tags

Replace the following values:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE is the name of the image in the repository.
  • --include-tags shows all versions of images, including digests and tags. If this flag is omitted, the returned list only includes top level container images.

For example, consider an image with the following characteristics:

  • Repository location: us-west1
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: my-image

The full repository name is:

us-west1-docker.pkg.dev/my-project/my-repo

The full image name is:

us-west1-docker.pkg.dev/my-project/my-repo/my-image

For details about the image name format, see Repository and image names.

Listing files

You can list files in a repository, files in all versions of a specified container image, or files in a specific version of an image.

For all the following commands, you can set a maximum number of files to return by adding the --limit flag to the command.

To list all files in the default project, repository, and location when the default values are configured:

gcloud artifacts files list

To list files in a specified project, repository, and location, run the command:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

To list files for all versions of a specific container image:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

To list files for a specific container image version:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION
To list files for a specific tag:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Replace the following values:

  • LOCATION: the regional or multi-regional location of the repository.
  • PROJECT: your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY: the name of the repository where the image is stored.
  • PACKAGE: the name of the image.
  • VERSION: the image digest, a string starting with sha256:.
  • TAG: the tag associated with the container image.

Deleting images

In an Artifact Registry repository, you can delete an entire container image or delete a specific image version associated with a tag or digest. Once you have deleted an image, you cannot undo the action.

To delete an image stored in Artifact Registry:

Console

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

    Open the Repositories page

  2. Click the image name to see versions of that image.

  3. Select versions that you want to delete.

  4. Click DELETE.

  5. In the confirmation dialog, click DELETE.

gcloud

To delete an image and all its tags, run the command:

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE --delete-tags

To delete a specific image version, use one of the following commands.

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG [--delete-tags]

or

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE@IMAGE-DIGEST [--delete-tags]

Where

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
  • REPOSITORY is the name of the repository where the image is stored.
  • IMAGE is the name of the image in the repository.
  • TAG is the tag for the version you want to delete. If multiple tags are associated with the same image version, you must include --delete-tags to delete the image version without removing the tags first.
  • IMAGE-DIGEST is the sha256 hash value for the version you want to delete. If a tag is associated with the image digest, you must include --delete-tags to delete the image version without removing the tag first.
  • --delete-tags removes all tags applied to the image version. This flag lets you force deletion of an image version when:
    • You specified a tag, but there are other tags associated with the image version.
    • You specified an image digest that has at least one tag.

What's next