Configuration and Setup for Fabric on OpenShift

Extract Fabric Image Tars

Quantum Fabric images will no longer be available to the public. Please ensure to download the tar files and extract the images.

For further information, refer to Extracting Images from tar files and pushing into private registry.

Configure the properties file

  1. Extract the provided FabricOpenShift.zip file. The OpenShift Fabric artifacts generation zip is organized as follows:
    • lib: Contains dependent jars and helper bash functions.
    • templates: Contains the following files
      • fabric-app-tmpl.yml: YAML template for Fabric deployments
      • fabric-db-tmpl.yml: YAML template for Fabric Database schema creation
      • fabric-services.yml: YAML template for Fabric services
    • config.properties: Contains inputs that you must configure for the installation
    • generate-kube-artifacts.sh: A user script that is used to generate required artifacts
    • helm_charts [V9SP6 or later]: Contains the following packages, which can be used to deploy Quantum Fabric
      • fabric_app: Helm charts that are used to deploy Fabric
      • fabric_db: Helm charts that are used to create a database and insert tables into the Fabric database server

    As a result of executing the generate-kube-artifacts.sh script, the artifacts folder is created containing YAML configuration files. The YAML configuration files are generated based on the config.properties file, and they must be applied later to deploy Quantum Fabric on the OpenShift cluster.

  2. Update the config.properties file with relevant information.

