2019.2.1

Installing on OpenShift

Event Streams makes using Apache Kafka in the enterprise easy and intuitive, and is now fully supported on the Red Hat OpenShift Container Platform.

Overview

You can install Event Streams on the Red Hat OpenShift Container Platform. The solution includes key IBM cloud foundational services such as installation, security, monitoring, and lifecycle management. These services help manage your Event Streams installation, and are provided by IBM Cloud Private.

Event Streams in OpenShift and IBM Cloud Private

The benefits of the solution mean you have a container platform from which you can perform administrative tasks in Red Hat OpenShift while taking some foundational services Event Streams relies on from IBM Cloud Private.

Any service task related to Kubernetes can be performed in both Red Hat OpenShift Container Platform and IBM Cloud Private. For example, you can perform administrative tasks through either platform, such as managing storage, reviewing status of components, and reviewing logs and events from each component.

Certain aspects of managing your Event Streams installation require the use of the IBM cloud foundational services provided by IBM Cloud Private. These services are as follows:

Installing the chart
Applying updates and fix packs
Modifying installation settings
Managing authentication and access (IAM)
Reviewing metering
Reviewing monitoring and metrics

Important: This documentation assumes the use of IBM Cloud Private for the IBM cloud foundational services required for managing your Event Streams installation.

Before you begin

Ensure you have set up your environment according to the prerequisites, including setting up your OpenShift Container Platform and your IBM Cloud Private integration.
The Event Streams installation process creates and runs jobs in the target namsepace (the namespace where you are installing Event Streams) and in the kube-system namespace. If you are using host groups with namespace isolation configured in your IBM Cloud Private cluster, ensure you have sufficient worker nodes available to the kube-system namespace to perform the installation (at least one worker node, or more, depending on your setup). Otherwise, the namespace isolation causes the installation process to hang with jobs in pending state.
Ensure you have planned for your installation, such as planning for persistent volumes if required, and creating a ConfigMap for Kafka static configuration.
Gather the following information from your administrator:
- The master host and port for your IBM Cloud Private cluster. These values are set during the installation of IBM Cloud Private. The default port is 5443 in IBM Cloud Private 3.1.2, while it is 443 if you are using IBM Cloud Private 3.2.0.
  
  Make a note of these values, and enter them in the steps that have https://<Cluster Master Host>:<Cluster Master API Port>
  
  Note: An administrator can retrieve the IBM Cloud Private cluster master address and port number from the ConfigMap in kube-public as follows:
  
  kubectl get cm ibmcloud-cluster-info -n kube-public -o yaml
  
  See the cluster_address value for the master address, and the cluster_router_https_port for the port number.
- The master port for your OpenShift Container Platform web console. The default port is 7443. If you are using IBM Cloud Private 3.1.2, the master host address is the same as the address for your IBM Cloud Private cluster. If you are using IBM Cloud Private 3.2.0, the master host address is different.
  
  Make a note of the port value, and enter that port together with the IBM Cloud Private master host in the steps that have https://<OpenShift Cluster Address>:<OpenShift Cluster API Port>
- The SSH password if you are connecting remotely to the master host of your IBM Cloud Private cluster.

Note: The installation process involves steps in both the web consoles and command lines of IBM Cloud Private and OpenShift Container Platform.

Create a project (namespace)

You perform this step by using the OpenShift Container Platform web console.

You must use a namespace that is dedicated to your Event Streams deployment. This is required because Event Streams uses network security policies to restrict network connections between its internal components.

If you plan to have multiple Event Streams instances, create namespaces to organize your Event Streams deployments into, and control user access to them.

When you create a project in the OpenShift Container Platform, a namespace with the same name is also created. This is the namespace to use when installing your Event Streams instance.

Go to the OpenShift Container Platform web console in your browser by using the URL https://<OpenShift Cluster Address>:<OpenShift Cluster API Port>. The default port is 7443. The master host address is the same as the address for your IBM Cloud Private cluster.
Log in using the user name and password provided to you by your administrator.
Create an OpenShift project for your Event Streams installation.
For example, log into the OpenShift Container Platform web console in your browser, click the Create project button, and type a unique name, display name, and description for the new project. This creates a project and a namespace.

Download the archive

Download the Event Streams installation image file from the IBM Passport Advantage site, and save the archive to the host where the IBM Cloud Private master cluster is installed.

Go to IBM Passport Advantage, and search for “Event Streams”. Download the images related to the part numbers for your platform (for example, the Event Streams package for the Red Hat OpenShift Container Platform includes rhel in the package name).

Preparing the platform

Prepare your platform for installing Event Streams as follows.

Important: You must perform the following steps by using a terminal opened on the host where the IBM Cloud Private master cluster is installed. If you are on a different host, you must first connect to the host machine by using SSH before logging in.

Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
cloudctl login -a https://<Cluster Master Host>:<Cluster Master API Port>
The master host and port for your cluster are set during the installation of IBM Cloud Private.

The default port is 5443 in IBM Cloud Private 3.1.2, while it is 443 if you are using IBM Cloud Private 3.2.0.
Run the following command to avoid certificate errors when running kubectl and oc commands later:
kubectl config set-cluster mycluster --insecure-skip-tls-verify=true

Run the setup script

You perform this step by using the IBM Cloud Private CLI.

You must run the following setup script to prepare the platform.

Go to the Event Streams archive you downloaded from IBM Passport Advantage, and locate the file called ibm-eventstreams-rhel-prod-<version>.tgz.
Extract the PPA tar.gz archive.
In your terminal window, change to the following directory: /pak_extensions/pre-install
Run the setup script as follows:
./scc.sh <namespace>
Where <namespace> is the namespace (project) you created for your Event Streams installation earlier.

