Jump to: navigation, search

Deploying GCXI using OpenShift

Beginning with release 9.0.016, Genesys CX Insights supports deployment using Red Hat OpenShift.

Important
Beginning with release 9.0.016, Genesys CX Insights supports deployment using Red Hat OpenShift as part of Genesys Engage Private Cloud Early Adopter Program.
Please note: Genesys plans to introduce support for OpenShift on the Genesys Engage Private Cloud platform in 2021, at which time Genesys will further extend our existing support of OpenShift in GCXI. Until that time, GCXI supports the basic installation of containers on customer-operated Openshift clusters. Customers own the responsibility of deploying and maintaining OpenShift clusters, and Genesys provides support only for issues related to GCXI containers.

This is an example scenario — This page provides a high-level outline, illustrating one scenario to help you visualize the overall process. Genesys does not provide support for OpenShift or other third party products, so you must have knowledge of OpenShift and other products to complete this type of installation. GCXI is known to work with OpenShift Cluster 4.5.16, which is described on this page.

Prerequisites for deploying using OpenShift

Before you begin, ensure that:

  • Your OpenShift cluster is configured and running in a suitable environment, with nodes in the Ready state.
  • OpenShift client and Helm-3 are installed on the host where the deployment will run.
  • The images gcxi and gcxi_control are loaded and tagged on each OpenShift worker node.
  • On each worker node, values are set for kernel.sem, vm.max_map_count, as required by MicroStrategy. For example: 
    echo "kernel.sem = 250 1024000 250 4096" >> /etc/sysctl.conf
echo "vm.max_map_count = 5242880" >> /etc/sysctl.conf
sysctl -p

Deploying GCXI with OpenShift

The following procedures describe example steps to deploy GCXI with OpenShift. The exact steps required will vary for your environment.

Procedure: 1. Configuring Ingress

Purpose: To make GCXI accessible from outside the cluster, a special entity called Ingress must be configured. You can find detailed instructions to deploy NGINX Ingress Controller here. The following steps provide an example only.

Steps

  1. Log in to the control plane node.
  2. Execute the following commands to add the Helm repository: 
    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo add stable https://charts.helm.sh/stable
helm repo update
  3. Execute the following commands to install the NGINX chart: 
    helm install --debug --set controller.kind=DaemonSet --set controller.hostNetwork=true --set tcp.34952=gcxi/gcxi:mstr --set tcp.8180=gcxi/gcxi:metrics gcxi-nginx ingress-nginx/ingress-nginx --create-namespace -n ingress-nginx
  4. Execute the following commands to verify that the NGINX chart is successfully installed: 
    helm list -n ingress-nginx
  5. Execute the following commands to verify that NGINX pods are successfully deployed on all cluster nodes: 
    kubectl get pod -n ingress-nginx

Procedure: 2. Preconfiguration steps

Purpose: Prepare the environment for deployment.

