Adding featured applications to clusters without Internet connectivity

You can add featured applications to IBM® Cloud Private Catalog on clusters that do not have Internet connectivity.

To add applications that are part of IBM Cloud Private bundles, see Installing IBM software onto IBM Cloud Private.

Applications that have Helm charts can be packaged into archives that contain the Helm chart and the container images with the IBM Cloud Private CLI on an Internet-connected operating system. From the IBM Cloud Private CLI, you can load your created archive into the cluster without Internet connectivity.

Before you add an application, complete the following prerequisites:

Install the IBM Cloud Private command line interface (CLI) on your operating system to create the archive. See Installing the IBM Cloud Private CLI.
Install the registry certificate so that you can use the Docker registry for IBM Cloud Private on your operating system to create the archive. See Docker Registry V2 API for more information.
Install the Helm CLI on the operating system that you are using to create the archive. For more information, see Installing the Helm CLI (helm).

Required access level: Cluster administrator

Important: Ensure that you have enough space available in your local Docker repository and on your disk to create the archive. Charts might require multiple dependent images.

Adding featured applications from IBM/charts repository

The IBM Cloud charts Helm repository Opens in a new tab contains Helm charts for many applications.

From the IBM Cloud Private CLI, provide the path to the Helm chart that you want to use to create the archive. Many of the Helm charts in the IBM/charts repository contain a manifest.yaml file in the ibm_cloud_pak directory. If the manifest.yaml file exists, the application directly supports this process. If the file does not exist, the application might work if it meets certain criteria. View the Adding applications by Helm chart section for the criteria of adding an application by using only the Helm chart.
Archives support one or more CPU architectures. If the ibm_cloud_pak/manifest.yaml file exists, the CPU architectures that the archive is created for is defined. Consult the Helm chart README.md file for supported CPU architectures. If the file does not exist, the archive is created for one CPU architecture of the operating system that the archive is created on. If the file does not exist and a multiarchitecture archive is needed, you must create a manifest.yaml file. Follow the instructions in Creating an archive from a YAML file section to create a manifest.yaml file.

To create an archive from an application that is in the IBM/charts repository, complete the following steps:

Clone the repository by running the following command:
```
 git clone https://github.com/IBM/charts.git
```

 cloudctl login -a <cluster_ip> --skip-ssl-validation

Log in to a Docker registry by running the following command:
```
 docker login <cluster_hostname>:<registry_port>
```
To log in to a Docker registry named mycluster.icp:8500, run the following command:
```
 docker login mycluster.icp:8500
```
Create the archive by running the following command:
```
 cloudctl catalog create-archive -c charts/stable/<helm-chart-name> -a <path-to-archive-file-to-create>
```
- helm-chart-name is the name of the Helm chart directory.
- path-to-archive-file-to-create, is the relative or absolute path to the directory where you want to save the archive that you are creating.
  
  See the following example command:
```
cloudctl catalog create-archive -c charts/stable/ibm-transadv-dev/ -a ibm-transadv-dev.tgz
```
  For more information about the cloudctl catalog create-archive command, see IBM Cloud Private CLI catalog commands (catalog).

Load the archive by running the following command:

 cloudctl catalog load-archive --archive ibm-transadv-dev.tgz --registry <cluster_hostname>:<registry_port>/<namespace>

To upload the archive to a Docker registry named mycluster.icp:8500 using the kube-system namespace, run the following command:

 cloudctl catalog load-archive --archive ibm-transadv-dev.tgz --registry mycluster.icp:8500/kube-system

For macOS, you can load the archive by setting the DOCKER_USER and DOCKER_PWD environment variables or you can run the following command:

 cloudctl catalog load-archive --archive ibm-transadv-dev.tgz --registry mycluster.icp:8500/kube-system --username <username> --password <password>

Example bash scripts for loading multiple applications from IBM/charts

After completing the first three steps from the previous section, you can load multiple applications from IBM Cloud charts Helm repository Opens in a new tab . Complete the following steps to load multiple applications:

Complete steps 1, 2 and 3 from the previous section.

