Configure an Event Manager as an Event Gateway Service

You can configure your Event Manager instance to be registered as an Event Gateway Service in IBM API Connect, which you can use to manage events and APIs in one place.

To register an Event Manager instance as an Event Gateway Service:

  1. Add the server certificate of API Connect and the JSON Web Key Set (JWKS) endpoint as configuration in your Event Manager instance so that communications received from API Connect are trusted.
  2. Use the Event Gateway API and the Event Manager endpoint to configure an Event Gateway Service in Cloud Manager.

Important: Ensure you install and configure an instance of both an Event Manager and an Event Gateway before configuring API Connect integration with that Event Manager instance.

Follow the steps to configure your Event Manager as an Event Gateway Service.

Retrieve the API Connect JSON Web Key Set (JWKS) endpoint

Before you begin, you must retrieve the API Connect jwksUrl endpoint. The value that you retrieve is required to configure trust between API Connect and Event Endpoint Management.

By using the OpenShift web console

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
  3. Expand the Project drop-down menu and select the project the API Connect instance is installed in.
  4. Select the API Connect operator.
  5. In the API Connect cluster, click the installed instance.
  6. In the YAML, find the status.endpoints section of the APIConnectCluster custom resource.
  7. Retrieve the value in the jwksUrl field.

By using other Kubernetes platforms

The jwksUrl is defined as the platform API hostname with the following subpath: api/cloud/oauth2/certs. To obtain the jwksUrl from your API Connect custom resource, complete the following steps:

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
  2. Get the list of endpoints from your API Connect pod by using the following command kubectl describe pod <apic-pod>.
  3. Look for the APIC_PLATFORM_API_ENDPOINT.
    Note: The APIC_PLATFORM_API_ENDPOINT is a URL with /api at the end.
  4. To obtain the jwksUrl, append /cloud/oauth2/certs to the end of the APIC_PLATFORM_API_ENDPOINT URL.

Configure Event Endpoint Management to trust API Connect

To allow communication between API Connect and Event Endpoint Management, your Event Endpoint Management configuration requires the CA certificate that is used to issue the certificates presented by API Connect’s API endpoints.

  1. Obtain a copy of the API Connect CA certificate.

    The CA certificate can be found in a secret called ingress-ca, which is created as a part of your API Connect instance. For more information about ingress-ca, see the API Connect documentation.

    Note: If installed as a part of an IBM Cloud Pak for Integration instance, the name of your secret is prefixed by the name of your APIConnectCluster resource. For example: <name>-ingress-ca.

    You can obtain the CA certificate from the Kubernetes cluster where your API Connect instance is installed by using the Openshift UI if running in an Openshift environment, or by using the CLI.

    • By using the OpenShift Container Platform web console:

      1. Log in to the OpenShift Container Platform web console using your login credentials.
      2. Expand the Workloads drop-down menu and select Secrets.
      3. Expand the Project drop-down menu and select the project the API Connect instance is installed in.
      4. Find the <name>-ingress-ca secret, and select it.
      5. Depending on how you want to create the secret in the next step, copy the value from one of the following locations:
        • For a decoded value to be used in the OpenShift web console, click the Details tab and copy value in ca.crt.
        • For a Base64-encoded value to be used with the CLI, click the YAML tab and copy the value under data.ca.crt.

    • By using the CLI:

      1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

      2. Depending on how you want to create the secret in the next step, run the following command:

        • To extract the decoded certificate to be used in the OpenShift web console:

          kubectl -n <APIC namespace> get secret <ingress-ca name> -ojsonpath="{.data['ca\.crt']}" | base64 -d

        • To extract the Base64-encoded certificate to use with the CLI:

          kubectl -n <APIC namespace> get secret <ingress-ca name> -ojsonpath="{.data['ca\.crt']}"

          Where APIC namespace is the namespace where your API Connect instance is installed.

  2. In the Kubernetes cluster running Event Endpoint Management, create a secret that contains the CA certificate. Create a secret to store the API Connect certificate as follows.

    • By using the OpenShift Container Platform web console:

      Note: When creating secrets in the OpenShift Container Platform UI, the input value must not be encoded. Therefore, ensure you retrieve a decoded value in step 1, or if you have a Base64-encoded certificate, decode it before completing the following steps.

      1. Log in to the OpenShift Container Platform web console using your login credentials.
      2. Expand the Workloads drop-down menu and select Secrets.
      3. Expand the Project drop-down menu and select the project the Event Manager instance is installed in.
      4. Expand the Create drop-down menu and select Key/value secret.
      5. Enter apim-cpd as the Secret name.
      6. Enter ca.crt as the Key.
      7. Under Value, select the text area, and enter the decoded certificate.
      8. Click Create.

    • By using the CLI:

      Note: When creating secrets by using the CLI, the certificate must be Base64-encoded.

      1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

      2. Run the following command to create a secret called apim-cpd:

        cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: apim-cpd
  namespace: <namespace the Event Manager instance is installed in>
