IBM Sterling Order Management Software Professional Edition, version 10.0

SSL configurations for securing external connections

As part of your solution, you might come across situations where your application or agent servers need to communicate with an external or a third-party service for leveraging certain capabilities. Most of the times, these services are exposed over secure protocols such as HTTPS. At times, some services require mutual authentication (mTLS) to securely exchange data. For this, you need to configure SSL certificates in application and agent servers to enable trust with the external services and establish a successful secure connection. The Helm chart provides all the configurations required to configure the SSL certificates for your application and agent servers.

• Trusting external server certificates

  To trust an external service from your application or agent servers, the Helm chart provides these options.

  • Using a custom TrustStore

    This approach provides you the flexibility to trust the specific services with which your application must establish SSL connection. You can create your own TrustStore by using the keytool command of JDK in p12 format. Copy the newly created TrustStore to the Persistent Volume and provide the complete path to the TrustStore with respect to the volume mounted within the pod in the Helm values by using global.security.ssl.trustStore.storeLocation. Also, add the password for this TrustStore in the secret created as a prerequisite provided in Create a Secret section with the key trustStorePassword. For example, if the TrustStore is present in the Persistent Volume at certs/truststore.p12 provide the value of global.security.ssl.trustStore.storeLocation as /shared/certs/truststore.p12.

  • Using specific server certificates

    This approach provides you the ability to pass trusted server certificates as PEM files in the Persistent Volume. Provide the path to the directory that contains the trusted certificates in the Helm values by using global.security.ssl.trustStore.trustedCertDir. The application and agent servers already uses the default Java TrustStore. Use this option only if the certificates you want to trust are not already present in the default Java TrustStore. In case you do not want your servers to trust the certificates in default Java TrustStore, set the value of global.security.ssl.trustStore.trustJavaCACerts parameter to False.

• Providing identity certificates for mutual or client authentication

  You can provide your identity certificates for mutual or client authentication. You can create your own KeyStore by using the keytool command of JDK in p12 format. Ensure that this KeyStore includes all your identity certificates and keys that are required for mutual authentication between application and agent servers and external services. Copy the newly created KeyStore to the Persistent Volume and provide the complete path to the KeyStore with respect to the volume mounted within the pod in the Helm values by using global.security.ssl.keyStore.storeLocation. Also, add the password for this KeyStore in the secret created as a prerequisite provided in Create a Secret section with the key keyStorePassword. For example, if the KeyStore is present in the Persistent Volume at certs/keystore.p12 provide the value of global.security.ssl.keyStore.storeLocation as /shared/certs/keystore.p12.

Note: If you add a new certificate to the TrustStore or KeyStore, ensure that you perform a rolling update of application and agent servers so that the new certificates are considered.

Deploying multiple application images

By using the Helm chart, you can deploy multiple application images as part of a single Helm release.

To deploy multiple application images, use the following appserver.images structure in values.yaml:

appserver:
  replicaCount:
  image:
    tag: 
    pullPolicy:
    names:
      - name:
        probePath:
        tag:
        replicaCount:
        applications:
        - path:
          routePrefix:

To pass an array of image names, use appserver.image.names with optional configuration for specifying:

• paths to expose
• context root to expose
• route prefixes
• tag name
• replica count

For example:

appserver:
  replicaCount: 1
  image:
    tag: 10.0.0.29
    pullPolicy: IfNotPresent
    names:
      - name: om-app
        tag: 10.0.0.29
      - name: om-app-isccs_sbc
      - name: om-app-sma_wsc
        applications:
          - path: '/sma'
          - path: '/wsc'
            routePrefix: webstore
        replicaCount: 2
      - name: om-app-docs
        probePath: '/smcfsdocs/yfscommon/api_javadocs'
        applications:
          - path: '/smcfsdocs'
            routePrefix: 'smcfsdocs'

In this example, 4 deployments are created for 4 images that are listed (om-app, om-app-isccs_sbc, om-app-sma_wsc, and om-app-docs).

