1. There is an integration between VM and OC, VM and SBC, IFS and OC. All the sections in values.yaml such as global, vmappserver, ocappserver, ifs, ifsappserver, ifsagentserver, ifsdatasetup, vmdatasetup, runtime, and metering, needs to be populated, before installing any applications (VM, OC, or IFS).
2. So, during the installation of VM, the application requires ingress host of OC and ssl certificate of OC. The same applies for OC and IFS as well.
3. The integration works when the user populates one section at a time and install the application. For example, user must not populate vmappserver and install VM.

Installing the CASE

Replace the definition with the namespace of the target environment. To create a custom ClusterRole and RoleBinding, create a file cpq_psp_role_and_binding.yaml with the definition and run the following command:

Red Hat OpenShift SecurityContextConstraints Requirements

ibm-restricted-scc:  Use the predefined securitycontextconstraint - restricted.

Custom SecurityContextConstraints definition

Time zone considerations

To deploy the IBM Sterling Configure Price Quote software, the database, application servers, and agents must have the same time zone. Additionally, the time zone must be compatible with the locale code specified in the Configure Price Quote software. By default, the containers are deployed in UTC time zone. The locale code in Configure Price Quote software is also set to en_US_UTC time zone, which ensures that the database is also deployed in UTC.

Configuration

Ingress

• For IBM Sterling Visual Modeler, ingress can be enabled by setting the parameter vmappserver.ingress.enabled to true. If ingress is enabled, the application is exposed as a ClusterIP service, otherwise the application is exposed as NodePort service. It is recommended to enable and use ingress for accessing the application from outside the cluster. For production workloads, the only recommended approach is ingress with cluster IP. Do not use NodePort.

• vmappserver.ingress.host: It is a fully qualified domain name that resolves to the IP address of your cluster’s proxy node. Based on your network settings it is possible that multiple virtual domain names resolve to the same IP address of the proxy node. You can use any one of those domain names. For example, "example.com" or "test.example.com".

• vmappserver.ingress.ssl.enabled: It is recommended to enable SSL. If SSL is enabled by setting this parameter to true, a secret is needed to hold the TLS certificate.

• For the IBM Sterling Omni Configurator application, ingress can be enabled by setting the parameter ocappserver.ingress.enabled to true. If ingress is enabled, the application is exposed as a ClusterIP service, otherwise the application is exposed as NodePort service. It is recommended to enable and use ingress for accessing the application from outside the cluster. For production workloads, the only recommended approach is Ingress with cluster IP. Do not use NodePort.

• ocappserver.ingress.host: It is a fully qualified domain name that resolves to the IP address of your cluster’s proxy node. Based on your network settings it is possible that multiple virtual domain names resolve to the same IP address of the proxy node. You can use any one of the domain names. For example, "example.com" or "test.example.com".

• ocappserver.ingress.ssl.enabled: It is recommended to enable SSL. If SSL is enabled by setting this parameter to true, a secret is needed to hold the TLS certificate.

Installation of new database

The following process creates the required database tables and factory data in the database.

Db2 database secrets:

• Create a Db2 user.
• Add the following properties in the cpq-secrets.yaml file.

• Create a secret by running the following command:

Oracle database secret:

• In the Oracle database, create a user.
• Create tablespace DATA on database server by using the following script:

The tablespace is required to import data into the Oracle user database.

• Add the following properties in the cpq-secrets.yaml file:

• Create a secret by running the following command:

  oc create -f cpq-secrets.yaml

• Make the following changes in the values.yaml file to install a new database:

• Run the following command to install the database.

Configurable parameters for IBM Sterling Visual Modeler and IBM Sterling Omni Configurator charts

Affinity and Toleration

The chart provides various ways to configure advance pod scheduling in Kubernetes, in the form of node affinity, pod affinity, pod anti-affinity, and tolerations. For more information about the usage and specifications of the following features, see Kubernetes documentation.

• Toleration: It can be configured by using the parameter vmappserver.tolerations for the vmappserver. Similar parameters can be used for IBM Sterling Omni Configurator charts.

• Node affinity: It can be configured by using the parameters: 

