Push and pull Helm charts - Container Registry - Alibaba Cloud Documentation Center

The Helm chart feature of Container Registry Enterprise Edition helps you effectively manage and distribute various Kubernetes resources. You can push and pull charts only after you have installed and configured a Helm client and configured a Container Registry Enterprise Edition instance. This topic describes how to use Helm 2.X and 3.X to push and pull charts.

Background information

Kubernetes provides a unified API which you can use to define Kubernetes resources in YAML files. Kubernetes has a variety of resource types, such as Deployments, StatefulSets, and ConfigMaps.

As the YAML-based software delivery system is constantly improved, the Cloud Native Computing Foundation (CNCF) community has developed charts and its implementation tool Helm to manage resources at a higher level.

A chart is a collection of files that describe a related set of Kubernetes resources. For example, a chart can be a collection of files that describe WordPress and MySQL resources or a collection of resource description files for an etcd cluster.
Helm is a command-line interface (CLI) tool used to manage charts and their releases.

Container Registry Enterprise Edition allows you to manage Helm 2.X and 3.X. The Helm clients help you manage your cloud-native assets with ease. Helm clients of different versions allow you to manage Helm charts in different ways:

If you use Helm 3.X, you can directly use Container Registry Enterprise Edition to manage Helm charts.
If you use Helm 2.X, you must turn on Charts in the Component Settings section on the Overview page of your Enterprise Edition instance. When the component starts to run, you can manage chart repositories.

Use Helm 3.X to push and pull charts

Note

To distinguish from Helm 2, this section uses helm3 commands.

Use Helm 3.7 or later to push and pull charts

Step 1: Configure your Enterprise Edition instance

Create a namespace.
1. Log on to the Container Registry console.
2. In the left-side navigation pane, click Instances.
3. On the Instances page, click the Enterprise Edition instance that you want to manage.
4. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Repository > Namespace.
5. On the Namespace page, click Create Namespace.
6. In the Create Namespace dialog box, set Namespace, Automatically Create Repository, and Default Repository Type, and then click Confirm.

Creates a repository for the Enterprise Edition instance.

In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Repository > Repositories.
On the Repositories page, click Create Repository.
In the Repository Info step, set Namespace, Repository Name, Repository Type, Tags, Accelerated Images, Summary, and Description. Then, click Next.

In the Code Source step, configure Code Source, Build Settings, and Build Rules, and then click Create Repository.

Parameter	Description
Code source	The code source.
Build Settings	Automatically Build Images When Code Changes: An image is automatically built when code is committed from a branch. Intelligently Build Overseas Sources: Images are built on servers outside the Chinese mainland and then pushed to the repository in the specified region. Build Without Cache: The system pulls the relied base image for every image to be built. This may prolong the building duration.
Build Rules	After the repository is created, go to the image building page to create image building rules. For more information, see Create a repository and build images.

Configure an access credential.
Set a password or a temporary token that is used to log on to the repositories of your Enterprise Edition instance. In this example, a password is set.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Instances > Access Credential.
2. On the Access Credential page, click Set Password.
3. In the Set Password dialog box, set the Password and Confirm Password parameters. Click Confirm.
Configure console access policies.
Enable Internet access or enable access over a virtual private cloud (VPC) to facilitate the upload of Helm charts. In this example, Internet access is enabled. For more information about how to enable access over VPCs, see Configure a VPC ACL.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Repository > Access Control.
2. On the Access Control page, click the Internet tab.
3. On the Internet tab, turn on Access Portal and click Add Internet Whitelist.
4. In the Add Internet Whitelist dialog box, specify the CIDR block that is allowed to access the Enterprise Edition instance and the description, and click Confirm.

Step 2: Push and pull charts