Steps

  1. Ensure that the GCXI project has been created. (Writer's Note: Do we need to add steps or more explanation? )
  2. Ensure that four NFS PersistentVolume (PV) have been created, and four NFS PersistentVolumeClaim (PBC) with the following names have been created in the gcxi workspace:
    • gcxi-backup-pvc
    • gcxi-log-pvc
    • gcxi-postgres-pvc
    • gcxi-share-pvc
    Writer's Note: Should we add more detail to the preceding steps? Is this similar to what is described in Deploying GCXI using Helm?
  3. To configure OpenShift Security Context Constraints to allow pods to run under non-root user with UID=500, configure the following users inside the GCXI container: 
    root:root (0:0)
genesys:genesys (500:500)
    You can use either of these users to run the container. Running it with any other user causes an error such as:
    "500 is not an allowed group spec.containers[0].securityContext.securityContext.runAsUser: Invalid value: 500: must be in the ranges: [1000570000, 1000579999]]"
    Genesys recommends the preceding method all production environments. For test environments, execute the following command if you wish to run pods as any user:
    oc adm policy add-scc-to-user anyuid -z default

Procedure: 3. Prepare

Purpose: Prepare the environment, and gather files needed for deployment.

Steps

  1. On the Control plane node, create a folder: helm.
  2. Download the tar.gz archive of Helm charts into helm folder, and extract the archive in a subfolder called helm/gcxi.
  3. Delete the following helm templates from the template subfolder &mdash they are not needed, since as PVCs are already created in our environment:
    • gcxi-backup-pvc.yaml
    • gcxi-log-pvc.yaml
    • gcxi-postgres-pvc.yaml
    • gcxi-share-pvc.yaml
  4. View the file helm/gcxi/Chart.yaml, and ensure that the appVersion is set to the desired GCXI version.
  5. Open the file helm/gcxi/values.yaml, and follow the instructions it provides to guide you in creating a new file, values-test.yaml with appropriate settings. Save the new file in the helm folder.
    For example, the following content in the values-test.yaml file is appropriate for a simple deployment using PostgreSQL inside the container, and PersistentVolumes of the type local. Create content in the values-test.yaml file that is appropriate for your environment:
    gcxi:
  env:
    GCXI_GIM_DB:
      DSNDEF: DSN_NAME=GCXI_GIM_DB;DB_TYPE=POSTGRESQL;DB_TYPE_EX=PostgreSQL;HOST=gim_db_host;PORT=5432;DB_NAME=gim_login;LOGIN=;PASSWORD=;DRV_TYPE=JDBC;GCXI_QENGINE=ON
      LOGIN: gim_login
      PASSWORD: gim_password

    IWD_DB:
      DSNDEF: DSN_NAME=IWD_DB;DB_TYPE=POSTGRESQL;DB_TYPE_EX=PostgreSQL;HOST=iwd_db_host;PORT=5432;DB_NAME=dm_gcxi;LOGIN=;PASSWORD=;DRV_TYPE=JDBC;GCXI_QENGINE=ON
      LOGIN: iwd_login
      PASSWORD: iwd_password

    PGDATA: /var/lib/postgresql/data/mydata4

  deployment:
    deployPostgres: true
    deployLocalPV: false
    useDynamicLogPV: false
    useHostPathLogInitContainer: true
    hostIPC: false

  imagePullPolicy:
    worker: IfNotPresent
    control: IfNotPresent
  
  replicas:
    worker: 2

  images:
    postgres:
      version: 11

Procedure: 4. Deploy


Steps

  1. Execute the following command to log in to OpenShift cluster from the host where you will run deployment. 
    oc login --token <token> --server <url of api server>
  2. Execute the following command to make the GCXI project the default: 
    oc project gcxi
  3. Execute the following commands (Writer's Note: Can we explain what is accomplished by this step? And, is this the right place for it in the sequence?: 
    chown -R 500 /genesys/gcxi/backup
chown -R 500 /genesys/gcxi/shared
chown -R 500 /mnt/log/gcxi
chown -R 500 /genesys/gcxi/data
  4. For debug purposes, execute the following command to render templates without installing: 
    helm template --debug -f values-test.yaml gcxi-helm gcxi/
    Kubernetes descriptors are displayed. The values you see generated from Helm templates, and based on settings from values.yaml and values-test.yaml. Ensure no errors are displayed; you will later apply this configuration to your Kubernetes cluster.
  5. Execute the following command to deploy GCXI: 
    helm install --debug --namespace gcxi --create-namespace -f values-test.yaml gcxi-helm gcxi/
    This process takes several minutes. Wait until all objects are created and allocated, and the Kubernetes descriptors applied to the environment appear.
  6. To check the installed Helm release, execute the following command: 
    helm list –all-namespaces
  7. To check the Operating System status, execute the following command: 
    os status
  8. To check GCXI OpenShift objects created by Helm, execute the following command: 
    oc get all

Maintenance Procedures

This section provides additional procedures, such as troubleshooting steps.

Procedure: Troubleshooting

Purpose: Use the instructions in this section only if you encounter errors or other difficulties. Problems with the deployment are most often associated with the following three kinds of objects:

  • PVs
  • PVCs
  • pods

Steps

  1. To list the objects that might cause problems, execute the following commands: 
    kubectl get pv -o wide
    kubectl get pvc -o wide
    kubectl get po -o wide
  2. Examine the output from each get command.
  3. If any of the objects have a non-ready state (for example, Unbound (PVCs only), Pending, or CrashLoop) execute the following command to inspect the object more closely using oc describe: 
    kubectl describe <type> <name>
    For example:
    describe pod gcxi-0
    kubectl describe po gcxi-0
  4. In the describe output, inspect the section Events.

Procedure: Uninstall GCXI

Purpose: To remove GCXI

Steps

  1. To remove GCXI, execute the following command: 
    helm uninstall gcxi-oc
Comments or questions about this documentation? Contact us for support!