Registering an Event Gateway Service
Access to your event sources can be controlled by the Event Gateway Service. The service enforces runtime policies to secure and control access to Kafka topics hosted on one or more backend Kafka clusters. It provides endpoints that a Kafka consumer client can use to consume messages from Kafka topics.
The gateway service is deployed as part of an Event Endpoint Management instance and you can run a single gateway in front of multiple Kafka clusters, containing multiple topics. To socialize the Event Gateway Service client endpoint, it is registered through the Cloud Manager.
To enable clients to access AsyncAPI events through the Event Gateway Service, add the gateway service to a catalog. This will make the service aware of the current set of application subscriptions.
Before you begin
Before registering an Event Gateway Service in Cloud Manager, ensure you complete the following prerequisite steps.
Retrieve endpoint details
Locate and make a note of the management endpoint and API endpoint information for your gateway service.
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 that manages the project.
Select the Event gateway cluster tab and search the Name column for the installed instance and click it.
Select the YAML tab and find the
status.endpoints
section of theEventGatewayCluster
custom resource. Make a note of the following:The management endpoint is the endpoint named
eventGatewayManager
.The API endpoint is the endpoint named
eventGateway
.
By using the command line:
Log in to your OpenShift Container Platform as a cluster administrator by using
oc login
.Run
oc get eventgatewayclusters
to see all the availableEventGatewayCluster
custom resources on your system.Run the
oc get
command against the Event gateway cluster custom resource for your project as follows to retrieve the management endpoint:oc get eventgatewaycluster <event_gateway_cr_name> -ojsonpath='{.status.endpoints[?(@.name=="eventGatewayManager")].uri}'
Run the
oc get
command against the Event gateway cluster custom resource for your project as follows to retrieve the API endpoint:oc get eventgatewaycluster <event_gateway_cr_name> -ojsonpath='{.status.endpoints[?(@.name=="eventGateway")].uri}'
Retrieve Cloud Manager login details
An Event Gateway Service is registered in the Cloud Manager UI. Locate the Cloud Manager UI address and log in using your login credentials.
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 that manages the project.
Select the Event Endpoint Manager tab and search the Name column for the installed instance and click it.
Select the YAML tab and find the
status.endpoints
section of the EventGatewayCluster custom resource.The Cloud Manager UI address is the endpoint named
admin
.Log in to the UI by using the Cloud Administrator user name and password. If you are logging in for the first time, enter
admin
for the user name and7iron-hide
for the password. Otherwise, enteradmin
for the user name and<your password>
for the password.
By using the command line:
Log in to your OpenShift Container Platform as a cluster administrator by using
oc login
.Run
oc get eventendpointmanagers
to see all available Event Endpoint Manager custom resources on your system.Run the
oc get
command against the Event gateway cluster custom resource for your project as follows to retrieve the Cloud Manager UI address:oc get eventendpointmanager <event_endpoint_manager_cr_name> -ojsonpath='{.status.endpoints[?(@.name=="admin")].uri}'
Log in to the UI by using the Cloud Administrator user name and password. If you are logging in for the first time, enter
admin
for the user name and7iron-hide
for the password. Otherwise, enteradmin
for the user name and<your password>
for the password.
Create gateway TLS server profile
Create the TLS server profile that the Event Gateway Service will use for the endpoints that Kafka clients connect to.
Obtain a certificate and private key for the endpoint to use. This can either be a self-signed certificate or one issued by a well-known authority. If you use self-signed certificates, supply the issuing Certificate Authority (CA) to your clients.
In the Cloud Manager, select Manage Resources, then TLS in the menu on the left.
Scroll down to the Keystore section, then click Create.
Enter a Title and optional Summary for the keystore.
Drag and drop or upload the certificate and private key.
Note: If you have a separate certificate and key files, then both require the extension
.pem
.Save the keystore.
In the TLS server profile section, click Create.
Enter a Title and optional Summary for the profile.
Select TLS version
1.2
and None for mutual authentication.In the Keystore section, select the store created earlier in steps 3 to 6.
Click Save.
For more information about TLS server profiles, see Creating a TLS Server Profile.
Procedure: configuring an Event Gateway Service
Complete the following steps to configure a gateway service for your cloud:
In the Cloud Manager, click Topology.
From the Availability Zone that will contain the gateway service, select Register Service.
On the Configure Service page, select Event Gateway as the service type.
Enter the values as follows to configure the Event Gateway Service and click Save.
Field | Description |
---|---|
Title (required) | Enter a descriptive title for the gateway service. This title will be displayed on the screen. |
Name (required) | This field is auto-populated by the system and used as the internal field name. |
Summary (optional) | Enter a brief description. |
Management endpoint on the gateway service: Endpoint (required) | Enter the Event Gateway Service management endpoint obtained earlier. For example, https://gateway.mycompany.com |
Management endpoint on the gateway service: TLS client profile (required) | Specify the TLS Client profile to use when contacting the gateway through the management endpoint. This TLS Client profile must trust the certificates supplied to the Event Gateway Service by the operator. To prevent registration failure, select Event gateway management client TLS client proile:1.0.0 |
API invocation endpoint: API endpoint base (required) | Enter the Event Gateway Service API endpoint obtained earlier. For example, api.mycompany.com:8090 |
API invocation endpoint: Server Name Indication (SNI) - Host name (required) | To configure an Event Gateway Service, provide a host name value of * . This is the default value which is set for you. |
API invocation endpoint: Server Name Indication (SNI) - TLS server profile (required) | Select the TLS server profile created earlier. |
Selecting a Kafka client to use with Event Endpoint Management
The following Kafka client applications have been tested against the Event Gateway Service.
This information might be useful for application developers connecting to your event sources. You can share this information in the AsyncAPI document describing the event source.
The official client for the Kafka API is written in Java, and as such contains the latest features and bug fixes. For other languages, run one of the following clients.
Official Apache Kafka client:
Client | Language | Recommended version | Minimum version |
---|---|---|---|
Apache Kafka client | Java | Latest | 2.0.0 |
Third-party clients:
Client | Language | Recommended version | Minimum version |
---|---|---|---|
node-rdkafka | Node.js | Latest | 2.10.1 |
Note: If you cannot run any of the clients listed, you can use other third-party clients that meet the following minimum requirements:
Supports Kafka 1.0.0 or later
Can connect and authenticate using SASL PLAIN with TLSv1.2
For example, librdkafka.
In all cases, the latest version of the client is recommended.