IBM Cloud Docs
Using Helm charts in Container Registry

Using Helm charts in Container Registry

You can securely store and share Helm charts with other users in IBM Cloud® Container Registry.

OCI support for Helm charts

The Open Container Initiative (OCI) released Open Container Initiative Distribution Specification v1.0.0 in September 2021. This specification supports other artifact types in addition to container images. One of the artifact types that is supported is the Helm chart.

Helm v3.8.0 provides support to store and work with charts in OCI registries, as an alternative to Helm chart repositories. For more information, see the Helm Registries documentation.

Adding Helm charts to your namespace

You can securely store and share Helm charts with other users by adding charts to your namespaceA collection of repositories that store images in a registry. A namespace is associated with an IBM Cloud account, which can include multiple namespaces. in IBM Cloud Container Registry.

Every Helm chart that you want to add to your namespace must exist on your local computer first. You can either download (pull) a chart from another repository to your local computer, or build your own chart by using the helm create command. To add a chart to your namespace, you must upload (push) the local chart to your namespace in IBM Cloud Container Registry.

Do not put personal information in your charts (for example, in namespace names or description fields) or in any chart or chart configuration data (for example, chart names or chart labels).

Pulling charts from another registry or Helm repository

You can pull (download) a chart from any private or public registryA storage and distribution service that contains public or private images that are used to create containers. source or Helm repository, and then tag it for later use in IBM Cloud Container Registry.

Pull a chart from a private or public registry or Helm repository to your computer.
Pull charts from another registry

Before you begin, complete the following tasks.

  1. Download the Helm chart to your local computer.

    • Download the Helm chart from the OCI registry:

      helm pull oci://<registry/<my_namespace>/<chart_name> --version <chart_version>

      Example, where <registry> is localhost:5000, <my_namespace> is helm-charts, <chart_name> is mychart, and <chart_version> is 0.1.0:

      helm pull oci://localhost:5000/helm-charts/mychart --version 0.1.0

    • Download the Helm chart from a Helm repository:

      helm pull <chart URL | repo/chartname> --version <chart_version>

      Example, where <repo/chartname> is ibm-charts/ibm-istio and <chart_version> is 1.2.2.

      You can add the repo alias by using the helm repo add command.

      helm pull ibm-charts/ibm-istio  --version 1.2.2

    If you get an unauthorized: authentication required or a denied: requested access to the resource is denied message, run the ibmcloud cr login command.

After you pull a chart for your namespace, you can upload (push) the chart from your local computer to your namespace.

Pushing Helm charts to your namespace

You can push (upload) a chart to your namespace in IBM Cloud Container Registry to store and share your chart with other users.

Push a chart from your computer to IBM Cloud Container Registry.
Push charts to your namespace

Before you begin, complete the following tasks.

To upload (push) a chart, complete the following steps:

  1. Log in to the CLI by running the ibmcloud cr login command.

    ibmcloud cr login

    You must log in if you pull a chart from your private IBM Cloud Container Registry.

  2. To view all namespaces that are available in your account, run the ibmcloud cr namespace-list command.

  3. Upload the chart to your namespace.

    helm push <my_chart_package> oci://<region>.icr.io/<my_namespace>

    Example, where <my_chart_package> is mychart-0.1.0.tgz, <region> is uk, and <my_namespace> is helm-charts:

    helm push mychart-0.1.0.tgz oci://uk.icr.io/helm-charts

    If you get an unauthorized: authentication required or a denied: requested access to the resource is denied message, run the ibmcloud cr login command.

After you push your chart to IBM Cloud Container Registry, you can install the Helm chart to the cluster in IBM Cloud Kubernetes Service.

Copying charts between registries

You can pull a chart from a registry in one region and push it to a registry in another region so that you can share the chart with users in both regions.

Copying charts between registries.
Copying charts between registries

Before you begin, complete the following tasks.

To copy a chart between two registries, complete the following steps:

  1. Pull a chart from a registry.
  2. Push the chart to another registry. Make sure that you use the correct domain name for the new region that you are targeting.

After you copy your chart, you can install the Helm chart to the cluster in IBM Cloud Kubernetes Service.

Installing a Helm chart to the cluster

You can install a Helm chart to the cluster in IBM Cloud Kubernetes Service directly from the registry. Follow the instructions in the Helm chart README, and use the full registry reference to the chart and chart version for installation.

helm install <release_name> oci://<region>.icr.io/<my_namespace>/<chart_name> --version <chart_version>

Example, where <release_name> is myrelease, <region> is uk, <my_namespace> is helm-charts, <chart_name> is mychart, and <chart_version> is 0.1.0:

helm install myrelease oci://uk.icr.io/helm-charts/mychart --version 0.1.0

Deleting charts from your private repository

You can delete unwanted charts from your private IBM Cloud repository by using either the IBM Cloud console or the CLI.

If you want to delete a private repository and its associated charts, see Deleting a private repository and any associated charts.

Deleting a chart that is being used by an existing deployment might cause a Helm upgrade, rollback, or delete to fail.

If you want to restore a deleted chart, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected chart by running the ibmcloud cr image-restore command. You can use these commands because Helm charts are a supported artifact type in OCI.

Where multiple tagsA user-defined identifier attached to a grouping of resources that are contained in an account. Tags are visible account-wide. exist for the same chart digest within a repository, the ibmcloud cr image-rm command removes the underlying chart and all its tags. If the same chart exists in a different repository or namespace, the copy of the chart is not removed.

A tag must always match the chart's semantic version, which means that a latest tag isn't used.

Deleting charts from your private repository in the CLI

