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
- If the target repository doesn't exist, create a new repository. Choose Docker as the repository format.
- Verify that you have the required permissions for the repository.
- (Optional) Configure defaults for Google Cloud CLI commands.
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.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.
Change to the directory that contains your chart.
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:
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:
Open the Repositories page in the Google Cloud console.
Click the repository with the container image.
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
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
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 withsha256:
.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
Open the Repositories page in the Google Cloud console.
Click on the image name to see versions of that image.
Select versions that you want to delete.
Click DELETE.
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
- Learn about managing Docker images.
- Download individual files from your repository without using Helm commands.