For more information about the properties, refer to the following section.

  1. INSTALL_ENV_NAME: The install environment name must be a in string value in lowercase. For example: dev, qa, prod, or eastusprod.
  2. KONY_FABRIC_BUILD_VER: The build version of Fabric that you want to install. While upgrading, this specifies the build version to which you want to upgrade.
  3. KONY_FABRIC_BUILD_TYPE: The type of Fabric environment that must be created. For production environments, the value must be PRODUCTION. For dev, QA, or other non-production environments, the value must be NON-PRODUCTION.

  4. Install Components: The following properties must be set to either Y (yes) or N (no). Make sure that at least one of the following input properties must be set to Y. If ALL_COMPONENTS_ENABLED is set to Y, the rest of the inputs can be left empty.

    • ALL_COMPONENTS_ENABLED
    • INTEGRATION_ENABLED
    • IDENTITY_ENABLED
    • MESSAGING_ENABLED
    • CONSOLE_ENABLED
    • APIPORTAL_ENABLED
  5. Application Server Details
    • SERVER_DOMAIN_NAME: The Domain Name for Quantum Fabric. This value should be the hostname of the LoadBalancer. For example: abc.companyname (DNS name).
    • COM_PROTOCOL: The communication protocol for Quantum Fabric. This value can be either http or https.
    • PASSTHROUGH_ENABLED: Enables HTTPS passthrough mode while creating routes from the OpenShift Console.
    • KEYSTORE_FILE: The path to an existing keystore file, which must be a valid jks file. This parameter can be left empty for HTTP and HTTPS without passthrough.
    • KEYSTORE_FILE_PASS: The password for the jks file that is specified in the KEYSTORE_FILE parameter.
    • KEYSTORE_FILE_PASS_SECRET_KEY: The secret key for the Keystore password. This parameter is required if you are using an encrypted Keystore password.
  6. Database Details
    • DB_TYPE - The Database type that is used to host Quantum Fabric. The possible values are:
      • For MySQL DB server: mysql
      • For Azure MSSQL or SQL Server: sqlserver
      • For Oracle DB server: oracle
    • DB_HOST - The Database Server hostname that is used to connect to the Database Server.
    • DB_PORT– The Port Number that is used to connect to the Database Server. This can be empty for cloud manage service.
    • DB_USER - The Database Username that is used to connect to the Database Server.
    • DB_PASS - The Database Password that is used to connect to the Database Server.
    • DB_PASS_SECRET_KEY - This is the decryption key for the database password, which is required only if you are using an encrypted password.

      • IMPORTANT: If you are using an encrypted password, use the values that you receive from the encryption utility. For more information, refer to Encrypting the Database Password.

    • DB_PREFIX – The Database server prefix for Quantum Fabric Schemas/Databases.
    • DB_SUFFIX – The Database server suffix for Quantum Fabric Schemas/Databases.
      • NOTE:
      • Database Prefix and Suffix are optional inputs.
      • In case of upgrade, ensure that the values of the Database Prefix and Suffix that you provide are the same as you had provided during the initial installation.
    • If DB_TYPE is set as oracle, the following String values must be provided:
      • DB_DATA_TS: Database Data tablespace name.
      • DB_INDEX_TS: Database Index tablespace name.
      • DB_LOB_TS: Database LOB tablespace name.
      • DB_SERVICE: Database service name.
    • USE_EXISTING_DB: If you want to use an existing database from a previous Quantum Fabric instance, set this property to Y. Otherwise, set the property to N.

      If you want to use an existing database, you must provide the location of the previously installed artifacts (the location should contain the upgrade.properties file).

      For example: PREVIOUS_INSTALL_LOCATION = /C/kony-fabric-containers-onprem/kubernetes.

  7. Time Zone: The time zone must be set to maintain consistency between the application server and the database. This section contains the following property:
    • TIME_ZONE: The country code of the time zone from the tz database. For more information, refer to List of tz database time zones. The default value is UTC.
  8. Readiness and Liveness Probes Details: The readiness and liveness probes are used to check the status of a container. The probes can check whether a container is ready to receive traffic, or if a container can be stopped and restarted. The following properties specify the initial delay (in seconds) of the probes for the Fabric components:
    • IDENTITY_READINESS_INIT_DELAY
    • IDENTITY_LIVENESS_INIT_DELAY
    • CONSOLE_READINESS_INIT_DELAY
    • CONSOLE_LIVENESS_INIT_DELAY
    • INTEGRATION_READINESS_INIT_DELAY
    • INTEGRATION_LIVENESS_INIT_DELAY
    • ENGAGEMENT_READINESS_INIT_DELAY
    • ENGAGEMENT_LIVENESS_INIT_DELAY
  9. Minimum and Maximum RAM percentage Details: These properties specify the minimum and maximum RAM (in percentage) that a Fabric component can use on the server. For example: CONSOLE_MAX_RAM_PERCENTAGE="80". This section contains the following properties:
    • CONSOLE_MIN_RAM_PERCENTAGE
    • CONSOLE_MAX_RAM_PERCENTAGE
    • ENGAGEMENT_MIN_RAM_PERCENTAGE
    • ENGAGEMENT_MAX_RAM_PERCENTAGE
    • IDENTITY_MIN_RAM_PERCENTAGE
    • IDENTITY_MAX_RAM_PERCENTAGE
    • INTEGRATION_MIN_RAM_PERCENTAGE
    • INTEGRATION_MAX_RAM_PERCENTAGE
    • APIPORTAL_MIN_RAM_PERCENTAGE
    • APIPORTAL_MAX_RAM_PERCENTAGE
  10. Container resource limits for memory and CPU: The resource limits are used to restrict resource usage for the Fabric components. The values must be provided in gigabytes (G) or megabytes (m). For example: CONSOLE_RESOURCE_REQUESTS_CPU="300m". This section contains the following properties:
    • IDENTITY_RESOURCE_MEMORY_LIMIT
    • IDENTITY_RESOURCE_REQUESTS_MEMORY
    • IDENTITY_RESOURCE_REQUESTS_CPU
    • CONSOLE_RESOURCE_MEMORY_LIMIT
    • CONSOLE_RESOURCE_REQUESTS_MEMORY
    • CONSOLE_RESOURCE_REQUESTS_CPU
    • APIPORTAL_RESOURCE_MEMORY_LIMIT
    • APIPORTAL_RESOURCE_REQUESTS_MEMORY
    • APIPORTAL_RESOURCE_REQUESTS_CPU
    • INTEGRATION_RESOURCE_MEMORY_LIMIT
    • INTEGRATION_RESOURCE_REQUESTS_MEMORY
    • INTEGRATION_RESOURCE_REQUESTS_CPU
    • ENGAGEMENT_RESOURCE_MEMORY_LIMIT
    • ENGAGEMENT_RESOURCE_REQUESTS_MEMORY
    • ENGAGEMENT_RESOURCE_REQUESTS_CPU
  11. Custom JAVA_OPTS Details: The custom JAVA_OPTS properties specify Java options that must be configured for the Fabric components on the application server. The following properties can be used to configure additional Java options for the Fabric components:
    • CONSOLE_CUSTOM_JAVA_OPTS
    • ENGAGEMENT_CUSTOM_JAVA_OPTS
    • IDENTITY_CUSTOM_JAVA_OPTS
    • INTEGRATION_CUSTOM_JAVA_OPTS
    • APIPORTAL_CUSTOM_JAVA_OPTS
  12. Number of instances to be deployed for each component: These properties specify the number of instances that must be deployed for every component. This section contains the following properties:
    • IDENTITY_REPLICAS
    • CONSOLE_REPLICAS
    • APIPORTAL_REPLICAS
    • INTEGRATION_REPLICAS
    • ENGAGEMENT_REPLICAS

