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 following methods are available to deploy your Event Gateways:

Docker container. The Event Endpoint Management UI generates a Docker command to start an Event Gateway container. The Docker command contains the necessary arguments to register the gateway with your Event Manager.
Kubernetes Deployment. The Event Endpoint Management UI generates the YAML contents for a Kubernetes Deployment that runs the Event Gateway.
Operator-managed custom resource. The Event Endpoint Management UI generates the YAML contents for a Kubernetes custom resource that runs the Event Gateway. Your Event Endpoint Management operator manages this custom resource.

Do not add gateways that are at an earlier version from your Event Endpoint Management instance.

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.

Docker gateways: Ensure that you have at least 2 CPU cores and 2 GiB of memory available.
Kubernetes Deployment and operator-managed gateways: Review the Kubernetes Requests and Limits requirements in Resource requirements.

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 is installed.

If the operator is installed into a specific namespace, then it can be used only to manage 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, including instances created after the operator was deployed.

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.

Manually deployed 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.
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.

Limitations

Endpoints that need to be shared between a mixture of remote 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 remote gateway is 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 expects to connect to. Therefore, ensure that you manually configure the number of ports that are exposed on the host of the Event Gateway 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.

Generating Event Gateway configurations with the Event Endpoint Management UI

In the navigation pane, click Administration > Event Gateways.
Click Add gateway.
Select the Docker, Kubernetes Deployment, or Operator-managed deployment tile, according to your preferred gateway deployment method, 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. Not applicable to Docker gateway.
- Server URL: The address of your new gateway that client applications use to access event endpoints through the gateway.
Communication between client applications and your Event Gateway is secured with TLS by default on the operator-managed gateway. To configure TLS communication between client applications and the gateway on Docker and Kubernetes Deployments, you must upload the following certificate files:
- Gateway private key: PEM file that contains the private key that is used to encrypt client application connections to your new gateway. The private key must be created with the gateway address in the SAN.
- Gateway certificate: PEM file that contains the public certificate that is used to encrypt client application connections to your new gateway. The certificate must be created with the gateway address in the SAN.
- CA certificate: PEM file that contains the CA certificate that client applications must add to their truststores for secure communication with your new gateway. This CA certificate must be an ancestor of the Gateway certificate.
Note: Setting the Server URL and uploading the Gateway private key and certificate is optional, but if not done then the generated Docker command or YAML file contains placeholders for these properties. Replace the placeholders with the actual Server URL and certificate file paths when you deploy the gateway.
Use the generated Docker command, Kubernetes Deployment, or custom resource YAML to install the Event Gateway in your environment.
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 from the generated configuration

Installing an operator-managed Event Gateway instance by using the OpenShift Container Platform web console

To install an Event Gateway instance through the OpenShift Container Platform web console, complete the following steps:

Log in to the OpenShift Container Platform web console using your login credentials.
Click the + (Quick create) icon at the upper-right.
Select Import YAML.
Set Project to the namespace where you want to install the Event Gateway.
Paste in the generated custom resource YAML. Replace any placeholder variables in the YAML, such as the TLS certificates if you did not upload them. See Configuring for more information on properties you can configure in the Event Gateway YAML.
Click Create to begin the Event Gateway installation process.

Installing the Event Gateway instance by using the CLI (`kubectl`)

To deploy an operator-managed or Kubernetes Deployment Event Gateway instance, run the following commands:

Copy the generated YAML to a new file called EventGateway-<gatewayID>.yaml.
Replace any placeholder values and set spec.containers.env.ACCEPT_LICENSE to "true".
Apply the file in your Kubernetes environment by using the kubectl command. For example:
```
 kubectl apply -f EventGateway-eg1.yaml -n my-namespace
```

Installing the Event Gateway as a Docker container

To install a Docker Event Gateway, run the Docker command that you generated. For example:

  docker run \
  -e backendURL="eem-manager.example.com" \
  -e swid="EA" \
  -e KAFKA_ADVERTISED_LISTENER="eem-gateway.example.com" \
  -e BACKEND_CA_CERTIFICATES="-----BEGIN CERTIFICATE-----\nMIID..." \
  -v "<provide-path-to-tls-certificate>:/certs/client.pem" \
  -v "<provide-path-to-tls-key>:/certs/client.key" \
  -e GATEWAY_PORT=8443 \
  -p 8443:8443 \
  -e API_KEY="36e88938-fb08-401b-ab89-191ea9b30503" \
  -e LICENSE_ID="L-AUKS-FKVXVL" \
  -e ACCEPT_LICENSE="true" \
  -d icr.io/cpopen/ibm-eventendpointmanagement/egw:11.5.0