You can delete unwanted charts and all their tags from your private IBM Cloud repository by using the CLI.

Deleting a chart that is being used by an existing deployment might cause a Helm upgrade, rollback, or delete to fail.

If you want to restore a deleted chart, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected chart by running the ibmcloud cr image-restore command.

To delete a chart by using the CLI, complete the following steps:

  1. Log in to IBM Cloud by running the ibmcloud login command.

  2. To delete a chart, run the following command, where CHART is the name of the chart that you want to remove, in the format repository@digest or repository:tag. Unlike images, a tag must be specified because the latest tag doesn't exist because a tag must always match the chart's semantic version. You can delete multiple charts by listing each private IBM Cloud registry path in the command with a space between each path.

    ibmcloud cr image-rm CHART

    To find the names of your charts, run ibmcloud cr image-list. The registry stores different artifact types that include Helm charts and container images. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. To identify your chart by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest.

  3. Verify that the chart was deleted by running the following command, and check that the chart does not show in the list.

    ibmcloud cr image-list

Deleting charts from your private repository in the console

You can delete unwanted charts and all their tags from your private IBM Cloud repository by using the IBM Cloud console.

Deleting a chart that is being used by an existing deployment might cause a Helm upgrade, rollback, or delete to fail.

If you want to restore a deleted chart, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected chart by running the ibmcloud cr image-restore command.

To delete a chart by using the IBM Cloud console, complete the following steps.

  1. Log in to the IBM Cloud console https://cloud.ibm.com/login with your IBMid.
  2. If you have multiple IBM Cloud accounts, select the account and region that you want to use from the account menu.
  3. Click the Navigation menu icon, then click Container Registry.
  4. Click Images. A list of your charts (and images if they exist) is displayed. The registry stores different artifact types that include Helm charts and container images.
  5. In the row that contains the chart that you want to delete, select the checkbox.
  6. Click Delete Image.

Listing charts in the trash

You can list deleted charts that are in the trash and see when they expire.

To find out which charts are in the trash, you can use the ibmcloud cr trash-list command. Charts are stored in the trash for 30 days.

To list the charts in the trash, complete the following steps.

  1. Log in to IBM Cloud by running the ibmcloud login command.

  2. You can list the charts in the trash by running the following command.

    ibmcloud cr trash-list

  3. You can list only the charts in the trash for the namespace that you are interested in by running the following command, where <namespace> is your namespace.

    ibmcloud cr trash-list --restrict <namespace>

Restoring charts

You can restore the charts from the trash. Deleted charts are stored in the trash for 30 days.

You can restore a chart from the trash by running the ibmcloud cr image-restore command. To find out which charts are in the trash, run the ibmcloud cr trash-list command.

You can restore the charts by running the ibmcloud cr image-restore command. You can use the following options:

Restoring charts by digest

When you restore a chart by digest, the digest is moved from the trash into your live repository, and all the tags for that digest in the repository are restored.

To restore a chart by digest from the trash, complete the following steps:

  1. Log in to IBM Cloud by running the ibmcloud login command.

  2. List the charts in the trash by running the following command.

    ibmcloud cr trash-list

    A table is displayed that shows the items in the trash. The table shows the digest, the days until expiry, and the tags for that digest.

  3. Note the digest for the chart that you want to restore.

  4. Run the following command to restore the chart to your repository. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, and <digest> is the digest of the chart that you want to restore.

    ibmcloud cr image-restore <dns>/<namespace>/<repo>@<digest>

    If some tags aren't restored, see Why aren't all the tags restored when I restore by digest? for assistance.

    In your live repository, you can pull the chart by digest. If you run the ibmcloud cr image-digests command, the chart shows in the output.

Restoring charts by tag

When you restore a chart by tag, only that specific tag is moved out of the trash into your live repository.

To restore a chart by tag from the trash, complete the following steps.

  1. Log in to IBM Cloud by running the ibmcloud login command.

  2. List the charts in the trash by running the following command.

    ibmcloud cr trash-list

    A table is displayed that shows the items in the trash. The table shows the digest, the days until expiry, and the tags for that digest.

  3. For the chart that you want to restore, make a note of the digest up to, but not including, the at sign (@). This section of the digest is <dns>/<namespace>/<repo>, where <dns> is the domain name, <namespace> is the namespace, and <repo> is the repository.

  4. For the chart that you want to restore, make a note of the tag <tag>.

  5. Run the following command to restore the chart to your repository, where <dns>/<namespace>/<repo> is the name of the chart that you want to restore and <tag> is the tag.

    ibmcloud cr image-restore <dns>/<namespace>/<repo>:<tag>

    In your live repository, you can pull the chart by tag.

    If you run the ibmcloud cr trash-list command, the digest and any other tags show in the output, but the tag is no longer displayed.

Deleting a private repository and any associated charts

You can delete private repositories that are no longer required, and any associated charts, by using the IBM Cloud console.

When you delete a repository, all charts in that repository are deleted. This action can't be undone.

Before you begin, you must back up any charts that you want to keep.

To delete a private repository by using the IBM Cloud console, complete the following steps.

  1. Log in to the IBM Cloud console https://cloud.ibm.com/login with your IBMid.

  2. If you have multiple IBM Cloud accounts, select the account and region that you want to use from the account menu.

  3. Click the Navigation menu icon, then click Container Registry.

  4. Click Repositories. A list of your private repositories is displayed.

  5. In the row that contains the private repository that you want to delete, select the checkbox.

    Ensure that the correct repository is selected because this action can't be undone.

  6. Click Delete Repository.