The routes and paths that are exposed adheres to the following conventions:

• If the image name is om-app and if you do not define the paths, the application exposes contexts that are defined in appserver.ingress.contextRoots property and defaults the routePrefix to <context>-default. For example, smcfs-default, sbc-default, and so on.
• If the image name is om-app-<modules>, the module names are broken by using a hyphen (-) and underscore (_) characters to form a list of modules. Also, the routePrefix is defaulted to <context>-app-default. For example, for the om-app-isccs_sbc image, the paths exposed are isccs and sbc with routePrefixes isccs-app-default and sbc-app-default, respectively.
• If the image name is provided only with the pathinformation, routePrefix is defaulted to <path>-path-default. For example, if only - path: "/sma" is provided with no routePrefix, the routePrefix is computed to sma-path-default.
• In all of these cases, if you define routePrefix, routes are exposed with the provided prefix. Also, when you explicitly list the paths under applications, the application exposes only the listed paths through the routes. For example, if you specify om-app image with path: "/smcfs", the application exposes only smcfs context root in the route.
• You can generate the API Javadoc image with the name om-app-docs by following the instructions provided in the Generating Javadoc section. To deploy this image by using the Helm chart,
  • Pass om-app-docs under appserver.image.names.
  • Define probePath under om-app-docs as /smcfsdocs/yfscommon/api_javadocs
  • After deploying the om-app-docs image, you can access:
    • The API Javadoc from <routePrefix>.<appserver.ingress.host>/smcfsdocs/yfscommon/api_javadocs/index.html
    • The Core Javadoc from <routePrefix>.<appserver.ingress.host>/smcfsdocs/yfscommon/core_javadocs/index.html
    • The ERD from <routePrefix>.<appserver.ingress.host>/smcfsdocs/yfscommon/ERD/HTML/erd.html

Deploying the REST API service

If a route API (route.openshift.io/v1) exists in cluster, you can use appserver.exposeRestService to create and dedicate the deployment to REST API. If you set the value of appserver.exposeRestService to true, the application creates a new deployment by using the om-app image and the tag provided in appserver.image.tag with a dedicated service and associated route. the Helm chart also prefixes the route with xapirest.

Exposing the deployed applications

The following configurations are provided for exposing the applications based on your deployment platform:

Configuring Kubernetes Ingress

Note: Ingress is enabled by default and the application is exposed as a ClusterIP service.

Configure the following parameters of values.yaml:

• appserver.ingress.host - The 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 of the domain names, for example "example.com" or "test.example.com".

• appserver.ingress.ssl.enabled - Set to true by default as SSL is recommended for production environments.

• appserver.ingress.ssl.secretname - The secret name that contains TLS certificate, which is used for SSL. If this parameter is blank, the Helm chart automatically generates a secret with a self-signed certificate.

  Note: You can use the self-signed certificates only for development purposes.

  For production environments, it is recommended that you obtain a CA certified TLS certificate and manually create a secret by completing the following steps:

  1. Obtain a CA certified TLS certificate for the given appserver.ingress.host in the form of a key and certificate files.

  2. Run the following command to create a secret with the name <Release-name>-ingress-secret by using the key and certificate files:

     oc create secret tls <Release-name>-ingress-secret --key <file containing key> --cert <file containing certificate> -n <namespace>

  3. Set the secret name as the value under appserver.ingress.ssl.secretname.

• appserver.ingress.contextRoots - Ingress by default exposes smcfs, sbc, sma, isccs, wsc, and adminCentercontext roots. If you want to allow any additional context roots, add them to the list.

Configuring Red Hat OpenShift route

Note: If you are using the Red Hat OpenShift cluster, routes are enabled by default and the application is exposed as a ClusterIP service.

Configure the following parameters of values.yaml:

• appserver.ingress.host - The fully qualified domain name of the cluster through which the applications are exposed.

• appserver.ingress.ssl.enabled - Set to true by default as SSL is recommended for production environments.

