Configure an Event Endpoint Management Manager as an Event Gateway Service

You can configure your Event Endpoint Management instance (Manager) 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 Event Endpoint Management 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 Endpoint Management instance so that communications received from API Connect are trusted.
  2. Use the Event Gateway API and the Event Manager 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 Endpoint Management Manager as an Event Gateway Service.

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

Before beginning, you must retrieve the API Connect jwksUrl endpoint.

  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.

The value that you retrieved is required to configure trust between API Connect and Event Endpoint Management.

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. More information about the ingress-ca can be found here

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

    The CA certificate can be obtained 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.

    • Using the OpenShift Container Platform UI:

      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. Click the YAML tab.
      6. Copy the value under data.ca.crt.

    • Using the CLI:

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

      2. Run the following command to extract the Base64-encoded certificate:

        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.

    Note: This value is Base64-encoded. However, if you retrieve the value from the Details tab in the OpenShift Container Platform UI instead, the value is not Base64-encoded.

  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.

    • Using the OpenShift Container Platform UI:

    Note: When creating secrets in the OpenShift Container Platform UI, the input value must not be encoded. Therefore, if you have a Base64-encoded certificate from step 1, 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 Endpoint Management 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.

    • Using the CLI:

      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 Endpoint Management instance is installed in>
data:
  ca.crt: >-
    <Base64-certificate>
type: Opaque
EOF

        Where:

        • <namespace> is the namespace the Event Endpoint Management 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 Endpoint Management 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

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 Endpoint Management 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 Event Endpoint Management as an Event Gateway Service in API Connect

After configuring the Event Endpoint Management to trust API Connect, register the Event Endpoint Management 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 Endpoint Management instance is installed in.
  3. Use the search bar to locate the secret named <Event Endpoint Management Manager instance name>-ibm-eem-manager and click the secret.
  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

N.b if you provided your own certificate via a secret for the eem manager use the data stored in that

For more information on these certificates, see the API Connect documentation.

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 Endpoint Management 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.

     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

Note: If you provided your own certificate through a secret for the Event Manager, use the data stored in the secret.

For more information about these certificates, see the API Connect documentation.

  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 Endpoint Management 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 Endpoint Management 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 Endpoint Management 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 Endpoint Management 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 Event Endpoint Management 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 export an AsyncAPI to use in API Connect.