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:

  1. Log in to the OpenShift Container Platform web console using your login credentials.

  2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.

  3. Expand the Project dropdown and select the project the instance is installed in (this is the namespace you set earlier).

  4. Click the operator called IBM API Connect that manages the project.

  5. Select the Event gateway cluster tab and search the Name column for the installed instance and click it.

  6. Select the YAML tab and find the status.endpoints section of the EventGatewayCluster 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:

  1. Log in to your OpenShift Container Platform as a cluster administrator by using oc login.

  2. Run oc get eventgatewayclusters to see all the available EventGatewayCluster custom resources on your system.

  3. 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}'

  4. 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:

  1. Log in to the OpenShift Container Platform web console using your login credentials.

  2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.

  3. Expand the Project dropdown and select the project the instance is installed in (this is the namespace you set earlier).

  4. Click the operator called IBM API Connect that manages the project.

  5. Select the Event Endpoint Manager tab and search the Name column for the installed instance and click it.

  6. Select the YAML tab and find the status.endpoints section of the EventGatewayCluster custom resource.

  7. The Cloud Manager UI address is the endpoint named admin.

  8. 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 and 7iron-hide for the password. Otherwise, enter admin for the user name and <your password> for the password.

By using the command line:

  1. Log in to your OpenShift Container Platform as a cluster administrator by using oc login.

  2. Run oc get eventendpointmanagers to see all available Event Endpoint Manager custom resources on your system.

  3. 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}'

  4. 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 and 7iron-hide for the password. Otherwise, enter admin 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.

  1. 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.

  2. In the Cloud Manager, select Manage Resources, then TLS in the menu on the left.

  3. Scroll down to the Keystore section, then click Create.

  4. Enter a Title and optional Summary for the keystore.

  5. 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.

  6. Save the keystore.

  7. In the TLS server profile section, click Create.

  8. Enter a Title and optional Summary for the profile.

  9. Select TLS version 1.2 and None for mutual authentication.

  10. In the Keystore section, select the store created earlier in steps 3 to 6.

  11. 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:

  1. In the Cloud Manager, click Topology.

  2. From the Availability Zone that will contain the gateway service, select Register Service.

  3. On the Configure Service page, select Event Gateway as the service type.

  4. 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.