Note: When SSL is enabled, routes are automatically created with TLS certificates. Also, the intracluster traffic is encrypted by using re-encrypt termination policy. During deployment, the routes are updated with the automatically generated service certificates. For more information about re-encrypt termination policy, see Red Hat OpenShift documentation.

Network policy

A network policy specifies how groups of pods are allowed to communicate with each other and other network endpoints.

The Kubernetes Network Policy resource provides firewall capabilities to pods that are similar to the AWS security groups and programs and the software defined networking infrastructure (OpenShift Default, Flannel, and so on). You can implement the sophisticated network access policies to control the Ingress access to your workload pods.

<Release-name>-network-policy network policy is by default provided that establishes the pod communications with the role as appserver. For example,

---
kind: NetworkPolicy
apiVersion: networking.k8s.io/v1
metadata:
  name: <Release-name>-network-policy
spec:
  podSelector:
    matchLabels:
      role: appserver

You can implement your own network policy. For more information about implementing a network policy, see Kubernetes documentation.

Configuring IBM MQ for agent and integration servers

To configure IBM MQ, complete the following steps:

1. Ensure that the JMS resources that are required for agent and integration servers are configured in IBM MQ and the corresponding .bindings file is generated.

2. Create a ConfigMap to store the IBM MQ bindings. For example, run the following command to create a ConfigMap for the .bindings file.

   oc create configmap <config map name> --from-file=<path_to_.bindings_file> -n <namespace>

3. Specify the ConfigMap in global.mq.bindingConfigName.

After saving your changes in the values.yaml, run the helm upgrade command. For more information about upgrading the Helm chart, see Upgrading the Helm chart.

Configuring the agent and integration servers

Note: Ensure that you have configured IBM MQ.

After you have a deployment ready with the application server running, you can configure the agents and integration servers by logging in to Applications Manager. After completing the configurations, upgrade the release as follows:

To start the agent and integration servers, in values.yaml of the Helm chart, specify the names of agent or integration servers for omserver.servers as illustrated in the following example:

---
servers:
  - group: 'Logical Group 1'
    name:
      - scheduleOrder
      - releaseOrder
    jvmArgs: "-Xms512m\ -Xmx1024m"
    replicaCount: 1
    resources:
      requests:
        memory: 1024Mi
        cpu: 0.5

  - group: 'Logical Group 2'
    name:
      - integrationServer1
      - orderPurge
    jvmArgs: "-Xms512m\ -Xmx1024m"
    replicaCount: 2
    resources:
      requests:
        memory: 1024Mi
        cpu: 0.5

Note: While defining the agent or integration servers, do not use underscore(_) in the server name.

The common parameters that are defined under omserver.commonsuch as jvmArgs, resources, tolerations, and others are applied to agent or integration server that is defined under omserver.servers. For the corresponding agent or integration server, the parameters provided under omserver.servers override the parameters that are defined under omserver.common. The agent servers defined under the same group share the same omserver.common parameters, for example resources. If there is a need to define a different set of omserver.common parameter, you can define multiple groups in omserver.servers[]. For example, if you have to run certain agents with higher CPU and memory requests or replication count, define a new group and appropriately update the resources object.

Deployment strategy

If you are upgrading to a new Helm chart version, you typically consider how to minimize the application downtime (if any), manage errors with minimal impact on users, address failed deployments in a reliable and effective way, and so on. Depending on your business logic, you might want to choose different strategies for your deployments.

Deployment strategy can be used to define how to replace the existing pods with new pods. The supported deployment strategies are Recreate or RollingUpdate. By default, the RollingUpdate deployment strategy is used.

For more information about the deployment strategies, see Kubernetes documentation.

Sample deployment strategies

RollingUpdate

The RollingUpdate deployment strategy replaces the existing pods with the new pods systematically such that there is minimal or no downtime.

...
spec:
  replicas: 2
  strategy:
        type: RollingUpdate
        rollingUpdate:
           maxSurge: 25%
           maxUnavailable: 25%  
  template:
...

• maxUnavailable is an optional field that specifies the maximum number of pods that are unavailable during the update process.

• maxSurge is an optional field that specifies the number of pods that can be created beyond the maximum number of pods defined in replicas.

Recreate

The Recreate deployment strategy kills the existing pods at once and replaces with new pods.

...
spec:
  replicas: 2
  strategy:
        type: Recreate
  template:
...

PodSecurityPolicy Requirements

Note: These instructions are applications only for vanilla Kubernetes platform.

The Helm chart requires a PodSecurityPolicy to be bound to the target namespace prior to installation. You can select either a predefined PodSecurityPolicy or custom PodSecurityPolicy that is shared by your cluster administrator.

Custom PodSecurityPolicy definition:

apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  annotations:
    kubernetes.io/description: 'This policy allows pods to run with
      any UID and GID, but preventing access to the host.'
  name: ibm-oms-anyuid-psp
spec:
  allowPrivilegeEscalation: true
  fsGroup:
    rule: RunAsAny
  requiredDropCapabilities:
    - MKNOD
  allowedCapabilities:
    - SETPCAP
    - AUDIT_WRITE
    - CHOWN
    - NET_RAW
    - DAC_OVERRIDE
    - FOWNER
    - FSETID
    - KILL
    - SETUID
    - SETGID
    - NET_BIND_SERVICE
    - SYS_CHROOT
    - SETFCAP
  runAsUser:
    rule: RunAsAny
  seLinux:
    rule: RunAsAny
  supplementalGroups:
    rule: RunAsAny
  volumes:
    - configMap
    - emptyDir
    - projected
    - secret
    - downwardAPI
    - persistentVolumeClaim
  forbiddenSysctls:
    - '*'

To create a custom PodSecurityPolicy, create a yaml file with the custom PodSecurityPolicy definition and run the following command:

oc create -f <custom_psp.yaml>

Sample ClusterRole and RoleBinding definitions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
  name: ibm-oms-anyuid-clusterrole
rules:
  - apiGroups:
      - extensions
    resourceNames:
      - ibm-oms-anyuid-psp
    resources:
      - podsecuritypolicies
    verbs:
      - use

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ibm-oms-anyuid-clusterrole-rolebinding
  namespace: <namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: ibm-oms-anyuid-clusterrole
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: system:serviceaccounts:<namespace>

Replace the <namespace> definition with the namespace of the target environment.

To create a custom ClusterRole and RoleBinding, create a yaml file with the custom ClusterRole and RoleBinding definition and run the following command:

oc create -f <custom_psp_role_and_binding.yaml>

Red Hat OpenShift SecurityContextConstraints Requirements

The Helm chart is verified with the predefined SecurityContextConstraints named anyuid. Alternatively, you can use a custom SecurityContextConstraints. Ensure that you bind the SecurityContextConstraints resource to the target namespace prior to installation.

SecurityContextConstraints Requirements

Custom SecurityContextConstraints definition:

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  annotations:
  name: ibm-oms-scc
allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
allowPrivilegedContainer: false
allowedCapabilities: []
allowedFlexVolumes: []
defaultAddCapabilities: []
fsGroup:
  type: MustRunAs
  ranges:
    - max: 65535
      min: 1
readOnlyRootFilesystem: false
requiredDropCapabilities:
  - ALL
runAsUser:
  type: MustRunAsRange
seccompProfiles:
  - docker/default
seLinuxContext:
  type: RunAsAny
supplementalGroups:
  type: MustRunAs
  ranges:
    - max: 65535
      min: 1
volumes:
  - configMap
  - downwardAPI
  - emptyDir
  - persistentVolumeClaim
  - projected
  - secret
priority: 0

To create a custom SecurityContextConstraints, create a yaml file with the custom SecurityContextConstraints definition and run the following command:

oc create -f <custom-scc.yaml>

Installing the chart

