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:
- 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.
- 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
- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
- Expand the Project drop-down menu and select the project the API Connect instance is installed in.
- Select the API Connect operator.
- In the API Connect cluster, click the installed instance.
- In the YAML, find the
status.endpoints
section of theAPIConnectCluster
custom resource. - 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:
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. - Get the list of endpoints from your API Connect pod by using the following command
kubectl describe pod <apic-pod>
. - Look for the APIC_PLATFORM_API_ENDPOINT.
Note: The APIC_PLATFORM_API_ENDPOINT is a URL with/api
at the end. - 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.
-
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 aboutingress-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:
- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Workloads drop-down menu and select Secrets.
- Expand the Project drop-down menu and select the project the API Connect instance is installed in.
- Find the
<name>-ingress-ca
secret, and select it. - 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
.
- For a decoded value to be used in the OpenShift web console, click the Details tab and copy value in
-
By using the CLI:
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
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.
-
- Log in to your Kubernetes cluster as a cluster administrator by setting your
-
-
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.
- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Workloads drop-down menu and select Secrets.
- Expand the Project drop-down menu and select the project the Event Manager instance is installed in.
- Expand the Create drop-down menu and select Key/value secret.
- Enter
apim-cpd
as the Secret name. - Enter
ca.crt
as the Key. - Under Value, select the text area, and enter the decoded certificate.
- Click Create.
-
By using the CLI:
Note: When creating secrets by using the CLI, the certificate must be Base64-encoded.
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
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.
- Log in to your Kubernetes cluster as a cluster administrator by setting your
-
-
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:- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
- Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Endpoint Management.
- Click the Event Endpoint Management tab and search the Name column for the installed instance and click the name.
- Click the YAML tab to edit the custom resource.
-
In the
spec.manager
field, add the following snippet:apic: jwks: endpoint: <jwksUrl>
-
In the
spec.manager.tls
field, add the following snippet:trustedCertificates: - certificate: ca.crt secretName: apim-cpd
- 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 thekubectl edit
command, or modify your original configuration file as follows.- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
Ensure you are in the namespace where your Event Manager instance is installed:
kubectl config set-context --current --namespace=<namespace>
-
Update your
EventEndpointManagement
instance’s YAML file on your local system. In thespec.manager
field, add the following snippet:apic: jwks: endpoint: <jwksUrl>
-
Also in the YAML, in the
spec.manager.tls
field, add the following snippet:trustedCertificates: - certificate: ca.crt secretName: apim-cpd
-
Apply the YAML to the Kubernetes cluster:
kubectl apply -f <file_name>
- Log in to your Kubernetes cluster as a cluster administrator by setting your
-
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:
- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Operators dropdown and select Installed Operators to open the Installed Operators page.
- Expand the Project dropdown and select the project the instance is installed in. Click the operator called IBM Event Endpoint Management.
- Click the Event Endpoint Management tab and search the Name column for the installed instance and click the name.
- Click the YAML tab to edit the custom resource.
-
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. - 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.
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
Ensure you are in the namespace where your Event Manager instance is installed:
kubectl config set-context --current --namespace=<namespace>
-
Update your
EventEndpointManagement
instance’s YAML file on your local system. In thespec.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. -
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
- Expand the Workloads drop-down menu and select Secrets.
- Expand the Project drop-down menu and select the project the Event Manager instance is installed in.
- Use the search bar to locate the secret named
<event-manager-instance-name>-ibm-eem-manager
and click the secret. - Scroll down to the
Data
section. - Copy the ca.crt and save it in a file called
cluster-ca.pem
- Copy the tls.crt and save it in a file called
manager-client.pem
- 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.
Obtain certificates for a TLS client profile on other Kubernetes platforms
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
Ensure you are in the namespace where your Event Manager instance is installed:
kubectl config set-context --current --namespace=<namespace>
-
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
- Copy the ca.crt and save it in a file called
cluster-ca.pem
- Copy the tls.crt and save it in a file called
manager-client.pem
- 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.
Navigate to Cloud Manager
- Expand the Networking dropdown and select Routes.
- Expand the Project drop-down menu and select the project the API Connect instance is installed in.
- 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.
- Create a client TLS keystore. Go to Home > Resources > TLS > Keystore and click Create.
- Upload the
manager-client-key.pem
into Step 1. - Upload the
manager-client.pem
into Step 2. - Click Save.
- Create a client TLS truststore. Go to Truststore and click Create.
- Upload the
cluster-ca.pem
. - Click Save.
- Create a TLS client profile. Go to TLS client profile and click Create.
- Choose the keystore and truststore you created.
- Tick Allow insecure server connections.
- 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
- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Networking dropdown and select Routes.
- Expand the Project drop-down menu and select the project the Event Manager instance is installed in.
- 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
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
Ensure you are in the namespace where your Event Manager instance is installed:
kubectl config set-context --current --namespace=<namespace>
-
List the ingress resources and locate the API Connect ingress for your instance, unless overridden the name ends in
-apic
.kubectl get ingress
- 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
- Log in to the OpenShift Container Platform web console using your login credentials.
- Expand the Networking dropdown and select Routes.
- Expand the Project drop-down menu and select the project the Event Gateway instance is installed in.
- 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. - Having retrieved the Location value, remove the
https://
protocol prefixing the endpoint, and append the port:443
as a suffix.
Other Kubernetes platforms
- Log in to your Kubernetes cluster as a cluster administrator by setting your
kubectl
context. -
Ensure you are in the namespace where your Event Gateway instance is installed:
kubectl config set-context --current --namespace=<namespace>
-
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
- 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.
- In the Cloud Manager UI, select Topology > Register Service > Event Gateway Service.
- Enter a title and an optional summary.
- In the Service endpoint field, enter the management endpoint that you obtained earlier.
- Select the TLS client profile that you created earlier from the TLS client profile drop-down menu.
- In the API invocation endpoint field, enter the Event Gateway API endpoint that you obtained earlier.
- Use the default TLS server profile that API Connect provides from the drop-down menu.
- 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.