Installing the Event Gateway

Event Gateways are added to Event Endpoint Management by deploying them with a configuration that points to your Event Manager. When the gateway is deployed, it registers itself with the Event Manager that is specified in its configuration. Use the Event Endpoint Management UI to generate the configuration properties for your gateway. The Event Endpoint Management UI can generate Event Gateway configurations for the following deployment methods:

Docker container. The Event Endpoint Management UI generates a Docker command to run an Event Gateway. The gateway configuration is contained in the Docker run command’s arguments.
Kubernetes Deployment. The Event Endpoint Management UI generates the YAML for a Kubernetes Deployment that runs the Event Gateway.
Operator-managed custom resource (CR). The Event Endpoint Management UI generates the YAML for a custom resource that runs the Event Gateway. Your Event Endpoint Management operator manages this custom resource.

Key points to consider:

The Kubernetes Deployment and operator-managed gateways are monitored and managed by the Kubernetes environment, restarting the Event Gateway pod if necessary. If a gateway that is deployed directly as a Docker container fails, then it must be restarted manually.
To minimize latency, locate Event Gateways as close as possible to the Kafka cluster.
Maintain the Event Manager and Event Gateway at the same Event Endpoint Management version.
The operator-managed gateway is the only gateway that is upgraded automatically when Event Manager is upgraded. You are responsible for upgrading Kubernetes Deployment and Docker Event Gateways at the same time as you upgrade the Event Manager.

System requirements

The Event Gateway container is provided as a multi-architecture docker image, with support for Linux 64-bit (x86_64) systems and Linux on IBM z (s390x) architectures. For more information about container and resource requirements see Resource requirements.

Event Gateway planning

Consider the following:

How many Event Gateways and gateway groups do you require?
Where do you want to run your Event Gateways? In the same environment as your Event Manager, or closer to your Kafka cluster?
How will the Event Gateways be run and managed? As an operator-managed gateway, a Kubernetes Deployment, or as a stand-alone Docker container?
What network access is required? Are your Kafka clients connecting from the public internet, or from a private network?
What certificates will secure the Event Gateway endpoint? You must provide the TLS certificates to secure your Event Gateway. If your organization does not have its own certificates, then you can create your own:
- For operator-managed and Kubernetes Deployment gateways, use cert-manager to generate certificates stored in Kubernetes secrets.
- For Docker gateways, use openssl to create certificate files.
What hostnames do you want for your Event Gateways?

If the Kafka cluster that you intend your Event Gateway to manage traffic for has multiple brokers, then you must have a separate hostname and port combination for each broker.

Operator-managed gateways

If you want to install the Event Gateway on the same cluster as the Event Manager, use the Event Endpoint Management operator to install instances by applying the EventGateway custom resource type.

Generate your EventGateway custom resource YAML file from the Event Endpoint Management UI.

Instances of the Event Gateway can be created only after the Event Endpoint Management operator and the Event Manager instance are installed.

If the operator is installed into a specific namespace, then it can be used to manage only instances of the Event Gateway in that namespace.
If the operator is installed for all namespaces, then it can be used to manage instances of the Event Gateway in any namespace.

When you install an instance of the operator-managed Event Gateway, ensure that you are using a namespace that an Event Endpoint Management operator is managing.

Note: On Kubernetes platforms other than OpenShift Container Platform, “all namespaces” refers to an installation where watchAnyNamespace=true was set during the Helm installation.

Kubernetes Deployment and Docker gateways

The typical scenario for using Kubernetes Deployment or Docker gateways is when your Kafka cluster is in a different environment from your operator, and you want to locate the gateway as close as possible to the Kafka cluster for optimum performance.

Note: Kubernetes Deployment or Docker Event Gateway instances can be installed only in an online environment.

The Docker 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.

Configuring and installing an operator-managed Event Gateway

In the navigation pane, click Administration > Event Gateways.
Click Add gateway.
Select the Operator-managed deployment tile, then click Next.
Provide the configuration details for your gateway, then click Next.
- Gateway group: Create or specify an existing gateway group for your new gateway.
- Gateway ID: Provide an ID for your new gateway that is unique within the gateway group.
- Replicas: The number of Kubernetes replicas of the gateway pod to create.
Copy the generated custom resource YAML to two separate files:
- gateway_cr_original.yaml
- gateway_cr.yaml
Important: Keep gateway_cr_original.yaml in a safe location and do not edit it. To remove write permissions to avoid accidental updates to this file you can run chmod a-w gateway_cr_original.yaml.
Create a Kubernetes secret that contains the TLS CA certificate and key that is used to create the gateway server certificate. Name the secret as follows: <gateway group>-<gateway ID>-certs. Alternatively, you can supply the CA certificate and key in the generated YAML.
Update the gateway_cr.yaml file as follows:

