Installing IBM Cloud Private Cloud Native, Enterprise, and Community editions

Follow the steps in this topic to install either IBM Cloud Private or IBM® Cloud Private-CE (Community Edition).

For either IBM Cloud Private Cloud Native or Enterprise editions, you can install a standard or high availability (HA) cluster. For IBM Cloud Private-CE, you can set up a master, worker, proxy, and optional management nodes in your cluster.

You can have an IBM Cloud Private cluster that supports Linux® x86_64, Linux® on Power® (ppc64le), and Linux® on IBM® Z and LinuxONE systems.

Before you install:

You must prepare your cluster. See Configuring your cluster.
If your master or proxy node uses a SUSE Linux Enterprise Server (SLES) operating system, during installation, you must disable all firewalls in your cluster.

Installation can be completed in six main steps:

Install Docker for your boot node only
Set up the installation environment
Customize your cluster
Set up Docker for your cluster nodes
Deploy the environment
Verify the installation

When the installation completes, you can access your cluster and complete post installation tasks.

If you encounter errors during installation, see Troubleshooting install.

Step 1: Install Docker for your boot node only

The boot node is the node that is used for installation of your cluster. The boot node is usually your master node. For more information about the boot node, see Boot node.

You need a version of Docker that is supported by IBM Cloud Private installed on your boot node. See Supported Docker versions. To install Docker, see Manually installing Docker.

Step 2: Set up the installation environment

Log in to the boot node as a user with full root permissions.
Download the installation file or image.
- For IBM Cloud Private Native or Enterprise installation: Download the correct file or files for the type of nodes in your cluster from the IBM Passport Advantage® website.
  - For a Linux® x86_64 cluster, download the ibm-cloud-private-x86_64-3.1.1.tar.gz file.
  - For a Linux® on Power® (ppc64le) cluster, download the ibm-cloud-private-ppc64le-3.1.1.tar.gz file.
  - For a IBM® Z cluster, download the ibm-cloud-private-s390x-3.1.1.tar.gz file.
- For IBM Cloud Private-CE installation: Download the CE image from Docker Hub by running the following command:
```
  docker pull ibmcom/icp-inception:3.1.1
```
For IBM Cloud Private Native or Enterprise installation only: Extract the images and load them into Docker. Extracting the images might take a few minutes.
- For Linux x86_64, run this command:
```
tar xf ibm-cloud-private-x86_64-3.1.1.tar.gz -O | sudo docker load
```
- For Linux® on Power® (ppc64le), run this command:
```
tar xf ibm-cloud-private-ppc64le-3.1.1.tar.gz -O | sudo docker load
```
Create an installation directory to store the IBM Cloud Private configuration files in and change to that directory. Note: The installation directory must have at least 50 GB of available disk space for the installation and install files. For example, to store the IBM Cloud Private configuration files in /opt/ibm-cloud-private-3.1.1, run the following commands:
```
   sudo mkdir /opt/ibm-cloud-private-3.1.1;
   cd /opt/ibm-cloud-private-3.1.1
```
Extract the configuration files from the installer image.
- For IBM Cloud Private Native or Enterprise installation:
  - For Linux x86_64, run this command:
```
sudo docker run -v $(pwd):/data -e LICENSE=accept \
ibmcom/icp-inception-amd64:3.1.1-ee \
cp -r cluster /data
```
  - For Linux on Power (ppc64le), run this command:
```
sudo docker run -v $(pwd):/data -e LICENSE=accept \
ibmcom/icp-inception-ppc64le:3.1.1-ee \
cp -r cluster /data
```
- For IBM Cloud Private-CE installation:
```
   sudo docker run -e LICENSE=accept \
   -v "$(pwd)":/data ibmcom/icp-inception:3.1.1 cp -r cluster /data
```
  A cluster directory is created inside your installation directory. For example, if your installation directory is /opt/ibm-cloud-private-3.1.1, the /opt/ibm-cloud-private-3.1.1/cluster folder is created. For an overview of the cluster directory structure, see Cluster directory structure.
  
  Note: By default, the cluster directory is owned by root. If you require the directory to be owned by a different user, run chmod -R on the directory.
Optional: You can view the license file for IBM Cloud Private.
- For IBM Cloud Private Native or Enterprise installation:
  - For Linux x86_64, run this command:
```
sudo docker run -e LICENSE=view -e LANG=$LANG ibmcom/icp-inception-amd64:3.1.1-ee
```
  - For Linux on Power (ppc64le), run this command:
```
sudo docker run -e LICENSE=view -e LANG=$LANG ibmcom/icp-inception-ppc64le:3.1.1-ee
```
- For IBM Cloud Private-CE installation:
```
  sudo docker run -e LICENSE=view -e LANG=$LANG ibmcom/icp-inception:3.1.1
```
  Note: The $LANG value must be in supported language. For example, to view the license in Simplified Chinese using Linux for a IBM Cloud Private Cloud Native or Enterprise installation, run the following command:
```
sudo docker run -e LICENSE=view -e LANG=zh_CN ibmcom/icp-inception-amd64:3.1.1-ee
```
  For a list of supported language formats, see Supported languages.
Create a secure connection from the boot node to all other nodes in your cluster. Complete one of the following setups:
- Set up SSH in your cluster. See Sharing SSH keys among cluster nodes.
- Set up password authentication in your cluster. See Configuring password authentication for cluster nodes.
Add the IP address of each node in the cluster to the /<installation_directory>/cluster/hosts file. See Setting the node roles in the hosts file. You can also define customized host groups, see Defining custom host groups.

Notes:
- For IBM Cloud Private Native or Enterprise installation: Worker nodes can support mixed architectures. You can add worker nodes into a single cluster that run on Linux, Linux on Power (ppc64le), and IBM® Z platforms. Non-worker nodes support only one type of architecture.
- For IBM Cloud Private-CE installation: Worker and proxy nodes can support mixed architectures. You do not need to download or pull any platform-specific packages to set up a mixed architecture worker or proxy environment for IBM Cloud Private-CE. To add worker or proxy nodes into a cluster that contains Linux, Linux on Power (ppc64le), and IBM® Z platforms, you need to add the IP address of these nodes to the /<installation_directory>/cluster/hosts file only.
For IBM Cloud Private Native or Enterprise installation only: Move the image files for your cluster to the /<installation_directory>/cluster/images folder.
1. Create an images directory:
```
sudo mkdir -p cluster/images
```
2. If your cluster contains any x86_64 nodes, place the x86 package in the images directory. Add the path to your installation image file to the following command:
```
 sudo mv /<installation_directory>/ibm-cloud-private-x86_64-3.1.1.tar.gz  cluster/images/
```
3. If your cluster contains any ppc64le nodes, place the ppc64le package in the images directory. Add the path to your installation image file to the following command:
```
 sudo mv /<installation_directory>/ibm-cloud-private-ppc64le-3.1.1.tar.gz  cluster/images/
```
4. If your cluster contains any s390x nodes, place the s390x package in the images directory. Add the path to your installation image file to the following command:
```
 sudo mv /<installation_directory>/ibm-cloud-private-s390x-3.1.1.tar.gz  cluster/images/
```

Step 3: Customize your cluster

The config.yaml file, which is located in the /<installation_directory>/cluster/, contains all the configuration settings that are needed to deploy your cluster.

Optional: Customize your cluster. To review the full list of parameters that are available to customize, see Customizing the cluster with the config.yaml file. For other types of customizations that must be configured during installation, such as configuring the monitoring service or GlusterFS, review Customizing your installation.
In an environment that has multiple network interfaces (NICs), such as OpenStack and AWS, you must add the following code to the config.yaml file:
- For IBM Cloud Private Native or Enterprise installation:
```
cluster_lb_address: <external address>
proxy_lb_address: <external address>
```
- For IBM Cloud Private-CE installation:
```
cluster_lb_address: <external IP address>
```
The <external address> value is the IP address, fully-qualified domain name, or OpenStack floating IP address that manages communication to external services. Setting the proxy_lb_address parameter is required for proxy HA environments only.
For HA environments, there are several HA installation options. See HA settings.

Step 4: Set up Docker for your cluster nodes

Cluster nodes are the master, worker, proxy, and management nodes. See, Architecture.

You need a version of Docker that is supported by IBM Cloud Private installed on your cluster node. See Supported Docker versions.

If you do not have supported version of Docker installed on your cluster nodes, IBM Cloud Private can automatically install Docker on your cluster nodes during the installation.

To prepare your cluster nodes for automatic installation of Docker, see Configuring cluster nodes for automatic Docker installation.

Step 5: Deploy the environment

