Post-installation tasks

Consider the following tasks after installing Event Endpoint Management.

Verifying an installation

To verify that your Event Endpoint Management installation deployed successfully, you can check the status of your instance either by using the command line (CLI), or if running on OpenShift Container Platform, by using the web console (UI).

Using the OpenShift Container Platform UI

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.
Select the Event Endpoint Management tab.
The Status column will display the current state of the EventEndpointManagement custom resource. When the Event Endpoint Management instance is ready, the status will display Phase: Running.

Using the CLI

After all the components of an Event Endpoint Management instance are active and ready, the EventEndPointManagement custom resource will have a Running phase in the status.

To verify the status:

Run the kubectl get command as follows:

kubectl get eventendpointmanagement <instance-name> -n <namespace> -o jsonpath='{.status.phase}'

An example output for a successful deployment:

$ kubectl get eventendpointmanagement development -n eem -o jsonpath='{.status.phase}'
Running

Note: It might take several minutes for all the resources to be created and the instance to become ready.

Setting up access

After the Event Endpoint Management instance is successfully created, set up user authentication and authorization for your chosen implementation. Event Endpoint Management supports locally defined authentication for testing purposes and OpenID Connect (OIDC) authentication for production purposes.

If you have selected LOCAL authentication, ensure you create user credentials before you access the Event Endpoint Management instance. For more information, see managing access.
After setting up LOCAL or OIDC authentication, assign users to roles. For more information, see managing roles.

Verifying the Event Gateway configuration

To verify the gateway configuration:

Login to your Event Endpoint Management instance with your configured credentials
Navigate to the Gateways page on the toolbar on the left side of the page.
The Gateways page displays all the Event Gateway instances registered with the Event Endpoint Management Manager instance and their configuration status. Verify that the Event Gateway you have configured is present in the table.

Backup the data encryption key

The secret <instance-name>-ibm-eem-mek contains an important key for decrypting the data stored by Event Endpoint Management. Ensure you back up and store the key safely outside your cluster.

To save the key to a file, complete the following steps.

Run the following command to retrieve the encryption secret.

kubectl get secret <instance-name>-ibm-eem-mek -n <namespace>

Create a backup of the encryption secret with the command:
```
kubectl get secret <instance-name>-ibm-eem-mek -n <namespace> -o yaml > encryption-secret.yaml
```
This command retrieves the encryption secret in YAML format and redirects the output to a file named encryption-secret.yaml.
Ensure that the backup file (encryption-secret.yaml) is stored in a secure location outside the cluster.

Validating a usage-based deployment

You can confirm if a usage-based deployment is operating as expected by checking the logs and the /ready endpoint of a running Event Endpoint Management manager instance.

When starting, verify the Event Endpoint Management manager logs if it is operating in usage-based mode. If it is, the manager will perform an initial test of the provided configuration settings. The following is an example of a successful check:

...
<DATETIME> INFO  com.ibm.ei.eim.ubp.UBPCollector (UBP Collector) - [configReceived:181] Usage Based Pricing enabled : License Service reporting usage to: <ENDPOINT>
...
<DATETIME> INFO  com.ibm.ei.eim.ubp.UBPCollector (UBP Collector) - [lambda$configReceived$8:188] Usage Based Pricing configuration test successful..
...

If at any time an issue occurs when reporting metrics, including the initial test, a message is written to the logs, detailing the cause of the error, and the payload which was being sent. The following is an example of an error message:

...
<DATETIME> WARN  com.ibm.ei.eim.ubp.UBPCollector (UBP Collector) - [lambda$sendMetrics$18:295] Failed to send data to the license service : <ENDPOINT> : <ERROR> : <PAYLOAD>

Note: If an error occurs when submitting the number of API calls to the Licensing Service, the actual number of API calls made is not lost. They will be reported, in addition to any new API calls, in the next submission.

This message and status is also available in the Event Endpoint Management manager component /ready endpoint on port 8081, under the UBP.Reporting.Status ID. This endpoint can be queried at any time. The following is an example query:

kubectl exec $(kubectl get pod -l app.kubernetes.io/instance=<INSTANCE_NAME> -n <NAMESPACE> -o name) -n <NAMESPACE> curl http://localhost:8081/ready

The result will return the current status of the gateway. The following is an example result of a healthy system with usage-based licensing configured:

{
  "code" : 200,
  "body" : {
    "components" : [ {
      "id" : "GatewayServices",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "FileStorageProvider",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "UBP.Reporting.Status",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "EEMUI",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "OperatorServices",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    } ],
    "readyComponentCount" : 5,
    "notReadyComponentCount" : 0,
    "code" : 200,
    "status" : "ok"
  }
}

The following is an example result of a system that has usage-based licensing configured, but is running with errors:

{
  "code" : 503,
  "body" : {
    "components" : [ {
      "id" : "GatewayServices",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "FileStorageProvider",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "UBP.Reporting.Status",
      "description" : "Failed to send data to the license service : https://ibm-licensing-service-instance.ibm-common-services.svc.cluster.local:8089/v2/metric_upload?token=cEDdqE9sodSl8n87Vz82Im39 : No route to host: ibm-licensing-service-instance.ibm-common-services.svc.cluster.local/172.30.42.210:8089 : {\"cloudpakId\":\"279abae6bfe647eca1f0efcbf136099c\",\"cloudpakName\":\"IBM Cloud Pak for Integration - API Calls\",\"productId\":\"3af7dda8ce3e4369b1c461c2982719c8\",\"productName\":\"IBM Event Endpoint Management Non Production\",\"productMetric\":\"MONTHLY_API_CALL\",\"productCloudpakRatio\":\"2:1\",\"cloudpakMetric\":\"RESOURCE_VALUE_UNIT\",\"aggregationPolicy\":\"ADD\",\"metricValue\":0}",
      "code" : 500,
      "conditions" : [ ]
    }, {
      "id" : "EEMUI",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    }, {
      "id" : "OperatorServices",
      "description" : "ok",
      "code" : 200,
      "conditions" : [ ]
    } ],
    "readyComponentCount" : 4,
    "notReadyComponentCount" : 1,
    "code" : 503,
    "status" : "Not ready"
  }
}

Updating and renewing certificates

After installing Event Endpoint Management, you can manage your certificates with the Cert Manager operator.

Important: When updating or renewing certificates, it is important to also update the spec.tls.caSecretName configuration (or ca.pem if deployed as a stand-alone gateway) of any Event Gateway in step with updates made to the Event Endpoint Management Manager instance they are registered with. Communication between the Event Gateway and Manager will fail until the certificate configuration is updated.

Renew an existing certificate

You can use Cert Manager to renew and regenerate a certificate if the secret for the certificate is deleted. You can also use the Cert Manager to renew your expired certificates.

By using `cmctl`

Cert Manager provides the cert-manager Command Line Tool (cmctl) for managing and renewing certificates.

Install the cert-manager Command Line Tool (cmctl).
Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
Ensure you are in the namespace where your Event Endpoint Management instance is installed:
```
kubectl config set-context --current --namespace=<namespace>
```
View the certificates of your Event Endpoint Management instance by running the following command:
```
kubectl get certificate
```
View the status of an existing certificate by running the following command:
```
cmctl status certificate <certificate_name>
```
Renew a certificate by running the following command:
```
cmctl renew <certificate_name>
```

By using the OpenShift Container Platform web console

If running on the OpenShift Container Platform, you can also renew a certificate by deleting the existing secret in the OpenShift web console as follows:

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.
In the EventEndpointManagement details dashboard, scroll down and locate the Ca Secret Name field, and then click the linked secret.
Click the Actions menu, and select Delete secret.

Note: Following deleting the secret, you will be navigated back to the Secrets page. Your deleted secret will have been regenerated with a new value, which will be used for your certificate in the IBM Cert Manager.

By using the CLI

You can also renew a certificate by deleting the existing secret. You can do this by using the kubectl command 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 Endpoint Management instance is installed:
```
kubectl config set-context --current --namespace=<namespace>
```
Run the following command to display the Event Endpoint Management instances:
```
kubectl get eventendpointmanagement
```
Run the following command to display the name of the secret representing the certificate for Event Endpoint Management:
```
kubectl get eventendpointmanagement <instance_name> --template '{ {.spec.manager.tls.caSecretName} }'
```
Run the following command to delete and regenerate the value of the certificate:
```
kubectl delete secret <secret_name>
```

Update a certificate to use an external secret

You can provide an externally generated certificate to Cert Manager. To use an externally generated certificate, update the Event Endpoint Management instance to use the external certificate as follows.

Generate a certificate externally

You can generate a certificate externally to register with Event Endpoint Management. There are several ways to generate a certificate externally. For example, you can create a certificate by using openssl as follows.

Generate a certificate key file by using openssl: openssl genrsa --out ca.key 4096
Generate a CA certificate by using the key file: openssl req -new -x509 -sha256 -days 10950 -key ca.key -out ca.crt

Register an externally generated certificate

Log in to your Kubernetes cluster as a cluster administrator by setting your kubectl context.
Ensure you are in the namespace where your Event Endpoint Management instance is installed:
```
kubectl config set-context --current --namespace=<namespace>
```
Encode your externally generated certificates to Base64 format, and make a note of the values:

base64 -i ca.crt

base64 -i ca.key

Create a YAML file called secret.yaml with the following content:

 apiVersion: v1
 kind: Secret
 metadata:
   name: ibm-ca-secret
   namespace: <eem namespace>
 type: Opaque
 data:
   ca.crt: <Base64 value for ca.crt>
   tls.crt: <Base64 value for ca.crt>
   tls.key: <Base64 value for ca.key>

Apply the secret by running the following command:
```
kubectl apply -f secret.yaml
```
Edit the custom resource of the Event Endpoint Management instance by running the following command:
```
kubectl edit eventendpointmanagement <instance-name>
```
Locate and update the spec.tls.caSecretName field to ibm-ca-secret, then save and exit.

This will update the certificate used in your Event Endpoint Management instance. Your pods will reload with the latest certificates in use.

Note: If you cannot log in to the Event Endpoint Management UI after changing your CA certificates, see troubleshooting to resolve the error.