Installing IBM software onto IBM Cloud Private

You can install other IBM® software onto IBM Cloud Private to either extend the functionality of the IBM Cloud Private platform or add to the IBM Cloud Private Catalog.

Note: These procedures apply to software that requires entitlement and to software that does not. These procedures also require an Internet connection. If you are installing software without an Internet connection, see Adding featured applications to clusters in an airgap environment.

There are three ways that you might install IBM software onto IBM Cloud Private with an Internet connection:

Adding IBM software directly from a Helm repository in the IBM Cloud Private Catalog.
Adding IBM software to the IBM Cloud Private Catalog: You can use the CLI to manually install the IBM software and then load the Helm chart into the IBM Cloud Private Catalog.
Installing IBM software onto the IBM Cloud Private platform: You can use the IBM Cloud Private installer to install and activate the IBM software immediately on the cluster.

You can obtain IBM software that can integrate with IBM Cloud Private through IBM Cloud Private bundles, IBM Cloud Paks, and IBM Certified Containers. Each IBM Cloud Private bundle and IBM Cloud Pak contains different entitled software that is either already available in the ibm-entitled-charts Helm repository in IBM Cloud Private Catalog, or that you can download from IBM Passport Advantage. The list of add-ons that are available on Passport Advantage changes frequently, as new ones are added. For more information, see IBM Cloud Private bundles, IBM Cloud Paks, and IBM Certified Containers.

These procedures are provided in the preferred order that that you complete them. Not all of these methods apply to all products. When you go in order, the first method that works is the method that you use to install the product. After you install your product, stop the procedures.

Required user type or access level: Cluster administrator or team administrator

Adding IBM software from the IBM Cloud Private Catalog

In some cases, the software that you are installing is provided in a Helm repository that is available in the IBM Cloud Private Catalog. You must manually install the Helm charts for other products that can integrate with IBM Cloud Private.

Before starting the procedures, complete the following prerequisites:

Install IBM Cloud Private. See Installing IBM Cloud Private Cloud Native, Enterprise, and Community editions.
Install the IBM Cloud Private CLI and log in to your cluster. See Installing the IBM Cloud Private CLI.
Configure authentication from your computer to the Docker private image registry host and log in to the private registry. See Configuring authentication for the Docker CLI.
If you are not a root user, ensure that your account is part of the docker group. See Post-installation steps for Linux® in the Docker documentation.
Ensure that you have a stable network connection between your computer and the cluster.

To install IBM software and load a Helm chart from the Catalog:

Log in to your IBM Cloud Private cluster.
Select Catalog in the menu bar to view the available software in the Catalog. Tip: You can make a selection in the Repositories menu to select the Helm repository that contains the software that you want to install:
- ibm-charts - Contains the Helm charts from IBM that are available.
- local-charts - Contains the Helm charts that you downloaded locally.
- mgmt-charts - Contains the Helm charts that are used for IBM Cloud Private environment requirements.
- ibm-charts-public - Contains the Helm charts for IBM software that are for general use.
- ibm-community-charts - Contains the charts that are made available by the open source community.
- ibm-entitled-charts - Contains the charts that require an entitlement key to install.
If you don't see the Helm repository that contains the software that you want to install, add it by completing the following steps:
1. In the main navigation, select Manage -> Helm Repositories.
2. Select Add Repository.
3. Add the name of your repository. For example, ibm-entitled-charts.
4. Enter the URL for the repository. For example, use the following URL for the connection for the new repository: https://raw.githubusercontent.com/IBM/charts/master/repo/entitled/.
5. Select Options for the repository, and select Sync to synchronize the content in the repository.
Deploy your software without a required entitlement. Important: If your software requires entitlement, skip to step 5.
1. Select Catalog in the title bar to view the Catalog contents.
2. In the Repositories menu, select the Helm repository that contains your content. The product that you want to deploy might appear on the list. If you do not see the product in that list, see Adding IBM software to the IBM Cloud Private Catalog for the steps that explain how to add the product to the Catalog by downloading it from IBM Passport Advantage.
3. Select the product that you want to deploy.
4. Install the content. If the product that you are installing requires entitlement and the secret is not configured correctly, the installation fails.
Deploy the software content with a required entitlement. Important: If your software does not require entitlement, complete step 4 instead of this step.
1. Obtain the entitlement key that is assigned to your ID.
  1. Log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software.
  2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
2. Create the secret in your IBM Cloud Private namespace by logging in to the IBM Cloud Private management console with editor permissions, or higher, and completing the steps in the Creating Secrets section of Managing Secrets. Tip: the user ID for creating the secret is cp, and the password is the entitlement key that you copied in the previous sub-step.
3. Select Catalog in the title bar to view the Catalog contents.
4. In the Repositories menu, select ibm-entitled-charts. The entitled content that you want to deploy should appear in the list. If you do not see the product in that list, see Adding IBM software to the IBM Cloud Private Catalog for the steps that explain how to install the product by downloading it from IBM Passport Advantage.
5. Select the product that you want to deploy.
6. Install the content into your cluster. If the secret is not configured correctly, or the package is not available, the installation fails.
Note: You can load the Helm charts only by using the Catalog. You cannot load the charts by using the Helm CLI.