data:
  ca.crt: >-
    <Base64-certificate>
type: Opaque
EOF

        Where:

        • <namespace> is the namespace the Event Manager instance is installed in.
        • <Base64-certificate> is the Base64-encoded certificate that you obtained in step 1.

  3. Update the EventEndpointManagement instance with the API Connect configuration details as follows.

    • On OpenShift Container Platform:

      Use the web console to edit the configuration of the EventEndpointManagement instance:

      1. Log in to the OpenShift Container Platform web console using your login credentials.
      2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
      3. Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Endpoint Management.
      4. Click the Event Endpoint Management tab and search the Name column for the installed instance and click the name.
      5. Click the YAML tab to edit the custom resource.

      6. In the spec.manager field, add the following snippet:

        apic:
  jwks:
    endpoint: <jwksUrl>

      7. In the spec.manager.tls field, add the following snippet:

        trustedCertificates:
  - certificate: ca.crt
    secretName: apim-cpd
      8. Click Save to apply your changes.

    • On other Kubernetes platforms:

      On other Kubernetes platforms, you can either edit the configuration of your EventEndpointManagement instance by using the kubectl edit command, or modify your original configuration file as follows.

      1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

      2. Ensure you are in the namespace where your Event Manager instance is installed:

        kubectl config set-context --current --namespace=<namespace>

      3. Update your EventEndpointManagement instance’s YAML file on your local system. In the spec.manager field, add the following snippet:

        apic:
  jwks:
    endpoint: <jwksUrl>

      4. Also in the YAML, in the spec.manager.tls field, add the following snippet:

        trustedCertificates:
  - certificate: ca.crt
    secretName: apim-cpd

      5. Apply the YAML to the Kubernetes cluster:

        kubectl apply -f <file_name>

Enabling mutual TLS

JSON Web Token (JWT) authentication is used by default to verify messages that are received from API Connect and cannot be disabled. All communications the Event Gateway Service receive from API Connect contain a JWT, and the JWKS endpoint you provided earlier is used to validate this token to ensure the authenticity of each message.

Based on your security requirements, you can optionally choose to also enable mutual TLS (MTLS), which uses certificates for authentication:

On OpenShift Container Platform web console

Use the web console to modify the EventEndpointManagement instance’s configuration:

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
  3. Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Endpoint Management.
  4. Click the Event Endpoint Management tab and search the Name column for the installed instance and click the name.
  5. Click the YAML tab to edit the custom resource.

  6. In the spec.manager.apic field, add the following snippet:

    clientSubjectDN: CN=<commonname>

    Where <commonname> is the Common Name on the certificates that are used when making the TLS client profile.

  7. Click Save to apply your changes.

On other Kubernetes platforms

On other Kubernetes platforms you can either edit the configuration of your EventEndpointManagement instance by using the kubectl edit command, or modify your original configuration file as follows.

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

  2. Ensure you are in the namespace where your Event Manager instance is installed:

    kubectl config set-context --current --namespace=<namespace>

  3. Update your EventEndpointManagement instance’s YAML file on your local system. In the spec.manager.apic field, add the following snippet:

    clientSubjectDN: CN=<commonname>

    Where is the Common Name on the certificates that are used when making the TLS client profile.

  4. Apply the YAML to the Kubernetes cluster:

    kubectl apply -f <file_name>

Registering the Event Manager as an Event Gateway Service in API Connect

After configuring Event Endpoint Management to trust API Connect, register the Event Manager as an Event Gateway Service as follows:

Obtain certificates for a TLS client profile on OpenShift

  1. Expand the Workloads drop-down menu and select Secrets.
  2. Expand the Project drop-down menu and select the project the Event Manager instance is installed in.

  3. Use the search bar to locate the secret named <event-manager-instance-name>-ibm-eem-manager and click the secret.

    Note: If you provided your own certificate to Event Manager in a secret when you configured TLS, use the data that is stored in the secret you created instead of <event-manager-instance-name>-ibm-eem-manager.

  4. Scroll down to the Data section.
  5. Copy the ca.crt and save it in a file called cluster-ca.pem
  6. Copy the tls.crt and save it in a file called manager-client.pem
  7. Copy the tls.key and save it in a file called manager-client-key.pem