•  vmappserver.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution, vmappserver.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution for the vmappserver

• ocappserver.common.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution, ocappserver.common.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution for the ocappserver.

• Depending on the architecture preference selected for the parameter global.arch, a suitable value for node affinity is automatically appended in addition to the user provided values.

• Pod affinity: It can be configured by using the following parameters:

•  vmappserver.podAffinity.requiredDuringSchedulingIgnoredDuringExecution, vmappserver.podAffinity.preferredDuringSchedulingIgnoredDuringExecution for the vmappserver

• ocappserver.common.podAffinity.requiredDuringSchedulingIgnoredDuringExecution, ocappserver.common.podAffinity.preferredDuringSchedulingIgnoredDuringExecution for the ocappserver.

• Pod anti-affinity: It can be configured by using the following parameters:

•  vmappserver.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution, vmappserver.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution for the appserver.

• ocappserver.common.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution, ocappserver.common.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution for the ocappserver.

• Depending on the value of the parameter podAntiAffinity.replicaNotOnSameNode, a suitable value for pod anti-affinity is automatically appended in addition to the user provided values. This step is to confirm whether the replica of a pod is to be scheduled on the same node.

• If the value is prefer, then podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution is automatically appended.

• If the value is require, then podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution is appended.

• If the value is blank, then pod anti-affinity value is not automatically appended.

• If the value is prefer, the weighting for the preference is set by using the parameter podAntiAffinity.weightForPreference that must be specified in the range 1 - 100.

Readiness and liveness

Readiness and liveness checks are provided for the agents and application server pods as applicable.

1. Application Server pod: The following parameters can be used to tune the readiness and liveness checks for application server pods:

• vmappserver.livenessCheckBeginAfterSeconds: It is used to specify the delay in starting the liveness check for the application server. The default value is 900 seconds (15 minutes).
• vmappserver.livenessFailRestartAfterMinutes: If the liveness check fails continuously for the specified period, this parameter is used to specify the approximate time period after which the pod restarts. The default value is 10 minutes.

For example, if the values for vmappserver.livenessCheckBeginAfterSeconds and vmappserver.livenessFailRestartAfterMinutes are 900 seconds and 10 minutes and the application server pod is not able to start even after 25 minutes, it will be restarted. After the application server starts successfully and if the liveness check fails continuously for 10 minutes, then it will be restarted.

Upgrading the Chart

You can upgrade your deployment when you have a new docker image for application or agent server or if there is a change in configuration. For example, if a new agent or an integration server needs to be deployed or started:

1. Ensure that the chart is downloaded locally by following the instructions given here.

2. Ensure that the ifsdatasetup.loadFactoryData parameter is set to donotinstall or blank.

3. Run the following command to upgrade your deployments:

Uninstalling the chart

To uninstall or delete the my-release deployment, run the following command:

Note: If you need to clean the installation, you can also consider deleting the secrets and persistent volume that was created as part of the prerequisites for installation.

Dashboard Experience

The Red Hat OpenShift comes with out of the box Dashboard displaying the objects that are deployed. You can check the Red Hat OpenShift documentation for the usage of Dashboard. https://docs.openshift.com/container-platform/4.6/welcome/index.html
Confirm the version of Red Hat OpenShift once you visit this page.

Limitations

• The database must be installed in UTC time zone.

Backup/recovery process

Back up of persistent data for IBM Sterling Configure Quote Price software can be a Database backup or a Repository backup. The database must be backed up regularly. Similarly, the repository folders must be backed up on a regularly to back up the model XML files and other properties defined as a part of the repository. Since the application pods are stateless, there is no backup or recovery process required for the pods.

The deployed application can be deleted by using the following command:

The application can also be rolled back by using the following command:

Usage of the vmoc base image and its customization

• Pull cpq-vmoc-base image into the local Docker repository.

• Create a custom base container from the base image by running the following command:
  podman run -it --net=podman --privileged -e LICENSE=accept:
  This command takes you inside the base container in "/opt/VMSDK" folder.

• The "/opt/VMSDK" folder contains all the artifacts.