a. Set spec.license.accept to true.

b. If in step 6 you created a <gateway group>-<gateway ID>-certs Kubernetes secret, then delete the <gateway group>-<gateway ID>-certs section from the YAML. If you did not create a secret, then replace <tls-certificate> and <tls-key> in the YAML with the CA certificate and key that you want to use for generating your gateway server certificate.

c. Replace any other placeholder variables in the YAML, and set other properties as required. For more information about properties that you can configure in the Event Gateway YAML file, see configuring.

d. Create a backup of the updated gateway_cr.yaml file, in addition to the gateway_cr_original.yaml file.
To install the Event Gateway through the OpenShift Container Platform web console, complete the following steps:

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

b. Click the + (Quick create) icon in the upper-right.

c. Select Import YAML.

d. Set Project to the namespace where you want to install the Event Gateway.

e. Paste in the contents of your updated gateway_cr.yaml file.

h. Click Create to start the Event Gateway installation process.
To install the Event Gateway by using the CLI, run the following commands:

a. If you are deploying an operator-managed gateway on other Kubernetes platforms, then add the spec.endpoints[] section to your gateway_cr.yaml file:
```
spec:
  endpoints:
    - name: gateway
      host: <gateway endpoint>
```
For more information about the endpoints property, see Configuring ingresses.

b. Apply the gateway_cr.yaml file in your Kubernetes environment by using the kubectl command. For example:
```
kubectl -n <gateway namespace> apply -f gateway_cr.yaml
```
Return to the Event Gateways page to monitor the status of the new Event Gateway. When the gateway is registered, the status reports Running.

Installing the Event Gateway as a Kubernetes Deployment

Follow the steps in installing the Event Gateway as a Kubernetes Deployment.

Installing the Event Gateway as a Docker container

Follow the steps in installing the Event Gateway as a Docker container.

Verifying the Event Gateway

Confirm that your Event Gateway is able to connect to your Kafka clusters, and that Kafka clients can connect to your gateway.

Verifying the Event Gateway endpoint

Verify that your Event Gateway endpoint is accessible to your Kafka clients and is secured with the TLS certificate that you expect.

In a web browser, navigate to your Event Gateway endpoint.

The browser responds with a security warning, and an option to view the endpoint’s TLS certificate.

Note: Instead of a browser you can use command line tools such as OpenSSL to view the certificate, for example:
```
openssl s_client -connect <gateway endpoint>:443 -showcerts
```
View the certificate, and confirm that it matches the certificate that you configured for your Event Gateway endpoint.
Exit from the browser.

Note: The gateway endpoint does not host any HTTP service, so no HTTP response is returned to the browser. This test is to check only that a client can make a TCP connection with your gateway endpoint.

Verifying the Event Gateway to Kafka cluster communication

To verify the connection between the gateway and your Kafka clusters, complete the following steps:

Log in to the Event Endpoint Management UI with your login credentials.
In the navigation pane, click Manage clusters.
Confirm that your clusters show All gateways connected in the Gateway visibility column.

Event Gateway license requirements

The Event Gateway must use the same license as the Event Manager. You accept the license by setting ACCEPT_LICENSE to "true" in the gateway configuration.

The gateway configuration templates generated from the Event Endpoint Management UI preset the LICENSE_ID based on the license used by the Event Manager.

If your Event Manager is not using a usage-based license and your gateway is not operator-managed, then you must install additional IBM licensing software:

If your gateway is installed as a Kubernetes Deployment, then install the IBM Licensing Service in the same environment as the gateway. The gateway YAML generated by the Event Endpoint Management UI sets the appropriate license configuration in metadata.annotations.
If your gateway is installed as a Docker container, then install the IBM License Management Tool in the same environment as your gateway and set the swid as follows:
- If the Event Manager uses an Event Automation license, then set swid="EA".
- If the Event Manager uses a IBM Cloud Pak for Integration license, then set swid="CP4I".