Installing

The following sections provide instructions about installing Event Streams on the Red Hat OpenShift Container Platform. The instructions are based on using the OpenShift Container Platform web console and oc command line utility.

When deploying in an air-gapped (also referred to as offline or disconnected) environment, ensure you have access to this documentation set, and see the instructions in the IBM Cloud Pak for Integration documentation.

Event Streams can also be installed as part of IBM Cloud Pak for Integration.

Overview

Event Streams is an operator-based release and uses custom resources to define your Event Streams configurations. The Event Streams operator uses the custom resources to deploy and manage the entire lifecycle of your Event Streams instances. Custom resources are presented as YAML configuration documents that define instances of the EventStreams custom resource type.

Installing Event Streams has two phases:

Install the Event Streams operator: this will deploy the operator that will install and manage your Event Streams instances.
Install one or more instances of Event Streams by using the operator.

Before you begin

Ensure you have set up your environment according to the prerequisites, including setting up your OpenShift Container Platform.
Ensure you have planned for your installation, such as preparing for persistent storage, considering security options, and considering adding resilience through multiple availability zones.
Obtain the connection details for your OpenShift Container Platform cluster from your administrator.
The Event Streams UI includes dashboards for monitoring Kafka health and topic health. To provide metrics for these dashboards, ensure you enable the OpenShift Container Platform monitoring stack as described in the IBM Cloud Pak for Integration documentation. In addition, to provide metrics about topic health, enable the Kafka Proxy.

Create a project (namespace)

Create a namespace into which the Event Streams instance will be installed by creating a project. When you create a project, a namespace with the same name is also created.

Ensure you use a namespace that is dedicated to a single instance of Event Streams. This is required because Event Streams uses network security policies to restrict network connections between its internal components. A single namespace per instance also allows for finer control of user accesses.

Important: Do not use any of the default or system namespaces to install an instance of Event Streams (some examples of these are: default, kube-system, kube-public, and openshift-operators).

Creating a project by using the web console

Log in to the OpenShift Container Platform web console using your login credentials.
Expand the Home dropdown and select Projects to open the Projects panel.
Click Create Project.
Enter a new project name in the Name field, and optionally, a display name in the Display Name field, and a description in the Description field.
Click Create.

Creating a project by using the CLI

Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the oc CLI (oc login).
Run the following command to create a new project:

oc new-project <project_name> --description="<description>" --display-name="<display_name>"

where description and display-name are optional flags to set a description and custom descriptive name for your project.
Ensure you are using the project you created by selecting it as follows:

oc project <new-project-name>

The following message is displayed if successful:
```
Now using project "<new-project-name>" on server "https://<OpenShift-host>:6443".
```

OpenShift 4.6 only: add certificate for metrics

The Event Streams UI requires the OpenShift Ingress CA certificate to read prometheus metrics.

If you are installing Event Streams on OpenShift Container Platform version 4.6, manually add the CA certificate to a ConfigMap called kube-root-ca.crt in the project (namespace) where you are installing the Event Streams instance. In later OpenShift Container Platform versions, the ConfigMap is automatically injected into the project (namespace).

To create the ConfigMap, run the following command:

oc get cm default-ingress-cert --namespace=openshift-config-managed -o yaml | sed 's/name: default-ingress-cert/name: kube-root-ca.crt/' | sed 's/namespace: openshift-config-managed/namespace: <target-namespace>/' | oc create -f -

Add the Event Streams operator to the catalog

Before you can install the Event Streams operator and use it to create instances of Event Streams, you must have the IBM Operator Catalog and the IBM Cloud Pak foundational services Catalog available in your cluster.

If you have other IBM products installed in your cluster, then you already have the IBM Operator Catalog available, and you can continue to installing the Event Streams operator. Ensure you also have the IBM Cloud Pak foundational services Catalog available, as described in the following steps.

If you are installing Event Streams as the first IBM product in your cluster, complete the following steps.

To make the Event Streams operator and related foundational services dependencies available in the OpenShift OperatorHub catalog, create the following YAML files and apply them as follows.

To add the IBM Operator Catalog:

Create a file for the IBM Operator Catalog source with the following content, and save as IBMCatalogSource.yaml:

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
   name: ibm-operator-catalog
   namespace: openshift-marketplace
