Deploying a standalone Event Gateway Service

The Event Gateway Service handles incoming requests from applications that want to consume from the stream of events described by the AsyncAPI document. You can install and run an Event Gateway Service outside of your Cloud Pak for Integration cluster, locating the gateway service adjacent to the Kafka cluster that hosts the topics, making the communication to the Kafka cluster more efficient.

Important: If you are deploying an instance of Event Endpoint Management on IBM Z, you will have to manually configure, deploy, and run a standalone Event Gateway Service by following the instructions in this topic. For other IBM Z install considerations, see the instructions in deploying Event Endpoint Management on IBM Z.

Note: Using a standalone Event Gateway Service in a usage-based Event Endpoint Management deployment that has an existing gateway is currently not supported. To use a standalone gateway with usage-based licensing, ensure you disable the Event Gateway Service that is deployed as part of your Event Endpoint Management instance. See the instructions in Configuring a standalone gateway for usage-based licensing.

Limitations

APIs that are intended to be shared between a mixture of standalone gateways and ones in OpenShift Container Platform need to use a host address that is resolvable by all gateways. For example, if the invoke section of an API uses the internal service address for a Kafka cluster, then a standalone gateway will not be able to resolve that address outside of the cluster. In such cases, separate APIs need to be created and deployed to different gateways.

Prerequisites

The standalone Event Gateway Service is provided as a Docker image and only a single Docker engine is deployed on the host. Entitlement and usage are tracked by different licensing tools depending on your deployment. If you have a usage-based license for tracking the number of API calls, ensure you configure the gateway for the IBM License Service. Otherwise, use the IBM License Metric Tool for any other deployments.

System requirements

Ensure you have at least 2 CPU cores and 2 GB of memory available on the system where you want to install and run the standalone Event Gateway Service.

Supported operating systems

  • Red Hat Enterprise Linux Server 7 (x86-64)

  • SUSE Linux Enterprise Server (SLES) 12.0 (x86-64)

Certificates

The Event Gateway Service uses a number of certificates to ensure encrypted communication. You will need both the certificate and the associated private key when running the service. The requirements are as follows:

  • A certificate for the Event Gateway Service to present to Kafka applications that are connecting to the gateway to access enforced AsyncAPIs.

  • A certificate for the API Manager to present to the Event Gateway Service.

  • A certificate for the Certificate Authority (CA) that has issued the certificates.

It is recommended that all certificates are issued by the same Certificate Authority (CA).

Create a local folder called certs on the host where you want to run the service, and generate the following files:

  • apim.pem: The public certificate for the Event Gateway Service management endpoint.

  • apim.key: The private key for the Event Gateway Service management certificate.

  • apim-client.pem: The public certificate for API Manager to present to the Event Gateway.

  • apim-client.key: The private key for the API Manager certificate.

  • gateway-client.pem: The public certificate for Event Gateway to present to Kafka clients.

  • gateway-client.key: The private key for the Event Gateway client certificate.

  • ca.pem: The public certificate for the CA that has issued the certificates. This certificate is stored in the secret <installation>-event-gw-management.

Generating self-signed certificates

You can also generate and use self-signed certificates when configuring an Event Gateway Service. Use the openssl command line tool to generate self-signed certificates as follows. Note: Copy the content of apim-client.pem to ca.pem in the certs folder (required because there is no CA).

openssl req -newkey rsa:2048 -nodes -keyout <name>.key -x509 -days 365 -out <name>.pem -subj "/C=<COUNTRY_CODE>/ST=<STATE>/L=<Locality>/O=<ORG>/OU=<ORG_UNIT>/CN=<COMMON_NAME>"

Where:

  • The Common Name (CN) is the name of the host where the Event Gateway Service is running.

  • If the certificate is to be used by Event Endpoint Management to communicate with the Event Gateway Service, then the value provided for the Distinguished Name (DN) subject will need to be used when starting the service.

Installing the IBM License Metric Tool

Important: This licensing tool is required for all Event Endpoint Management deployments except usage-based ones.

Entitlement to the standalone Event Gateway Service and its usage is checked by the IBM License Metric Tool.

Ensure you install the IBM License Metric Tool before installing the standalone Event Gateway Service. Also review the additional Docker-specific License Metric Tool considerations.

Installing

To install a standalone Event Gateway Service, download the Event Gateway Service Docker image from the IBM Container software library as follows:

docker login cp.icr.io -u cp
docker pull cp.icr.io/cp/apic/ibm-apiconnect-eventgateway-event-gateway@sha256:5e8cb0ba4e1ba8bebf8c08e49387906d49e39cef0a60ed141437d52585c07672

The password to log in to the IBM Container software library is your entitlement key which you can obtain from the container software library site.

Running the Event Gateway Service

Configuration options

Before starting the Event Gateway Service, define the following options:

  • API_MANAGER_DN: The Distinguished Name (DN) of the client certificate that Event Endpoint Management will use to connect to the Event Gateway Service. This is an additional security measure to ensure that only authorized applications can connect to and subsequently configure the service.

  • MANAGEMENT_PORT: The port on the host that will be exposed for external connections from Event Endpoint Management.

  • CLIENT_PORT: The port on the host that will be exposed for external connections from Kafka applications.