• Once you create the container, come out of the container (Ctrl+PQ). Copy the IBM_VisualModeler.jar, configurator.war, ConfiguratorUI.war of the latest Fixpack inside the container in the /opt/VMSDK/newartifacts folder. Go to the folder where the 3 artifacts from the Jenkins build are downloaded and run the following commands:

• Once you are inside the container, run the following command to create the three database-independent messages: Visual Modeler, Omni Configurator, and the base image.

  ./executeAll.sh --createDB=false --loadDB=false --MODE=all --generateImage=true --generateImageTar=true --pushImage=true --imageRegistryURL= --imageRegistryPassword=****** --IMAGE_TAG_NAME=

createDB: If you are generating the images, set value to false. To create and load the database, set value to true.

loadDB: If you are generating the images, set value to false. To create and load the database, set value to true.

MODE: Set value to vm to generate only Visual Modeler appserver image. Set value to oc to generate only Omni Configurator appserver image. Set value to base to generate only vmoc base image. Set value to all to generate all the 3 images.

generateImage: To generate the image, set value to true. Otherwise, set to false.

generateImageTar: To save the image into .tar file, set value to true.

pushImage: To push the image into registry, set value to true.

imageRegistryURL: Specify the registry URL to push the image.

imageRegistryPassword: Password or API key required to log in to registry.

IMAGE_TAG_NAME: Provide tag name to the image. The generated image is pushed in registry with this tag name.

• To generate database-specific image, run the following command:

Here,
DBTYPE: Provide the value for either Db2 or oracle to generate Db2 or oracle image.

• Run the following command inside the container to create "projects/matrix" folder under "/opt/VMSDK" folder that is used to customize the Visual Modeler image:

Follow the IBM Documentation for copying the customization changes. After the customization changes are copied, run following commands from "/opt/VMSDK" folder to build the Visual Modeler WAR file with the customized changes and generate or push the customized images:

• For more information about customizing IBM Sterling Omni Configurator repository, see IBM Documentation.

Customizing server.xml for Liberty

You can customize the server.xml for Liberty by using the Helm charts.

There are two files, server_vm.xml and server_oc.xml, which is deployed as server.xml to the respective applications.

IBM Field Sales version 10.0.0.16

Introduction

This section describes how to deploy the IBM Field Sales v10.0.0.16 on Red Hat OpenShift platform. This helm chart does not install database server or messaging server. Both the middleware needs to be set up and configured separately for IBM Field Sales.

Note: This helm chart supports deployment of IBM Field Sales with Db2 database and MQ messaging.

Chart Details

This chart does the following:

• Create a deployment -ibm-cpq-prod-ifsappserver for IBM Field Sales application server with 1 replica by default.
• Create a deployment -ibm-cpq-prod-ifshealthmonitor for IBM Field Sales HealthMonitor, if health monitor is enabled.
• Create a deployment -ibm-cpq-prod- for each of the IBM Field Sales agent or integration server configured.
• Create a service -ibm-cpq-prod-ifsappserver. This service is used to access the IBM Field Sales application server by using a consistent IP address.
• Create a job -ibm-cpq-prod-ifsdatasetup. It is used for performing data setup for IBM Field Sales that is required to deploy and run the application. If the data setup is disabled at the time of installation or upgrade, the job is not created.
• Create a job -ibm-cpq-prod-preinstall. It is used to perform pre-installation activities like generating ingress TLS secret.
• Create a ConfigMap -ibm-cpq-prod-ifsconfig. It is used to provide IBM Field Sales and Liberty configuration.
• Create a ConfigMap -ibm-cpq-prod-def-server-xml-conf. It is used to provide default server.xml for Liberty. If a custom server.xml is used, the configmap is not created.

Note: Refers to the name of the helm release and refers to the agent or integration server name.

Prerequisites for IFS

1. Kubernetes version >= 1.17.0

2. Ensure that Db2 database server is installed and the database is accessible from inside the cluster. For more information, see section time zone considerations.

3. Ensure that MQ server is installed and it is accessible from inside the cluster.