Run the following command to enable the experimental feature of Helm 3.7 or later:
```
export HELM_EXPERIMENTAL_OCI=1
```
Run the following command to log on to the Enterprise Edition instance:
Replace <Registry logon name> with your Alibaba Cloud account.
Note
If you push and pull a public chart repository, you can turn on Pull from Anonymous Users on the Overview page in the Container Registry console. You can then pull the public chart repositories anonymously without logging on.
```
helm3 registry login -u <Registry logon name> <Name of the Enterprise Edition instance>-registry.cn-<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com
```
Example:
```
helm3 registry login -u acr_test_***@test.aliyunid.com ***-registry.cn-hangzhou.cr.aliyuncs.com
```
In the command output, enter the logon password. The logon password is the password that you set in Step 1.
Run the following command to create a HelloWorld chart:
```
helm3 create helloworld
```
Run the following command to create a compressed package from the chart directory:
```
tar -zcvf test.tgz helloworld
```

Push and pull charts.

Push the chart package to repositories.

Note

You must conclude the path of the chart package with the namespace of the repository.

helm3 push test.tgz oci://<Name of the Enterprise Edition instance>-registry.cn-<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com/<namespace>

Example:

helm3 push test.tgz oci://***-registry.cn-hangzhou.cr.aliyuncs.com/test

Pull the chart package from the repositories.

Run the following command to pull the chart package from the repositories:

Note

You must conclude the path of the repository from which the chart is pulled with the name of the repository.

helm3 pull oci://<Name of the Enterprise Edition instance>-registry.cn-<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace name>/<Image repository name> --version <Image tag>

Example:

helm3 pull oci://***-registry.cn-hangzhou.cr.aliyuncs.com/test/trem --version helloworld

Run the following command to decompress the chart package:
```
tar -xzvf helloworld-[Image tag].tgz
```

Use Helm 3.7 or earlier to push and pull charts

Step 1: Configure your Enterprise Edition instance

Create a namespace.
1. Log on to the Container Registry console.
2. In the left-side navigation pane, click Instances.
3. On the Instances page, click the Enterprise Edition instance that you want to manage.
4. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Repository > Namespace.
5. On the Namespace page, click Create Namespace.
6. In the Create Namespace dialog box, set Namespace, Automatically Create Repository, and Default Repository Type, and then click Confirm.

Creates a repository for the Enterprise Edition instance.

In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Repository > Repositories.
On the Repositories page, click Create Repository.
In the Repository Info step, set Namespace, Repository Name, Repository Type, Tags, Accelerated Images, Summary, and Description. Then, click Next.

In the Code Source step, configure Code Source, Build Settings, and Build Rules, and then click Create Repository.

Parameter	Description
Code source	The code source.
Build Settings	Automatically Build Images When Code Changes: An image is automatically built when code is committed from a branch. Intelligently Build Overseas Sources: Images are built on servers outside the Chinese mainland and then pushed to the repository in the specified region. Build Without Cache: The system pulls the relied base image for every image to be built. This may prolong the building duration.
Build Rules	After the repository is created, go to the image building page to create image building rules. For more information, see Create a repository and build images.

Configure an access credential.
Set a password or a temporary token that is used to log on to the repositories of your Enterprise Edition instance. In this example, a password is set.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Instances > Access Credential.
2. On the Access Credential page, click Set Password.
3. In the Set Password dialog box, set the Password and Confirm Password parameters. Click Confirm.
Configure console access policies.
Enable Internet access or enable access over a virtual private cloud (VPC) to facilitate the upload of Helm charts. In this example, Internet access is enabled. For more information about how to enable access over VPCs, see Configure a VPC ACL.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Repository > Access Control.
2. On the Access Control page, click the Internet tab.
3. On the Internet tab, turn on Access Portal and click Add Internet Whitelist.
4. In the Add Internet Whitelist dialog box, specify the CIDR block that is allowed to access the Enterprise Edition instance and the description, and click Confirm.

Step 2: Push and pull charts

Download Helm of the required version from the official website.
Note
Make sure that the version of the client is 3.X. You can run the helm3 version -c command to check the version. In this example, the version of the client is 3.0.2.
Run the following command to enable the experimental feature for the Helm 3.X:
```
export HELM_EXPERIMENTAL_OCI=1
```
Run the following command to log on to the Enterprise Edition instance:
Replace <Registry logon name> with your Alibaba Cloud account.
Note
If you push and pull a public chart repository, you can turn on Pull from Anonymous Users on the Overview page in the Container Registry console. You can then pull the public chart repositories anonymously without logging on.
```
helm3 registry login --username=<Registry logon name> <Name of the Enterprise Edition instance>.<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com
```
Example:
```
helm3 registry login --username=123@188077086902**** m**-registry.cn-hangzhou.cr.aliyuncs.com
```
In the command output, enter the logon password. The logon password is the password that you set in Step 1.
Run the following command to create a HelloWorld chart:
```
helm3 create helloworld
```