Deploy Fabric on OpenShift

After you update the config.properties file, follow these steps to deploy Quantum Fabric on OpenShift:

  1. Create a project from the oc command line or from the OpenShift console.

    For example:
    oc new-project fabrictest
  2. Generate the Fabric services by running the following command:
    ./generate-kube-artifacts.sh config.properties svcs


    To generate the services configuration, you only need to fill the INSTALL_ENV_NAME property and the ## Install Components ### section in the config.properties file.



    IMPORTANT: For V9SP6 (or later), you can use Helm charts to install and deploy Quantum Fabric on OpenShift. For more information, refer to Deploy Fabric using Helm Charts.

  3. Create the services by running the following command:
    oc apply -f ./artifacts/<INSTALL_ENV_NAME>/fabric-services.yml
oc apply -f ./artifacts/<INSTALL_ENV_NAME>/fabric-db-secret.yml
oc apply -f ./artifacts/<INSTALL_ENV_NAME>/fabric-app-secret.yml


    The <INSTALL_ENV_NAME> is the install environment name input as provided in the config.properties file.
  4. Follow either of the following steps to expose Fabric publicly.
    • For development or proof of concept, using HTTP (non-SSL) routes and OpenShift generated hostnames is a quick way to get started.

      Create the routes from the OpenShift console or by running the following command:




      oc expose service/<fabric-service> --path=<context_path> --name=<route_name>


      For <fabric-service> and <context-path>, refer to Context paths for Fabric components. The <fabric-service> is one of the Fabric services that were created earlier.



      Executing the oc expose service command assigns a unique OpenShift generated host name to the route that is created. The assigned host name can be identified by executing the following command:
      oc describe route <fabric-route>


    • For production, Temenos recommends that you use a custom domain name and terminate your SSL connection at the public load balancer. You need to obtain a custom domain name from a DNS provider, and SSL certificate and keys from a certificate authority. For more information, refer to Exposing apps with routes in OpenShift 4.

      NOTE: To configure a Passthrough route type, refer to Configure Passthrough Routes.
      The Reencrypt route type is not supported.


      For a sample configuration, refer to the following screenshot.

Configure Passthrough Routes

To configure the passthrough, you need to create a secure route for the Fabric component. To do so, follow these steps:

  1. On the Create Route page, configure details for the Fabric component.

    NOTE: The details in the screenshot are specific to the API Portal component and use a specific domain. Make sure that you change the details for other routes.
    For more information, refer to Context paths and Service Names for Fabric components.

  2. Under Security, select the Secure Route check box.
  3. From the TLS termination list, select Passthrough.
  4. Provide the required values in the Application Server Details section of the config.properties file.

Context paths and Service Names for Fabric components

NOTE:
  • Make sure that you use the same host name for all the Fabric routes that you plan to create.
  • The Fabric components for accounts, mfconsole, and workspace share the same deployment and service. Therefore, while creating the routes, make sure that you map these routes to the same service: kony-fabric-console.

Make sure that the format of the route location is as follows:

<scheme>://<common_domain_name>/<fabric_context_path>

For example, https://quantum-fabric.domain/mfconsole