4. Ensure that the docker images for IBM Field Sales are loaded to an appropriate docker registry. The default images for IBM Field Sales can be loaded from IBM Passport Advantage. Alternatively, customized images for IBM Field Sales can also be used.

5. Ensure that the docker registry is configured in Manage -> Resource Security -> Image Policies and also ensure that docker image can be pulled on all the Kubernetes worker nodes.

6. Create a persistent volume with access mode as 'Read write many' with minimum 10GB space.

7. Create a secret with datasource connectivity details as given. The name of this secret needs to be supplied as the value of parameter ifs.appSecret. It is recommended to prefix the release name to the secret name.

8. When using Podman for image operations like launching base container, ensure you have root privileges for the logged in user. Alternatively, you can use sudo.

Creating a secret ifs_secrets.yaml

Create a secret with data source connectivity details as given here. The name of this secret needs to be supplied as the value of parameter ifs.appSecret. It is recommended to prefix the release name to the secret name.

See the following ifs_secrets.yaml file:

PodSecurityPolicy Requirements

This chart requires a PodSecurityPolicy to be bound to the target namespace before installation. Choose either a predefined PodSecurityPolicy or have your cluster administrator create a custom PodSecurityPolicy for you:

• ICPv3.1 - Predefined PodSecurityPolicy name: default
• ICPv3.1.1 - Predefined PodSecurityPolicy name: ibm-anyuid-psp
• Custom PodSecurityPolicy definition:

Run the following command to create the ifs_psp.yaml file:

Custom ClusterRole and RoleBinding definitions

The definition must be replaced with the namespace of the target environment. Run the following command to create the file:

Red Hat OpenShift SecurityContextConstraints Requirements

This chart requires a SecurityContextConstraints to be bound to the target namespace before installation.

The predefined SecurityContextConstraints name ibm-anyuid-scc is verified for this chart. If your target namespace is bound to this SecurityContextConstraints resource, you can proceed to install the chart.

Alternatively, a custom SecurityContextConstraints can be created by using the following definition:

Run the following command to create a file ibm-ifs-scc.yaml with the definition :

Time Zone considerations

In order to deploy IBM Field Sales, the time zone of the database, application servers, and agents must be same. Additionally, this time zone must be compatible with the locale code specified in IBM Field Sales. By default, the containers are deployed in UTC. Also, the locale code is set as en_US_UTC. Doing so, ensures that the database is also deployed in UTC.

Configuration

Installation on a new database

When installing the chart on a new database that does not have IBM Field Sales tables and factory data, complete the following steps:

• Ensure that ifsdatasetup.loadFactoryData parameter is set to install and ifsdatasetup.mode parameter is set as create. It creates the required database tables and factory data in the database before installing the chart.
• Ensure that you do not specify any agents or integration servers with parameters ifsagentserver.servers.name. When installing against a fresh database, you do not have any agent and integration server configured. Hence, it does not make sense to configure agents and integration servers in the chart. Once the application server is deployed, you can configure the agents or integration servers. For more information about agent deployment and integration servers, see section Configuring agent or integration servers.

Installation against a pre-loaded database

When installing the chart against a database that has the IBM Field Sales tables and factory data, ensure that the ifsdatasetup.loadFactoryData parameter is set to donotinstall or blank. This step avoids re-creating tables and overwriting factory data.

Following table lists the configurable parameters for the chart:

1. Create a shared directory in the host file system.. The shared directory must be mounted on the host file system.

   mkdir -p /opt/ssfs/shared

2. Download OMS Fixpack Jar(If required) and IFS Fixpack Jar from Fix Central.
For OMS_FP, copy to the "/opt/ssfs/shared/OMS_FP" directory. For IFS_FP, copy to the "/opt/ssfs/shared/IFS_FP" directory.
Make sure there is only one file in OMS_FP and IFS_FP.
Verify Jar file name patterns.  The file name for OMS is smcfs_10_FP*.jar. The file name for IFS is sfs_10_FP3.jar.
3. Create a IFS base container from the IFS base image by running the Podman command -

   podman run -e LICENSE=accept --privileged -v /opt/ssfs/shared:/opt/ssfs/shared -it --name cpq-ifs-base:

   This will take you inside the base container in /opt/ssfs/runtime folder.