Push and pull charts.

Push the chart to repositories.

Run the following command to save the chart directory as the chart tag in the Enterprise Edition instance:

helm3 chart save helloworld <Name of the Enterprise Edition instance>.<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace name>/<Name of the image repository>:<Image tag>

Example:

helm3 chart save helloworld m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest

Run the following command to push the tag to the repository in the Enterprise Edition instance.

helm3 chart push <Name of the Enterprise Edition instance>.<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace name>/<Name of the image repository>:<Image tag>

Example:

helm3 chart push m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest

Pull a chart from repositories.

Run the following command to pull the specified tag from the repository in the Enterprise Edition instance.

helm3 chart save helloworld <Name of the Enterprise Edition instance>.<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace name>/<Name of the image repository>:<Image tag>

Example:

helm3 chart save helloworld m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest

Run the following command to export the image tag to a local directory. You can then view a local chart directory.

helm3 chart export <Name of the Enterprise Edition instance>.<Region in which the Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace name>/<Name of the image repository>:<Image tag> -d .

Example:

helm3 chart export m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest -d .

Use Helm 2.X to push and pull charts

Step 1: Install the Helm client

Download Helm of the required version from the official website.
Note
Make sure that the version of the client is 2.X. You can run the helm version -c command to check the version. In this example, the version of the client is 2.14.2.

Run the following commands to decompress the installation package of Helm and move the decompressed file to a specified directory:

# Decompress the installation package. 
tar -zxvf helm-v2.14.2-linux-amd64.tgz
# Move the decompressed file to a specified directory. 
mv linux-amd64/helm /usr/local/bin/helm

Install the Helm plug-in of Alibaba Cloud.

Note

Before you install the Helm plug-in, make sure that Git is installed.

If your server resides outside the Chinese mainland or can access GitHub, run the following command to install the Helm plug-in.
```
helm plugin install https://github.com/AliyunContainerService/helm-acr
```

If your Helm version is v3.7 or earlier and your server resides in the Chinese mainland and runs a Linux OS, run the following commands to install the Helm plug-in.

git clone https://github.com/AliyunContainerService/helm-acr.git
sed -i 's/github.com/helm-acr-releases.oss-cn-hangzhou.aliyuncs.com/g' helm-acr/scripts/install_plugin.sh
helm plugin install helm-acr

If your Helm version is v3.7 or earlier and your server resides in the Chinese mainland and runs a Mac OS, run the following commands to install the Helm plug-in.

git clone https://github.com/AliyunContainerService/helm-acr.git
sed -i '' 's/github.com/helm-acr-releases.oss-cn-hangzhou.aliyuncs.com/g' helm-acr/scripts/install_plugin.sh
helm plugin install helm-acr

If your Helm version is v3.7 or later and your server resides in the Chinese mainland and runs a Linux OS, run the following commands to install the Helm plug-in.

wget https://helm-acr-releases.oss-cn-hangzhou.aliyuncs.com/AliyunContainerService/helm-acr/releases/download/v0.8.2/helm-acr.zip
unzip helm-acr.zip
mv helm-acr-master /root/.local/share/helm/plugins/helm-acr
wget https://helm-acr-releases.oss-cn-hangzhou.aliyuncs.com/AliyunContainerService/helm-acr/releases/download/v0.8.2/helm-acr_0.8.2_linux_amd64.tar.gz
tar -xzvf helm-acr_0.8.2_linux_amd64.tar.gz
mv bin /root/.local/share/helm/plugins/helm-acr/bin

Initialize Helm.
- If Helm is installed on a node of a Container Service for Kubernetes (ACK) cluster, the tiller has been initialized by default. You only need to initialize the client. If you do not want to access Google charts at the same time, run the following command to initialize Helm:
```
helm init --client-only --skip-refresh
```
- If Helm is installed on a node of a self-managed Kubernetes cluster and you do not want to access Google charts, run the following command:
```
helm init --skip-refresh
```

