Skip to main contentIBM Cloud Pak Playbook

Installation Guide v2020.1

Installation of the Cloud Pak for Integration 2020.1.x requires OpenShift Cloud Platform (OCP) 4.2 / 4.3.
This guide assumes you are installing into an OCP environment that meets this criteria. Both online and offline installation options are included. Review the Requirements section to determine your specific environment needs.

Prerequisites

This document does not describe how to install or configure the underlying OpenShift Cloud Platform (OCP). Prior to installing ensure you have a working OCP cluster with the necessary capacity available.

  • Check the Requirements section to ensure proper cluster sizing
  • For offline installs ensure you have downloaded the Cloud Pak for Integration Passport Advantage Archive (PPA) file for offline deployments (see requirements) and it is available from your installation server
  • All offline installation will require the docker client install on the installation server
  • For online installs make sure you have an entitlement key from MyIBM Container Software Library to access the IBM Entitled Docker Registry
  • For online installs ensure you have downloaded the Cloud Pak for Integration Passport Advantage Archive (PPA) file for online deployments (see requirements) and it is available from your installation server
  • All installation types require the OpenShift Container Platform CLI be configured on your installation server
  • Offline installation will require the docker client install on the installation server

Common Passport Advantage Part Numbers

  • CC644EN - IBM Cloud Pak For Integration 2020.1.1 On Openshift For Linux English
  • CC645EN - IBM Cloud Pak For Integration 2020.1.1 On Openshift For Linux English Online Installer

Configuring Your Installation

The installation of the Cloud Pak is configured via the settings in your config.yaml. As part of either the online or offline or air-gap install, this file will be made available to you via the installation package.

Below is an example of the config.yaml extracted from the inception image.

# Licensed Materials - Property of IBM
# IBM Cloud Pak for Integration
# @ Copyright IBM Corp. 2019 All Rights Reserved
# US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
---
# Nodes selected to run common services components.
#

Each section is described below.

cluster_nodes - This section describes which nodes in your cluster used to run Common Services. These components are split into three sections master, proxy and management. The number of nodes you specify in each section determines the number of nodes that the work can be split across and will determine the potential level resiliency. The most common best-practice approach to to specify the same three nodes for each of these. The values supplied should be chosen from the context of the results of oc get nodes. You must include master nodes in this list but you do not include your OCP master nodes.

storage_class - The storage class is the dynamic storage class that the installer will use when creating persistent volumes. The Cloud Pak for Integration base installation requires a block storage provider. Use oc get sc to view your available storage classes.

default_admin_password - The default_admin_password is the password that will be assigned the default admin user to authenticate to the Cloud Pak for Integration Navigator. Match the password format requirements for your organization. The below stanza provides a very open policy. Specify the default password for the admin user.

default_admin_password: your_password_here
password_rules:
- '(.*)'

management_services - The management_service section allows you to enable or disable some the Common Services. The default values are generally sufficient. Additional services may require additional capacity.

Offline Installation

Offline Install Process

This installation requires that you have downloaded the offline installation package and it is available from your installation server that has both Docker and the Open Container CLI installed.

1. From your installation server command line authenticate to the OpenShift Cloud Platform (OCP) cluster where you would like to install the Cloud Pak (the connection token can be copied from the OpenShift Console UI)

oc login --token=your_token_here --server=your_server_URL_here

2. Create a working directory and move the PPA archive package into that directory.

mkdir ibm-cp-int
mv ibm-cp-int-2020.1.1-offline.tgz ibm-cp-int/ibm-cp-int-2020.1.1-offline.tgz
cd ibm-cp-int

3. Extract the package and load the archive ( this may take ~10-20 minutes)

tar xvf ibm-cp-int-2020.1.1-offline.tgz
tar xf installer_files/cluster/images/common-services-boeblingen-x86_64.tar.gz -O | docker load

4. Change to the cluster directory and create the kubeconfig file that the installation will use to connect to your OCP cluster.

cd installer_files/cluster
oc config view --minify=true --flatten=true > kubeconfig

5. Edit the config.yaml and update the cluster_node section adding the names of your cluster compute / worker nodes to deploy the Common Services to. Remember, the best-practice is to use the same three nodes for each master, proxy and management. Use the exact node names from the oc get nodes command.

