Installing the Event Gateway as a Docker container

Install an Event Gateway as a Docker container in your container environment.

Before you begin

Review the planning topic, which covers host system and network requirements for the Event Gateway.

Determine the hostname and decide the ports to use for your gateway. If your Kafka clients are run on the same system as the gateway Docker container, then use localhost for the hostname. If your Kafka clients are not on the same system as the gateway, then use the hostname of the system that runs your Docker gateway.

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

For example, if your Kafka cluster has 3 brokers, then use the following hostname and port combinations:

localhost:9092
localhost:9093
localhost:9094

The hostnames must match the DNS alt_names that are specified in the certificate that secures the gateway endpoints. Using the preceding example, the alt_names in the certificate must specify localhost:

[alt_names]
DNS.1 = localhost

Create TLS certificates

You must provide the TLS public certificate, private key, and CA certificate for your Event Gateway endpoint. You can provide these certificates as PEM files in the Event Endpoint Management UI when you generate the gateway configuration, or you can provide the path to the PEM files when you run the Docker command.

See the following example for using the OpenSSL tool to generate a CA and the certificates that are required for the Event Gateway endpoint.

In this example, the FQDN of the gateway is localhost, and the gateway manages the traffic for a Kafka cluster that has 3 brokers, and so 3 port numbers are used to define the advertised listeners.

On MacOS, the openssl@3 and gettext packages are required and can be installed as follows:

a. Install openssl@3 and gettext:
```
brew install gettext openssl@3
```
b. Set the openssl command alias:
```
alias openssl=$(brew --prefix)/opt/openssl@3/bin/openssl
```
Create a file called my-gateway-cert.txt and paste in the following contents:
```
[req_ext]
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
```
Generate the TLS certificates by running the following commands:

a. Certificate Authority (CA) key:
```
openssl genrsa -out ca.key 4096
```
b. CA certificate:
```
openssl req -new -x509 -key ca.key -days 730 -out ca.crt
```
When prompted for the Common Name, enter IBM EEM. Answer the other prompts with appropriate values for your organization, or press return to accept the defaults.

c. Gateway private key:
```
openssl genrsa -out gateway.key 4096
```
d. Gateway certificate signing request (CSR):
```
openssl req -new -key gateway.key -out gateway.csr
```
When prompted for the Common Name, enter IBM EEM. Answer the other prompts with appropriate values for your organization, or press return to accept the defaults.

Sign the gateway CSR to create the gateway certificate:

openssl x509 -req -in gateway.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out gateway.crt -days 730 -extensions 'req_ext' -extfile <(envsubst < my-gateway-cert.txt)

Note: The envsubst utility is available on Linux and is installed by default as part of the gettext package.

Verify the gateway certificate by running the following command:
```
openssl verify -CAfile ca.crt gateway.crt
```
If you want to view the gateway certificate properties, run the following command:
```
openssl x509 -in gateway.crt -text -noout
```

Generating configurations with the Event Endpoint Management UI

In the navigation pane, click Administration > Event Gateways.
Click Add gateway.
Select the Docker tile, then click Next.
Provide a gateway group and ID 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.
- Server URL: The address or comma-separated addresses for the gateway to be used by client applications. This address might be a proxy in front of the gateway, or the gateway itself. For more information about the gateway address, see determine gateway address. Setting this value here is optional, but if not set then the generated Docker command includes the placeholder argument KAFKA_LISTENER_LISTENER_GROUP_GROUP_ADDRESSES where you must set this value.
When you click Next, a Docker command is generated that contains the configuration that is required to deploy an Event Gateway as a Docker container. Complete the configuration by replacing the placeholder values:
- KAFKA_LISTENER_LISTENER_GROUP_GROUP_ADDRESSES: If you did not specify a value for Server URL in step 4, then you must specify it here.
- <provide-path-to-tls-certificate>: Filepath to the TLS certificate that secures your gateway endpoint.
- <provide-path-to-tls-key>: Filepath to the private key that the TLS certificate uses.
- <provide-path-to-CA-certificates-to-trust-gateway>: Filepath to the CA that signs the TLS certificate.
The TLS certificate files must be in PEM format. The TLS certificate must contain the gateway address in the SAN. For more information about the TLS requirements, see Create TLS certificates.
Run the generated Docker command to deploy the gateway in your environment.

If you see the error message java.nio.file.AccessDeniedException, then check the file permissions of your certificate files, the Docker process must have read access to the certificate files you supplied.
Return to the Event Gateways page to monitor the status of the new Event Gateway. When the gateway is registered, the status reports Running.
If you need to customize the gateway for your environment or enable extra gateway features, see Advanced gateway configuration.
Verify that your Event Gateway is configured correctly by accessing a topic with a test application. See Verifying your Event Endpoint Management deployment.
Run the generated Docker command to deploy the gateway in your environment.
Return to the Event Gateways page to monitor the status of the Event Gateway. When the gateway is registered, the status reports Running.
If you need to customize the gateway for your environment or enable extra gateway features, see Advanced gateway configuration.

Docker configuration properties reference

The following properties are defined in the generated configuration

MANAGER_CLIENT_URL: The URL to be used by the Event Gateway to connect to the Event Manager. This URL is the gateway API endpoint that is defined in the Event Manager, and contains ibm-eem-gateway in the URL.
KAFKA_LISTENER_LISTENER_GROUP_GROUP_ADDRESSES:: A comma-separated list of the hosts and ports that client applications must use to make requests. If clients have direct access, then this is the host and ports (as specified in the PORT_MAPPINGS property) of the Event Gateway. Otherwise, it is the host and ports of the routing or proxy service that is in front of the Event Gateway.

For example, if you have a single host example.com and PORT_MAPPINGS set to -p 8443:8443 -p 8444:8443, then set KAFKA_ADVERTISED_LISTENER="example.com:8443,example.com:8444".
GATEWAY_PORT: The port on the gateway that Kafka applications connect to.
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 managed by the gateway. Ensure that the KAFKA_LISTENER_LISTENER_GROUP_GROUP_ADDRESSES: property has an entry for each port that you set here.
MANAGER_CLIENT_API_KEY: A GUID that is used to identify the Event Gateway with the Event Manager.
LICENSE_ID: The identifier (ID) of the license to use for this Event Gateway.
ACCEPT_LICENSE: Set to true to accept the license terms.