Installing stand-alone Event Gateways

A stand-alone gateway is useful when you need to position the gateway closer to your Kafka installation. If you need to install the Event Gateway on a different cluster to your Event Endpoint Management instance, you can install a stand-alone Event Gateway instance. The following sections describe how to install a stand-alone Event Gateway instance in an online environment.

Note: Stand-alone Event Gateway instances can only be installed in an online environment.

Limitations

Endpoints that need to be shared between a mixture of stand-alone gateways and those in a Kubernetes cluster must use a host address that is resolvable by all gateways. For example, if the cluster that is associated with a topic uses an internal service address for a Kafka cluster, then a stand-alone gateway will not be able to resolve that address outside of the cluster. In such cases, separate topic aliases must be created and deployed to different gateways.

Prerequisites

The stand-alone Event Gateway is provided as a Docker image and can be used only where 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 that you configure the gateway for the IBM License Service. Otherwise, use the IBM License Metric Tool for any other deployments.

System requirements

Ensure that you have at least 2 CPU cores and 2 GiB of memory available on the system that you want to install and run the stand-alone Event Gateway.

Supported operating systems

  • Red Hat Enterprise Linux® Server 7 (x86-64)
  • SUSE Linux® Enterprise Server (SLES) 12.0 (x86-64)

Certificates

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

  • A certificate for the Event Gateway to present to Kafka applications that are connecting to the gateway.
  • A client certificate for the Event Gateway to present to Event Manager which is used to register, authenticate, and authorize this gateway instance.
  • The certificate for the CA that issues the Event Manager certificate that the gateway connects to for its configuration.

Create a local folder called certs on the host where you want to run the service and add the following files (all files are in PEM format):

  • client.pem: The public certificate for Event Gateway to present to Kafka clients.
  • client.key: The private key for the Event Gateway client certificate.
  • egwclient.pem: The public certificate for Event Gateway to use a client certificate when it connects to the associated Event Manager.
  • egwclient-key.pem: The private key for Event Gateway to use a client certificate.
  • ca.pem: The public certificate for the CA that issues the Event Manager certificate.

Event Gateway client certificate

As detailed in Certificates the Event Gateway uses a client certificate to register itself with Event Manager. This certificate provides the necessary authentication and authorization to allow the gateway to pull information about topics and subscriptions from Event Manager. This means that the certificate has the following requirements

  • It must be issued by a CA that Event Manager trusts.
  • It must have a subject alternative name (SAN) URI of the following format : egw://<host>:<port>/<gwgroup>/<gwid>
    Where:
    • host: Is the host name that Kafka applications use to connect to the gateway.
    • port: Is the port number that Kafka applications use to connect to the gateway.
    • gwgroup: Is the name of the group that this gateway belongs to.
    • gwid: Is the unique ID for this gateway.

The following shows an example of this SAN requirement:

X509v3 extensions:
   X509v3 Subject Alternative Name: 
         URI:egw://localhost:8080/london/londongw1

Installing

To install a stand-alone Event Gateway, download the Event Gateway Docker image from the IBM Container software library as follows:

docker login cp.icr.io -u cp
docker pull cp.icr.io/cp/ibm-eventendpointmanagement/egw:11.0.5

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.

Configuration options

Before you start the Event Gateway, define the following options:

  • EEM_BACKEND_URL: The URL to be used by the Event Gateway to connect to the Event Manager. This URL is the gateway API endpoint defined in the Event Manager, and will contain ibm-eem-gateway in the URL.
  • GATEWAY_PORT: The port on the host that is exposed for external connections from Kafka applications.
  • PATH_TO_CERTIFICATES: A local directory in which the Certificates are placed.
  • KAFKA_ADVERTISED_LISTENER: The host and port that Kafka applications should receive when making requests. If applications have direct access, then this will be the host and port of the Event Gateway, otherwise it should be the host and port of the routing or proxy service that is in front of the Event Gateway.
  • swid: Specifies the license under which the stand-alone Event Gateway is deployed. It must be either EA for Event Automation licensed or CP4I for CP4I licensed.
  • ubp: Optionally, set this environment variable in the Docker container if the stand-alone Event Gateway is licensed under Usage Based Pricing terms. You cannot specify both the ubp and swid options at the same time as they are mutually exclusive licensing terms.

Starting the Event Gateway

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

docker run -e backendURL="<EEM_BACKEND_URL>" -e swid="EA/CP4I" [-e ubp=true] -e KAFKA_ADVERTISED_LISTENER="<KAFKA_ADVERTISED_LISTENER>" -e GATEWAY_PORT="<GATEWAY_PORT> -e certPaths="/certs/eem/client.pem,/certs/eem/client.key,/certs/eem/ca.pem,/certs/eem/egwclient.pem,/certs/eem/egwclient-key.pem" -v <PATH_TO_CERTIFICATES>:/certs/eem -d -p <GATEWAY_PORT>:8080 <IMAGE_NAME_FROM_CONTAINER_REGISTRY>

When the Event Gateway starts, it connects to the specified Event Manager at which point it is registered.

Installing the IBM License Metric Tool

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

The IBM License Metric Tool checks usage and entitlement to the stand-alone Event Gateway.

Ensure that you install the IBM License Metric Tool before you install the stand-alone Event Gateway. Also review the additional Docker-specific License Metric Tool considerations.