6. Add the storage class for your cluster in the storage_class field. The storage class must be a block storage provider. Use the exact node names from the oc get sc command.

7. Update the default_admin_password field with a suitable password

8. Define the management_services appropriate to your install. (The default is sufficient for many deployments.)

9. Start the installation (this can run for ~30-45min). The below command adds verbose logging and streams the results to an output file that can be referenced later.

sudo docker run -t --net=host -e LICENSE=accept -v $(pwd):/installer/cluster:z -v /var/run:/var/run:z -v /etc/docker:/etc/docker:z --security-opt label:disable cp.icr.io/cp/icp-foundation/icp-inception:3.2.4 addon -vvv | tee output.txt

10. Connect to the IBM Cloud Pak for Integration UI to verify the installation. Use the oc get routes -A | grep integration command to find the URL. The URL will take a form similar to the following ibm-icp4i-prod-integration.apps.your-cluster-domain.com

Online Installation

Online Install Process

This installation requires that you have downloaded the online installation package and it is available from your installation server (this may be your laptop) that has both Docker and the Open Container CLI installed.

1. Log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software. In the Entitlement Keys section, copy the entitlement key. This key will be used in future steps.

2. From your installation server command line authenticate to the OpenShift Cloud Platform (OCP) cluster where you would like to install the Cloud Pak (the connection token can be copied from the OpenShift Console UI)

oc login --token=your_token_here --server=your_server_URL_here

3. Verify that you are able to login to the public docker repo using your entitlement key. With some Cloud Pak installations (non-Integration), you would pull your inception image from this registry. For Integration you downloaded that image from PPA. This step simply verifies your entitlement key from above is valid.

docker login cp.icr.io --username cp --password <your entitlement key>

4. Create a working directory and move the PPA archive (online installation) package into that directory.

mkdir ibm-cp-int
mv ibm-cp-int-2020.1.1-online.tgz ibm-cp-int/ibm-cp-int-2020.1.1-online.tgz
cd ibm-cp-int

5. Extract the package and load the archive with Docker

tar xvf ibm-cp-int-2020.1.1-online.tgz
sudo docker load -i installer_files/cluster/images/icp-inception-3.2.4.tgz

4. Change to the cluster directory and create the kubeconfig file that the installation will use to connect to your OCP cluster

cd installer_files/cluster
oc config view --minify=true --flatten=true > kubeconfig

5. Edit the config.yaml and update the cluster_node section adding the names of your cluster compute / worker nodes to deploy the Common Services to. Remember, the best-practice is to use the same three nodes for each master, proxy and management. Use the exact node names from the oc get nodes command.

6. Continue in the config.yaml and add the storage class for your cluster in the storage_class field. The storage class must be a block storage provider. Use the exact node names from the oc get sc command.

7. Continue in the config.yaml and update the default_admin_password field with a suitable password

8. Also in the config.yaml include the required cloud and IBM entitled registry settings

roks_enabled: true
roks_url: <your OCP cluster API server URL from OC login command>
roks_user_prefix: "IAM#"
private_registry_enabled: true
image_repo: cp.icr.io/cp/icp-foundation
docker_username: cp
docker_password: your_entitlement_key_here

9. Define the management_services appropriate to your install. (The default is sufficient for many deployments.)

10. Start the installation (this can run for ~30-45min). The below command adds verbose logging and streams the results to an output file that can be referenced later.

sudo docker run -t --net=host -e LICENSE=accept -v $(pwd):/installer/cluster:z -v /var/run:/var/run:z -v /etc/docker:/etc/docker:z --security-opt label:disable ibmcom/icp-inception-amd64:3.2.4 addon -vvv | tee output.txt

Uninstall

Run the following command to uninstall the Cloud Pak for Integration

sudo docker run -t --net=host -e LICENSE=accept -v $(pwd):/installer/cluster:z -v /var/run:/var/run:z -v /etc/docker:/etc/docker:z --security-opt label:disable ibmcom/icp-inception-amd64:3.2.4 uninstall-addon -vvv | tee output.txt

Additional Resources