Look up the registry address

You perform this step by using the OpenShift CLI.

Look up the internal OpenShift Docker registry address by using the following command:

oc get svc docker-registry -n default

The following is an example output:

NAME              TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
docker-registry   ClusterIP   198.51.100.24   <none>        5000/TCP   2d

The <OpenShift_Docker_registry_address> is made up of the values from the CLUSTER-IP and PORT fields as follows: <CLUSTER-IP>:<PORT>

In this example, the <OpenShift_Docker_registry_address> is 198.51.100.24:5000. Make a note of the address, including the port number. You will need it later in the installation process.

Load the archive into the catalog

Make the downloaded archive available in your catalog by using the IBM Cloud Private CLI.

Log in to the Docker private image registry:
docker login -u any_value -p $(oc whoami -t) <OpenShift_Docker_registry_address>

Where the <OpenShift_Docker_registry_address> is the internal OpenShift Docker registry address you looked up earlier, including the port number, for example: 198.51.100.24:5000.

Note: The docker login command uses a session token (oc whoami -t) in the password field to perform authentication. This means the -u user name field is required, but not used by Docker.
Make the Event Streams Helm chart available in the catalog by using the compressed image you downloaded from IBM Passport Advantage.
cloudctl catalog load-ppa-archive --archive <PPA-image-name.tar.gz> --registry <OpenShift_Docker_registry_address>/<namespace-to-install-into>

For example:
cloudctl catalog load-ppa-archive --archive eventstreams.rhel.2019.2.1.x86.pak.tar.gz --registry 198.51.100.24:5000/event-streams

When the image installation completes successfully, the catalog is updated with the Event Streams local chart, and the internal Docker repository is populated with the Docker images used by Event Streams.

Preparing the repository

Prepare your repository for the installation as follows.

The following steps require you to run kubectl commands. To run the commands, you must be logged in to your IBM Cloud Private cluster as an administrator. Log in as described in earlier.

Create an image pull secret

Create an image pull secret for the namespace where you intend to install Event Streams (this is the name of the project created earlier). The secret enables access to the internal Docker repository provided by the OpenShift Container Platform.

To create a secret, use the following command:

kubectl create secret docker-registry regcred --docker-server=<OpenShift_Docker_registry_address> --docker-username=<any_value> --docker-password=$(oc whoami -t) --docker-email=<any_value> -n <namespace>

Where:

--docker-server is the internal OpenShift Docker registry address you looked up earlier.
--docker-username can be any value. Docker uses a session token (oc whoami -t) in the password field to perform authentication. This means the --docker-username user name field is required, but not used by Docker.
--docker-email can be any value. It is required, but not used by Docker.
-n: is the project namespace (this is the name of the project created earlier).

For example:

kubectl create secret docker-registry regcred --docker-server=198.51.100.24:5000 --docker-username=user --docker-password=$(oc whoami -t) --docker-email=john.smith@ibm.com -n event-streams

For more information about creating image pull secrets, see the IBM Cloud Private documentation.

Create an image policy

Create an image policy for the internal Docker repository. The policy enables images to be retrieved during installation.

Note: If you are using IBM Cloud Private 3.2.0, you only need to follow these steps if the image-security-enforcement service is enabled. If the service is not enabled, you can ignore these steps.

To create an image policy:

Create a .yaml file with the following content, then replace <OpenShift_Docker_registry_address> with the address you looked up earlier, and replace the <namespace_for_event_streams> value with the project name where you intend to install Event Streams (set as -n event-streams in the previous example):
```
apiVersion: securityenforcement.admission.cloud.ibm.com/v1beta1
kind: ImagePolicy
metadata:
  name: image-policy
  namespace: <namespace_for_event_streams>
spec:
  repositories:
  - name: docker.io/*
    policy: null
  - name: <OpenShift_Docker_registry_address>/*
    policy: null
```
Run the following command: kubectl apply -f <filename>.yaml

For more information about container image security, see the IBM Cloud Private documentation.

Installing the Event Streams chart

You perform this step in a browser by using the IBM Cloud Private cluster management console.

Install the Event Streams chart as follows.

Log in to your IBM Cloud Private cluster management console from a supported web browser by using the URL https://<Cluster Master Host>:<Cluster Master API Port>. The master host and port for your cluster are set during the installation of IBM Cloud Private. For more information, see the IBM Cloud Private documentation.
The default port is 5443 in IBM Cloud Private 3.1.2, while it is 443 if you are using IBM Cloud Private 3.2.0.
Ensure you log in as a user that has the Cluster Administrator role.
Click Catalog in the top navigation menu.
Search for ibm-eventstreams-rhel-prod and select it from the result. The Event Streams README is displayed.
Click Configure.
Note: The README includes information about how to install Event Streams by using the CLI. To use the CLI, follow the instructions in the README instead of clicking Configure.
Important: You might see the following warnings on this page. These warnings are harmless and can be safely ignored as the OpenShift Container Platform does not use PodSecurityPolicy settings.
Enter a release name that identifies your Event Streams installation, select the target namespace you created previously, and accept the terms of the license agreement.
Expand the All parameters section to configure the settings for your installation as described in configuring. Configuration options to consider include setting up persistent storage, external access, and preparing for geo-replication.
Important: As part of the configuration process, enter the name of the secret you created previously in the Image pull secret field.
Note: Ensure the Docker image registry field value includes the OpenShift Docker registry address and the namespace, for example: 198.51.100.24:5000/event-streams
Click Install.
Verify your installation and consider other post-installation tasks, such as fixing certificate errors affecting the IBM Cloud Private CLI.