Reference table for the mapping of paths and service names:

Fabric Component Fabric Service Name Context Path
mfconsole kony-fabric-console /mfconsole
workspace kony-fabric-console /workspace
accounts kony-fabric-console /accounts
Identity kony-fabric-identity /authService
Integration kony-fabric-integration /admin
Services kony-fabric-integration /services
apps kony-fabric-integration /apps
Engagement kony-fabric-engagement /kpns
ApiPortal kony-fabric-apiportal /apiportal

Additional Resources

You can also use automatic certificate management for your cluster. To automate with OpenShift routes, you can use the open-source project openshift-acme. To automate with Kubernetes Ingress, you can use cert-manager.

Alternatively, if you are using a managed OpenShift service, the public cloud vendor might offer a key manager service, such as Certificate Manager on IBM Cloud.

Deploy Kubernetes artifacts

After deploying Fabric and creating routes for the components, follow these steps to deploy the remaining Fabric Kubernetes artifacts:

  1. In the config.properties file, in the SERVER_DOMAIN_NAME field, add the custom host name or the host name that was generated while creating the routes.
  2. In the config.properties file, update the Database Details section with appropriate information.
  3. Generate the Fabric application and database configuration files by executing the following command.
    ./generate-kube-artifacts.sh config.properties
     
  4. Edit the privileged security context by running the following command, and then add the service account that corresponds to your project.
    oc edit scc privileged
     
    For example: In the following screenshot, fabrictest is the project and default is the service account that is being used.

    NOTE: Adding the service account to the privileged security context is only needed to create the database schema in the following step. After the execution of the Fabric database job is completed, you can remove the service account from the privileged security context.

  5. Create the database schema by executing the following command.


    oc apply -f ./artifacts/<INSTALL_ENV_NAME>/fabric-db.yml

    The <INSTALL_ENV_NAME> is the name of the install environment that you provided in the config.properties file.
  6. After the database schema creation is completed, verify the completion by executing the following command.
    oc get jobs

  7. Create the Fabric deployments by executing the following command.
    

oc apply -f ./artifacts/<INSTALL_ENV_NAME>/fabric-app.yml

    Based on the default replica count that is provided in the config.properties file, one deployment of every Fabric component is created. Based on your requirements, the Fabric deployments can be scaled up from the OpenShift Console, or from the command line.

Deploy Fabric using Helm Charts

To deploy Fabric by using Helm charts, make sure that you have installed Helm, and then follow these steps:

  1. Open a terminal console and navigate to the extracted folder.
  2. Generate the Fabric services by running the following command:


    ./generate-kube-artifacts.sh config.properties svcs

    To generate the services configuration, you only need to fill the INSTALL_ENV_NAME property and the ## Install Components ### section in the config.properties file.
  3. Navigate to the helm_charts folder by executing the following command.
    cd helm_charts
  4. Create the fabricdb and fabricapp Helm charts by executing the following commands.
    helm package fabric_db/
    helm package fabric_app/
  5. Install the fabricdb Helm chart by executing the following command.
    helm install fabricdb  fabric-db-<Version>.tgz
  6. Install the fabricapp Helm chart by executing the following command.
    helm install fabricapp  fabric-app-<Version>.tgz
IMPORTANT:
  • Make sure that you generate the artifacts (generate-artifacts.sh) before creating the Helm charts.
  • Make sure that the fabricdb Helm chart installation is complete before installing the fabricapp Helm chart.

Launch the Fabric Console

  1. After all the Fabric services are up and running, launch the Fabric console by using the following URL.
    <scheme>://<fabric-hostname>/mfconsole

    The <scheme> is http or https based on your OpenShift cluster. The <fabric-hostname> is the custom host name or the host name that was generated while creating routes for the Fabric components.
  2. After you launch the Fabric Console, create an administrator account by providing the appropriate details.

After you create an administrator account, you can sign-in to the Fabric Console by using the credentials that you provided.

Logging Considerations

All Fabric application logs will be streamed to the Standard Output (stdout). You can view the logs by using the kubectl logs command. For more details refer to Interacting with running Pods.