If the IFS base container already exist then use the following command to get into the IFS base container.
podman exec -it /bin/bash
4. IFS fixpack images can be created by running following scripts.

   ./installFixpack.sh | tee ifs_fixPack.log

   This script will taken an hour to complete.
5. Once the script completes the ifs image tar file can be located in /opt/ssfs/shared folder.
cpq-ifs-app_.tar, cpq-ifs-agent_.tar, cpq-ifs-base_.tar
6. Exit from the IFS Base container.
7. Load the app image using following command from /opt/ssfs/shared folder.

   podman load -i cpq-ifs-app_

   Similar command can be followed to load agent image.
8. Tag and push the image to the image registry(For example Red Hat OpenShift image registry) using following command.

   podman tag :

   podman push :

9. Update values.yaml with required details.
10. Install IFS Application

    helm install my-release [chartpath] --timeout 3600 --set global.license=true, global.install.visualmodeler.enabled=false, global.install.configurator.enabled=false, global.install.ifs.enabled=true, global.install.runtime.enabled=false

11. Log in to IFS application and verify IFS fix pack version from About Menu.
12. Log in to SBC application and verify OMS fix pack version from About Menu.

1. Download the fix pack from IBM Fix Central and save the file to a temporary location on a installation node.
2. Locate the fix pack compressed file and extract the file contents
For example, the compressed file name for fix pack 9 is 10.0.0.0-Sterling-VM-All-fp0009.zip
3. Extract the contents of the fix pack compressed file to the temp location on the installation node.
4. Create base container using base image cpq-vmoc-base.
5. If the base container exists, go to the base container shell.
For more information, see link https://www.ibm.com/support/knowledgecenter/SS4QMC_10.0.0/installation/c_cpqRHOC_customizing_runtime.html
6. Copy the content from temp location in Step 3, VM10-FP9.jar, ConfiguratorUI.zip, and configurator.war to fix pack location inside the base container.
The corresponding container path is /opt/VMSDK/fixpack.Copy the VM10-FP9.jar, ConfiguratorUI.zip, and configurator.war to the /opt/VMSDK/fixpack directory. Use podman cp to copy the jar file to the base container.
7. In the container shell, go to the /opt/VMSDK directory.
8. Generate the images by running executeAll script which will install the VM10-FP9.jar, ConfiguratorUI.zip, and configurator.war.
'

   /executeAll.sh --DBTYPE="$DBTYPE" --createDB=false --loadDB=false --loadMatrixDB=false --MODE=vm --generateImage=true --pushImage=false --generateImageTar=true --IMAGE_TAG_NAME="$IMAGE_TAG_NAME"

   /executeAll.sh --DBTYPE="$DBTYPE" --createDB=false --loadDB=false --loadMatrixDB=false --MODE=oc --generateImage=true --pushImage=false --generateImageTar=true --IMAGE_TAG_NAME="$IMAGE_TAG_NAME"

9. The command will create two image files cpq-oc-app_.tar and cpq-vm-app_.tar
10. Copy the tar file outside the container and create image out of it using podman load command.

Reinstall the Chart

To re-install the chart, you need to first delete the deployment.

helm delete my-release

Please make sure all the objects related to your release are deleted.

You can do that by running the command:

This command will give you a list of all the objects that are related to your release. If you see any objects related to your release remaining, please delete them by using the command:

To re-install, run the command:

Import Certificates

If there is a requirement to import server certificates into IBM Sterling Configure Price Quote software, you can do that by the import certificate feature of the chart. For example, integration with Salesforce (SFDC) requires importing certificates to Configure Price Quote.

1. Get the certificate which you need to add to the application. One way of getting a certificate is by exporting it through browser (lock icon in the location bar). The browser will show the certificate which you can save as either a .crt file or as a .pem file if you need the chain of certificates.
2. Save this file into the node where you have installed the helm charts.
3. You will need to create a Red Hat OpenShift secret object using this certificate file. To do that execute the command:

Dashboard Experience

