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 the 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 on the Overview page of your Container Registry Enterprise Edition instance. When the component starts to run, you can manage chart repositories. Turn on Charts

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 Container Registry Enterprise Edition instance

  1. 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 required Container Registry Enterprise Edition instance.
    4. On the management page of the Container Registry Enterprise Edition instance, choose Repository > Namespace in the left-side navigation pane.
    5. On the Namespace page, click Create Namespace.
    6. In the Create Namespace dialog box, set the Namespace, whether to Automatically Create Repository, and Default Repository Type parameters, and click Confirm.
  2. Create a repository for the Container Registry Enterprise Edition instance.
    1. On the management page of the Container Registry Enterprise Edition instance, choose Repository > Repositories in the left-side navigation pane.
    2. On the Repository page, click Create Repository.
    3. In the Repository Info step, set the Namespace, Repository Name, Repository Type, Tags, Accelerated Image, Summary, and Description parameters, and click Next.
    4. In the Code Source step, set the Code Source, Build Settings, and Build Rules parameters, and then click Create Repositories.
      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 dependent base image for every image to be built. This may prolong the build time.
      Build Rules After the repository is created, you can go to the Build page to create build rules. For more information, see Create a repository and build images.
  3. Configure an access credential.
    Set a password or a temporary token that is used to log on to the repositories of your Container Registry Enterprise Edition instance. In this example, set a password.
    1. On the management page of the Container Registry Enterprise Edition instance, choose Instances > Access Credential in the left-side navigation pane.
    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.
  4. 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 information about how to enable access over VPCs, see Configure access over VPCs.
    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 Container Registry Enterprise Edition instance and the description, and click Confirm.

Step 2: Push and pull charts

  1. Run the following command to enable the experimental feature of Helm 3.7 or later:
    export HELM_EXPERIMENTAL_OCI=1
  2. Run the following command to log on to the Container Registry 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 Container Registry Enterprise Edition instance>.cn-<The region where the Container Registry 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.

  3. Run the following command to create a HelloWorld chart:
    helm3 create helloworld
  4. Run the following command to create a compressed package from the chart directory:
    tar -zcvf test.tgz helloworld
  5. 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 Container Registry Enterprise Edition instance>-registry.cn-<The region where the Container Registry 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.
      1. 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 Container Registry Enterprise Edition instance>-registry.cn-<The region where the Container Registry Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace>/<Repository name> --version <Image version>
        Example:
        helm3 pull oci://***-registry.cn-hangzhou.cr.aliyuncs.com/test/trem --version helloworld
      2. Run the following command to decompress the chart package:
        tar -xzvf helloworld-[image version].tgz

Use Helm 3.7 or earlier to push and pull charts

Step 1: Configure your Container Registry Enterprise Edition instance

  1. 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 required Container Registry Enterprise Edition instance.
    4. On the management page of the Container Registry Enterprise Edition instance, choose Repository > Namespace in the left-side navigation pane.
    5. On the Namespace page, click Create Namespace.
    6. In the Create Namespace dialog box, set the Namespace, whether to Automatically Create Repository, and Default Repository Type parameters, and click Confirm.
  2. Create a repository for the Container Registry Enterprise Edition instance.
    1. On the management page of the Container Registry Enterprise Edition instance, choose Repository > Repositories in the left-side navigation pane.
    2. On the Repository page, click Create Repository.
    3. In the Repository Info step, set the Namespace, Repository Name, Repository Type, Tags, Accelerated Image, Summary, and Description parameters, and click Next.
    4. In the Code Source step, set the Code Source, Build Settings, and Build Rules parameters, and then click Create Repositories.
      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 dependent base image for every image to be built. This may prolong the build time.
      Build Rules After the repository is created, you can go to the Build page to create build rules. For more information, see Create a repository and build images.
  3. Configure an access credential.
    Set a password or a temporary token that is used to log on to the repositories of your Container Registry Enterprise Edition instance. In this example, set a password.
    1. On the management page of the Container Registry Enterprise Edition instance, choose Instances > Access Credential in the left-side navigation pane.
    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.
  4. 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 information about how to enable access over VPCs, see Configure access over VPCs.
    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 Container Registry Enterprise Edition instance and the description, and click Confirm.