Installing the IBM License Metric Tool for Docker gateways

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 Docker Event Gateway. The operator-managed and Kubernetes Deployment Event Gateways do not require this additional installation.

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

Configuration properties

The following properties are defined in the generated configuration:

backendURL: 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_ADVERTISED_LISTENER: A comma-separated list of the hosts and ports that client applications must use to make requests. If applications 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"
BACKEND_CA_CERTIFICATES: The CA certificate used to secure the connection to the Event Manager.
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_ADVERTISED_LISTENER property has an entry for each port that you set here.
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. This must match the ID that you provided when you installed your Event Manager instance (as set in spec.license.license). For information about the right value for your deployment, see the licensing reference.
swid: Specifies the license under which the 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 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.
ACCEPT_LICENSE: Set this to true to accept the license terms.

Example Kubernetes Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gateway-group-test-gateway1
  labels:
    app: gateway-group-test-gateway1
    gatewayGroup: gateway-group
    gatewayId: test-gateway1
  annotations:
    productChargedContainers: manager;egw
    productID: 46c2d3697ae4406d9157c58de4b66dcc
    productMetric: VIRTUAL_PROCESSOR_CORE
    productName: IBM Event Automation Non-Production
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gateway-group-test-gateway1
      gatewayGroup: gateway-group
      gatewayId: test-gateway1
  template:
    metadata:
      labels:
        app: gateway-group-test-gateway1
        gatewayGroup: gateway-group
        gatewayId: test-gateway1
    spec:
      containers:
      - name: egw
        image: icr.io/cpopen/ibm-eventendpointmanagement/egw:11.5.0
        ports:
        - containerPort: 8443
        env:
        - name: backendURL
          value: "https://eem.eem-manager-instance-ibm-eem-server-eim.k-eem-rc1-11-5-0-master.fyre.ibm.com/gateway"
        - name: GATEWAY_PORT
          value: "8443"
        - name: KAFKA_ADVERTISED_LISTENER
          value: "<provide-gateway-advertised-listener-addresses>"
        - name: BACKEND_CA_CERTIFICATES
          value: "-----BEGIN CERTIFICATE-----\nMIIDbDCCA...vvt7Ew==\n-----END CERTIFICATE-----\n"
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              key: apiKey
              name: gateway-group-test-gateway1
        - name: LICENSE_ID
          value: L-AUKS-FKVXVL
        - name: ACCEPT_LICENSE
          value: "false"
---
apiVersion: v1
kind: Secret
metadata:
  name: gateway-group-test-gateway1
  labels:
    app: gateway-group-test-gateway1
    gatewayGroup: gateway-group
    gatewayId: test-gateway1
type: Opaque
stringData:
  apiKey: "8684cbb3-83f8-452f-9fce-b4b1c9223a47"

Example operator-managed gateway YAML

apiVersion: events.ibm.com/v1beta1
kind: EventGateway
metadata:
  name: gateway-group-test-gateway2
spec:
  license:
    accept: false
    license: L-AUKS-FKVXVL
    metric: VIRTUAL_PROCESSOR_CORE
    use: EventAutomationNonProduction
  managerEndpoint: "https://eem.eem-manager-instance-ibm-eem-server-eim.k-eem-rc1-11-5-0-master.fyre.ibm.com/gateway"
  maxNumKafkaBrokers: 20
  gatewayGroupName: gateway-group
  gatewayID: test-gateway2
  replicas: 1
  template:
    pod:
      spec:
        containers:
          - name: egw
            env:
              - name: BACKEND_CA_CERTIFICATES
                value: "-----BEGIN CERTIFICATE-----\nMIIDbDCC...PpLj0vvt7Ew==\n-----END CERTIFICATE-----\n"
              - name: API_KEY
                valueFrom:
                  secretKeyRef:
                    key: apiKey
                    name: gateway-group-test-gateway2
  tls:
    caSecretName: gateway-group-test-gateway2-certs
---
apiVersion: v1
kind: Secret
metadata:
  name: gateway-group-test-gateway2-certs
  labels:
    app: gateway-group-test-gateway2
type: Opaque
stringData:
  # Provide CA certificate and key in PEM format
  tls.crt: <tls-certificate>
  tls.key: <tls-key>
---
apiVersion: v1
kind: Secret
metadata:
  name: gateway-group-test-gateway2
  labels:
    app: gateway-group-test-gateway2
type: Opaque
stringData:
  apiKey: "f28c526b-a292-4198-9016-a35c17995ae4"