Installing and upgrading 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 Manager 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 Kafka 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 event source aliases must be created and deployed to different gateways.

A Kafka client implementation might require that the Event Gateway presents at least one endpoint for each broker that the client is expecting to connect to. Therefore, ensure you manually configure the number of ports exposed on the host of the Event Gateway container to be greater than or equal to the maximum number of brokers across all the clusters that the Event Gateway is managing. Also ensure that all the host ports map to the exposed port on the Event Gateway container.

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.

  • A supported container host environment as defined in the Red Hat Enterprise Linux Container Compatibility Matrix is required.

  • Ensure that both your Event Gateway and Event Manager instances are from the same version of Event Endpoint Management, or that the Event Gateway is from an earlier version.

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.

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 the 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

The Event Gateway uses a client certificate to register itself with the Event Manager. This certificate provides the authentication and authorization that allows the gateway to pull information about topics and subscriptions from the Event Manager. This means that the certificate must be issued by a CA that the Event Manager trusts.

Installing

The stand-alone Event Gateway image is provided as a multi-architecture docker image, with support for Linux 64-bit (x86_64) systems and Linux on IBM z (s390x) architectures. 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.4.0

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_ID: The unique ID for this gateway.
  • GATEWAY_GROUP: The name of the group for the gateway to join.
  • GATEWAY_PORT: The port on the host that is exposed for external connections from Kafka applications.
  • GATEWAY_CONTACT: Optional: for providing contact information that is displayed in the Event Endpoint Management UI.
  • 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.
  • PORT_MAPPINGS: a sequence of port assignments (-p <HOST_PORT>:<GATEWAY_PORT>) that satisfies the requirement that the number of exposed host ports is greater than, or equal to, the total number of Kafka brokers that are managed by this gateway.
  • swid: Specifies the license under which the stand-alone Event Gateway is deployed. It must be either EA for Event Automation license, or CP4I for Cloud Pak for Integration license.
  • 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.
  • LICENSE_ID: The identifier (ID) of the license to use for this Event Gateway. This must match the ID that you provided when installing your Event Manager instance (as set in spec.license.license). For information about the right value for your deployment, see the licensing reference.
  • ACCEPT_LICENSE: Set this environment variable to true in the Docker container if you accept the license terms. You must accept the license terms to run the Event Gateway.

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 GATEWAY_ID="<GATEWAY_ID>"  -e GATEWAY_GROUP="<GATEWAY_GROUP>" -e GATEWAY_CONTACT="<GATEWAY_CONTACT>" \
   -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 \
   -e LICENSE_ID="<LICENSE_ID>" -e ACCEPT_LICENSE="<ACCEPT_LICENSE>" \
   -d -p <HOST_PORT>:<GATEWAY_PORT> <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.

Upgrading a stand-alone Event Gateway

To upgrade a stand-alone Event Gateway, complete the following steps:

  1. Download the Event Gateway Docker image from the IBM Container software library as described in installing a new standalone-gateway.
  2. To ensure that the new gateway works with previously configured clients, use the same bootstrap server address and certificate detail as set for the old gateway when running the command to start the new gateway.
  3. Check whether any new configuration is required to deploy the gateway version correctly and adjust the command to start the gateway accordingly. For more information, see the available configuration options.
  4. Uninstall the previous gateway as described in uninstalling a stand-alone Event Gateway.
  5. Start the new Event Gateway as described in starting the Event Gateway.