This project demonstrates how to deploy an IBM® Operational Decision Manager (ODM) clustered topology using the container-native load balancer of GKE.
The ODM services will be exposed using the Ingress provided by the ODM on Kubernetes Helm chart. This deployment implements Kubernetes and Docker technologies. Here is the Google Cloud home page: https://cloud.google.com
The ODM on Kubernetes Docker images are available in the IBM Entitled Registry. The ODM Helm chart is available in the IBM Helm charts repository.
The project comes with the following components:
- IBM Operational Decision Manager
- Google Kubernetes Engine (GKE)
- Google Cloud SQL for PostgreSQL
- IBM License Service
The commands and tools have been tested on macOS and Linux.
First, install the following software on your machine:
Then, perform the following tasks:
-
Create a Google Cloud account by connecting to the Google Cloud Platform console. When prompted to sign in, create a new account by clicking Create account.
Without the relevant billing level, some Google Cloud resources will not be created.
Note
Prerequisites and software supported by ODM 9.0.0 are listed on the Detailed System Requirements page.
- Prepare your GKE instance 30 min
- Create the Google Cloud SQL PostgreSQL instance 10 min
- Prepare your environment for the ODM installation 10 min
- Manage a digital certificate 2 min
- Install the ODM release 10 min
- Access ODM services
- Track ODM usage with the IBM License Service
Refer to the GKE quickstart for more information.
After installing the gcloud tool, use the following command line:
gcloud auth loginThere are several types of clusters.
In this article, we chose to create a regional cluster.
Regions and zones (used below) can be listed respectively with gcloud compute regions list and gcloud compute zones list.
-
Set the project (associated to a billing account):
gcloud config set project <PROJECT_ID>
-
Set the region:
gcloud config set compute/region <REGION (ex: europe-west9)>
-
Set the zone:
gcloud config set compute/zone <ZONE (ex: europe-west9-b)>
-
Create a cluster and enable autoscaling. Here, we start with 6 nodes (16 max):
gcloud container clusters create <CLUSTER_NAME> \ --release-channel=regular --cluster-version=1.30 \ --enable-autoscaling --num-nodes=6 --total-min-nodes=1 --total-max-nodes=16
Note
If you get a red warning about a missing gke-gcloud-auth-plugin, install it with gcloud components install gke-gcloud-auth-plugin.
For Kubernetes versions lower than 1.26 you have to enable it for each kubectl command with export USE_GKE_GCLOUD_AUTH_PLUGIN=True (more information).
Note
You can also create your cluster from the Google Cloud Platform using the Kubernetes Engine > Clusters panel and clicking the Create button
-
Create a kubeconfig to connect to your cluster:
gcloud container clusters get-credentials <CLUSTER_NAME>
Note
You can also retrieve the command line to configure kubectl from the Google Cloud Console using the Kubernetes Engine > Clusters panel and clicking Connect on the dedicated cluster.
-
Check your environment
If your environment is set up correctly, you should be able to get the cluster information by running the following command:
kubectl cluster-info
We will use the Google Cloud Platform console to create the database instance.
- Go to the SQL context, and then click the CREATE INSTANCE button
- Click Choose PostgreSQL
- Database version:
PostgreSQL 15 - Instance ID:
<YourInstanceName> - Password:
<PASSWORD>- Take note of this password. - Region:
<REGION>(must be the same as the cluster for the communication to be optimal between the database and the ODM instance) - Eventually select Multiple zones for Zonal availability for redundancy
- Expand Show customization option and expand Connections
- As Public IP is selected by default, in Authorized networks, click the ADD NETWORK button, put a name and add 0.0.0.0/0 for Network, then click DONE.
NOTE: It is not recommended to use a public IP. In a production environment, you should use a private IP.
- As Public IP is selected by default, in Authorized networks, click the ADD NETWORK button, put a name and add 0.0.0.0/0 for Network, then click DONE.
- Database version:
- Click CREATE INSTANCE
After the database instance is created, you can drill on the SQL instance overview to retrieve needed information to connect to this instance, like the IP address and the connection name. Take note of the Public IP address.
To secure access to the database, you must create a secret that encrypts the database user and password before you install the Helm release.
kubectl create secret generic odmdbsecret \
--from-literal=db-user=postgres \
--from-literal=db-password=<PASSWORD>Where:
<PASSWORD>is the database password (PASSWORD set during the PostgreSQL instance creation above)
To get access to the ODM material, you need an IBM entitlement key to pull the images from the IBM Entitled Registry.
-
Log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software.
-
In the Container software library tile, verify your entitlement on the View library page, and then go to Get entitlement key to retrieve the key.
kubectl create secret docker-registry registrysecret \
--docker-server=cp.icr.io \
--docker-username=cp \
--docker-password='<API_KEY_GENERATED>' \
--docker-email=<USER_EMAIL>Where:
<API_KEY_GENERATED>is the entitlement key from the previous step. Make sure you enclose the key in quotes.<USER_EMAIL>is the email address associated with your IBMid.
Note
The cp.icr.io value for the docker-server parameter is the only registry domain name that contains the images. You must set the docker-username to cp to use an entitlement key as docker-password.
The image.repository parameter will later be set to cp.icr.io/cp/cp4a/odm.
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
helm repo updatehelm search repo ibm-odm-prod
NAME CHART VERSION APP VERSION DESCRIPTION
ibm-helm/ibm-odm-prod 24.1.0 9.0.0.1 IBM Operational Decision ManagerIn this step, you will generate a certificate to be used by the GKE load balancer.
If you do not have a trusted certificate, you can use OpenSSL and other cryptography and certificate management libraries to generate a certificate file and a private key to define the domain name and to set the expiration date. The following command creates a self-signed certificate (.crt file) and a private key (.key file) that accept the domain name mynicecompany.com. The expiration is set to 1000 days:
openssl req -x509 -nodes -days 1000 -newkey rsa:2048 -keyout mynicecompany.key \
-out mynicecompany.crt -subj "/CN=mynicecompany.com/OU=it/O=mynicecompany/L=Paris/C=FR"kubectl create secret tls mynicecompany-tls-secret --key mynicecompany.key --cert mynicecompany.crtThe certificate must be the same as the one you used to enable TLS connections in your ODM release. For more information, see Server certificates and Working with certificates and SSL.
The ODM services will be exposed with an Ingress that uses the previously created mynicecompany certificate.
It automatically creates an HTTPS GKE load balancer. We will disable the ODM internal TLS as it is not needed.
-
Get the gcp-values.yaml file and replace the following keys:
<DB_ENDPOINT>: the database IP
Note
You can configure the driversUrl parameter to point to the appropriate version of the Google Cloud SQL PostgreSQL driver. For more information, refer to the Cloud SQL Connector for Java documentation.
-
Install the chart from IBM's public Helm charts repository:
helm install <release> ibm-helm/ibm-odm-prod --version 24.1.0 -f gcp-values.yaml
Note
You might prefer to access ODM components through the NGINX Ingress controller instead of using the IP addresses. If so, please follow these instructions.
Run the following command to check the status of the pods that have been created:
kubectl get pods
NAME READY STATUS RESTARTS AGE
<release>-odm-decisioncenter-*** 1/1 Running 0 20m
<release>-odm-decisionrunner-*** 1/1 Running 0 20m
<release>-odm-decisionserverconsole-*** 1/1 Running 0 20m
<release>-odm-decisionserverruntime-*** 1/1 Running 0 20mTo get the status of the current deployment, go to the Kubernetes Engine / Services & Ingress Panel in the console.
The Ingress remains in the state Creating ingress for several minutes until the pods are up and running, and the backend gets in a healthy state.
You can also check the load balancer status. It provides information about the backend using the service health check.
In the Ingress details, you should get a HEALTHY state on all backends. This panel also provides some logs on the load balancer activity. When the Ingress shows an OK status, all ODM services can be accessed.
Sticky session is needed for Decision Center. The browser contains a cookie which identifies the user session that is linked to a unique container. The ODM on Kubernetes Helm chart has a clientIP for the Decision Center session affinity. Unfortunately, GKE does not use it automatically. You will not encounter any issue until you scale up the Decision Center deployment.
A configuration that uses BackendConfig is needed to manage session affinity at the load balancer level.
-
Create the Decision Center Backend Config:
kubectl create -f decisioncenter-backendconfig.yaml
-
Annotate the Decision Center Service with this GKE Backend Config:
kubectl annotate service <release>-odm-decisioncenter \ cloud.google.com/backend-config='{"ports": {"9453":"dc-backendconfig"}}'
As soon as GKE manages Decision Center session affinity at the load balancer level, you can check the ClientIP availability below the Decision Center Network Endpoint Group configuration from the Google Cloud Console in the Load Balancer details.
In a real enterprise use case, to access the mynicecompany.com domain name, you have to deal with Google Managed Certificate and Google Cloud DNS.
In this trial, we use a self-signed certificate. So, there is no extra charge like certificate and domain purchase. We only have to manage a configuration to simulate the mynicecompany.com access.
-
Get the EXTERNAL-IP with the command line:
kubectl get ingress <release>-odm-ingress -o jsonpath='{.status.loadBalancer.ingress[].ip}'
-
Edit your /etc/hosts file and add the following entry:
<EXTERNAL-IP> mynicecompany.com
-
You can now access all ODM services with the following URLs:
| SERVICE NAME | URL | USERNAME/PASSWORD |
|---|---|---|
| Decision Server Console | https://mynicecompany.com/res | odmAdmin/odmAdmin |
| Decision Center | https://mynicecompany.com/decisioncenter | odmAdmin/odmAdmin |
| Decision Center REST-API | https://mynicecompany.com/decisioncenter-api | odmAdmin/odmAdmin |
| Decision Server Runtime | https://mynicecompany.com/DecisionService | odmAdmin/odmAdmin |
| Decision Runner | https://mynicecompany.com/DecisionRunner | odmAdmin/odmAdmin |
Note
You can also click the Ingress frontends accessible from the Google Cloud console under the Kubernetes Engine/Services & Ingress Details Panel.
This section explains how to track ODM usage with the IBM License Service.
Follow the Installation section of the Manual installation without the Operator Lifecycle Manager (OLM) and stop before it asks you to update the License Service instance. It will be done in the next paragraph.
Get the licensing-instance.yaml file and run the following command:
kubectl apply -f licensing-instance.yaml -n ibm-licensingNote
You can find more information and use cases on this page.
As Google native Load Balancer does not support the same URL rewriting rules as other ones (such as NGINX), some settings have to be modified directly on GCP Web UI.
You have to look for the ibm-licensing-service-instance in the list of Ingresses, then select its Load Balancer in the list of resources at the bottom:
Edit the rule about /ibm-licensing-service-instance/* and add / as path prefix rewrite:
Note
GKE Load Balancer may take a few minutes after its new configuration to actually apply it.
After a couple of minutes, the Ingress configuration is created and you will be able to access the IBM License Service by retrieving the URL with the following command:
export LICENSING_URL=$(kubectl get ingress ibm-licensing-service-instance -n ibm-licensing -o jsonpath='{.status.loadBalancer.ingress[0].ip}')/ibm-licensing-service-instance
export TOKEN=$(kubectl get secret ibm-licensing-token -o jsonpath={.data.token} -n ibm-licensing |base64 -d)You can access the http://${LICENSING_URL}/status?token=${TOKEN} URL to view the licensing usage or retrieve the licensing report .zip file by running the following command:
curl -v "http://${LICENSING_URL}/snapshot?token=${TOKEN}" --output report.zipIf your IBM License Service instance is not running properly, refer to this troubleshooting page.
If your ODM instances are not running properly, refer to our dedicated troubleshooting page.
Get hands-on experience with IBM Operational Decision Manager in a container environment by following this Getting started tutorial.