Event Endpoint Management deployment
Event Endpoint Management provides the capability to describe and catalog the APIs of Kafka event sources, and to socialize those APIs with application developers.
You can deploy an instance of Event Endpoint Management as part of Cloud Pak for Integration. You can also enable event endpoints as part of deploying the API management capability, and have both API and event endpoints enabled in the same instance of the capability.
Important: To deploy an instance of Event Endpoint Management on IBM Z, follow the instructions in deploying on IBM Z.
Before you begin
This version of Cloud Pak for Integration includes Event Endpoint Management version 10.0.5.2, which is installed and managed by the API Connect Operator as follows:
Cloud Pak for Integration | Event Endpoint Management (instance) | Operator (API Connect operator ibm-apiconnect ) |
Operator channel |
---|---|---|---|
2022.4.1 | 10.0.5.2 | 3.2.0 | v3.2 |
For the latest fixes, install the highest operator version and iFix instance version.
If you have not already done so, review Overview: Installation and follow the installation procedures required for your cluster.
Review the required cluster-scoped permissions for API Connect.
Event Endpoint Management uses the default
restricted
Security Context Constraint (SCC) that comes with the OpenShift Container Platform.
Allow Ingress traffic from the default namespace
If the Openshift Cluster Ingress Controller is configured to use the HostNetwork
endpoint publishing strategy, ensure you label the default
namespace to allow Ingress traffic to the Event Gateway Service in Event Endpoint Management.
By using the CLI:
Log in to the Red Hat OpenShift cluster CLI as a Cluster Administrator.
Confirm the
endpointPublishingStrategy
type for the IngressController.oc get --namespace openshift-ingress-operator ingresscontrollers/default \ --output jsonpath='{.status.endpointPublishingStrategy.type}'; echo
If the value is
HostNetwork
, then enable Ingress traffic through the default namespace as described in the next step.Add the label
network.openshift.io/policy-group=ingress
to the default namespace as follows.oc label namespace default 'network.openshift.io/policy-group=ingress'
By using the UI:
Log in to the Red Hat OpenShift cluster Console UI as a Cluster Administrator.
Click Home and then Explore. Enter the filter value
IngressController
and select the kindIngressController
.Open the instance named
default
and view the YAML. If thestatus.endpointPublishingStrategy.type
isHostNetwork
, then enable Ingress traffic through the default namespace as described in the next step.Click Home and then Explore. Enter the filter value
Namespace
and select the kindNamespace
. Open the instance nameddefault
and click Actions > Edit Labels.Add the label
network.openshift.io/policy-group=ingress
and click Save.
Installing an instance of Event Endpoint Management
You can create an instance of Event Endpoint Management as part of Cloud Pak for Integration by using the Platform UI or the command line.
Note: Install an instance of the Event Endpoint Management capability in a single namespace. If you want to deploy additional instances of Event Endpoint Management or API Connect, you must deploy them into different namespaces.
Ensure you have the IBM API Connect operator installed. Event Endpoint Management is installed and configured by the API Connect operator through the EventEndpointManager
custom resource type. When you install the operator, you can choose whether to install it to all namespaces in the cluster, or to a single namespace. Event Endpoint Management deploys one instance of each subsystem into a particular namespace.
All namespaces in the cluster (default): If selected, the operator can manage instances of Event Endpoint Management in any namespace. The operator is deployed into the system namespace
openshift-operators
. In this case, you can specify the namespace to install the instance into as described later (see the Namespace field).A specific namespace on the cluster: If selected, the operator can only manage instances of Event Endpoint Management in the same namespace. The operator is deployed into the specified namespace. In this case, you do not specify a namespace later.
Installing by using the Platform UI
Log in to the IBM Cloud Pak for Integration Platform UI as a Cluster Administrator. Use the authentication method and credentials set by your administrator.
Click the Navigation Menu in the top left.
Expand Administration and click Integration instances.
Click Create an instance.
Select the Event endpoint management tile and click Next.
Select a deployment type and click Next:
Select Event Endpoints - One Node - Minimum for a starter deployment intended for development and testing purposes. It is not suitable for production environments. Installs one node of the management, Event Gateway Service, and portal subsystems.
Select Event Endpoints - Three Node - Production for a production deployment. In addition to an Event Gateway Service, it includes multiple nodes of the management and portal subsystems to improve capacity and availability.
Select Event Endpoints - Three Node - Production (no Event Gateway Service) for a production deployment that uses a standalone Event Gateway Service. This configuration includes multiple nodes of the management and portal subsystems, and deploys a reporting endpoint for usage-based licensing deployments. Select this option if you want to locate a standalone Event Gateway Service outside of Cloud Pak for Integration and closer to your Kafka cluster for increased efficiency.
Note: If you are deploying an instance of Event Endpoint Management on IBM Z, only
Event Endpoints - One Node - Minimum (no Event Gateway Service)
andEvent Endpoints - Three Node - Production (no Event Gateway Service)
options are available. Both require a standalone Event Gateway Service to be manually configured and deployed after the installation of Event Endpoint Management completes.Fill in the fields as follows. By using the UI form view, update the following fields:
Name: Add a name for your Event Endpoint Management instance.
Namespace: Select the namespace where this instance will be created.
Note: This field only displays if you selected All namespaces in the cluster (default) when you installed the operator. If the API Connect operator was installed for a single namespace, this field will not be displayed. It is only applicable when the operator is installed for all namespaces, which means you have to select the namespace where you want to create the instance. You can only deploy one instance of Event Endpoint Management or API Connect in a single namespace.
License acceptance: To install the instance, you must accept the license agreement.
License use: Select production or nonproduction to match the license that you purchased. Default is nonproduction.
License metric: To enable a usage-based Event Endpoint Management deployment, enter
MONTHLY_API_CALL
. Otherwise, leave blank for default valueVIRTUAL_PROCESSOR_CORE
.License ID: Select the license ID for the Event Endpoint Management program that you purchased. The following are the license options for Event Endpoint Management. Find out more about API Connect licenses.
Select L-GVEN-GFUPVE for program name "IBM API Connect Enterprise".
Select L-RJON-CJR3A7 for program name "IBM Cloud Pak for Integration - API Calls".
Note: You can deploy Event Endpoint Management with a usage-based license, where usage is tracked and charged by the number of API calls handled by Event Endpoint Management. Usage is reported automatically to the IBM License Service, where usage can be tracked, monitored, and audited. Setting License metric (
spec.license.metric
) toMONTHLY_API_CALL
and License ID (spec.license.license
) toL-RJON-CJR3A7
configures any Event Gateway Service that is managed by the IBM API Connect Operator to automatically track API usage.Note: If you have a usage-based license with a standalone Event Gateway Service, configure the gateway manually to report usage. This is required because a standalone gateway is not managed by the API Connect operator in OpenShift, so usage is not reported automatically to the License Service.
Deployment profile: Select the type of API Connect installation profile you want. Default is
n1xc10.m48
, which corresponds to Event Endpoints - One Node - Minimum.Development profile is
n1xc10.m48
, which deploys 1 replica of each pod, so this profile is most suitable for a small, non-HA system. Recommended use of this profile is for development and testing.Production profile is
n3xc14.m48
, which deploys 3 or more replicas of each pod, so this profile is most suitable for larger systems and for production environments. This profile is supported for installation on a cluster with three or more nodes. It is not supported on a cluster with fewer than three nodes.
Product version: Select the product version or channel to be installed in the system, for example,
10.0.5.2
.Storage class: Specify the RWO block storage class to use for persistence storage. This will be used when creating a PVC. Specification of the storage class is highly recommended. If not specified, the default cluster storage class for API Connect is used.
See Storage considerations for more information about storage considerations.
Note: You can define different storage settings for each subsystem in the YAML tab, as described later. For example, you can set up different storage for the API Manager and the Developer Portal.
Supported endpoint types: Only available when you click Advanced settings.
Events
is selected by default to manage event streaming sources that use Kafka. You can also selectAPIs
if you additionally want to manage interfaces such as REST APIs and GraphQL with the instance.Note: You can also enable both API and event endpoints types when you install an API management instance. Important: If you are installing an instance of Event Endpoint Management on IBM Z and select the
APIs
endpoint type, additional prerequisite steps will be required to configure your clusters.
Alternatively, you can also configure the instance by using the the YAML editor in the YAML tab.
Note: For more samples to use, see section for Event Endpoint Management in templates for creating instances of capabilities.
Non-production sample:
apiVersion: eventendpointmanager.apiconnect.ibm.com/v1beta1 kind: EventEndpointManager metadata: name: eventendpointmanager-minimum namespace: eventapis labels: { app.kubernetes.io/instance: "eventendpointmanager-minimum", app.kubernetes.io/managed-by: "ibm-apiconnect", app.kubernetes.io/name: "eventendpointmanager-minimum" } spec: endpointTypes: - Events license: accept: false license: L-GVEN-GFUPVE metric: VIRTUAL_PROCESSOR_CORE use: nonproduction profile: "n1xc10.m48" storageClassName: "" version: "10.0.5.2"
Production sample:
apiVersion: eventendpointmanager.apiconnect.ibm.com/v1beta1 kind: EventEndpointManager metadata: name: eventendpointmanager-production namespace: eventapis labels: { app.kubernetes.io/instance: "eventendpointmanager-production", app.kubernetes.io/managed-by: "ibm-apiconnect", app.kubernetes.io/name: "eventendpointmanager-production" } spec: endpointTypes: - Events license: accept: false license: L-GVEN-GFUPVE metric: VIRTUAL_PROCESSOR_CORE use: production profile: "n3xc14.m48" storageClassName: "" version: "10.0.5.2"
Note: You can override specific services as required. For example, to define the storage class and specify the size of PersistentVolumeClaims (PVCs) for API Manager and the Developer Portal separately, you could add the following to the
EventEndpointManager
custom resource underspec
:management: databaseVolumeClaimTemplate: storageClassName: rook-ceph-block volumeSize: 20Gi portal: adminVolumeClaimTemplate: storageClassName: ibmc-block-gold volumeSize: 10Gi
Click Create.
After the installation completes, check the status of your release and verify that your instance deployed successfully.
(Optional) For usage-based deployments, you can verify usage tracking after installation completes.
Installing by using the command line
You can also use the EventEndpointManager
custom resource to install the Event Endpoint Management capability by using the command line.
Ensure you have a YAML file saved locally with the custom resource configuration (see the YAML editor examples earlier).
Log in to your OpenShift Container Platform as a cluster administrator by using
oc login
.Set the project (namespace) to where you will install the instance by using
oc project <namespace>
Apply the
EventEndpointManager
custom resource to create anEvent Endpoint Management
instance:oc apply -f <custom-resource-file-path>
For example:
oc apply -f eventapi.yaml
Verifying your installation
To verify that your installation completed successfully, you can check the status of your instance through the OpenShift Container Platform web console or command line.
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 (this is the namespace you set earlier). Click the operator called IBM API Connect managing the project.
Select the Event Endpoint Management tab and search the Name column for the installed instance and click it.
The Phase field in the
EventEndpointManager
custom resource will display the current state of theEvent Endpoint Management
instance. When the Event Endpoint Management instance is ready, the phase will display Ready, meaning the deployment has completed.
By using the command line
After all the components of an Event Endpoint Management instance are active and ready, the EventEndpointManager
custom resource for the Event Endpoint Management
instance will have a Ready
phase in the status. To verify the status:
Log in to your OpenShift Container Platform as a cluster administrator by using
oc login
.Run the oc get command as follows:
oc get eventendpointmanager <cr_name> -ojsonpath={.status.phase}
For example, the installation of the instance called development
is complete when the STATUS
returned by the oc get
command displays Ready
:
$ oc get eventendpointmanager development -ojsonpath={.status.phase}
>
NAME STATUS
development Ready
Configuring your instance
After successfully installing your instance and verifying that it is ready, complete the following basic configuration for your instance:
Click the Navigation Menu in the top left.
Expand Administration and click Integration instances.
Click the link for your instance in the Name column (has Event endpoint management administration in the Type column).
Log in to Cloud Manager with the Common Services user registry. Use the same username and password that you used for logging in to the Platform UI.
Complete the following configuration tasks to set up your instance:
Create user registries to manage authentication and security.
Create provider organizations to manage teams that develop and manage APIs and related assets.
Create catalogs and spaces where APIs are developed and maintained.
Create consumer organizations and manage their access to your Developer Portal and API products.
Next steps
Start using Event Endpoint Management to create and publish definitions of your Kafka topic content as described in socializing Kafka events.