Note: Ensure you provide the Distinguished Name (DN) value in the format of CN=<>,OU=<>,O=<>,L=<>,ST=<>,C=<>. The client certificate used by Event Endpoint Management is stored in the secret <installation>-event-gw-management. You can view the DN in the secret. If some of the values are not set, then omit them entirely from the name. You can use OpenSSL commands to check the value of the certificate if it is available on your system.

Starting the service

To run the Event Gateway Service, use the following command and the configuration options described in the previous section:

docker run -e MANAGEMENT_CLIENT_SUBJECT_DN="<API_MANAGER_DN>" -v <PATH_TO_CERTIFICATES>:/certs/eem -d -p <MANAGEMENT_PORT>:8080 -p <CLIENT_PORT>:8092 <IMAGE_NAME_FROM_CONTAINER_REGISTRY>

Registering with Event Endpoint Management

Before you can register the standalone Event Gateway Service with Event Endpoint Management, create the following resources in Cloud Manager:

  • A Truststore containing ca.pem for the API Manager to trust the Event Gateway. Note: When using self-signed certificates, upload apim.pem.

  • A Keystore containing apim-client.pem and apim-client.key for the API Manager to present to the Event Gateway.

  • A Keystore containing gateway-client.pem and gateway-client.key for the Event Gateway to present to Kafka clients.

  • A TLS Client profile containing the API Manager Keystore and the Event Gateway management Truststore.

  • A TLS Server profile containing the Event Gateway Keystore.

For more information about creating these resources, see TLS profiles overview.

Register the Event Gateway Service in Cloud Manager as described in registering the service. The high-level steps are as follows:

  1. Create a new Event Gateway Service.

  2. Select the TLS client and TLS server profiles you created.

  3. Provide the URL for the Event Gateway management endpoint in the format https://<HOSTNAME>:<MANAGEMENT_PORT> Note: The Event Gateway Service provides a TCP endpoint, not an HTTP endpoint. So, the URL must not contain the <protocol> stanza.

  4. Provide the base URL for the Event Gateway client endpoint in the format <HOSTNAME>:<CLIENT_PORT>

Upgrading the Event Gateway Service

To upgrade the gateway to a later version:

  1. Retrieve the new image from the IBM Container software library as described in installing.

  2. Stop the current Event Gateway Service.

  3. Start the service with the latest image as described in Starting the service.

Warning: The upgrade process requires downtime. Consider the impact of downtime on your operations when upgrading the service.

Configuring a standalone gateway for usage-based licensing

Important: Only required for usage-based Event Endpoint Management deployments.

When using a standalone Event Gateway Service with usage-based licensing, usage metrics are reported to the Event Endpoint Management instance in the OpenShift Container Platform cluster. The gateway must be configured to switch to usage-based licensing to ensure it is not tracked by the IBM License Management Tool.

Disable the cluster Event Gateway

If you did not deploy your instance by using the sample Event Endpoints - Three Node - Production (no Event Gateway Service), you have to disable the Event Gateway Service deployed in the Cloud Pak for Integration cluster, as described in migrating to different gateway.

Provide additional configuration to the standalone gateway

If you have a usage-based license, additional configuration is required for the standalone gateway to report usage. To provide the required configuration for the gateway, download the configuration file, modify it, and reference the file when running the gateway as follows.

Note: The following steps use the OpenShift CLI (oc) commands to extract the required data.

  1. Download the starting configuration file.

    A ConfigMap is available for the EventEndpointManager custom resource as part of the Event Endpoint Management installation. It is created in your namespace where you deployed Event Endpoint Management. Use the OpenShift CLI to download and extract the data.gatewayConfig\.json settings from the ConfigMap. For example:

    oc get configmap -l app.kubernetes.io/name=eem-services -n <NAMESPACE> -ojsonpath='{.items[0].data.gatewayConfig\.json}' > gatewayConfig.json

    The configuration is written to a file called gatewayConfig.json in your current working directory.

    Note: Depending on the length of your instance, the ConfigMap name is generated as follows: if the instance name is less than 63 characters, the ConfigMap is called <INSTANCE_NAME>-eem-services-config; if the name is longer than 63 characters, the instance name is truncated and a random string is generated in between (for example, mylongname-2219f52a-eem-services-config).

  2. Run the following command to retrieve the address of the route set up by Event Endpoint Management to report usage.

    oc get route <INSTANCE_NAME>-eem-services -n <NAMESPACE> -ojsonpath='{.status.ingress[0].host}'

  3. Modify the content of the downloaded JSON configuration file to update it with information about where to report usage to.

    • Edit lsConfig.endpoint and add the address of the route you retrieved in the previous step, including the https:// protocol prefix

    • Edit features to add standalone to any existing value. For example, apic,kafka would become standalone,apic,kafka

  4. Run the standalone gateway with this configuration. Include the following argument to mount the JSON configuration file in the Event Gateway docker image.

    -v <full-path-to-config-file>:/gatewayConfig.json

    Where full-path-to-config-file is the absolute path to the configuration file downloaded and modified in previous steps.

  5. You can verify that usage reporting is set up and working as expected.

Support

To help diagnose an issue, IBM Support might request that you enable higher levels of logging than are set by default. You can set higher levels of logging by starting the Event Gateway Service with the TRACE_SPEC environment variable. Logs are written to stdout and can be collected with the docker logs command.

Use the -e option when starting the gateway to set the TRACE_SPEC environment variable:

docker run -e TRACE_SPEC=http.request.logging:trace,com.ibm.eem:debug,com.ibm.eem.core:trace