The following sections provide instructions about installing Event Endpoint Management on the Red Hat OpenShift Container Platform. The instructions are based on using the OpenShift Container Platform web console and oc
command-line utility.
Before you begin
- Ensure you have set up your environment according to the prerequisites, including setting up your OpenShift Container Platform and installing a supported version of a certificate manager.
- 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.
- If you want to authenticate with Keycloak, ensure you have IBM Cloud Pak for Integration 16.1.0 (operator version 7.3.0) or later installed, including the required dependencies.
Create a project (namespace)
Create a namespace into which Event Endpoint Management 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 deployment of Event Endpoint Management. This is required because Event Endpoint Management 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 Event Endpoint Management (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>"
The
description
anddisplay-name
command arguments are optional settings that you can use to specify a description and a custom name for your project. -
When you create a project, your namespace automatically switches to your new namespace. Ensure you are using the project that 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".
Create an image pull secret
Before installing an instance, create an image pull secret called ibm-entitlement-key
in the namespace where you want to create an instance of the Event Manager. 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 the Event Manager as follows.
Name the secret
ibm-entitlement-key
, usecp
as the username, your entitlement key as the password, andcp.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.
Choose the operator installation mode
Before installing an operator, decide whether you want the operator to:
-
Manage instances in any namespace.
To use this option, select
All namespaces on the cluster (default)
later. The operator will be deployed into the system namespaceopenshift-operators
, and will be able to manage instances in any namespace. -
Only manage instances 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 in any other namespace.
Decide version control and catalog source
Before you can install the required IBM operators, make them available for installation by adding the catalog sources to your cluster. Selecting how the catalog source is added will determine the versions you receive.
Consider how you want to control your deployments, whether you want to install specific versions, and how you want to receive updates.
-
Latest versions: You can install the latest versions of all operators from the IBM Operator Catalog as described in adding latest versions. This means that every deployment will always have the latest versions made available, and you cannot specify which version is installed. In addition, upgrades to latest versions are automatic and provided when they become available. This path is more suitable for development or proof of concept deployments.
-
Specific versions: You can control the version of the operator and instances that are installed by downloading specific Container Application Software for Enterprises (CASE) files as described in adding specific versions. This means you can specify the version you deploy, and only receive updates when you take action manually to do so. This is often required in production environments where the deployment of any version might require it to go through a process of validation and verification before it can be pushed to production use.
Adding latest versions
Important: Use this method of installation only if you want your deployments to always have the latest version and if you want upgrades to always be automatic.
Before you can install the latest operators and use them to create instances of the Event Manager, make the IBM Operator Catalog available in your cluster.
If you have other IBM products that are installed in your cluster, then you might already have the IBM Operator Catalog available. If it is configured for automatic updates as described in the following section, it already contains the required operators, and you can skip the deployment of the IBM Operator Catalog.
If you are installing the Event Endpoint Management operator as the first IBM operator in your cluster, to make the operators available in the OpenShift OperatorHub catalog, create the following YAML file and apply it as follows.
To add the IBM Operator Catalog:
-
Create a file for the IBM Operator Catalog source with the following content, and save as
ibm_catalogsource.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
Automatic updates of your IBM Operator Catalog can be disabled by removing the polling attribute,
spec.updateStrategy.registryPoll
. To disable automatic updates, remove the following parameters in the IBM Operator Catalog source YAML under thespec
field:updateStrategy: registryPoll: interval: 45m
Important: Other factors such as Subscription might enable the automatic updates of your deployments. For tight version control of your operators or to install a fixed version, add a specific version of the CASE bundle, and install the operator by using the CLI.
- 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 ibm_catalogsource.yaml
Alternatively, you can add the catalog source through the OpenShift web console by using the Import YAML option:
- Select the plus icon on the upper right.
- Paste the IBM Operator Catalog source YAML in the YAML editor. You can also drag-and-drop the YAML files into the editor.
- Select Create.
This adds the catalog source for Event Endpoint Management to the OperatorHub catalog, making the operator available to install.
Adding specific versions
Important: Use this method if you want to install specific versions and do not want to automatically receive upgrades or have the latest versions made available immediately.
Before you can install the required operator versions and use them to create instances of the Event Manager, make their catalog source available in your cluster as described in the following steps.
Note: This procedure must be performed by using the CLI.
-
Before you begin, ensure that you have the following set up for your environment:
- The OpenShift Container Platform CLI (
oc
) installed. - The IBM Catalog Management Plug-in for IBM Cloud Paks (
ibm-pak
) installed. After installing the plug-in, you can runoc ibm-pak
commands against the cluster. Run the following command to confirm thatibm-pak
is installed:
oc ibm-pak --help
- The OpenShift Container Platform CLI (
-
Run the following command to download, validate, and extract the latest CASE version.
oc ibm-pak get ibm-eventendpointmanagement
Note: You can also specify the version of the CASE you want to install by using
--version <case-version>
. -
Generate mirror manifests by running the following command:
oc ibm-pak generate mirror-manifests ibm-eventendpointmanagement icr.io
Note: To filter for a specific image group, add the parameter
--filter <image_group>
to the previous command.The previous command generates the following files based on the target internal registry provided:
- catalog-sources.yaml
- catalog-sources-linux-
<arch>
.yaml (if there are architecture specific catalog sources) - image-content-source-policy.yaml
- images-mapping.txt
-
Apply the catalog sources for the operator to the cluster by running the following command:
oc apply -f ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case-version>/catalog-sources.yaml
Where
<case-version>
is the version of the CASE you want to install.
This adds the catalog source for the Event Endpoint Management making the operator available to install. You can install the operator by using the OpenShift web console or the CLI.
Install the Event Endpoint Management operator
Follow the instructions to install the Event Endpoint Management operator.
Important: To install the operators by using the OpenShift web console, you must add the operators to the OperatorHub catalog. OperatorHub updates your operators automatically when a latest version is available. This might not be suitable for some production environments. For production environments that require manual updates and version control, add specific version and install the Event Endpoint Management operator by using the CLI.
Installing by using the web console
To install the operator by using the OpenShift Container Platform web console, complete the following steps:
- 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.
- In the All Items search box enter
IBM Event Endpoint Management
to locate the operator title. - Click the IBM Event Endpoint Management tile to open the install side panel.
- Click the Install button to open the Install Operator 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.
Installing by using the command line
To install the operator by using the OpenShift Container Platform command line, complete the following steps:
-
Change to the namespace (project) where you want to install the operator. For command line installations, this sets the chosen installation mode for the operator:
- Change to the system namespace
openshift-operators
if you are installing the operator to be able to manage instances in all namespaces. - Change to the custom namespace if you are installing the operator for use in a specific namespace only.
oc project <target-namespace>
- Change to the system namespace
-
Check whether there is an existing
OperatorGroup
in your target namespace:oc get OperatorGroup
If there is an existing
OperatorGroup
, continue to the next step to create aSubscription
.If there is no
OperatorGroup
, create one as follows:a. Create a YAML file with the following content, replacing
<target-namespace>
with your namespace:apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: ibm-eventautomation-operatorgroup namespace: <target-namespace> spec: targetNamespaces: - <target-namespace>
b. Save the file as
operator-group.yaml
.c. Run the following command:
oc apply -f operator-group.yaml
-
Create a
Subscription
for the Event Endpoint Management operator as follows:a. Create a YAML file similar to the following example:
apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: ibm-eventendpointmanagement namespace: <target-namespace> spec: channel: <current-channel> installPlanApproval: <install-plan-approval> name: ibm-eventendpointmanagement source: <catalog-source-name> sourceNamespace: openshift-marketplace
Where:
<target-namespace>
is the namespace where you want to install Event Endpoint Management (openshift-operators
if you are installing in all namespaces, or a custom name if you are installing in a specific namespace).<current_channel>
is the operator channel for the release you want to install (see the support matrix).<install-plan-approval>
is the user approval policy for an InstallPlan. Value must be eitherAutomatic
orManual
.<catalog-source-name>
is the name of the catalog source that was created for this operator. This isibm-eventendpointmanagement
when installing a specific version by using a CASE bundle, oribm-operator-catalog
if the source is the IBM Operator Catalog.
b. Save the file as
subscription.yaml
.c. Run the following command:
oc apply -f subscription.yaml
Checking the operator status
You can view the status of the installed operator as follows.
By using the web console
- 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 Endpoint Management.
- 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.
When the Event Endpoint Management operator is installed, the following additional operators will appear in the installed operator list:
- Operand Deployment Lifecycle Manager.
- IBM Common Service Operator.
By using the CLI
To check the status of the installed operator by using the command line:
oc get csv
The command returns a list of installed operators. The installation is successful if the value in the PHASE
column for your Event Endpoint Management operator is Succeeded
.
Install an Event Manager instance
Instances of the Event Manager can be created after the Event Endpoint Management operator is installed. If the operator was installed into a specific namespace, then it can only be used to manage instances of the Event Manager in that namespace. If the operator was installed for all namespaces, then it can be used to manage instances of the Event Manager in any namespace, including those created after the operator was deployed.
When installing an instance of the Event Manager, ensure you are using a namespace that an operator is managing.
Installing an Event Manager instance by using the web console
To install an Event Manager 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 Endpoint Management.
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 Endpoint Management tab.
- Click the Create EventEndpointManagement button to open the Create EventEndpointManagement panel. You can use this panel to define an
EventEndpointManagement
custom resource.
From here you can install by using the YAML view or the form view. For advanced configurations or to install one of the samples, see installing by using the YAML view.
See the configuring section for more information about the available options in the Custom Resource Definition.
Installing an Event Manager instance by using the YAML view
You can configure the EventEndpointManagement
custom resource by editing YAML documents. To do this, select YAML view.
A number of sample configurations are provided on which you can base your deployment. These range from quick start deployments for non-production development to large scale clusters ready to handle a production workload. Alternatively, a pre-configured YAML file containing the custom resource can be dragged and dropped onto this screen to apply the configuration.
To view the samples, do the following:
- Click the Samples tab to view the available sample configurations.
- Click the Try it link under any of the samples.
Note: If experimenting with Event Endpoint Management for the first time, the Quick start sample is the smallest and simplest example that can be used to create an experimental deployment. For a production setup, use the Production sample configuration.
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 as required.
When modifying the sample configuration, the updated document can be exported from the Create EventEndpointManagement panel by clicking the Download button and re-imported by dragging the resulting file back into the window. You can also directly edit the custom resource YAML by clicking the editor.
When modifying the sample configuration, ensure that the following fields are updated based on your requirements:
- The
spec.license.accept
field in the custom resource YAML is set totrue
. - The correct values are selected for the
spec.license.use
,spec.license.license
, andspec.license.metric
fields before deploying an Event Manager instance. For information about the right values for your deployment, see the licensing reference. manager.storageSpec.type
field is updated asephemeral
orpersistent-claim
based on your requirements. See configuring to select the correct storage type and other optional specifications such as storage size, root storage path, and secrets.-
manager.tls.caSecretName
ormanager.tls.secretName
field is updated based on your requirements. If no value is specified forcaSecretName
andsecretName
, self-signed Issuer and CA certificates are generated by the operator. See the configuring section for more information and other optional TLS settings. -
Optional: If you are installing with a usage-based license, ensure you copy the secrets created by the IBM License Service before installing the Event Manager instance, and then complete the following steps to provide details of your License Service:
a. Update
spec.manager.extensionServices
to include license service details as follows:extensionServices: - endpoint: <licensing-service-endpoint> name: licensing-service secretName: <licensing-upload-token>
for example:
extensionServices: - endpoint: https://ibm-licensing-service-instance-ibm-common-services.apps.eem-cluster.cp.fyre.ibm.com name: licensing-service secretName: ibm-licensing-upload-token
b. Update
spec.manager.tls
to include trusted certs for license service:tls: trustedCertificates: - certificate: <secret-key> secretName: <licensing-service-cert-secret>
for example:
tls: trustedCertificates: - certificate: tls.crt secretName: ibm-license-service-cert
To deploy an Event Manager instance, use the following steps:
- Complete any changes to the sample configuration in the Create EventEndpointManagement panel.
- Click Create to begin the installation process.
- Wait for the installation to complete.
Installing an Event Manager instance by using the form view
Alternatively, you can configure an EventEndpointManagement
custom resource by using the interactive form. You can load
samples into the form and then edit as required.
To view a sample in the form view, complete the following steps:
- Select YAML view in the Configure via section.
- Click the Samples tab to view the available sample configurations.
- Click the Try it link under any of the samples.
- Select Form view in the Configure via section to switch back to the form view with the data from the sample populated.
- Edit as required.
Note: If experimenting with Event Endpoint Management for the first time, the Quick start sample is the smallest and simplest example that can be used to create an experimental deployment. For a production setup, use the Production sample configuration.
To configure an EventEndpointManagement
custom resource, complete the following steps:
- Enter a name for the instance in the Name field.
- In License > License Acceptance, select the accept checkbox, enter the correct values for License, Metric, and Use.
- In Manager > storage > type, select
ephemeral
orpersistent-claim
based on your requirements. See configuring persistence for information about storage types, and other optional specifications such as storage size, root storage path, and secrets. -
In Manager > tls, use one of the following configurations (for additional options, see the configuring section):
- User-provided CA certificate: In caSecretName, choose the name of the secret that contains the root CA certificate to be used by the operator in generating other certificates.
- User-provided certificate: In secretName, choose the name of the secret that contains a CA certificate, server certificate, and a key that has the required DNS names for accessing the Manager.
- Operator-configured CA: By default, if no value is provided for caSecretName and secretName, a self-signed Issuer and CA certificate is generated.
For more information, see configuring TLS.
-
Optional: You can configure other components in Manager, such as Extension Service and Auth Config to suit your requirements.
-
If you are installing with a usage-based license, ensure you copy the secrets created by the IBM License Service before installing the Event Manager instance, and then complete the following steps to provide details of your License Service:
a. In Manager > extensionServices, click Add extensionService.
b. Enter
licensing-service
as the extensionService name.c. Enter the license service route in endpoint.
-
To fetch the endpoint for license service, run the following command:
oc get routes <INSTANCE> -n <NAMESPACE> -ojsonpath='{.status.ingress[*].host}'
For example: If you have created license service
instance
inibm-common-services
project:oc get routes ibm-licensing-service-instance -n ibm-common-services -ojsonpath='{.status.ingress[*].host}'
d. Select the secret
ibm-licensing-upload-token
.e. Add License Service CA as a trusted certificate. In manager > tls > trustedCertificates, click Add trustedCertificate.
f. In secretName, select the secret
ibm-license-service-cert
. In certificate, enter the key astls.crt
. -
-
- Scroll down and select Create to deploy the Event Manager instance.
- Wait for the installation to complete.
Installing an Event Manager instance by using the CLI
To install an instance of the Event Manager from the command-line, you must first prepare an EventEndpointManagement
custom resource configuration in a YAML file.
A number of sample configuration files are available in GitHub where you can select the GitHub tag for your Event Endpoint Management version, and then go to /cr-examples/eventendpointmanagement
to access the samples. These range from quick start deployments for non-production development to large scale clusters ready to handle a production workload.
Note: If experimenting with Event Endpoint Management for the first time, the Quick start sample is the smallest and simplest example that can be used to create an experimental deployment. For a production setup, use the Production sample configuration.
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 as required.
When modifying the sample configuration, ensure that the following fields are updated based on your requirements:
- The
spec.license.accept
field in the custom resource YAML is set totrue
. - The correct values are selected for the
spec.license.use
,spec.license.license
, andspec.license.metric
fields before deploying an Event Manager instance. For information about the right values for your deployment, see the licensing reference. manager.storageSpec.type
field is updated asephemeral
orpersistent-claim
based on your requirements. See configuring to select the correct storage type and other optional specifications such as storage size, root storage path, and secrets.manager.tls.caSecretName
ormanager.tls.secretName
field is updated based on your requirements. If neither is specified, self-signed certificates are used. See the configuring section for more information and other optional TLS settings.- If you are installing with a usage-based license, ensure you add the license service CA as a trusted certificate by updating the
manager.tls.trustedCertificates
. Set thetrustedCertificates.secretName
asibm-license-service-cert
and entertrustedCertificates.certificate
astls.crt
.
To deploy an Event Manager instance, run the following commands:
-
Set the project where your
EventEndpointManagement
custom resource will be deployed in:oc project <project-name>
-
Apply the configured
EventEndpointManagement
custom resource:oc apply -f <custom-resource-file-path>
For example:
oc apply -f production.yaml
-
Wait for the installation to complete.