Step 2: Configure your Enterprise Edition instance

Create a namespace.
1. Log on to the Container Registry console.
2. In the left-side navigation pane, click Instances.
3. On the Instances page, click the Enterprise Edition instance that you want to manage.
4. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Helm Chart > Namespace.
5. On the Namespace page, click Create Namespace.
6. In the Create Namespace dialog box, set Namespace, Automatically Create Repository, and Default Repository Type, and then click Confirm.
Create a chart repository.
Note
When Automatically Create Repository is selected for the namespace, you can use Helm to push charts to a chart repository without the need to create the chart repository in advance in the console.
The chart repository of the Enterprise Edition instance is in the following format: <Instance name>-chart.<Region ID>.cr.aliyuncs.com/<Namespace>/<Chart repository name>. The version of the chart repository is <Chart name>-<Version number>. If you want to access the chart repository over a VPC, the chart repository must be in the following format: <Instance name>-chart-vpc.<Region ID>.cr.aliyuncs.com/<Namespace>/<Chart repository name>.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Helm Chart > Repositories.
2. On the Chart Repositories page, click Create Repositories.
3. In the Create Helm Chart dialog box, set Namespace, Repository Name, and Type, and then click Confirm.
Configure an access credential.
Set a password or a temporary token that is used to access Helm charts. In this example, a password is set.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Instances > Access Credential.
2. On the Access Credential page, click Set Password.
3. In the Set Password dialog box, set the Password and Confirm Password parameters. Click Confirm.
Configure console access policies.
Enable Internet access or enable access over a VPC to facilitate the upload of Helm charts. In this example, Internet access is enabled. For more information about how to enable access over VPCs, see Configure a VPC ACL.
1. In the left-side navigation pane of the management page of the Enterprise Edition instance, choose Access Control.
2. On the Access Control page, click the Internet tab.
3. On the Internet tab, turn on Access Portal and click Add Internet Whitelist.
4. In the Add Internet Whitelist dialog box, specify the CIDR block that is allowed to access the Enterprise Edition instance and the description, and click Confirm.

Run the following commands to configure on-premises repository mapping:

You must specify an on-premises repository and map it to a chart repository in a namespace in Container Registry.

export HELM_REPO_USERNAME='<Account in the access credential of the Enterprise Edition instance>';
export HELM_REPO_PASSWORD='<Password in the access credential of the Enterprise Edition instance>';
helm repo add <Name of the on-premises repository> acr://<Instance name>-chart.<Region ID>.cr.aliyuncs.com/<Namespace>/<Chart repository> --username ${HELM_REPO_USERNAME} --password ${HELM_REPO_PASSWORD}

Step 3: Push and pull charts

Turn on Pull from Anonymous Users.
After you turn on Pull from Anonymous Users, you can access the open chart repository anonymously without logging on.
1. Log on to the Container Registry console.
2. In the top navigation bar, select a region.
3. In the left-side navigation pane, click Instances.
4. On the Instances page, click the Enterprise Edition instance that you want to manage.
5. In the Instances section on the right side of the Overview page, turn on Pull from Anonymous Users.
6. In the Tips dialog box, click OK.

Push a chart.

Run the following commands to push the chart:

# Create an on-premises chart. 
helm create <Chart name>

# Push the chart directory. 
helm push <Chart name> <Name of the on-premises repository>

# Push the compressed chart package. 
helm cm-push <Chart name>-<Chart version>.tgz <Name of the on-premises repository>

On the Chart Repositories page, click the name of the destination chart repository. On the page that appears, click Versions in the left-side navigation pane. On the Versions page, you can view the pushed chart.

Run the following command to pull the chart:

# Update the on-premises chart index from the chart repository in Container Registry. 
helm repo update

# Pull a chart. 
helm fetch <Name of the on-premises repository>/<Chart name> --version <Chart version>

# Install a chart directly. 
helm install -f values.yaml <Name of the on-premises repository>/<Chart name> --version <Chart version>