Change to the cluster folder in your installation directory by running the following command:
```
 cd ./cluster
```
Optional for IBM Cloud Private Native or Enterprise installation only: Depending on your options, you might need to add more parameters to the deployment command. If you had specified the offline_pkg_copy_path parameter in the config.yaml file; in the deployment command, add the -e ANSIBLE_REMOTE_TEMP=<offline_pkg_copy_path> option, where <offline_pkg_copy_path> is the value of the offline_pkg_copy_path parameter that you set in the config.yaml file.

Note: By default, the command to deploy your environment is set to deploy 15 nodes at a time. If your cluster has more than 15 nodes, the deployment might take a longer time to finish. If you want to speed up the deployment, you can specify a higher number of nodes to be deployed at a time. Use the argument -f <number of nodes to deploy> with the command.

Deploy your environment:

For IBM Cloud Private Native or Enterprise installation:

For Linux x86_64, run this command:

sudo docker run --net=host -t -e LICENSE=accept \
-v "$(pwd)":/installer/cluster ibmcom/icp-inception-amd64:3.1.1-ee install

For Linux on Power (ppc64le), run this command:

sudo docker run --net=host -t -e LICENSE=accept \
 -v "$(pwd)":/installer/cluster ibmcom/icp-inception-ppc64le:3.1.1-ee install

For IBM Cloud Private-CE installation:

   sudo docker run --net=host -t -e LICENSE=accept \
   -v "$(pwd)":/installer/cluster ibmcom/icp-inception:3.1.1 install

Optional for IBM Cloud Private Native or Enterprise installation only: If you encounter errors during deployment, rerun the deployment command with -v to collect other error messages. If you continue to receive errors during the rerun, run the following command to collect the log files:
- For Linux x86_64, run this command:
```
sudo docker run --net=host -t -e LICENSE=accept -v "$(pwd)":/installer/cluster ibmcom/icp-inception-amd64:3.1.1-ee healthcheck
```
- For Linux on Power (ppc64le), run this command:
```
sudo docker run --net=host -t -e LICENSE=accept -v "$(pwd)":/installer/cluster ibmcom/icp-inception-ppc64le:3.1.1-ee healthcheck
```
  The log files are located in the cluster/logs directory.

Step 6: Verify the status of your installation

If the installation succeeded, the access information for your cluster is displayed. For the URL, master_ip is the IP address of the master node for your cluster.

Note: If you created your cluster within a private network, use the public IP address of the master node to access the cluster. Specify the public IP address in the config.yaml and update the cluster_lb_address parameter before you install IBM Cloud Private.

For IBM Cloud Private Native or Enterprise installation, the URL can be either https://<ip_address>:8443 or https://master_ip:8443.

If you specified a cluster_lb_address value in your config.yaml file, the <ip_address> is the cluster_lb_address address. If you did not specify that value, in HA clusters, the <ip_address> in this message is the cluster_vip address that you specified, and in standard clusters, it is the IP address of the master node.
For IBM Cloud Private-CE installation, the URL is https://master_ip:8443.

Access your cluster

Now you can access your cluster. From a web browser, browse to the URL of your cluster. For a list of supported browsers, see Supported browsers.

To learn how to access your cluster by using the IBM Cloud Private management console from a web browser, see Accessing your IBM Cloud Private cluster by using the management console.
To learn how to access your cluster by using the Kubernetes command line (kubectl), see Accessing your IBM Cloud Private cluster by using the kubectl CLI.

Notes:

If you’re unable to log in immediately after the installation completes, it might be because the management services are not ready. Wait for a few minutes and try again.
You might see a 502 Bad Gateway message when you open a page in the management console shortly after installation. If you do, the NGINX service has not started all components. The pages load after all components start.

Post installation tasks

Restart your firewall.
Ensure that all the IBM Cloud Private default ports are open. For more information about the default IBM Cloud Private ports, see Default ports.
Back up the boot node. Copy your /<installation_directory>/cluster directory to a secure location. If you use SSH keys to secure your cluster, ensure that the SSH keys in the backup directory remain in sync.
Maintain proper boot node access. The boot node contains authentication information that is used for initial day 1 deployment of IBM Cloud Private and day 2 updates to IBM Cloud Private. Access to the boot node must be limited to only the users with an actual business need and this access must be governed by using enterprise identity management tools for approval, periodic recertification, access revocation on employee termination, or job role changes. Only users who have access to the boot node should be those who have the clusteradmin role for IBM Cloud Private.
Install other software from your bundle. See Installing IBM software onto IBM Cloud Private.