IBM Event Streams makes using Apache Kafka in the enterprise easy and intuitive, and is now fully supported on the Red Hat OpenShift Container Platform.
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.
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.
- 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 connection details for your IBM Cloud Private cluster in the format
<cluster_address>:<cluster_router_https_port>. An administrator can retrieve these details from the ConfigMap in
kubectl get cm ibmcloud-cluster-info -n kube-public -o yaml
cluster_addressvalue for the master address, and the
cluster_router_https_portfor the port number.
The connection details for your OpenShift Container Platform cluster.
Create a project (namespace)
You perform this step by using the OpenShift Container Platform command line.
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 IBM 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.
You can create a project by using the web console or the CLI. For example, to create a project by using the CLI:
oc login -u=<username> -p=<password> --server=<your-openshift-server> --insecure-skip-tls-verify oc new-project <project_name> --description="<description>" --display-name="<display_name>"
Download the archive
Download the IBM 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 “IBM Event Streams”.
Preparing the platform
For the following steps, log in to IBM Cloud Private to prepare your platform for installing Event Streams. Log in to your cluster as an administrator by using the IBM Cloud Private CLI:
cloudctl login -a https://<cluster-address>:<cluster-router-https-port>
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
- Extract the PPA
- In your terminal window, change to the following directory:
- Run the setup script as follows:
<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 Kubernetes and OpenShift CLIs.
You will require two addresses for the OpenShift Docker registry:
<external_OpenShift_Docker_registry_address>is required to access the OpenShift docker registry externally to load the PPA archive in a later step.
<internal_OpenShift_Docker_registry_address>is required when installing the Event Streams chart later, and also required to prepare the repository if you have the
Retrieve the external address
To retrieve the external address:
Look up the external OpenShift Docker registry address by using the following command:
kubectl get routes docker-registry -n default
The following is an example output:
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD docker-registry docker-registry-default.apps.cluster-abc.my-domain.com docker-registry <all> passthrough None
<external_OpenShift_Docker_registry_address> is the values of the
Note: You can only retrieve the address if your docker registry is exposed.
Retrieve the internal address
To retrieve the internal address:
<internal_OpenShift_Docker_registry_address> is a value in the following format:
Look up the internal OpenShift Docker registry port number 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
In this example, where the namespace is
default and the port is
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) <external_OpenShift_Docker_registry_address>
<external_OpenShift_Docker_registry_address>is the external OpenShift Docker registry address you looked up earlier.
docker logincommand uses a session token (
oc whoami -t) in the password field to perform authentication. This means the
-uuser 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 <external_OpenShift_Docker_registry_address>/<namespace-to-install-into>
cloudctl catalog load-ppa-archive --archive eventstreams.2019.4.1.z_x86.pak.tar.gz --registry docker-registry-default.apps.cluster-abc.my-domain.com/event-streams
When the image installation completes successfully, the catalog is updated with the IBM Event Streams local chart, and the internal Docker repository is populated with the Docker images used by IBM Event Streams.
Preparing the repository
Prepare your repository by creating an image policy.
Note: 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.
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 policy for the internal Docker repository. The policy enables images to be retrieved during installation.
To create an image policy:
- Create a
.yamlfile with the following content, then replace
<internal_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 IBM Event Streams (set as
-n event-streamsin 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: <internal_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 as an administrator. For more information, see the IBM Cloud Private documentation.
Ensure you log in as a user that has the Team Administrator or Cluster Administrator role.
- Click Catalog in the top navigation menu.
- Search for
ibm-eventstreams-prodand select it from the result. The IBM Event Streams README is displayed.
- Click Configure.
Note: The README includes information about how to install IBM 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, select a target cluster (for example, local-cluster), 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.
Note: Ensure the Docker image registry field value includes the
<internal_OpenShift_Docker_registry_address>you looked up earlier, and the namespace where you are installing Event Streams, for example:
- Click Install.
- Verify your installation and consider other post-installation tasks.