spec:
   displayName: "IBM Operator Catalog"
   publisher: IBM
   sourceType: grpc
   image: icr.io/cpopen/ibm-operator-catalog
   updateStrategy:
     registryPoll:
       interval: 45m

Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the oc CLI (oc login).
Apply the source by using the following command:

oc apply -f IBMCatalogSource.yaml

The IBM Operator Catalog source is added to the OperatorHub catalog, making the Event Streams operator available to install.

To add the IBM Cloud Pak foundational services Catalog:

Create a file for the IBM Cloud Pak foundational services Catalog source with the following content, and save as IBMCSCatalogSource.yaml:

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
   name: opencloud-operators
   namespace: openshift-marketplace
spec:
   displayName: "IBMCS Operators"
   publisher: IBM
   sourceType: grpc
   image: icr.io/cpopen/ibm-common-service-catalog:latest
   updateStrategy:
     registryPoll:
       interval: 45m

Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the oc CLI (oc login).
Apply the source by using the following command:

oc apply -f IBMCSCatalogSource.yaml

The IBM Cloud Pak foundational services Catalog source is added to the OperatorHub catalog, making the IBM Cloud Pak foundational services items available to install for Event Streams.

Install the Event Streams operator

Ensure you have considered the Event Streams operator requirements, including resource requirements and the required cluster-scoped permissions.

Choosing operator installation mode

Before installing the Event Streams operator, decide if you want the operator to:

Manage instances of Event Streams in any namespace.

To use this option, select All namespaces on the cluster (default) later. The operator will be deployed into the system namespace openshift-operators, and will be able to manage instances of Event Streams in any namespace.
Only manage instances of Event Streams in a single namespace.

To use this option, select A specific namespace on the cluster later. The operator will be deployed into the specified namespace, and will not be able to manage instances of Event Streams in any other namespace.

Installing by using the web console

To install the operator by using the OpenShift Container Platform web console, do the following:

Log in to the OpenShift Container Platform web console using your login credentials.
Expand the Operators dropdown and select OperatorHub to open the OperatorHub dashboard.
Select the project you want to deploy the Event Streams instance in.
In the All Items search box enter Event Streams to locate the operator title.
Click the Event Streams tile to open the install side panel.
Click the Install button to open the Create Operator Subscription dashboard.
Select the chosen installation mode that suits your requirements. If the installation mode is A specific namespace on the cluster, select the target namespace you created previously.
Click Install to begin the installation.

The installation can take a few minutes to complete.

Important: Only install one Event Streams operator on a cluster.

Checking the operator status

You can see the installed operator and check its status as follows:

Log in to the OpenShift Container Platform web console using your login credentials.
Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Streams managing the project.
Scroll down to the ClusterServiceVersion details section of the page.
Check the Status field. After the operator is successfully installed, this will change to Succeeded.

In addition to the status, information about key events that occur can be viewed under the Conditions section of the same page. After a successful installation, a condition with the following message is displayed: install strategy completed with no errors.

Note: If the operator is installed into a specific namespace, then it will only appear under the associated project. If the operator is installed for all namespaces, then it will appear under any selected project. If the operator is installed for all namespaces and you select all projects from the Project drop down, the operator will be shown multiple times in the resulting list, once for each project.

Note: If the required IBM Cloud Pak foundational services are not installed, they will be automatically deployed when the Event Streams operator is installed and the following additional operators will appear in the installed operator list:

Operand Deployment Lifecycle Manager.
IBM Common Service Operator.

Install an Event Streams instance

Instances of Event Streams can be created after the Event Streams operator is installed. If the operator was installed into a specific namespace, then it can only be used to manage instances of Event Streams in that namespace. If the operator was installed for all namespaces, then it can be used to manage instances of Event Streams in any namespace, including those created after the operator was deployed.

When installing an instance of Event Streams, ensure you are using a namespace that an operator is managing.

Creating an image pull secret

Before installing an Event Streams instance, create an image pull secret called ibm-entitlement-key in the namespace where you want to create an instance of Event Streams. The secret enables container images to be pulled from the registry.

Obtain an entitlement key from the IBM Container software library.
Create the secret in the namespace that will be used to deploy an instance of Event Streams as follows.