In values.yaml, set the values of global.license and global.licenseStoreCallCenter to True along with the required chart parameters.

For detailed instructions on how to install the application and agent servers, see Deploying the application and agent servers.

Note: Depending on the capacity of Kubernetes worker node and database connectivity, the complete deployment process can take approximately 2 to 3 minutes on a preloaded database, and 20 to 30 minutes on a fresh database.

When you check the deployment status, you can see the following values:

• Running: Indicates that the container has started.
• Init: 0/1: Indicates that the primary container will start only after the init container starts.

You can also see the following values in readiness state:

• 0/1: Indicates that the container has started, but the application is not yet ready to use.
• 1/1: Indicates that the application is ready to use.

Run the following command to verify that the log file does not contain any errors:

# Run the following command to retrieve the list of pods in the deployment namespace and identify the application server pod.
oc get pods -n <namespace>

# Run the following command to view the list of application server pod:
oc logs -f -n <namespace> <pod_name>

Air gap Installation

You can install certified containers in an air gap environment where your Kubernetes cluster does not have access to the internet. Therefore, it is important to properly configure and install the certified containers in such an environment.

Downloading Sterling Order Management Software case bundle

You can download the Sterling Order Management Software case bundle and the Helm chart from the remote repositories to your local machine, which will eventually be used for offline installation by running the following command:

  cloudctl case save                                \
    --case <URL containing the CASE file to parse.> \
    --outputdir </path/to/output/dir> 

For additional help on cloudctl case save, run cloudctl case save -h.

Setting credentials to pull or push certified container images

To set up the credentials for downloading the certified container images from IBM Entitled Registry to your local registry, run the appropriate command.

• For local registry without authentication

    # Set the credentials to use for source registry
    cloudctl case launch              \
    --case </path/to/downloaded/case> \
    --inventory ibmOmsProProd         \
    --action configure-creds-airgap   \
    --args "--registry $SOURCE_REGISTRY --user $SOURCE_REGISTRY_USER --pass $SOURCE_REGISTRY_PASS"

• For local registry with authentication

    # Set the credentials for the target registry (your local registry)
    cloudctl case launch              \
    --case </path/to/downloaded/case> \
    --inventory ibmOmsProProd         \
    --action configure-creds-airgap   \
    --args "--registry $TARGET_REGISTRY --user $TARGET_REGISTRY_USER --pass $TARGET_REGISTRY_PASS"

Mirroring the certified container images

To mirror the certified container images and configure your cluster by using the provided credentials, run the following command:

  cloudctl case launch              \
  --case </path/to/downloaded/case> \
  --inventory ibmOmsProProd         \ 
  --action mirror-images            \
  --args "--registry <your local registry> --inputDir </path/to/directory/that/stores/the/case>"

The certified container images are pulled from the source registry to your local registry that you can use for offline installation.

Installing the Helm chart in an air gap environment

Before you begin, ensure that you review and complete the prerequisites.

To install the Helm chart, run the following command:

  cloudctl case launch                    \
      --case </path/to/downloaded/case>   \
      --namespace <NAME_SPACE>            \
      --inventory ibmOmsProProd           \
      --action install                    \
      --args "--values </path/to/values.yaml> --releaseName <release-name> --chart </path/to/chart>"
  
  # --values: refers to the path of values.yaml file.
  # --releaseName: refers to the name of the release.
  # --chart: refers to the path of downloaded chart.

Uninstalling the Helm chart in an air gap environment

To uninstall the Helm chart, run the following command:

  cloudctl case launch                    \
      --case </path/to/downloaded/case>   \
      --namespace <NAME_SPACE>            \
      --inventory ibmOmsProProd           \
      --action uninstall                  \
      --args "--releaseName <release-name>"
  
  # --releaseName: refers to the name of the release.

Configuring affinity and tolerations

helm upgrade <release-name> -f values.yaml ./ibm-oms-pro-prod --timeout 3600s

helm rollback <release-name> <revision>

 helm uninstall <release-name>