Create a create-archives.sh file and copy the the following content into your file. Edit the _white_list and _black_list array variables in the current directory with the following content:

 #!/bin/bash

 set -e

 # CONFIGURATION - modify these variables to control which Helm charts to create archives for
 # _white_list is a space-separated set of directories or files to create archives for
 #   - leave empty to create for everything in the charts directory
 #   - values should be relative to the charts directory
 _white_list=$(cat <<- EOM
 EOM
 )

 # _black_list is a space-separated set of directories or files to not create archives for
 #   - leave empty to create for everything in the charts directory
 #   - values should be relative to the charts directory
 _black_list=$(cat <<- EOM
     ibm-ace-dev ibm-cam ibm-cam-prod ibm-cem ibm-db2oltp-dev ibm-db2warehouse-dev ibm-dsm-dev ibm-dsx-dev
     ibm-eventstreams-dev ibm-f5bigip-controller ibm-iisee-eval ibm-spectrum-conductor ibm-was-vm-quickstarter
 EOM
 )

 # ARGUMENTS -  
 # $1 (required) - the directory that contains Helm chart archive files or Helm chart directories
 _charts_dir=${1%/} # remove a trailing slash
 if [[ "$_charts_dir" == "" ]]; then
     echo "Provide the path to the directory containing Helm chart source directories or archive files.   Example: ~/charts/stable"
     exit 1
 fi

 # $2 (optional) - a destination path for the created archives
 _dest_dir=${2:-$(pwd)}
 _dest_dir=${_dest_dir%/} # remove a trailing slash
 mkdir -p _dest_dir

 _charts=$(ls $_charts_dir)
 for _chart in ${_charts[@]}
 do
     _helm_chart="$_charts_dir/$_chart"
     if [ "$_white_list" != "" ]; then
         if [[ $_white_list = *"$_chart"* ]]; then
             cloudctl catalog create-archive -c $_helm_chart -a $_dest_dir/$_chart.tgz
             echo ""
         fi
     elif [[ $_black_list != "" && $_black_list = *"$_chart"* ]]; then
         echo "Skipping $_chart"
     elif [ -d "$_helm_chart" -o "${_helm_chart: -4}" == ".tgz" -o "${_helm_chart: -7}" == ".tar.gz" ]; then
         cloudctl catalog create-archive -c $_helm_chart -a $_dest_dir/$_chart.tgz
         echo ""
     fi
 done

Create the archives by running the following command:
```
 sh create-archives.sh charts/stable archives
```

Create a load-archives.sh file in the current directory with the following content:

 #!/bin/bash

 set -e # keep going even if one chart fails

 # ARGUMENTS -
 # $1 (required) - the directory that contains the archives to load
 _archives_dir=${1%/} # remove a trailing slash
 if [[ "$_archives_dir" == "" ]]; then
     echo "Provide the path to the directory containing the archives to load."
     exit 1
 fi

 _archives=$(ls $_archives_dir)
 for _archive in ${_archives[@]}
 do
     if [ "${_archive: -4}" == ".tgz" -o "${_archive: -7}" == ".tar.gz" ]; then
         echo "Loading archive $_archive ..."
         cloudctl catalog load-archive -a "$_archives_dir/$_archive"
         echo ""
     fi
 done

For macOS, you can load the archives by setting up the DOCKER_USER and DOCKER_PWD environment variables or you can run the following command:

cloudctl catalog load-archive --archive ibm-transadv-dev.tgz --registry mycluster.icp:8500/kube-system --username <username> --password <password>

Load the archives by running the following command:
```
 sh load-archives.sh archives
```

Adding applications with a Helm chart

An archive can be created only with the input of a Helm chart. This method can be used for open source community charts and private charts if the chart contents meet the following conditions:

All image repository values must be defined in the chart's values.yaml file. You cannot add hardcoded image repository values in the template YAML files.
The Helm chart must not use subcharts.
The archive that you create defines the single CPU architecture only.

Important: The method to add applications with a Helm chart might not work for all Helm charts. If you have trouble with this method, follow the steps from the Creating an archive with a manifest YAML file section.

Creating an archive with a manifest YAML file

You can create an archive by creating a manifest YAML file that defines the chart and images that go into the archive. Complete the following steps to create an archive with a manifest YAML file:

Create the manifest YAML file named manifest.yaml.