Name the secret ibm-entitlement-key, use cp as the username, your entitlement key as the password, and cp.icr.io as the docker server:

oc create secret docker-registry ibm-entitlement-key --docker-username=cp --docker-password="<your-entitlement-key>" --docker-server="cp.icr.io" -n <target-namespace>

Note: If you do not create the required secret, pods will fail to start with ImagePullBackOff errors. In this case, ensure the secret is created and allow the pod to restart.

Installing an instance by using the web console

To install an Event Streams instance through the OpenShift Container Platform web console, do the following:

Log in to the OpenShift Container Platform web console using your login credentials.
Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Streams managing the project.

Note: If the operator is not shown, it is either not installed or not available for the selected namespace.
In the Operator Details dashboard, click the Event Streams tab.
Click the Create EventStreams button to open the Create EventStreams panel. You can use this panel to define an EventStreams custom resource.

From here you can install by using the form view. For more advanced configurations or to install one of the samples, see installing by using the YAML view.

Installing by using the form view

To configure an EventStreams custom resource, do the following:

Enter a name for the instance in the Name field.
Click the license accept toggle to set it to True.
Ensure that the correct value is selected for the Product use from the dropdown. Select CloudPakForIntegrationNonProduction for development and test deployments not intended for production use, and select CloudPakForIntegrationProduction for production deployments. See the licensing section for more details about selecting the correct value.
You can optionally configure other components such as Kafka, ZooKeeper, and Security to suit your requirements.
Scroll down and click the Create button at the bottom of the page to deploy the Event Streams instance.
Wait for the installation to complete.
You can now verify your installation and consider other post-installation tasks.

Installing by using the YAML view

Alternatively, you can configure the EventStreams custom resource by editing YAML documents. To do this, click the Edit YAML tab.

A number of sample configurations are provided on which you can base your deployment. These range from smaller deployments for non-production development or general experimentation to large scale clusters ready to handle a production workload. Alternatively, a pre-configured YAML file containing the custom resource sample can be dragged and dropped onto this screen to apply the configuration.

To view the samples, do the following:

Select the Samples tab to show the available sample configurations.
Click the Try it link under any of the samples to open the configuration in the Create EventStreams panel.

More information about these samples is available in the planning section. You can base your deployment on the sample that most closely reflects your requirements and apply customizations on top as required.

When modifying the sample configuration, the updated document can be exported from the Create EventStreams panel by clicking the Download button and re-imported by dragging the resulting file back into the window.

Important: You must ensure that the spec.license.accept field in the custom resource YAML is set to true and that the correct value is selected for the spec.license.use field before deploying the Event Streams instance. Select CloudPakForIntegrationNonProduction for development and test deployments not intended for production use, and select CloudPakForIntegrationProduction for production deployments. See the licensing section for more details about selecting the correct value.

Accepting license

Note: If experimenting with Event Streams for the first time, the Lightweight without security sample is the smallest and simplest example that can be used to create an experimental deployment. For the smallest production setup, use the Minimal production sample configuration.

To deploy an Event Streams instance, use the following steps:

Complete any changes to the sample configuration in the Create EventStreams panel.
Click Create to begin the installation process.
Wait for the installation to complete.
You can now verify your installation and consider other post-installation tasks.

Installing an instance by using the CLI

To install an instance of Event Streams from the command line, you must first prepare an EventStreams custom resource configuration in a YAML file.

A number of sample configuration files have been provided to base your deployment on (download and extract the resources for your Event Streams version, then go to /cr-examples/eventstreams to access the samples). The sample configurations range from smaller deployments for non-production development or general experimentation to large scale clusters ready to handle a production workload.

Important: You must ensure that the spec.license.accept field in the configuration is set to true and that the correct value is selected for the spec.license.use field before deploying the Event Streams instance. Select CloudPakForIntegrationNonProduction for development and test deployments not intended for production use, and select CloudPakForIntegrationProduction for production deployments. See the licensing section for more details about selecting the correct value.

Accepting license

To deploy an Event Streams instance, run the following commands:

Set the project where your EventStreams custom resource will be deployed in:

oc project <project-name>
Apply the configured EventStreams custom resource:

oc apply -f <custom-resource-file-path>

For example: oc apply -f development.yaml
Wait for the installation to complete.
You can now verify your installation and consider other post-installation tasks.