Kelson Martins Blog

Introduction

Currently, I am having the opportunity to work with IBM Cloud Private, which is a highly scalable cloud platform backed by technologies such as Kubernetes and Cloud Foundry to enable companies to deploy on-premises cloud-native software.

IBM Cloud Private or ICP, how is commonly referenced, contains a community edition (latest version 3.1.2 at the time of this writing) that is available at no charge at Docker Hub. Although its installation is simple (which steps can be found here), the process can be a little daunting as the documentation may span across multiples links depending on the type of setup a user may be looking for.

A typical ICP production cluster (with High Availability), consists of multiple Masters and Worker nodes, but for a development perspective, an All-in-One ICP cluster can do the job very well.

With that being said, this post aims to demonstrate the simplest way for a Single Node (Boot, Master, and Workers) ICP 3.1.2 cluster to be installed in a single Ubuntu 16.04 LTS VM.

Requirements

Aiming to run all ICP services, which includes Monitoring (through Prometheus and Grafana) and Logging (through an ELK Stack), the following is the recommended requirements for the Ubuntu VM:

ResourceRequirement
Cores8 or more
CPU>=2.4 GHz
RAM32 or more
Disk250 or more

Installation

Before diving into the actual installation steps, please note that some of the steps from a typical installation will be skipped, with the reason being the fact that this installation is an All-in-One Single Node ICP, being installed into a Ubuntu 16.04 VM.

The following are the steps this post will be covering:

  1. Preparing the Host
  2. Installing Docker
  3. Setup and Customize the Installation Environment
  4. Install IBM Cloud Private

Step 1 – Preparing the Host

The first step in the installation is to ensure that all required ports are open. A complete list of required ports is available here.

To check if the ports are open in your host, the following command can be executed:

ss -tnlp | awk '{print $4}'| egrep -w "<port_numbers>"

A command that checks for the ports used by the most common ICP services is presented below:

ss -tnlp | awk '{print $4}'| egrep -w "179|9099|9091|9200|9300|9108|3000|31031|31030|80|443|5601|10248|10249|10250|10251|10252|6969|3100|3000|9090|44134"

If the output is empty, the port is not in use and you are ready to proceed to configure the /etc/hosts file in your host.

Include your IP address and hostname in your /etc/hosts file, while also commenting out the lines that begin with 127.0.1.1 and ::1 localhost.

An example of such modification is:

 127.0.0.1       localhost
 # 127.0.1.1     <host_name>
 # The following lines are desirable for IPv6 capable hosts
 #::1     localhost ip6-localhost ip6-loopback
 ff02::1 ip6-allnodes
 ff02::2 ip6-allrouters
 192.X.X.X icpubuntu.test.com

The final step in the VM preparation is to ensure python ant ntpdate is installed on your host. Ubuntu 16.04 ships with both python (2 or 3) and ntpdate (for clock synchronization), and you can confirm with the following commands:

[email protected]:~# python --version
Python 2.7.12
[email protected]:~# timedatectl status
      Local time: Mon 2019-06-03 13:12:57 PDT
  Universal time: Mon 2019-06-03 20:12:57 UTC
        RTC time: Mon 2019-06-03 20:12:57
       Time zone: America/Los_Angeles (PDT, -0700)

Step 2 – Installing Docker

IBM Cloud Private supports a few versions of the community version of docker. The supported versions can be viewed here. On this article, version 18.06.2 will be installed.

First, we must set up the repository and the first step is to update the apt package index.

sudo apt-get update

Then, the installation of packages to allow apt to use the repository over HTTPS is required.

sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

Next, Docker’s official GPG key is added.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

The next step involves setting-up the Docker’s stable repository.

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

Before actually installing Docker, a new apt update is required.

sudo apt-get update

Finally, we can install a specific Docker version supported by ICP with the following command:

sudo apt-get install docker-ce=18.06.2~ce~3-0~ubuntu containerd.io

Verify your installation by checking if the docker engine is running with:

sudo systemctl start docker
sudo systemctl status docker

Next, setup Docker logs rotation, which reduces disk issues caused by retaining too many logs. This is especially important for Single-Node Clusters, as all microservices will be running under one docker engine.

To update the rotation, the block --log-opt max-size=10m --log-opt max-file=10 should be added in the ExecStart parameter of the /lib/systemd/system/docker.service file.

[Service]
Type=notify
# the default is not to use systemd for cgroups because the delegate issues still
# exists and systemd currently does not support the cgroup feature set required
# for containers run by docker
ExecStart=/usr/bin/dockerd -H fd:// --log-opt max-size=10m --log-opt max-file=10
ExecReload=/bin/kill -s HUP $MAINPID

Also, confirm that Docker’s logging-driver is set to json-file.

sudo docker info|grep "Logging Driver"

As a final step, reload and restart Docker service.

sudo systemctl daemon-reload
sudo systemctl restart docker

3 – Setup and Customize the Installation Environment

First, pull the ICP 3.1.2 docker image from Docker Hub with the following command:

sudo docker pull ibmcom/icp-inception:3.2.1

Next, create the dir to host ICP configuration files, and move into the newly created directory.

sudo mkdir /opt/ibm-cloud-private-ce-3.1.2;  \
 cd /opt/ibm-cloud-private-ce-3.1.2

Next, extract the configuration files:

sudo docker run -e LICENSE=accept \
 -v "$(pwd)":/data ibmcom/icp-inception:3.1.2 cp -r cluster /data

Also, update the /opt/ibm-cloud-private-ce-3.1.2/cluster/hosts file to include the IP of your host in the installationhosts file.

[master]
<YOUR_IP>

[worker]
<YOUR_IP>

[proxy]
<YOUR_IP>

The next step involves generating a private key in your host and add it into your installation directory folder. You can perform these steps with:

ssh-keygen -b 4096 -f ~/.ssh/id_rsa -N ""
sudo cp ~/.ssh/id_rsa/opt/ibm-cloud-private-ce-3.1.2/cluster/ssh_key

As a final step on this preparation phase, you can customize the many parameters of your ICP installation in the/opt/ibm-cloud-private-ce-3.1.2/cluster/config.yml file. The default options will work well, but you must at least update the default_admin_password parameter to match the following regex: ^([a-zA-Z0-9\-]{32,})$.

A full listing of customization options is available here.

4 – Install IBM Cloud Private

It is finally time to install ICP. First, move to the cluser folder inside the installation directory:

cd /opt/ibm-cloud-private-ce-3.1.2/cluster

Next, the following command will install ICP in the host:

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

Congratulations! The installation process may take a while, but once it completes, your ICP cluster will be ready to be accessed through the following link: https://HOST_IP:8443.

ICP Homepage

As a good practice, keep a copy of the cluster folder in your installation directory /opt/ibm-cloud-private-ce-3.1.2/cluster, which you may need in case of a future update.

Conclusion

Private Cloud solutions is an important part of many organizations and IBM Cloud Private provides a robust, reliable and scalable solution for such need.
Although IBM Cloud Private installation options go much further than what is presented in this post, the content presented is more than enough to provide developers with the information needed to deploy a development ICP environment in a short period of time.

If you are interested in discovering more about ICP, stay tuned for future posts.

Software engineer, geek, traveler, wannabe athlete and a lifelong learner. Works at @IBM

Next Post