Push and pull Charts as OCI artifacts-Container Registry(ACR)-阿里云帮助中心

Helm 3 supports the Open Container Initiative (OCI) artifact format for packaging and distributing Helm charts. This topic walks you through authenticating with Container Registry, pushing a chart as an OCI artifact, and installing it to a Kubernetes cluster.

Prerequisites

Before you begin, make sure you have:

Helm 3.8 or later. Run helm version to check. OCI support became generally available in Helm 3.8.
A Container Registry instance with at least one namespace created.
Docker or another OCI-compatible client installed and configured.
Credentials (username and password, or an access token) for the registry.

Authenticate with Container Registry

Before pushing or pulling OCI artifacts, log in to the registry with the Helm client.

helm registry login <registry-domain> \
  --username <username> \
  --password <password>

Replace the placeholders with your registry details:

Placeholder	Description	Example
`<registry-domain>`	Your Container Registry endpoint	`registry.cn-hangzhou.aliyuncs.com`
`<username>`	Your Alibaba Cloud account username or RAM user	`user@example.com`
`<password>`	Your account password or access token	—

Expected output:

Login Succeeded

Note

If you use a temporary access token, the token is valid for a limited period. Refresh it before it expires to avoid authentication failures in automated pipelines.

Package a Helm chart

Package your local Helm chart into a .tgz archive before pushing it to the registry.

helm package <chart-directory>

Expected output:

Successfully packaged chart and saved it to: /path/to/<chart-name>-<version>.tgz

For example, if your chart directory is my-chart at version 0.1.0, the output file is my-chart-0.1.0.tgz.

Push a chart to the registry

Push the packaged chart to your Container Registry namespace.

helm push <chart-name>-<version>.tgz oci://<registry-domain>/<namespace>

Expected output:

Pushed: <registry-domain>/<namespace>/<chart-name>:<version>
Digest: sha256:<digest-hash>

Record the digest value. You can use it later to install the chart by digest for stronger integrity guarantees.

OCI registry URL format

The OCI registry host must be specified without a URL scheme or path. The following table shows valid and invalid formats:

Format	Valid	Note
`registry.cn-hangzhou.aliyuncs.com`	Yes	Hostname only
`localhost:5000`	Yes	Hostname with port
`https://registry.cn-hangzhou.aliyuncs.com`	No	Scheme not allowed
`registry.cn-hangzhou.aliyuncs.com/my-namespace`	No	Path not allowed in host

Always prefix the full OCI reference with oci:// when passing it to Helm commands:

oci://registry.cn-hangzhou.aliyuncs.com/my-namespace/my-chart

Pull a chart from the registry

Download a chart from the registry to your local machine.

helm pull oci://<registry-domain>/<namespace>/<chart-name> --version <version>

Note

If an archive with the same name already exists in the current directory, helm pull overwrites it without warning.

Install a chart from the registry

Install by tag

helm install <release-name> oci://<registry-domain>/<namespace>/<chart-name> \
  --version <version>

Install by digest

A digest-based install is more secure than a tag-based install because a digest is immutable — the referenced artifact cannot be replaced silently.

helm install <release-name> \
  oci://<registry-domain>/<namespace>/<chart-name>@sha256:<digest-hash>

Use the digest printed when you pushed the chart.

What's next

To automate chart pushes in a CI/CD pipeline, integrate the helm registry login and helm push commands into your build workflow.
To learn more about managing Helm charts and OCI artifacts in Container Registry, see the Container Registry documentation.
To create and develop your own Helm charts, see the Helm chart template guide.