Adding IBM software to the IBM Cloud Private Catalog

For this procedure, you must manually install the Helm charts for other products that can integrate with IBM Cloud Private.

Before you load a chart, complete the following prerequisites:

Install IBM Cloud Private. See Installing IBM Cloud Private Cloud Native, Enterprise, and Community editions.
Install the IBM Cloud Private CLI and log in to your cluster. See Installing the IBM Cloud Private CLI.
Configure authentication from your computer to the Docker private image registry host and log in to the private registry. See Configuring authentication for the Docker CLI.
If you are not a root user, ensure that your account is part of the docker group. See Post-installation steps for Linux® in the Docker documentation.
Ensure that you have a stable network connection between your computer and the cluster.

To install IBM software and load a Helm chart into the Catalog:

Download the compressed file from IBM Passport Advantage® .
Ensure that you have enough disk space to load the images in the compressed files to your computer.
1. Check the Docker disk usage by running the following command:
```
docker system df
```
  For more command options, see docker system df in the Docker documentation.
2. If you need more disk space, perform one of the following actions:
  - Remove the old Docker images.
  - Increase the amount of storage that the Docker daemon uses. To increase the amount of storage that the Docker daemon uses, see the entry for dm.basesize in the dockerd Docker documentation.
Log in to your cluster from the IBM Cloud Private CLI and log in to the Docker private image registry by entering the following command:
```
 cloudctl login -a https://<Cluster Master Host>:<Cluster Master API Port> --skip-ssl-validation
 docker login <cluster_CA_domain>:8500
```
Where, <Cluster Master Host>:<Cluster Master API Port> is defined in Master endpoint. The cluster_CA_domain is the certificate authority (CA) domain. If you did not specify a CA domain, the default value is mycluster.icp. See Specifying your own certificate authority (CA) for IBM Cloud Private services.
Install the file from Passport Advantage:
- For either Linux or Windows, run the following command:
```
cloudctl catalog load-archive --archive <compressed_file_name> --registry mycluster.icp:8500/namespace
```
  The compressed_file_name parameter is the name of the file that you downloaded from Passport Advantage, --registry is the registry where the Docker image is pushed to, and namespace is the Docker namespace that hosts the Docker image.
- For macOS, run the following command:
```
cloudctl catalog load-archive --archive <compressed_file_name> --username user --password pass --registry mycluster.icp:8500/namespace
```
Note: The --registry parameter is not required. If the --registry parameter is not specified, images are uploaded to the registry associated with the default cluster CA domain and the current targeted namespace.
View the charts in the IBM Cloud Private Catalog:

From the IBM Cloud Private management console, click Catalog. The new Helm charts load into the Catalog, and you can install them into your cluster.

Note: You can load the Helm charts by using only the Catalog. You cannot load the charts by using the Helm CLI.

Installing IBM software onto the IBM Cloud Private platform

You can use the IBM Cloud Private installer to install and activate the IBM software immediately on the cluster.

Before you begin, you must have an installed IBM Cloud Private cluster that is version 3.2.1 or later.

To install IBM software onto IBM Cloud Private:

Download the compressed file from IBM Passport Advantage® .
Optional: Prepare the archive dependency yaml resource file.
Optional: Create a directory called resources in your cluster directory and put the yaml resource file under it.
```
 mkdir -p cluster/resources
 mv your-resource.yaml cluster/resources/
```
Create a directory called addon in your cluster directory by running the following command:
```
 mkdir -p cluster/addon
```
Move the archive package to the directory that you just created. For example:
```
 mv software-version.tgz cluster/addon/
```
Update the cluster/config.yaml file by adding the following content. For example:
```
 archive_addons:
   software_name:
     namespace: default
     repo: local-charts
     path: addon/software-version.tgz

     charts:
       - name: software
         values:
           service:
           name: software-service
```
The following list describes the content in the example:
- namespace: The namespace where you want to upload IBM Passport Advantage images and install your IBM Passport Advantage charts.
- repo: The Helm repo where you want to upload the IBM Passport Advantage charts. This can be either local-charts or mgmt-charts.
- path: The IBM Passport Advantage package path relative to the cluster directory.
- charts: A list of charts that you want to install. If no charts are listed, no chart is installed.
- charts[].name: The Passport Advantage chart that is installed with the installation of IBM Cloud Private.
- charts[].values: The customized values of the IBM Passport Advantage chart.
Run the IBM Cloud Private installation command. The installer uploads the specified charts and images to the Helm repository and registry.