Step 2: Push and pull charts

  1. 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 helm version -c command to check the version. In this example, the version of the client is 3.0.2.
  2. Run the following command to enable the experimental feature for the Helm 3.X:
    export HELM_EXPERIMENTAL_OCI=1
  3. Run the following command to log on to the Container Registry 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 Container Registry Enterprise Edition instance>.<The region where the Container Registry 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.

  4. Run the following command to create a HelloWorld chart:
    helm3 create helloworld
  5. Push and pull charts.
    • Push the chart to repositories.
      1. Run the following command to save the chart directory as the image tag of the repository in the Container Registry Enterprise Edition:
        helm3 chart save helloworld <Name of the Container Registry Enterprise Edition instance>.<The region where the Container Registry Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace>/<Repository name>:<Image tag>
        Example:
        helm3 chart save helloworld m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest
      2. Run the following command to push the image tag to the repository in the Container Registry Enterprise Edition instance.
        helm3 chart push <Name of the Container Registry Enterprise Edition instance>.<The region where the Container Registry Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace>/<Repository name>:<Image version>
        Example:
        helm3 chart push m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest
    • Pull a chart from repositories.
      1. Run the following command to pull the specified image tag from the repository in the Container Registry Enterprise Edition.
        helm3 chart save helloworld <Name of the Container Registry Enterprise Edition instance>.<The region where the Container Registry Enterprise Edition instance resides>.cr.aliyuncs.com/<Namespace>/<Repository name>:<Image tag>
        Example:
        helm3 chart save helloworld m**-registry.cn-hangzhou.cr.aliyuncs.com/m**/test:latest
      2. 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 Container Registry Enterprise Edition instance>.<The region where the Container Registry Enterprise Edition instance resides>.cr.aliyuncs.com/<Name of the Namespace>/<Repository name>:<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

  1. 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.
  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                    
  3. 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 you use Helm 3.7 or earlier and your server resides within the Chinese mainland and runs the Linux operating system, 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 you use Helm 3.7 or earlier and your server resides within the Chinese mainland and runs the Mac operating system, 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 you use Helm 3.7 or later and your server resides within the Chinese mainland and runs the Linux operating system, 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
  4. 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 Container Registry Enterprise Edition instance

  1. 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 required Container Registry Enterprise Edition instance.
    4. On the page that appears, choose Chart Repository > Namespace.
    5. On the Namespace page, click Create Namespace.
    6. In the Create Namespace dialog box, set the Namespace, Automatically Create Repository, and Default Repository Type parameters, and click Confirm.
  2. 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 Container Registry 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. On the management page of a Container Registry Enterprise Edition instance, choose Helm Chart > Repositories in the left-side navigation pane.
    2. On the Chart Repositories page, click Create Repositories.
    3. In the Create Helm Chart dialog box, set the Namespace, Repository Name, and Type parameters, and click Confirm.
  3. Configure an access credential.
    Set a password or a temporary token that is used to access Helm charts. In this example, set a password.
    1. On the management page of the Container Registry Enterprise Edition instance, choose Instances > Access Credential in the left-side navigation pane.
    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.
  4. 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 access over VPCs.
    1. On the management page of a Container Registry Enterprise Edition instance, choose Helm Chart > Access Control in the left-side navigation pane.
    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 Container Registry Enterprise Edition instance and the description, and click Confirm.
  5. 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='<The account in the access credential of the Container Registry Enterprise Edition instance>';
    export HELM_REPO_PASSWORD='<The password in the access credential of the Container Registry Enterprise Edition instance>';
    helm repo add <Local repository name> acr://<Iinstance name>-chart.<Region ID>.cr.aliyuncs.com/<Namespace>/<Chart repository> --username ${HELM_REPO_USERNAME} --password ${HELM_REPO_PASSWORD}            
    Configure on-premises repository mapping

Step 3: Push and pull charts

  1. 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 required Container Registry Enterprise Edition instance.
    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.
  2. Push a chart.
    1. 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> <On-premises repository name>
      
      # Push the compressed chart package. 
      helm push <Chart name>-<Chart version>.tgz <On-premises repository name>            
      Push a chart.
    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.
  3. 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 <On-premises repository name>/<Chart name> --version <Chart version>
    
    # Install a chart directly. 
    helm install -f values.yaml <On-premises repository name>/<Chart name> --version <Chart version>