Obtain certificates for a TLS client profile on other Kubernetes platforms

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

  2. Ensure you are in the namespace where your Event Manager instance is installed:

    kubectl config set-context --current --namespace=<namespace>

  3. Display the secret for your EventEndpointManagement instance, it will have the name <instance-name>-ibm-eem-manager.

    Note: If you provided your own certificate to Event Manager in a secret when you configured TLS, use the data that is stored in the secret you created instead of <event-manager-instance-name>-ibm-eem-manager.

     kubectl get secret <instance-name>-ibm-eem-manager -o yaml
  4. Copy the ca.crt and save it in a file called cluster-ca.pem
  5. Copy the tls.crt and save it in a file called manager-client.pem
  6. Copy the tls.key and save it in a file called manager-client-key.pem
  1. Expand the Networking dropdown and select Routes.
  2. Expand the Project drop-down menu and select the project the API Connect instance is installed in.
  3. Use the search bar to find the route with the Name ending in admin. Click the URL in the Location column. This takes you to the Cloud Manager UI.

Create a TLS Client Profile

Create the TLS Client profile to use when contacting the Event Gateway Service through the management endpoint.

  1. Create a client TLS keystore. Go to Home > Resources > TLS > Keystore and click Create.
  2. Upload the manager-client-key.pem into Step 1.
  3. Upload the manager-client.pem into Step 2.
  4. Click Save.
  5. Create a client TLS truststore. Go to Truststore and click Create.
  6. Upload the cluster-ca.pem.
  7. Click Save.
  8. Create a TLS client profile. Go to TLS client profile and click Create.
  9. Choose the keystore and truststore you created.
  10. Tick Allow insecure server connections.
  11. Click Save.

Retrieving the Event Gateway management endpoint

To register an Event Manager instance with API Connect, you must provide an endpoint which defines where configuration updates from API Connect are sent. This is referred to as the Service Endpoint when registering an Event Gateway Service in the Cloud Manager. This endpoint can be retrieved from Event Endpoint Management as follows:

Using the OpenShift web console

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand the Networking dropdown and select Routes.
  3. Expand the Project drop-down menu and select the project the Event Manager instance is installed in.
  4. Use the search bar to find the route with the Name ending in apic. The URL in the Location column is the management endpoint.

Using the CLI

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

  2. Ensure you are in the namespace where your Event Manager instance is installed:

    kubectl config set-context --current --namespace=<namespace>

  3. List the ingress resources and locate the API Connect ingress for your instance, unless overridden the name ends in -apic.

     kubectl get ingress
  4. Obtain the URL for the ingress resource from the Host column.

Retrieving the Event Gateway client endpoint

To register an Event Manager instance with API Connect, you must provide an endpoint which defines where clients should connect to in order to consume events. Depending where you have deployed your Event Gateway, the steps to retrieve the client endpoint will differ:

OpenShift cluster deployment

  1. Log in to the OpenShift Container Platform web console using your login credentials.
  2. Expand the Networking dropdown and select Routes.
  3. Expand the Project drop-down menu and select the project the Event Gateway instance is installed in.
  4. Use the search bar to find the route with the Name ending in ibm-egw-rt. The URL in the Location column is the client endpoint.
  5. Having retrieved the Location value, remove the https:// protocol prefixing the endpoint, and append the port :443 as a suffix.

Other Kubernetes platforms

  1. Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.

  2. Ensure you are in the namespace where your Event Gateway instance is installed:

    kubectl config set-context --current --namespace=<namespace>

  3. List the ingress resources and locate the API Connect ingress for your instance, unless overridden the name ends in -ibm-egw-rt.

     kubectl get ingress
  4. Obtain the URL for the ingress resource from the Host column.

Stand-alone deployment

When deployed as a stand-alone gateway, the client endpoint value to use will be the name of the docker host running the gateway, and the GATEWAY_PORT value specified when starting the gateway container.

Register the Event Manager as an Event Gateway Service

To socialize the Event Gateway client endpoint, register the Event Gateway through the Cloud Manager as follows.

  1. In the Cloud Manager UI, select Topology > Register Service > Event Gateway Service.
  2. Enter a title and an optional summary.
  3. In the Service endpoint field, enter the management endpoint that you obtained earlier.
  4. Select the TLS client profile that you created earlier from the TLS client profile drop-down menu.
  5. In the API invocation endpoint field, enter the Event Gateway API endpoint that you obtained earlier.
  6. Use the default TLS server profile that API Connect provides from the drop-down menu.
  7. Click Save.

The Cloud Manager UI displays a notification to indicate the Event Gateway Service is successfully registered. You can now generate an AsyncAPI to use in API Connect.