Note: The archive attribute must be a URI in one of the following formats: http://, https:// or file://. For URIs using file://, use an absolute path or a path relative to the manifest.yaml file.

Create a manifest YAML file for a single CPU architecture archive. Your manifest.yaml file might resemble the following content:

charts:
- archive: <URI to the Helm chart archive file>
  repository-keys:
  - <values.yaml image key in dot notation to modify at load time>
  registry-keys:
  - <values.yaml image registry key in dot notation to replace at load time>
images:
- image: <the image name and tag to be loaded into the image registry>
  references:
  - repository: <the same value as image above>
    pull-repository: <the image and tag to pull in to the archive>

View the manifest.yaml file from the redis-ha chart in the Helm repository Opens in a new tab , assuming that the chart is packaged as redis-ha-3.1.5.tgz in the same directory as the manifest.yaml file:

charts:
- archive: file://redis-ha-3.1.5.tgz
  repository-keys:
  - image.repository
images:
- image: redis:5.0.3
  references:
  - repository: redis:5.0.3
    pull-repository: redis:5.0.3

Create a manifest YAML file for multiple CPU architecture archives:

charts:
- archive: <URI to the Helm chart archive file>
  repository-keys:
  - <values.yaml image key in dot notation to modify at load time>
  registry-keys:
  - <values.yaml image registry key in dot notation to replace at load time>
images:
- image: <the image name and tag to be loaded into the image registry>
  references:
  - repository: <a different value than the image value above so it is architecture specific>
    pull-repository: <the image and tag to pull in to the archive for the architecture>
    platform:
      os: linux
      architecture: <amd64|ppc64le|s390x>

View the manifest.yaml file of multiple CPU architecture archives for the redis-ha chart in the Helm repository Opens in a new tab , assuming that the chart is packaged as redis-ha-3.1.5.tgz in the same directory as the manifest.yaml file:

 charts:
 - archive: file://redis-ha-3.1.5.tgz
   repository-keys:
   - image.repository
 images:
 - image: redis:5.0.3
   references:
   - repository: redis-amd64:5.0.3
     pull-repository: amd64/redis:5.0.3
     platform:
       os: linux
       architecture: amd64
   - repository: redis-ppc64le:5.0.3
     pull-repository: ppc64le/redis:5.0.3
     platform:
       os: linux
       architecture: ppc64le
   - repository: redis-s390x:5.0.3
     pull-repository: s390x/redis:5.0.3
     platform:
       os: linux
       architecture: s390x

Create the archive by running the following command:
```
 cloudctl catalog create-archive -s <path-to-yaml-file> -a <path-to-archive-file>
```
- path-to-yaml-file is the relative or absolute path to the location of the YAML file.
- path-to-archive-file is the relative or absolute path to the directory where you want to save the archive that you are creating.
  - Create an archive for your Helm chart. Your command might resemble the following line:
```
cloudctl catalog create-archive -s manifest.yaml -a <helm-chart-name>redis-ha-3.1.5-archive.tgz
```
  - Create an archive for the redis-ha chart by running the following command:
```
cloudctl catalog create-archive -s manifest.yaml -a redis-ha-3.1.5-archive.tgz
```
Log in to the Docker registry by running the following command:
```
 docker login <cluster_hostname>:<registry_port>
```
To log in to a Docker registry named mycluster.icp:8500, run the following command:
```
 docker login mycluster.icp:8500
```

Load the archive from the Helm chart by running the following command:

 cloudctl catalog load-archive --archive <archive_helm_chart_name> --registry <cluster_hostname>:<registry_port>/<namespace>

To upload the archive from the redis-ha chart to a Docker registry named mycluster.icp:8500 using the kube-public namespace, run the following command:
```
cloudctl catalog load-archive --archive redis-ha-3.1.5-archive.tgz --registry mycluster.icp:8500/kube-public
```

For macOS, you can load the archive by setting up the DOCKER_USER and DOCKER_PWD environment variables or you can run the following command:

cloudctl catalog load-archive --archive redis-ha-3.1.5-archive.tgz --registry mycluster.icp:8500/kube-public --username <username> --password <password>

Featured applications from the IBM Cloud Private Catalog is added on to your cluster without Internet connectivity.