Red Hat OpenShift comes with Out of the box Dashboard displaying objects deployed.
Please check the Red Hat OpenShift documentation for the usage of Dashboard.
https://docs.openshift.com/container-platform/4.6/welcome/index.html
(Please confirm the version once you visit the page.)

Troubleshooting

The health of the applications can be checked by running the command:

See the example for a pod named as mypod:

NAME READY STATUS

mypod 1/1 Running

Here, NAME is name of the pod running and the second and third columns show the status of the pods. If you don't see READY status, you will need to collect log to identify the issue.

Note: The Visual Modeler application takes up to 5 minutes to be up and running.

To get information about all pods running along with what node they are running on, run the command:

To get the information about events fired in the namespace, run the command:

To describe the pod in a human readable format, run the following command:

To get information about the pod in YAML format, run the following command:

To get the console logs of the pod, run the following command:

Execute the commands to collect information about the pod that you are interested in. You can locate Events section when you describe a pod to know about any triggered events on the pod. To get more information about the messages or errors found by executing the commands you can visit https://docs.openshift.com.

To know more about the application logs, you can open a shell to the pod by running the command:

The command allows you to execute Linux commands to locate logs. To locate logs you can use the following command inside the pod.:

More debug logs can be found at cd /output inside the pod. For easier view of log files you can copy logs out of the pod to your local as shown:

To check whether the NFS is mounted in pod you can run the command:

Then run the following command inside the pod:

To restart a pod you can delete it and it will auto restart:

The logs for Visual Modeler, Omni Configurator and FieldSales are available on the shared NFS server where you store the repository. You can mount the repository on a system and check out the logs in path /omscommonfile/configrepo in the repository. Look into the repository install section for repository details.

'Customizing server.xml for Liberty' and Liberty IBM Documentation online. The console logs would appear in messages log file

Check yfs_application_menu to make sure IBM Field Sales application is installed properly. This table should contain Application_Menu_Key for Field Sales (Field_Sales_Menu).

Check yfs_heartbeat and make sure the entry HealthMonitor Service is present.

Some common errors

• ImagePullBackOff: This error can mean multiple things. To get the exact error you will need to describe the pod and look into the Events section.

• CrashLoopBackOff: A CrashloopBackOff means that you have a pod starting and crashing intermittently. You will need to describe the pod and look into the Events section. Also you can look into the application logs by opening a session in the pod.

• LivenessProbeFailure: If the liveness probe fails, the Red Hat OpenShift kills the container and the container is subjected to its restart policy. You can describe the pod and also look into application logs to identify any exception or error.

• ReadinessProbeFailure: Indicates whether the container is ready to service requests. If the readiness probe fails, the endpoints controller removes the pod’s IP address from the endpoints of all services that match the pod. You can describe the pod and also look into application logs to identify any exception or error.

• If podman push or pull causes the following errors Error: Error copying image to the remote destination: Error trying to reuse blob or Error: error pulling image, you will need to make sure you log in to the registry where you want to push the image. Make sure you have logged in to the cluster by running the command:

Resources required

• Minimum - 3 master 3 worker nodes
• Minimum - Each node should have 8CPU, 16GB RAM, 250GB Disk

• 2560Mi memory for application servers
• 1 CPU core for application servers
• 3840Mi memory for application servers
• 2 CPU core for application servers

• 2560Mi memory for application server
• 1024Mi memory for each agent/integration server and health monitor
• 1 CPU core for application server
• 0.5 CPU core for each agent/integration server and health monitor

Upgrade Path

To get to the v10 container version,

• If you are on 9.x, upgrade to v10 non-containerized version first.
• Once you are on v10, upgrade to the v10 containerized version.
• You need to download the v10 images, put any customization using the base image and use the same database from the version you will be upgrading from. More documentation can be found on the IBM Documentation.

Limitations

Backup or recovery process

Back up of persistent data for IBM Field Sales like database back up needs to be taken on regular basis. Since the application pods are stateless, there is no backup or recovery process required for the pods.

You can delete the deployed application by running the command:

The application can be rolled back using the command:

To see revision numbers, run the commands:

• helm history my-release
• helm rollback my-release 0