Managing Helm charts

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

Before you begin

  1. If the target repository does not 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 gcloud commands.
  4. Install Helm 3 if it is not already installed.

  5. 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
    
  6. Run the following command to load your updated .bashrc (or .bash_profile) file:

    source ~/.bashrc
    
  7. 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.

Saving a chart in OCI format

Before you can push a chart to Artifact Registry, you must save it as a container image.

  1. Change to the directory that contains your chart.

  2. Save the chart as an OCI image, using the full path to the image location in the target repository.

    helm chart save CHART-PATH LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
    

    Replace the following values:

    • CHART-PATH is the path that contains your Chart.yaml file.
    • 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 image version.

    If you do not specify a tag with :TAG, Helm tags the image with the default chart version number in your CHART-PATH/Chart.yaml file. Updating this version number whenever you make changes to a chart is a useful way to keep the metadata in Chart.yaml in sync with your container image tags.

    Consider this example:

    helm chart save my-chart/ us-central1-docker.pkg.dev/my-project/my-repo/my-chart
    

    If the chart version is 0.1.0, Helm uses this version number as the tag. The save command output looks like this:

    ref:     us-central1-docker.pkg.dev/my-project/my-repo/my-chart:0.1.0
    digest:  decd0b41c389fd46c586c292eaf05f446fe05dc56248f409bef2c123ab7b7032
    size:    3.5 KiB
    name:    my-chart
    version: 0.1.0
    0.1.0: saved
    
  3. List charts in your local cache to confirm that the chart is saved locally.

    helm chart list
    

    The list includes your saved chart.

    REF                                                             NAME            VERSION DIGEST  SIZE    CREATED
    us-central1-docker.pkg.dev/my-project/my-repo...   my-chart     0.1.0   decd0b4 3.5 KiB 2 minutes
    

You can now push the image of your chart to Artifact Registry.

Pushing a chart

After you have saved your chart as a container image, you can push it to Artifact Registry.

To push the chart, run the following command:

helm chart push LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

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.
  • TAG is the tag for the image version.

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

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

If you no longer need a copy of the image in your Helm local cache, you can delete the local copy.

Pulling charts

You cannot deploy a release directly from a chart saved as a container image. To use the chart, you must pull the image, extract the chart files, and then use the extracted files to perform the deployment.

  1. Pull the image of the chart from Artifact Registry with the command:

    helm chart pull LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
    

    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.
    • TAG is the tag for the image version.
  2. To extract the chart files from the image run the command:

    helm chart export LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
    

You can now use the extracted chart files to install a release with the helm install command.

The following example installs a release named release1 using a chart stored in the directory my-chart.

helm install release1 ./my-chart

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, both artifact types appear in the list.

Console

To view images in a repository:

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click the repository that contains the chart.

  3. Click on 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 [--include-tags]

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

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

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
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: my-image

The full repository name is:

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

The full image name is:

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

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

Adding and removing tags

When you package a chart as an OCI image without specifying a tag, Helm automatically adds a tag using the chart version number in Chart.yaml.

You can add and delete additional tags in Artifact Registry using the Google Cloud Console or the command line.

Adding tags

In a repository, tags are unique to a version of an image. So if you have multiple versions of an image, each tag only applies to one of the versions. If you tag an image with a tag that's already in use, you will move the tag from the original version to the newly tagged version.

Console

To tag an image in a repository:

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click the image to view versions of the image.

  3. Select the image version to tag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. Type new tags into the field and then click SAVE.

gcloud

To tag images in a repository, specify the image version using the image digest or tag, and then specify the tag to add. Run one of the following commands:

gcloud artifacts docker tags add IMAGE-VERSION TAG

Where

  • IMAGE-VERSION is the full name of the image version to tag, using either the image digest or an existing tag on the image version.
  • TAG is the full name of the tag that you want to add.

For example, consider an image with the following characteristics:

  • Repository location: us
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: my-image
  • Existing tag: iteration6-final
  • Tag to add: release-candidate

To add the tag release-candidate to the version of the image with the tag iteration6-final, run the following command:

gcloud artifacts docker tags add \
us-docker.pkg.dev/my-project/my-repo/my-image:iteration6-final \
us-docker.pkg.dev/my-project/my-repo/my-image:release-candidate

For details about the image name format, including handling domain-scoped projects, see Repository and image names.

Deleting tags

You can remove a tag from an image in Artifact Registry using the Google Cloud Console or the command line.

Console

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click the image to view versions of the image.

  3. Select the image version to untag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. Delete the tag and then click SAVE.

gcloud

To delete a tag and remove it from the image, run the following command:

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

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.

Deleting images

When you save chart files locally as an image with the helm chart save command, Helm stores the image in its local cache. Once the image is stored in Artifact Registry, you can delete your local copy of the image from the cache.

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 in the local Helm image cache, run the following command.

helm chart remove LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

Replace the following values:

  • LOCATION is the regional or multi-regional location of the repository.
  • PROJECT is your Google Cloud project ID.
  • 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 image version.

To delete an image stored in Artifact Registry:

Console

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click on 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 box, 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 enables you to 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