Deploying Red Hat Process Automation Manager on Red Hat OpenShift Container Platform

Red Hat Process Automation Manager 7.10

Abstract

This document describes how to deploy a variety of Red Hat Process Automation Manager environments on Red Hat OpenShift Container Platform, such as an authoring environment, a managed server environment, an immutable server environment, and other supported environment options.

Preface

As a developer or system administrator, you can deploy a variety of Red Hat Process Automation Manager environments on Red Hat OpenShift Container Platform, such as an authoring environment, a managed server environment, an immutable server environment, and other supported environment options.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Part I. Deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 4 using Operators

As a system engineer, you can deploy a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 4 to provide an infrastructure to develop or execute services, process applications, and other business assets. You can use OpenShift Operators to deploy the environment defined in a structured YAML file and to maintain and modify this environment as necessary.

Note

For instructions about deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 3 using templates, see Deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 3 using templates.

Prerequisites

  • A Red Hat OpenShift Container Platform 4 environment is available. For the exact versions of Red Hat OpenShift Container Platform that the current release supports, see Red Hat Process Automation Manager 7 Supported Configurations.
  • The OpenShift project for the deployment is created.
  • You are logged into the project using the OpenShift web console.
  • The following resources are available on the OpenShift cluster. Depending on the application load, higher resource allocation might be necessary for acceptable performance.

    • For an authoring environment, 4 gigabytes of memory and 2 virtual CPU cores for the Business Central pod. In a high-availability deployment, these resources are required for each replica and two replicas are created by default.
    • For a production or immutable environment, 2 gigabytes of memory and 1 virtual CPU core for each replica of the Business Central Monitoring pod.
    • 2 gigabytes of memory and 1 virtual CPU core for each replica of each KIE Server pod.
    • 1 gigabyte of memory and half a virtual CPU core for each replica of a Smart Router pod.
    • In a high-availability authoring deployment, additional resources according to the configured defaults are required for the MySQL, Red Hat AMQ, and Red Hat Data Grid pods.

      Note

      The default values for MaxMetaspaceSize are:

      • Business Central images: 1024m
      • KIE Server images: 512m
      • For other images: 256m
  • Dynamic persistent volume (PV) provisioning is enabled. Alternatively, if dynamic PV provisioning is not enabled, enough persistent volumes must be available. By default, the deployed components require the following PV sizes:

    • Each KIE Server deployment by default requires one 1Gi PV for the database. You can change the database PV size. You can deploy multiple KIE Servers; each requires a separate database PV. This requirement does not apply if you use an external database server.
    • By default, Business Central requires one 1Gi PV. You can change the PV size for Business Central persistent storage.
    • Business Central Monitoring requires one 64Mi PV.
    • Smart Router requires one 64Mi PV.
  • If you intend to deploy a high-availability authoring environment or any environment with Business Central Monitoring pods, your OpenShift environment supports persistent volumes with ReadWriteMany mode. If your environment does not support this mode, you can use NFS to provision the volumes. For information about access mode support in OpenShift public and dedicated clouds, see Access Modes in Red Hat OpenShift Container Platform documentation.

Chapter 1. Overview of Red Hat Process Automation Manager on Red Hat OpenShift Container Platform

You can deploy Red Hat Process Automation Manager into a Red Hat OpenShift Container Platform environment.

In this solution, components of Red Hat Process Automation Manager are deployed as separate OpenShift pods. You can scale each of the pods up and down individually to provide as few or as many containers as required for a particular component. You can use standard OpenShift methods to manage the pods and balance the load.

The following key components of Red Hat Process Automation Manager are available on OpenShift:

  • KIE Server, also known as Execution Server, is the infrastructure element that runs decision services, process applications, and other deployable assets (collectively referred to as services) . All logic of the services runs on execution servers.

    A database server is normally required for KIE Server. You can provide a database server in another OpenShift pod or configure an execution server on OpenShift to use any other database server. Alternatively, KIE Server can use an H2 database; in this case, you cannot scale the pod.

    In some templates, you can scale up a KIE Server pod to provide as many copies as required, running on the same host or different hosts. As you scale a pod up or down, all of its copies use the same database server and run the same services. OpenShift provides load balancing and a request can be handled by any of the pods.

    You can deploy a separate KIE Server pod to run a different group of services. That pod can also be scaled up or down. You can have as many separate replicated KIE Server pods as required.

  • Business Central is a web-based interactive environment used for authoring services. It also provides a management and monitoring console. You can use Business Central to develop services and deploy them to KIE Servers. You can also use Business Central to monitor the execution of processes.

    Business Central is a centralized application. However, you can configure it for high availability, where multiple pods run and share the same data.

    Business Central includes a Git repository that holds the source for the services that you develop on it. It also includes a built-in Maven repository. Depending on configuration, Business Central can place the compiled services (KJAR files) into the built-in Maven repository or (if configured) into an external Maven repository.

  • Business Central Monitoring is a web-based management and monitoring console. It can manage the deployment of services to KIE Servers and provide monitoring information, but does not include authoring capabilities. You can use this component to manage staging and production environments.
  • Smart Router is an optional layer between KIE Servers and other components that interact with them. When your environment includes many services running on different KIE Servers, Smart Router provides a single endpoint to all client applications. A client application can make a REST API call that requires any service. Smart Router automatically calls the KIE Server that can process a particular request.

You can arrange these and other components into various environment configurations within OpenShift.

1.1. Architecture of an authoring environment

In Red Hat Process Automation Manager, the Business Central component provides a web-based interactive user interface for authoring services. The KIE Server component runs the services.

The KIE Server uses a database server to store the state of process services.

You can also use Business Central to deploy services onto a KIE Server. You can use several KIE Servers to run different services and control the servers from the same Business Central.

Single authoring environment

In a single authoring environment, only one instance of Business Central is running. Multiple users can access its web interface at the same time, however the performance can be limited and there is no failover capability.

Business Central includes a built-in Maven repository that stores the built versions of the services that you develop (KJAR files/artifacts). You can use your continuous integration and continuous deployment (CICD) tools to retrieve these artifacts from the repository and move them as necessary.

Business Central saves the source code in a built-in Git repository, stored in the .niogit directory. It uses a built-in indexing mechanism to index the assets in your services.

Business Central uses persistent storage for the Maven repository and for the Git repository.

A single authoring environment, by default, includes one KIE Server. This KIE Server uses a built-in H2 database engine to store the state of process services.

A single authoring environment can use the controller strategy. Business Central includes the Controller, a component that can manage KIE Servers. When you configure a KIE Server to connect to Business Central, the KIE Server uses a REST API to connect to the Controller. This connection opens a persistent WebSocket. In an OpenShift deployment that uses the controller strategy, each KIE Server is initially configured to connect to the Business Central Controller.

When you use the Business Central user interface to deploy or manage a service on the KIE Server, the KIE Server receives the request through the Controller connection WebSocket. To deploy a service, the KIE Server requests the necessary artifact from the Maven repository that is a part of Business Central.

Client applications use a REST API to use services that run on the KIE Server.

Figure 1.1. Architecture diagram for a single authoring environment

Clustering KIE Servers and using multiple KIE Servers

You can scale a KIE Server pod to run a clustered KIE Server environment. To scale a KIE Server, you must ensure that it uses a database server in a separate pod or an external database server, and not a built-in H2 database engine.

In a clustered deployment, several instances of the KIE Server run the same services. These servers can connect to the Business Central Controller using the same server ID, so they can receive the same requests from the controller. Red Hat OpenShift Container Platform provides load-balancing between the servers. Decision services and business optimizer services that run on a clustered KIE Server must be stateless, because requests from the same client might be processed by different instances.

You can also deploy several independent KIE Servers to run different services. In this case, the servers connect to the Business Central Controller with different server ID values. You can use the Business Central UI to deploy services to each of the servers.

Smart Router

The optional Smart Router component provides a layer between client applications and KIE Servers. It can be useful if you are using several independent KIE Servers.

The client application can use services running on different KIE Servers, but always connects to the Smart Router. The Smart Router automatically passes the request to the KIE Servers that runs the required service. The Smart Router also enables management of service versions and provides an additional load-balancing layer.

High-availability authoring environment

In a high-availability (HA) authoring environment, the Business Central pod is scaled, so several instances of Business Central are running. Red Hat OpenShift Container Platform provides load balancing for user requests. This environment provides optimal performance for multiple users and supports failover.

Each instance of Business Central includes the Maven repository for the built artifacts and uses the .niogit Git repository for source code. The instances use shared persistent storage for the repositories. A persistent volume with ReadWriteMany access is required for this storage.

An instance of Red Hat DataGrid provides indexing of all projects and assets developed in Business Central.

An instance of Red Hat AMQ propagates Java CDI messages between all instances of Business Central. For example, when a new project is created or when an asset is locked or modified on one of the instances, this information is immediately reflected in all other instances.

The controller strategy is not suitable for clustered deployment. In an OpenShift deployment, a high-availability Business Central must manage KIE Servers using the OpenShift startup strategy.

Each KIE Server deployment (which can be scaled) creates a ConfigMap that reflects its current state. The Business Central discovers all KIE Servers by reading their ConfigMaps.

When the user requests a change in KIE Server configuration (for example, deploys or undeploys a service), Business Central initiates a connection to the KIE Server and sends a REST API request. The KIE Server changes the ConfigMap to reflect the new configuration state and then triggers its own redeployment, so that all instances are redeployed and reflect the new configuration.

You can deploy several independent KIE Servers in your OpenShift environment. Each of the KIE Servers has a separate ConfigMap with the necessary configuration. You can scale each of the KIE Servers separately.

You can include Smart Router in the OpenShift deployment.

Figure 1.2. Architecture diagram for a high-availability authoring environment

Chapter 2. Preparation for deploying Red Hat Process Automation Manager in your OpenShift environment

Before deploying Red Hat Process Automation Manager in your OpenShift environment, you must complete several procedures. You do not need to repeat these procedures if you want to deploy additional images, for example, for new versions of processes or for other processes.

Note

If you are deploying a trial environment, complete the procedure described in Section 2.1, “Ensuring your environment is authenticated to the Red Hat registry” and do not complete any other preparation procedures.

2.1. Ensuring your environment is authenticated to the Red Hat registry

To deploy Red Hat Process Automation Manager components of Red Hat OpenShift Container Platform, you must ensure that OpenShift can download the correct images from the Red Hat registry.

OpenShift must be configured to authenticate with the Red Hat registry using your service account user name and password. This configuration is specific for a namespace, and if operators work, the configuration is already completed for the openshift namespace.

However, if the image streams for Red Hat Process Automation Manager are not found in the openshift namespace or if the operator is configured to update Red Hat Process Automation Manager to a new version automatically, the operator needs to download images into the namespace of your project. You must complete the authentication configuration for this namespace.

Procedure

  1. Ensure you are logged in to OpenShift with the oc command and that your project is active.
  2. Complete the steps documented in Registry Service Accounts for Shared Environments. You must log in to Red Hat Customer Portal to access the document and to complete the steps to create a registry service account.
  3. Select the OpenShift Secret tab and click the link under Download secret to download the YAML secret file.
  4. View the downloaded file and note the name that is listed in the name: entry.
  5. Run the following commands:

    oc create -f <file_name>.yaml
    oc secrets link default <secret_name> --for=pull
    oc secrets link builder <secret_name> --for=pull

    Replace <file_name> with the name of the downloaded file and <secret_name> with the name that is listed in the name: entry of the file.

2.2. Creating the secrets for KIE Server

OpenShift uses objects called secrets to hold sensitive information such as passwords or keystores. For more information about OpenShift secrets, see What is a secret in the Red Hat OpenShift Container Platform documentation.

In order to provide HTTPS access, KIE Server uses an SSL certificate. The deployment can create a sample secret automatically. However, in production environments you must create an SSL certificate for KIE Server and provide it to your OpenShift environment as a secret.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for KIE Server.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named kieserver-app-secret from the new keystore file:

    $ oc create secret generic kieserver-app-secret --from-file=keystore.jks

2.3. Creating the secrets for Business Central

In order to provide HTTPS access, Business Central uses an SSL certificate. The deployment can create a sample secret automatically. However, in production environments you must create an SSL certificate for Business Central and provide it to your OpenShift environment as a secret.

Do not use the same certificate and keystore for Business Central and KIE Server.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for Business Central.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named businesscentral-app-secret from the new keystore file:

    $ oc create secret generic businesscentral-app-secret --from-file=keystore.jks

2.4. Creating the secrets for the AMQ broker connection

If you want to connect any KIE Server to an AMQ broker and to use SSL for the AMQ broker connection, you must create an SSL certificate for the connection and provide it to your OpenShift environment as a secret.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for the AMQ broker connection.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named broker-app-secret from the new keystore file:

    $ oc create secret generic broker-app-secret --from-file=keystore.jks

2.5. Creating the secrets for Smart Router

In order to provide HTTPS access, Smart Router uses an SSL certificate. The deployment can create a sample secret automatically. However, in production environments you must create an SSL certificate for Smart Router and provide it to your OpenShift environment as a secret.

Do not use the same certificate and keystore for Smart Router as the ones used for KIE Server or Business Central.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for Smart Router.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named smartrouter-app-secret from the new keystore file:

    $ oc create secret generic smartrouter-app-secret --from-file=keystore.jks

2.6. Building a custom KIE Server extension image for an external database

If you want to use an external database server for a KIE Server and the database server is not a MySQL or PostgreSQL server, you must build a custom KIE Server extension image with drivers for this server before deploying your environment.

Complete the steps in this build procedure to provide drivers for any of the following database servers:

  • Microsoft SQL Server
  • IBM DB2
  • Oracle Database
  • Sybase

Optionally, you can use this procedure to build a new version of drivers for any of the following database servers:

  • MySQL
  • MariaDB
  • PostgreSQL

For the supported versions of the database servers, see Red Hat Process Automation Manager 7 Supported Configurations.

The build procedure creates a custom extension image that extends the existing KIE Server image. You must import this custom extension image into your OpenShift environment and then reference it in the EXTENSIONS_IMAGE parameter.

Prerequisites

  • You are logged in to your OpenShift environment using the oc command. Your OpenShift user must have the registry-editor role.
  • For Oracle Database, IBM DB2, or Sybase, you downloaded the JDBC driver from the database server vendor.
  • You have installed the following required software:

    • Docker: For installation instructions, see Get Docker.
    • Cekit version 3.2: For installation instructions, see Installation.
    • The following libraries and extensions for Cekit. For more information, see Dependencies.

      • docker, provided by the python3-docker package or similar package
      • docker-squash, provided by the python3-docker-squash package or similar package
      • behave, provided by the python3-behave package or similar package

Procedure

  1. For IBM DB2, Oracle Database, or Sybase, provide the JDBC driver JAR file in a local directory.
  2. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  3. Unzip the file and, using the command line, change to the templates/contrib/jdbc/cekit directory of the unzipped file. This directory contains the source code for the custom build.
  4. Enter one of the following commands, depending on the database server type:

    • For Microsoft SQL Server:

      make mssql
    • For MySQL:

      make mysql
    • For PostgreSQL:

      make postgresql
    • For MariaDB:

      make mariadb
    • For IBM DB2:

      make db2 artifact=/tmp/db2jcc4.jar version=10.2

      In this command, replace /tmp/db2jcc4.jar with the path name of the IBM DB2 driver and 10.2 with the version of the driver.

    • For Oracle Database:

      make oracle artifact=/tmp/ojdbc7.jar version=7.0

      In this command, replace /tmp/ojdbc7.jar with the path name of the Oracle Database driver and 7.0 with the version of the driver.

    • For Sybase:

      make build sybase artifact=/tmp/jconn4-16.0_PL05.jar version=16.0_PL05

      In this command, replace /tmp/jconn4-16.0_PL05.jar with the path name of the downloaded Sybase driver and 16.0_PL05 with the version of the driver.

      Alternatively, if you need to update the driver class or driver XA class for the Sybase driver, you can set the DRIVER_CLASS or DRIVER_XA_CLASS variable for this command, for example:

      export DRIVER_CLASS=another.class.Sybase && make sybase artifact=/tmp/jconn4-16.0_PL05.jar version=16.0_PL05
  5. Enter the following command to list the Docker images that are available locally:

    docker images

    Note the name of the image that was built, for example, jboss-kie-db2-extension-openshift-image, and the version tag of the image, for example, 11.1.4.4 (not the latest tag).

  6. Access the registry of your OpenShift environment directly and push the image to the registry. Depending on your user permissions, you can push the image into the openshift namespace or into a project namespace. For instructions about accessing the registry and pushing the images, see Accessing registry directly from the cluster in the Red Hat OpenShift Container Platform product documentation.

2.7. Preparing Git hooks

In an authoring environment you can use Git hooks to execute custom operations when the source code of a project in Business Central is changed. The typical use of Git hooks is for interaction with an upstream repository.

To enable Git hooks to interact with an upstream repository using SSH authentication, you must also provide a secret key and a known hosts file for authentication with the repository.

Skip this procedure if you do not want to configure Git hooks.

Procedure

  1. Create the Git hooks files. For instructions, see the Git hooks reference documentation.

    Note

    A pre-commit script is not supported in Business Central. Use a post-commit script.

  2. Create a configuration map (ConfigMap) or persistent volume with the files.

    • If the Git hooks consist of one or several fixed script files, use the oc command to create a configuration map. For example:

      oc create configmap git-hooks --from-file=post-commit=post-commit
    • If the Git hooks consist of long files or depend on binaries, such as executable or JAR files, use a persistent volume. You must create a persistent volume, create a persistent volume claim and associate the volume with the claim, and transfer files to the volume.

      For instructions about persistent volumes and persistent volume claims, see Storage in the Red Hat OpenShift Container Platform documentation. For instructions about copying files onto a persistent volume, see Transferring files in and out of containers.

  3. If the Git hooks scripts must interact with an upstream repository using SSH authentication, prepare a secret with the necessary files:

    1. Prepare the id_rsa file with a private key that matches a public key stored in the repository.
    2. Prepare the known_hosts file with the correct name, address, and public key for the repository.
    3. Create a secret with the two files using the oc command, for example:

      oc create secret git-hooks-secret --from-file=id_rsa=id_rsa --from-file=known_hosts=known_hosts
      Note

      When the deployment uses this secret, it mounts the id_rsa and known_hosts files into the /home/jboss/.ssh directory on Business Central pods.

2.8. Provisioning persistent volumes with ReadWriteMany access mode using NFS

If you want to deploy Business Central Monitoring or high-availability Business Central, your environment must provision persistent volumes with ReadWriteMany access mode.

If your configuration requires provisioning persistent volumes with ReadWriteMany access mode but your environment does not support such provisioning, use NFS to provision the volumes. Otherwise, skip this procedure.

Procedure

Deploy an NFS server and provision the persistent volumes using NFS. For information about provisioning persistent volumes using NFS, see the "Persistent storage using NFS" section of the OpenShift Container Platform Storage guide.

2.9. Extracting the source code from Business Central for use in an S2I build

If you are planning to create immutable KIE servers using the source-to-image (S2I) process, you must provide the source code for your services in a Git repository. If you are using Business Central for authoring services, you can extract the source code for your service and place it into a separate Git repository, such as GitHub or an on-premise installation of GitLab, for use in the S2I build.

Skip this procedure if you are not planning to use the S2I process or if you are not using Business Central for authoring services.

Procedure

  1. Use the following command to extract the source code:

    git clone https://<business-central-host>:443/git/<MySpace>/<MyProject>

    In this command, replace the following variables:

    • <business-central-host> with the host on which Business Central is running
    • <MySpace> with the name of the Business Central space in which the project is located
    • <MyProject> with the name of the project
    Note

    To view the full Git URL for a project in Business Central, click MenuDesign<MyProject>Settings.

    Note

    If you are using self-signed certificates for HTTPS communication, the command might fail with an SSL certificate problem error message. In this case, disable SSL certificate verification in git, for example, using the GIT_SSL_NO_VERIFY environment variable:

    env GIT_SSL_NO_VERIFY=true git clone https://<business-central-host>:443/git/<MySpace>/<MyProject>
  2. Upload the source code to another Git repository, such as GitHub or GitLab, for the S2I build.

2.10. Preparing for deployment in a restricted network

You can deploy Red Hat Process Automation Manager in a restricted network that is not connected to the public Internet. For instructions about operator deployment in a restricted network, see Using Operator Lifecycle Manager on restricted networks in Red Hat OpenShift Container Platform documentation.

Important

In Red Hat Process Automation Manager 7.10, deployment on restricted networks is for Technology Preview only. For more information on Red Hat Technology Preview features, see Technology Preview Features Scope.

In order to use a deployment that does not have outgoing access to the public Internet, you must also prepare a Maven repository with a mirror of all the necessary artifacts. For instructions about creating this repository, see Section 2.11, “Preparing a Maven mirror repository for offline use”.

2.11. Preparing a Maven mirror repository for offline use

If your Red Hat OpenShift Container Platform environment does not have outgoing access to the public Internet, you must prepare a Maven repository with a mirror of all the necessary artifacts and make this repository available to your environment.

Note

You do not need to complete this procedure if your Red Hat OpenShift Container Platform environment is connected to the Internet.

Prerequisites

  • A computer that has outgoing access to the public Internet is available.

Procedure

  1. Configure a Maven release repository to which you have write access. The repository must allow read access without authentication and your OpenShift environment must have network access to this repository.

    You can deploy a Nexus repository manager in the OpenShift environment. For instructions about setting up Nexus on OpenShift, see Setting up Nexus in the Red Hat OpenShift Container Platform 3.11 documentation. The documented procedure is applicable to Red Hat OpenShift Container Platform 4.

    Use this repository as a mirror to host the publicly available Maven artifacts. You can also provide your own services in this repository in order to deploy these services on immutable servers or to deploy them on managed servers using Business Central monitoring.

  2. On the computer that has an outgoing connection to the public Internet, complete the following steps:
  3. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

    • Product: Red Hat Process Automation Manager
    • Version: 7.10

      1. Download and extract the Red Hat Process Automation Manager 7.10.0 Offliner Content List (rhpam-7.10.0-offliner.zip) product deliverable file.
      2. Extract the contents of the rhpam-7.10.0-offliner.zip file into any directory.
      3. Change to the directory and enter the following command:

        ./offline-repo-builder.sh offliner.txt

        This command creates the repository subdirectory and downloads the necessary artifacts into this subdirectory. This is the mirror repository.

        If a message reports that some downloads have failed, run the same command again. If downloads fail again, contact Red Hat support.

      4. Upload all artifacts from the repository subdirectory to the Maven mirror repository that you prepared. You can use the Maven Repository Provisioner utility, available from the Maven repository tools Git repository, to upload the artifacts.
  4. If you developed services outside of Business Central and they have additional dependencies, add the dependencies to the mirror repository. If you developed the services as Maven projects, you can use the following steps to prepare these dependencies automatically. Complete the steps on the computer that has an outgoing connection to the public Internet.

    1. Create a backup of the local Maven cache directory (~/.m2/repository) and then clear the directory.
    2. Build the source of your projects using the mvn clean install command.
    3. For every project, enter the following command to ensure that Maven downloads all runtime dependencies for all the artifacts generated by the project:

      mvn -e -DskipTests dependency:go-offline -f /path/to/project/pom.xml --batch-mode -Djava.net.preferIPv4Stack=true

      Replace /path/to/project/pom.xml with the path of the pom.xml file of the project.

    4. Upload all artifacts from the local Maven cache directory (~/.m2/repository) to the Maven mirror repository that you prepared. You can use the Maven Repository Provisioner utility, available from the Maven repository tools Git repository, to upload the artifacts.

Chapter 3. Dashbuilder Standalone on Red Hat OpenShift Container Platform

Dashbuilder Standalone is an independent implementation of Dashbuilder, which is the dashboard and reporting tool that is integrated with Business Central.

You can install Dashbuilder Standalone separately from Red Hat Process Automation Manager and import or create your own dashboards.

For more information about Dashbuilder integrated with Business Central, see Dashbuilder runtimes in the Installing and configuring Red Hat Process Automation Manager on Red Hat JBoss EAP 7.3 guide.

3.1. Custom Resource Parameters

When you use the Dashbuilder Container Image within operator, you can configure Dashbuilder by using the environment variables or through Custom Resource.

Table 3.1. Custom Resource parameters

ParameterEquivalent Environment VariableDescriptionExample value

allowExternalFileRegister

DASHBUILDER_ALLOW_EXTERNAL_FILE_REGISTER

Allows downloading of external (remote) files. Default value is false.

False

componentEnable

DASHBUILDER_COMP_ENABLE

Enables external components.

True

componentPartition

DASHBUILDER_COMPONENT_PARTITION

Enables partitioning of components by the Runtime Model ID. Default value is true.

True

configMapProps

DASHBUILDER_CONFIG_MAP_PROPS

Allows the use of the properties file with Dashbuilder configurations. Unique properties are appended and if a property is set more than once, the one from the properties file is used.

True

dataSetPartition

DASHBUILDER_DATASET_PARTITION

Enables partitioning of Dataset IDs by the Runtime Model ID. Default value is true.

True

enableBusinessCentral

 — 

Enables integration with Business Central by configuring Business Central and Dashbuilder automatically. Only available on operator.

True

enableKieServer

 — 

Enables integration with KIE Server by configuring KIE Server and Dashbuilder automatically. Only available on operator.

True

externalCompDir

DASHBUILDER_EXTERNAL_COMP_DIR

Sets the base directory where dashboard ZIP files are stored. If PersistentConfigs is enabled and ExternalCompDir is not set to an existing path, the /opt/kie/dashbuilder/components directory is used.

 — 

importFileLocation

DASHBUILDER_IMPORT_FILE_LOCATION

Sets a static dashboard to run automatically. If this property is set, imports are not allowed.

 — 

importsBaseDir

DASHBUILDER_IMPORTS_BASE_DIR

Sets the base directory where dashboard ZIP files are stored. If PersistentConfigs is enabled and ImportsBaseDir is not set to an existing path, the /opt/kie/dashbuilder/imports directory is used. If ImportFileLocation is set ImportsBaseDir is ignored.

 — 

kieServerDataSets

KIESERVER_DATASETS

Defines the KIE Server Datasets access configuration.

 — 

kieServerTemplates

KIESERVER_SERVER_TEMPLATES

Defines the KIE Server Templates access configuration.

 — 

modelFileRemoval

DASHBUILDER_MODEL_FILE_REMOVAL

Enables automatic removal of model file from the file system. Default value is false.

False

modelUpdate

DASHBUILDER_MODEL_UPDATE

Allows Runtime to check model last update in the file system to update the content. Default value is true.

True

persistentConfigs

``

Sets Dashbuilder as not ephemeral. If ImportFileLocation is set PersistentConfigs is ignored. Default value is true. Available only on operator.

True

runtimeMultipleImport

DASHBUILDER_RUNTIME_MULTIPLE_IMPORT

Allows Runtime to allow imports (multi-tenancy). Default value is false.

False

uploadSize

DASHBUILDER_UPLOAD_SIZE

Sets the size limit for dashboard uploads (in kb). Default value is 10485760 kb.

10485760

env

 — 

Represents an environment variable present in a Container.

 — 

You can use Operator to set environment variables by using the env property. All configurations listed above with a corresponding environment variable is shown in the following example:

apiVersion: app.kiegroup.org/v2
kind: KieApp
metadata:
  name: standalone-dashbuilder
spec:
  environment: rhpam-standalone-dashbuilder
  objects:
    dashbuilder:
      env:
        - name: DASHBUILDER_UPLOAD_SIZE
          value: '1000'

3.2. Installing Dashbuilder Standalone using Operator

Use Operator to install Dashbuilder Standalone separately from other services.

Procedure

  1. On the Installation page, enter a name for your application in the Application name field.
  2. In the Environment field, enter a name for your environment, for example rhpam-standalone-dashbuilder.
  3. Click Next.
  4. Optional: On the Security page, configure LDAP or Red Hat Single Sign-On.
  5. On the Components page, select Dashbuilder from the Components list.
  6. To add a KIE Server dataset, complete the following tasks:

    1. Click Add new KIE Server DataSets.
    2. In the DataSet name field, enter kieserver-1.
    3. In the Kie Server Location field, enter the location of your KIE Server, for example https://my-kie-server:80/services/rest/server.
    4. To set your credentials, complete one of the following tasks:

      • If you do not have a token set, in the Username and Password fields, enter your username and password. Leave the Token field blank.
      • If you have a token, in the Token field, enter your token. Leave the Username and Password fields blank.

        The custom resource example:

        apiVersion: app.kiegroup.org/v2
        kind: KieApp
        metadata:
          name: standalone-dashbuilder
        spec:
          environment: rhpam-standalone-dashbuilder
          objects:
            dashbuilder:
              config:
                kieServerDataSets:
                  - name: kieserver-1
                    location: 'https://my-kie-server:80/services/rest/server'
                    user: kieserverAdmin
                    password: kieserverAdminPwd
                    replaceQuery: true

    NOTE: You can add additional KIE Server DataSets by repeating this step.

  7. To add a KIE Server template, complete the following tasks:

    1. Click Add new KIE Server Templates.
    2. In the Template name field, enter a name for your template, for example kieserver-template.
    3. In the KIE Server Location field, enter the location of your KIE Server, for example https://my-other-kie-server:80/services/rest/server.
    4. To set your credentials, complete one of the following tasks:

      • If you do not have a token set, in the Username and Password fields, enter your username and password. Leave the Token field blank.
      • If you have a token, in the Token field, enter your token. Leave the Username and Password fields blank.

        apiVersion: app.kiegroup.org/v2
        kind: KieApp
        metadata:
          name: standalone-dashbuilder
        spec:
          environment: rhpam-standalone-dashbuilder
          objects:
            dashbuilder:
              config:
                kieServerDataSets:
                  - name: kieserver-1
                    location: 'https://my-kie-server:80/services/rest/server'
                    user: kieserverAdmin
                    password: kieserverAdminPwd
                    replaceQuery: true
                kieServerTemplates:
                  - name: kieserver-template
                    location: 'https://my-another-kie-server:80/services/rest/server'
                    user: user
                    password: pwd
                    replaceQuery: true

    NOTE: You can add additional KIE Server Templates by repeating this step.

Chapter 4. Deployment and management of a Red Hat Process Automation Manager environment using OpenShift operators

To deploy a Red Hat Process Automation Manager environment, the OpenShift operator uses a YAML source that describes the environment. Red Hat Process Automation Manager provides an installer that you can use to form the YAML source and deploy the environment.

When the Business Automation operator deploys the environment, it creates a YAML description of the environment, and then ensures that the environment is consistent with the description at all times. You can edit the description to modify the environment.

You can remove the environment by deleting the operator application in Red Hat OpenShift Container Platform.

Note

When you remove an environment with a high-availability Business Central, the operator does not delete Persistent Volume Claims that were created as part of the JBoss Datagrid and JBoss AMQ StatefulSet creation. This behaviour is a part of Kubernetes design, as deletion of the Persistent Volume Claims could cause data loss. For more information about handling persistent volumes during deletion of a StatefulSet, see the Kubernetes documentation.

If you create a new environment using the same namespace and the same application name, the environment reuses the persistent volumes for increased performance.

To ensure that new deployments do not use any old data, you can delete the Persistent Volume Claims manually.

4.1. Subscribing to the Business Automation operator

To be able to deploy Red Hat Process Automation Manager using operators, you must subscribe to the Business Automation operator in OpenShift.

Procedure

  1. Enter your project in the OpenShift Web cluster console.
  2. In the OpenShift Web console navigation panel, select Catalog → OperatorHub or Operators → OperatorHub.
  3. Search for Business Automation, select it and click Install.
  4. On the Create Operator Subscription page, select your target namespace and approval strategy.

    Optional: Set Approval strategy to Automatic to enable automatic operator updates. An operator update does not immediately update the product, but is required before you update the product. Configure automatic or manual product updates using the settings in every particular product deployment.

  5. Click Subscribe to create a subscription.

4.2. Deploying a Red Hat Process Automation Manager environment using the operator

After you subscribe to the Business Automation operator, you can use the installer wizard to configure and deploy a Red Hat Process Automation Manager environment.

Important

In Red Hat Process Automation Manager 7.10, the operator installer wizard is for Technology Preview only. For more information on Red Hat Technology Preview features, see Technology Preview Features Support Scope.

4.2.1. Starting the deployment of a Red Hat Process Automation Manager environment using the Business Automation operator

To start deploying a Red Hat Process Automation Manager environment using the Business Automation operator, access the installer wizard. The installer wizard is deployed when you subscribe to the operator.

Prerequisites

Procedure

  1. In the Red Hat OpenShift Container Platform web cluster console menu, select Catalog → Installed operators or Operators → Installed operators.
  2. Click the name of the operator that contains businessautomation. Information about this operator is displayed.
  3. Click the Installer link located on the right side of the window.
  4. If prompted, log in with your OpenShift credentials.

Result

The Installation tab of the wizard is displayed.

4.2.2. Setting the basic configuration of the environment

After you start to deploy a Red Hat Process Automation Manager environment using the Business Automation operator, you must select the type of the environment and set other basic configuration.

Prerequisites

Procedure

  1. In the Application Name field, enter a name for the OpenShift application. This name is used in the default URLs for all components.
  2. In the Environment list, select the type of environment. This type determines the default configuration; you can modify this configuration as necessary. The following types are available for Red Hat Process Automation Manager:

    • rhpam-trial: A trial environment that you can set up quickly and use to evaluate or demonstrate developing and running assets. Includes Business Central and a KIE Server. This environment does not use any persistent storage, and any work you do in the environment is not saved.
    • rhpam-authoring: An environment for creating and modifying services using Business Central. It consists of pods that provide Business Central for the authoring work and a KIE Server for test execution of the services.
    • rhpam-authoring-ha: An environment for creating and modifying services using Business Central. It consists of pods that provide Business Central for the authoring work and a KIE Server for test execution of the services. This version of the authoring environment supports scaling the Business Central pod to ensure high availability.

      Important

      In Red Hat Process Automation Manager 7.10, high-availability Business Central functionality deployment using the operator is for Technology Preview only. For more information about Red Hat Technology Preview features, see Technology Preview Features Support Scope. For a fully supported high-availability deployment, use the high-availability authoring template on Red Hat OpenShift Container Platform version 3.11. For instructions about deploying this template, see Part II, “Deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 3 using templates”.

    • rhpam-production: An environment for running existing services for staging and production purposes. This environment includes Business Central Monitoring, Smart Router, and two groups of KIE Server pods. You can deploy and undeploy services on every such group and also scale the group up or down as necessary. Use Business Central Monitoring to deploy, run, and stop the services and to monitor their execution.
    • rhpam-production-immutable: An alternate environment for running existing services for staging and production purposes. You can configure one or more KIE Server pods that build services from source or pull them from a Maven repository. You can then replicate each pod as necessary.

      You cannot remove any service from the pod or add any new service to the pod. If you want to use another version of a service or to modify the configuration in any other way, deploy a new server image to replace the old one. You can use any container-based integration workflows to manage the pods.

      When configuring this environment, in the KIE Servers tab you must customize the KIE Server and either click the Set immutable server configuration button or set the KIE_SERVER_CONTAINER_DEPLOYMENT environment variable. For instructions about configuring the KIE Server, see Section 4.2.5, “Setting custom KIE Server configuration of the environment”.

      Optionally, you can also use the Console tab to include Business Central Monitoring in this environment to monitor, stop, and restart the execution of process services. For instructions about configuring Business Central Monitoring, see Section 4.2.4, “Setting the Business Central configuration of the environment”.

  3. If you want to enable automatic upgrades to new versions, select the Enable Upgrades box. If this box is selected, when a new patch version of Red Hat Process Automation Manager 7.10 becomes available, the operator automatically upgrades your deployment to this version. All services are preserved and normally remain available throughout the upgrade process.

    If you also want to enable the same automatic upgrade process when a new minor version of Red Hat Process Automation Manager 7.x becomes available, select the Include minor version upgrades box.

    Note

    Disable automatic updates if you want to use a custom image for any component of Red Hat Process Automation Manager.

  4. If you want to use a custom image registry, under Custom registry, enter the URL of the registry in the Image registry field. If this registry does not have a properly signed and recognized SSL certificate, select the Insecure box.
  5. Under Admin user, enter the user name and password for the administrative user for Red Hat Process Automation Manager in the Username and Password fields.

    Important

    If you use RH-SSO or LDAP authentication, the same user must be configured in your authentication system with the kie-server,rest-all,admin roles for Red Hat Process Automation Manager.

  6. If you want to use a custom version tag for images, complete the following steps:

    1. Click Next to access the Security tab.
    2. Scroll to the bottom of the window.
    3. Enter the image tag in the Image tag field.

Next steps

If you want to deploy the environment with the default configuration, click Finish and then click Deploy to deploy the environment. Otherwise, continue to set other configuration parameters.

4.2.3. Setting the security configuration of the environment

After you set the basic configuration of a Red Hat Process Automation Manager environment using the Business Automation operator, you can optionally configure authentication (security) settings for the environment.

Prerequisites

  • You completed basic configuration of a Red Hat Process Automation Manager environment using the Business Automation operator in the installer wizard according to the instructions in Section 4.2.2, “Setting the basic configuration of the environment”.
  • If you want to use RH-SSO or LDAP for authentication, you created users with the correct roles in your authentication system. You must create at least one administrative user (for example, adminUser) with the kie-server,rest-all,admin roles. This user must have the user name and password that you configured on the Installation tab.
  • If you want to use RH-SSO authentication, you created the clients in your RH-SSO system for all components of your environment, specifying the correct URLs. This action ensures maximum control. Alternatively, the deployment can create the clients.

Procedure

  1. If the Installation tab is open, click Next to view the Security tab.
  2. In the Authentication mode list, select one of the following modes:

    • Internal: You configure the initial administration user when deploying the environment. The user can use Business Central to set up other users as necessary.
    • RH-SSO: Red Hat Process Automation Manager uses Red Hat Single Sign-On for authentication.
    • LDAP: Red Hat Process Automation Manager uses LDAP for authentication
  3. Complete the security configuration based on the Authentication mode that you selected.

    If you selected RH-SSO, configure RH-SSO authentication:

    1. In the RH-SSO URL field, enter the RH-SSO URL.
    2. In the Realm field, enter the RH-SSO realm name.
    3. If you did not create RH-SSO clients for components of your environment enter the credentials of an administrative user for your RH-SSO system in the SSO admin user and SSO admin password fields.
    4. If your RH-SSO system does not have a proper signed SSL certificate, select the Disable SSL cert validation box.
    5. If you want to change the RH-SSO principal attribute used for the user name, in the Principal attribute field enter the name of the new attribute.

    If you selected LDAP, configure LDAP authentication:

    1. In the LDAP URL field, enter the LDAP URL.
    2. Configure LDAP parameters that correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended Login Module.

      Note

      If you want to enable LDAP failover, you can set two or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

  4. If you selected RH-SSO or LDAP, if your RH-SSO or LDAP system does not define all the roles required for your deployment, you can map authentication system roles to Red Hat Process Automation Manager roles.

    To enable role mapping, you must provide a role mapping configuration file in an OpenShift configuration map or secret object in the project namespace. The file must contain entries in the following format:

    ldap_role = product_role1, product_role2...

    For example:

    admins = kie-server,rest-all,admin

    To enable the use of this file, make the following changes:

    1. Under RoleMapper, in the Roles properties file field, enter the fully qualified path name of the role mapping configuration file, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties.
    2. If you want to replace roles defined in the authentication system with roles that you define in the mapping file, select the Replace roles box. Otherwise, both the roles defined in RH-SSO or LDAP and the roles defined in the configuration file are available.
    3. In the fields under RoleMapper Configuration object, select the Kind of the object that provides the file (ConfigMap or Secret) and enter the Name of the object. This object is automatically mounted on Business Central and KIE Server pods in the path that you specified for the role mapping configuration file.
  5. Configure other passwords, if necessary:

Next steps

If you want to deploy the environment with the default configuration of all components, click Finish and then click Deploy to deploy the environment. Otherwise, continue to set configuration parameters for Business Central, KIE Servers, and Smart Router.

4.2.4. Setting the Business Central configuration of the environment

After you set the basic and security configuration of a Red Hat Process Automation Manager environment using the Business Automation operator, you can optionally configure settings for the Business Central or Business Central Monitoring component of the environment.

All environment types except rhpam-production-immutable include this component.

By default, the rhpam-production-immutable environment does not include Business Central Monitoring. To include Business Central Monitoring in this environment, you must set the number of replicas for the Business Central Monitoring pod in the Replicas field or make any other change to the Business Central configuration fields.

Prerequisites

Procedure

  1. If the Installation or Security tab is open, click Next until you view the Console tab.
  2. If you created the secret for Business Central according to the instructions in Section 2.3, “Creating the secrets for Business Central”, enter the name of the secret in the Secret field.
  3. Optional: Configure Git hooks.

    In an authoring environment, you can use Git hooks to facilitate interaction between the internal Git repository of Business Central and an external Git repository. If you want to use Git hooks, you must prepare a Git hooks directory in an OpenShift configuration map, secret, or persistent volume claim object in the project namespace. You can also prepare a secret with the SSH key and known hosts files for Git SSH authentication. For instructions about preparing Git hooks, see Section 2.7, “Preparing Git hooks”.

    To use a Git hooks directory, make the following changes:

    1. Under GitHooks, in the Mount path field, enter a fully qualified path for the directory, for example, /opt/kie/data/git/hooks.
    2. In the fields under GitHooks Configuration object, select the Kind of the object that provides the file (ConfigMap, Secret, or PersistentVolumeClaim) and enter the Name of the object. This object is automatically mounted on the Business Central pods in the path that you specified for the Git hooks directory.
    3. Optional: In the SSH secret field enter the name of the secret with the SSH key and known hosts files.
  4. Optional: Enter the number of replicas for Business Central or Business Central monitoring in the Replicas field. Do not change this number in a rhpam-authoring environment.
  5. Optional: To set the Business Central persistent volume size pvSize, on the Console component page, enter the desired size in the Persistent Volume Size field. The default size is 1Gi for Business Central and 64Mb for Business Central Monitoring.
  6. Optional: Enter requested and maximum CPU and memory limits in the fields under Resource quotas.
  7. If you want to customize the configuration of the Java virtual machine on the Business Central pods, select the Enable JVM configuration box and then enter information in any of the fields under Enable JVM configuration. All fields are optional. For the JVM parameters that you can configure, see Section 4.4, “JVM configuration parameters”.
  8. If you selected RH-SSO authentication, configure RH-SSO for Business Central:

    1. Enter the client name in the Client name field and the client secret in the Client secret field. If a client with this name does not exist, the deployment attempts to create a new client with this name and secret.
    2. If the deployment is to create a new client, enter the HTTP and HTTPS URLs that will be used for accessing the KIE Server into the SSO HTTP URL and SSO HTTPS URL fields. This information is recorded in the client.
  9. Optional: Depending on your needs, set environment variables. To set an environment variable, click Add new Environment variable, then enter the name and value for the variable in the Name and Value fields.

    • In a rhpam-production or rhpam-production-immutable environment, if you want Business Central Monitoring to run in a simplified mode that does not use a file system, set the ORG_APPFORMER_SIMPLIFIED_MONITORING_ENABLED to true.

      In the simplified mode, Business Central Monitoring does not require a persistent volume claim. You can use this mode in environments that do not support ReadWriteMany access to persistent storage. You can not use Business Central Monitoring in the simplified mode to design custom dashboards.

    • If you want to use an external Maven repository, set the following variables:

      • MAVEN_REPO_URL: The URL for the Maven repository
      • MAVEN_REPO_ID: An identifier for the Maven repository, for example, repo-custom
      • MAVEN_REPO_USERNAME: The user name for the Maven repository
      • MAVEN_REPO_PASSWORD The password for the Maven repository

        Important

        In an authoring environment, if you want Business Central to push a project into an external Maven repository, you must configure this repository during deployment and also configure exporting to the repository in every project. For information about exporting Business Central projects to an external Maven repository, see Packaging and deploying a Red Hat Process Automation Manager project.

    • If your OpenShift environment does not have a connection to the public Internet, configure access to a Maven mirror that you set up according to Section 2.11, “Preparing a Maven mirror repository for offline use”. Set the following variables:

      • MAVEN_MIRROR_URL: The URL for the Maven mirror repository that you set up in Section 2.11, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
      • MAVEN_MIRROR_OF: The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

        If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

        If your authoring environment uses a built-in Business Central Maven repository, change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.

    • In some cases, you might want to persist the Maven repository cache for Business Central. By default, the cache is not persisted, so when you restart or scale a Business Central pod, all Maven artifacts are downloaded again and all projects within Business Central must be built again. If you enable persistence for the cache, the download is not necessary and startup time can improve in some situations. However, significant additional space on the Business Central persistence volume is required.

      To enable persistence for the Maven repository cache, set the KIE_PERSIST_MAVEN_REPO environment variable to true.

      If you set KIE_PERSIST_MAVEN_REPO to true, you can optionally set a custom path for the cache using the KIE_M2_REPO_DIR variable. The default path is /opt/kie/data/m2. Files in the /opt/kie/data directory tree are persisted.

    • In some authoring environments, you might need to ensure that several users can deploy services on the same KIE Server at the same time. By default, after deploying a service onto a KIE Server using Business Central, the user needs to wait for some seconds before more services can be deployed. The OpenShiftStartupStrategy setting is enabled by default and causes this limitation. To remove the limitation, you can configure an rhpam-authoring environment to use the controller strategy. Do not make this change unless a specific need for it exists; if you decide to enable controller strategy, make this change on Business Central and on all KIE Servers in the same environment.

      Note

      Do not enable the controller strategy in an environment with a high-availability Business Central. In such environments the controller strategy does not function correctly.

      To enable the controller strategy on Business Central, set the KIE_SERVER_CONTROLLER_OPENSHIFT_ENABLED environment variable to false.

Next steps

If you want to deploy the environment with the default configuration of KIE Servers, without Smart Router, and without Process Instance Migration, click Finish and then click Deploy to deploy the environment. Otherwise, continue to set configuration parameters for KIE Servers and Smart Router.

4.2.5. Setting custom KIE Server configuration of the environment

Every environment type in the Business Automation operator includes one or several KIE Servers by default.

Optionally, you can set custom configuration for KIE Servers. In this case, default KIE Servers are not created and only the KIE Servers that you configure are deployed.

Prerequisites

Procedure

  1. If the Installation, Security, or Console tab is open, click Next until you view the KIE Servers tab.
  2. Click Add new KIE Server to add a new KIE Server configuration.
  3. In the Id field, enter an identifier for the KIE Server. If the KIE Server connects to a Business Central or Business Central Monitoring instance, this identifier determines which server group the server joins.
  4. In the Name field, enter a name for the KIE Server.
  5. In the Deployments field, enter the number of similar KIE Servers that are to be deployed. The installer can deploy several KIE Servers with the same configuration. The identifiers and names of the KIE Servers are modified automatically and remain unique.
  6. If you created the secret for KIE Server according to the instructions in Section 2.2, “Creating the secrets for KIE Server”, enter the name of the secret in the Keystore secret field.
  7. Optional: Enter the number of replicas for the KIE Server in the Replicas field.
  8. If you want to use a custom image for the KIE Server, complete the following additional steps:

    1. Click Set KIE Server image.
    2. If you want to use a Docker image name and not an OpenShift image stream tag, change the Kind value to DockerImage.
    3. Enter the name of the image stream in the Name field.
    4. If the image stream is not in the openshift namespace, enter the namespace in the Namespace field.

      For instructions about creating custom images, see Section 4.5, “Creating custom images for KIE Server and Smart Router”.

  9. If you want to configure an immutable KIE Server using a Source to Image (S2I) build, complete the following additional steps:

    Important

    If you want to configure an immutable KIE Server that pulls services from the Maven repository, do not click Set Immutable server configuration and do not complete these steps. Instead, set the KIE_SERVER_CONTAINER_REPLOYMENT environment variable.

    1. Click Set Immutable server configuration.
    2. In the KIE Server container deployment field, enter the identifying information of the services (KJAR files) that the deployment must extract from the result of a Source to Image (S2I) build. The format is <containerId>=<groupId>:<artifactId>:<version> or, if you want to specify an alias name for the container, <containerId>(<aliasId>)=<groupId>:<artifactId>:<version>. You can provide two or more KJAR files using the | separator, as illustrated in the following example: containerId=groupId:artifactId:version|c2(alias2)=g2:a2:v2.
    3. If your OpenShift environment does not have a connection to the public Internet, enter the URL of the Maven mirror that you set up according to Section 2.11, “Preparing a Maven mirror repository for offline use” in the Maven mirror URL field.
    4. In the Artifact directory field, enter the path within the project that contains the required binary files (KJAR files and any other necessary files) after a successful Maven build. Normally this directory is the target directory of the build. However, you can provide prebuilt binaries in this directory in the Git repository.
    5. If you want to use a custom base KIE Server image for the S2I build, click Set Base build image and then enter the name of the image stream in the Name field. If the image stream is not in the openshift namespace, enter the namespace in the Namespace field. If you want to use a Docker image name and not an OpenShift image stream tag, change the Kind value to DockerImage.
    6. Click Set Git source and enter information in the following fields:

      • S2I Git URI:The URI for the Git repository that contains the source for your services.
      • Reference: The branch in the Git repository.
      • Context directory: (Optional) The path to the source within the project downloaded from the Git repository. By default, the root directory of the downloaded project is the source directory.

        Note

        If you do not configure a Git source, the immutable KIE Server does not use an S2I build. Instead, it pulls the artifacts that you define in the KIE Server container deployment field from the configured Maven repository.

    7. If you are using S2I and want to set a Git Webhook so that changes in the Git repository cause an automatic rebuild of the KIE Server, click Add new Webhook. Then select the type of the Webhook in the Type field and enter the secret string for the Webhook in the Secret field.
    8. If you want to set a build environment variable for the S2I build, click Add new Build Config Environment variable and then enter the name and value for the variable in the Name and Value fields.
  10. Optional: Enter requested and maximum CPU and memory limits in the fields under Resource quotas. If you are configuring several KIE Servers, the limits apply to each server separately.
  11. If you selected RH-SSO authentication, configure RH-SSO for the KIE Server:

    1. Enter the client name in the Client name field and the client secret in the Client secret field. If a client with this name does not exist, the deployment attempts to create a new client with this name and secret.
    2. If the deployment is to create a new client, enter the HTTP and HTTPS URLs that will be used for accessing the KIE Server into the SSO HTTP URL and SSO HTTPS URL fields. This information is recorded in the client.
  12. If you want to interact with the KIE Server through JMS API using an external AMQ message broker, enable the Enable JMS Integration setting. Additional fields for configuring JMS Integration are displayed and you must enter the values as necessary:

    • User name, Password: The user name and password of a standard broker user, if user authentication in the broker is required in your environment.
    • Executor: Select this setting to disable the JMS executor. The executor is enabled by default.
    • Executor transacted: Select this setting to enable JMS transactions on the executor queue.
    • Enable signal: Select this setting to enable signal configuration through JMS.
    • Enable audit: Select this setting to enable audit logging through JMS.
    • Audit transacted: Select this setting to enable JMS transactions on the audit queue.
    • Queue executor, Queue request, Queue response, Queue signal, Queue audit: Custom JNDI names of the queues to use. If you set any of these values, you must also set the AMQ queues parameter.
    • AMQ Queues: AMQ queue names, separated by commas. These queues are automatically created when the broker starts and are accessible as JNDI resources in the JBoss EAP server. If you are using any custom queue names, you must enter the names of all the queues uses by the server in this field.
    • Enable SSL integration: Select this setting if you want to use an SSL connection to the AMQ broker. In this case you must also provide the name of the secret that you created in Section 2.4, “Creating the secrets for the AMQ broker connection” and the names and passwords of the key store and trust store that you used for the secret.
  13. If you want to customize the configuration of the Java virtual machine on the KIE Server pods, select the Enable JVM configuration box and then enter information in any of the fields under Enable JVM configuration. All fields are optional. For the JVM parameters that you can configure, see Section 4.4, “JVM configuration parameters”.
  14. In the Database type field, select the database that the KIE Server must use. The following values are available:

    • mysql: A MySQL server, created in a separate pod.
    • postgresql: A PostgreSQL server, created in a separate pod. Use this setting unless you have a specific reason to use any other setting.
    • h2: A built-in h2 database engine that does not require a separate pod. Do not scale the KIE Server pod if you use this setting.
    • external: An external database server.
  15. If you selected any database except external, a Persistent Volume Claim will be created to store the database. Optionally, set configuration parameters for the persistent volume:

    • In the Size field, enter the size of the persistence volume.
    • In the StorageClass name field, enter the storage class name for the persistent volume.
  16. Optional: If you selected the external database, configure the KIE Server extension image. If you want to use any database server except PostgreSQL, MySQL, or MariaDB, you must provide a KIE Server extension image with the database server driver according to instructions in Section 2.6, “Building a custom KIE Server extension image for an external database”. To configure the KIE Server to use this extension image, make the following changes:

    1. Select the Enable extension image stream box.
    2. In the Extension image stream tag field, enter the ImageStreamTag definition for the image that you created, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    3. Optional: In the Extension image stream namespace field, enter the namespace into which you pushed the image. If you do not enter any value in this field, the operator expects the image to be in the openshift namespace.
    4. Optional: In the Extension image install directory field, enter the directory within the extensions image where the extensions are located. If you used the procedure in Section 2.6, “Building a custom KIE Server extension image for an external database” to build the image, do not enter any value for this field.
  17. If you selected an external database server, provide the following information in additional fields:

    1. Driver: Enter the database server driver, depending on the server type:

      • mysql
      • postgresql
      • mariadb
      • mssql
      • db2
      • oracle
      • sybase
    2. Dialect: Enter the Hibernate dialect for the server, depending on the server type. The common settings are:

      • org.hibernate.dialect.MySQL5InnoDBDialect
      • org.hibernate.dialect.MySQL8Dialect
      • org.hibernate.dialect.MariaDB102Dialect
      • org.hibernate.dialect.PostgreSQL95Dialect
      • org.hibernate.dialect.PostgresPlusDialect (used for EntrepriseDB Postgres Advanced Server)
      • org.hibernate.dialect.SQLServer2012Dialect (used for MS SQL)
      • org.hibernate.dialect.DB2Dialect
      • org.hibernate.dialect.Oracle10gDialect
      • org.hibernate.dialect.SybaseASE15Dialect

        For a complete list of supported dialects, see the Hibernate SQL Dialects table in Hibernate properties in the Red Hat JBoss EAP documentation.

    3. Host: Enter the host name of the external database server.
    4. Port: Enter the port number of the external database server.
    5. Jdbc URL: Enter the JDBC URL for the external database server.

      Note

      If you are using the EntrepriseDB Postgres database server, use an URL starting with jdbc:postgresql:// and not with jdbc:edb://. Alternatively, do not set the URL and set the host and port parameters instead.

    6. NonXA: Select this box if you want to configure the data source in non-XA mode.
    7. JNDI name: Enter the JNDI name that the application uses for the data source.
    8. User name and Password: Enter the user name and password for the external database server.
    9. Background validation: Optionally, select this box to enable background SQL validation and enter the background validation interval.
    10. Optional: Set the minimum and maximum connection pool sizes, valid connection checker class, and exception sorter class for the database server.
  18. If you are using a MySQL version 8 external database server, enable the mysql_native_password plugin and use it for authentication. For instructions about this pluding, see Native Pluggable Authentication in the MySQL 8.0 Reference Manual.

    If you are using a MySQL version 8 image provided by Red Hat on Red Hat OpenShift Container Platform, to enable the plugin, set the MYSQL_DEFAULT_AUTHENTICATION_PLUGIN environment variable to mysql_native_password.

    If you created users on the MySQL version 8 server before enabling the mysql_native_password plugin, you must update the mysql-user table after you enable the plugin.

  19. Optional: Depending on your needs, set environment variables. To set an environment variable, click Add new Environment variable, then enter the name and value for the variable in the Name and Value fields.

    • If you want to configure an immutable KIE server that pulls services from the configured Maven repository, enter the following settings:

      1. Set the KIE_SERVER_CONTAINER_DEPLOYMENT environment variable. The variable must contain the identifying information of the services (KJAR files) that the deployment must pull from the Maven repository. The format is <containerId>=<groupId>:<artifactId>:<version> or, if you want to specify an alias name for the container, <containerId>(<aliasId>)=<groupId>:<artifactId>:<version>. You can provide two or more KJAR files using the | separator, as illustrated in the following example: containerId=groupId:artifactId:version|c2(alias2)=g2:a2:v2.
      2. Configure an external Maven repository.
    • If you want to configure an external Maven repository, set the following variables:

      • MAVEN_REPO_URL: The URL for the Maven repository
      • MAVEN_REPO_ID: An identifier for the Maven repository, for example, repo-custom
      • MAVEN_REPO_USERNAME: The user name for the Maven repository
      • MAVEN_REPO_PASSWORD: The password for the Maven repository
    • If your OpenShift environment does not have a connection to the public Internet, configure access to a Maven mirror that you set up according to Section 2.11, “Preparing a Maven mirror repository for offline use”. Set the following variables:

      • MAVEN_MIRROR_URL: The URL for the Maven mirror repository that you set up in Section 2.11, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment. If you configured this KIE Server as S2I, you already entered this URL.
      • MAVEN_MIRROR_OF: The value that determines which artifacts are to be retrieved from the mirror. If you configured this KIE Server as S2I, do not set this value. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

        If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

        If your authoring environment uses a built-in Business Central Maven repository, change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.

    • If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, set the PROMETHEUS_SERVER_EXT_DISABLED environment variable to false. For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.
    • If you are using Red Hat Single Sign-On authentication and the interaction of your application with Red Hat Single Sign-On requires support for CORS, set the SSO_ENABLE_CORS variable to true.
    • In some authoring environments, you might need to ensure that several users can deploy services on the same KIE Server at the same time. By default, after deploying a service onto a KIE Server using Business Central, the user needs to wait for some seconds before more services can be deployed. The OpenShiftStartupStrategy setting is enabled by default and causes this limitation. To remove the limitation, you can configure an rhpam-authoring environment to use the controller strategy. Do not make this change unless a specific need for it exists; if you decide to enable controller strategy, make this change on Business Central and on all KIE Servers in the same environment.

      Note

      Do not enable the controller strategy in an environment with a high-availability Business Central. In such environments the controller strategy does not function correctly.

      To enable controller strategy on a KIE Server, set the KIE_SERVER_STARTUP_STRATEGY environment variable to ControllerBasedStartupStrategy and the KIE_SERVER_CONTROLLER_OPENSHIFT_ENABLED environment variable to false.

Next steps

To configure additional KIE Servers, click Add new KIE Server again and repeat the procedure for the new server configuration.

If you want to deploy the environment without Smart Router and without Process Instance Migration, click Finish and then click Deploy to deploy the environment. Otherwise, continue to set configuration parameters for Smart Router.

4.2.6. Setting Smart Router configuration for the environment

By default, the deployed environment does not include Smart Router. You can add a Smart Router to the environment. You can also set configuration options for the Smart Router.

Prerequisites

Procedure

  1. If the Installation, Security, Console, or KIE Servers tab is open, click Next until you view the Smart Router tab.
  2. Click Set Smart Router to add Smart Router to the environment and to configure Smart Router.
  3. If you have created a custom Smart Router image according to the instructions in Section 4.5.3, “Creating a custom Smart Router image with an additional JAR file to implement custom routing”, set the following values:

    • Image context: The project name, for example, rhpam-project
    • Image: The custom image name, for example, rhpam-smartrouter-rhel8-custom

      If you used a custom tag for the image, set the Image tag field to this tag.

  4. If you created the secret for Smart Router according to the instructions in Section 2.5, “Creating the secrets for Smart Router”, enter the name of the secret in the Secret field.
  5. Optional: Enter the number of replicas for the Smart Router in the Replicas field.
  6. Optional: Enter requested and maximum CPU and memory limits in the fields under Resource quotas.
  7. Optional: Set the logging level using an environment variable:

    1. Click Add new Environment variable.
    2. In the Name field, enter LOG_LEVEL.
    3. In the Value field, enter a Java logging level. For a list of the available logging levels, see class Level.
    4. Optional: Set different logging levels for components by package name:

      1. Click Add new Environment variable.
      2. In the Name field, enter LOG_LEVEL.
      3. In the Value field, enter packages and logging levels for them, formatted as in the following example:

        com.example.abc=FINEST,com.example.def=SEVERE,com.example.xyz=FINE

Next steps

If you want to deploy the Process Instance Migration service, continue to deploy the service. Otherwise, click Finish and then click Deploy to deploy the environment.

4.2.7. Setting Process Instance Migration configuration for the environment

You can use the operator to deploy the Process Instance Migration (PIM) service. You can use the PIM service to define the migration between two different process definitions, known as a migration plan. You can apply the migration plan to the running process instances in a specific KIE Server.

The PIM service uses a database server for its operation.

Prerequisites

Procedure

  1. If the Installation, Security, Console, KIE Servers, or Smart Router tab is open, click Next until you view the Process Instance Migration tab.
  2. Click Set Process Instance Migration to add PIM to the environment and to configure PIM.
  3. In the Database type field, select the database that the PIM service must use. The following values are available:

    • mysql: A MySQL server, created in a separate pod.
    • postgresql: A PostgreSQL server, created in a separate pod. Use this setting unless you have a specific reason to use any other setting.
    • h2: A built-in h2 database engine that does not require a separate pod.
  4. Optional: Set configuration parameters of the persistent volume for the database:

    • In the Size field, enter the size of the persistence volume
    • In the StorageClass name field, enter the storage class name for the persistent volume

Next steps

Click Finish and then click Deploy to deploy the environment.

For instructions about using the PIM service, see Process Instance Migration in Managing and monitoring business processes in Business Central.

4.3. Modifying an environment that is deployed using operators

If an environment is deployed using operators, you cannot modify it using typical OpenShift methods. For example, if you delete a deployment configuration or a service, it is re-created automatically with the same parameters.

To modify the environment, you must modify the YAML description of the environment. You can change common settings such as passwords, add new KIE Servers, and scale KIE Servers.

Procedure

  1. Enter your project in the OpenShift web cluster console.
  2. In the OpenShift Web console navigation panel, select Catalog → Installed operators or Operators → Installed operators.
  3. Find the Business Automation operator line in the table and click KieApp in the line. Information about the environments that you deployed using this operator is displayed.
  4. Click the name of a deployed environment.
  5. Select the YAML tab.

    A YAML source is displayed. In this YAML source, you can edit the content under spec: to change the configuration of the environment.

  6. If you want to change the deployed version of Red Hat Process Automation Manager, add the following line under spec:

      version: 7.10.0

    You can replace 7.10.0 with another required version. Use this setting to upgrade Red Hat Process Automation Manager to a new version if automatic updates are disabled, for example, if you use a custom image.

  7. If you want to change common settings, such as passwords, edit the values under commonConfig:.
  8. If you want to add new KIE Servers, add their descriptions at the end of the block under servers:, as shown in the following examples:

    • To add two servers named server-a and server-a-2, add the following lines:

      - deployments: 2
        name: server-a
    • To add an immutable KIE Server that includes services built from source in an S2I process, add the following lines:

      - build:
          kieServerContainerDeployment: <deployment>
          gitSource:
            uri: <url>
            reference: <branch>
            contextDir: <directory>

      Replace the following values:

      • <deployment>: The identifying information of the decision service (KJAR file) that is built from your source. The format is <containerId>=<groupId>:<artifactId>:<version>. You can provide two or more KJAR files using the | separator, for example containerId=groupId:artifactId:version|c2=g2:a2:v2. The Maven build process must produce all these files from the source in the Git repository.
      • <url>: The URL for the Git repository that contains the source for your decision service.
      • <branch>: The branch in the Git repository.
      • <directory>: The path to the source within the project downloaded from the Git repository.
  9. If you want to scale a KIE Server, find the description of the server in the block under servers: and add a replicas: setting under that description. For example, replicas: 3 scales the server to three pods.
  10. If you want to make other changes, review the CRD source for the available settings. To view the CRD source, log in to the Red Hat OpenShift Container Platform environment with the oc command as an administrative user and then enter the following command:

    oc get crd kieapps.app.kiegroup.org -o yaml
  11. Click Save and then wait for a has been updated pop-up message.
  12. Click Reload to view the new YAML description of the environment.

4.4. JVM configuration parameters

When deploying Red Hat Process Automation Manager using the operator, you can optionally set a number of JVM configuration parameters for Business Central and KIE Servers. These parameters set environment variables for the corresponding containers.

The following table lists all JVM configuration parameters that you can set when deploying Red Hat Process Automation Manager using the operator.

The default settings are optimal for most use cases. Make any changes only when they are required.

Table 4.1. JVM configuration parameters

Configuration fieldEnvironment variableDescriptionExample

Java Opts append

JAVA_OPTS_APPEND

User specified Java options to be appended to generated options in JAVA_OPTS.

-Dsome.property​=foo

Java max memory ratio

JAVA_MAX_MEM_RATIO

The maximum percentage of container memory that can be used for the Java Virtual Machine. The remaining memory is used for the operating system. The default value is 50, for a limit of 50%. Sets the -Xmx JVM option. If you enter a value of 0, the -Xmx option is not set.

40

Java initial memory ratio

JAVA_INITIAL_MEM_RATIO

The percentage of container memory that is initially used for the Java Virtual Machine. The default value is 25, so 25% of the pod memory is initially allocated for the JVM if this value does not exceed the Java Max Initial Memory value. Sets the -Xms JVM option. If you enter a value of 0, the -Xms option is not set.

25

Java max initial memory

JAVA_MAX_INITIAL_MEM

The maximum amount of memory, in megabytes, that can be initially used for the Java Virtual Machine. If the initial allocated memory, as set in the Java initial memory ratio parameter, would otherwise be greater than this value, the amount of memory set in this value is allocated using the -Xms JVM option. The default value is 4096.

4096

Java diagnostics

JAVA_DIAGNOSTICS

Enable this setting to enable output of additional JVM diagnostic information to the standard output. Disabled by default.

true

Java debug

JAVA_DEBUG

Enable this setting to switch on remote debugging. Disabled by default. Adds the -⁠agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=${debug_port} JVM option, where ${debug_port} defaults to 5005.

true

Java debug port

JAVA_DEBUG_PORT

The port that is used for remote debugging. The default value is 5005.

8787

GC min heap free ratio

GC_MIN_HEAP_FREE_RATIO

Minimum percentage of heap free after garbage collection (GC) to avoid expansion. Sets the -XX:MinHeapFreeRatio JVM option.

20

GC max heap free ratio

GC_MAX_HEAP_FREE_RATIO

Maximum percentage of heap free after GC to avoid shrinking. Sets the -XX:MaxHeapFreeRatio JVM option.

40

GC time ratio

GC_TIME_RATIO

Specifies the ratio of the time spent outside the garbage collection (for example, the time spent for application execution) to the time spent in the garbage collection. Sets the -XX:GCTimeRatio JVM option.

4

GC adaptive size policy weight

GC_ADAPTIVE_SIZE_POLICY_WEIGHT

The weighting given to the current GC time versus previous GC times. Sets the -XX:AdaptiveSizePolicyWeight JVM option.

90

GC max metaspace size

GC_MAX_METASPACE_SIZE

The maximum metaspace size. Sets the -XX:MaxMetaspaceSize JVM option.

100

4.5. Creating custom images for KIE Server and Smart Router

You can create custom images to add files to KIE Server and Smart Router deployments. You must push the images to your own container registry. When deploying Red Hat Process Automation Manager, you can configure the operator to use the custom images.

If you use a custom image, you must disable automatic version updates. When you want to install a new version, build the image with the same name as before and the new version tag and push the image into your registry. You can then change the version and the operator automatically pulls the new image. For instructions about changing the product version in the operator, see Section 4.3, “Modifying an environment that is deployed using operators”.

In particular, you can create the following types of custom images:

  • A custom image of KIE Server that includes an additional RPM package
  • A custom image of KIE Server that includes an additional JAR class library
  • A custom image of Smart Router that includes an additional JAR class library to implement custom routing

4.5.1. Creating a custom KIE Server image with an additional RPM package

You can create a custom KIE Server image where an additional RPM package is installed. You can push this image into your custom registry and then use it to deploy the KIE Server.

You can install any package from the Red Hat Enterprise Linux 8 repository. This example installs the procps-ng package, which provides the ps utility, but you can modify it to install other packages.

Procedure

  1. Authenticate to the registry.redhat.io registry using the podman login command. For instructions about authenticating to the registry, see Red Hat Container Registry Authentication.
  2. To download the supported KIE Server base image, enter the following command:

    podman pull registry.redhat.io/rhpam-7/rhpam-kieserver-rhel8:7.10.0
  3. Create a Dockerfile that defines a custom image based on the base image. The file must change the current user to root, install the RPM package using the yum command, and then revert to USER 185, the Red Hat JBoss EAP user. The following example shows the content of the Dockerfile file:

    FROM registry.redhat.io/rhpam-7/rhpam-kieserver-rhel8:7.10.0
    USER root
    RUN yum -y install procps-ng
    USER 185

    Replace the name of the RPM file as necessary. The yum command automatically installs all dependencies from the Red Hat Enterprise Linux 8 repository. You might need to install several RPM files, in this case, use several RUN commands.

  4. Build the custom image using the Dockerfile. Supply the fully qualified name for the image, including the registry name. You must use the same version tag as the version of the base image. To build the image, enter the following command:

    podman build . --tag registry_address/image_name:7.10.0

    For example:

    podman build . --tag registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0
  5. After the build completes, run the image, log in to it, and verify that the customization was successful. Enter the following command:

    podman run -it --rm registry_address/image_name:7.10.0 /bin/bash

    For example:

    podman run -it --rm registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0 /bin/bash

    In the shell prompt for the image, enter the command to test that the RPM is installed, then enter exit. For example, for procps-ng, run the ps command:

    [jboss@c2fab36b778e ~]$ ps
    PID TTY          TIME CMD
      1 pts/0    00:00:00 bash
     13 pts/0    00:00:00 ps
    [jboss@c2fab36b778e ~]$ exit
  6. To push the custom image into your registry, enter the following command:

    podman push registry_address/image_name:7.10.0 docker://registry_address/image_name:7.10.0

    For example:

    podman push registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0 docker://registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0

Next steps

When deploying the KIE Server, set the image name and namespace to specify the custom image in your registry. Click Set KIE Server image, change the Kind value to DockerImage, and then provide the image name including the registry name, but without the version tag, for example:

registry.example.com/custom/rhpam-kieserver-rhel8

For instructions about deploying the KIE Server using the operator, see Section 4.2.5, “Setting custom KIE Server configuration of the environment”.

4.5.2. Creating a custom KIE Server image with an additional JAR file

You can create a custom KIE Server image where an additional JAR file (or several JAR files) is installed to extend the capabilities of the server. You can push this image into your custom registry and then use it to deploy the KIE Server.

For example, you can create a custom class JAR to provide custom Prometheus metrics in the KIE Server. For instructions about creating the custom class, see Extending Prometheus metrics monitoring in KIE Server with custom metrics in Managing and monitoring KIE Server.

Procedure

  1. Develop a custom library that works with the KIE Server. You can use the following documentation and examples to develop the library:

  2. Build the library using Maven, so that the JAR file is placed in the target directory. This example uses the custom-kieserver-ext-1.0.0.Final.jar file name.
  3. Authenticate to the registry.redhat.io registry using the podman login command. For instructions about authenticating to the registry, see Red Hat Container Registry Authentication.
  4. To download the supported KIE Server base image, enter the following command:

    podman pull registry.redhat.io/rhpam-7/rhpam-kieserver-rhel8:7.10.0
  5. Create a Dockerfile that defines a custom image based on the base image. The file must copy the JAR file (or several JAR files) into the /opt/eap/standalone/deployments/ROOT.war/WEB-INF/lib/ directory. The following example shows the content of the Dockerfile file:

    FROM registry.redhat.io/rhpam-7/rhpam-kieserver-rhel8:7.10.0
    COPY target/custom-kieserver-ext-1.0.0.Final.jar /opt/eap/standalone/deployments/ROOT.war/WEB-INF/lib/
  6. Build the custom image using the Dockerfile. Supply the fully qualified name for the image, including the registry name. You must use the same version tag as the version of the base image. To build the image, enter the following command:

    podman build . --tag registry_address/image_name:7.10.0

    For example:

    podman build . --tag registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0
  7. To push the custom image into your registry, enter the following command:

    podman push registry_address/image_name:7.10.0 docker://registry_address/image_name:7.10.0

    For example:

    podman push registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0 docker://registry.example.com/custom/rhpam-kieserver-rhel8:7.10.0

Next steps

When deploying the KIE Server, set the image name and namespace to specify the custom image in your registry. Click Set KIE Server image, change the Kind value to DockerImage, and then provide the image name including the registry name, but without the version tag, for example:

registry.example.com/custom/rhpam-kieserver-rhel8

For instructions about deploying the KIE Server using the operator, see Section 4.2.5, “Setting custom KIE Server configuration of the environment”.

4.5.3. Creating a custom Smart Router image with an additional JAR file to implement custom routing

By default, Smart Router routes requests based on the container alias. If several KIE Servers provide a service with the same container alias, Smart Router balances the load between them.

In some cases, custom routing functionality is required. You can create a custom class to implement the custom routing and then create a custom Smart Router image with the class. You can push this image into your custom registry and then use it to deploy Smart Router.

Prerequisites

  • A JDK and Apache Maven are installed.
  • The project for deploying Red Hat Process Automation Manager is created in your Red Hat OpenShift Container Platform environment
  • You know the route for the Red Hat OpenShift Container Platform image registry and have the permission to push images into the registry. For instructions about configuring the registry, see Registry in Red Hat OpenShift Container Platform product documentation.

Procedure

  1. Download the sample source of the router extention from the GitHub repository.
  2. Modify the sample source of the router extension as necessary. The existing code implements simple routing based on the version of the container.
  3. Build the source code with Maven:

    mvn clean package

    The build process generates the following JAR file: target/router-ext-0.0.1-SNAPSHOT.jar

  4. Create a working directory for creating the custom image, copy the generated JAR file into the directory, and then change to the directory, for example:

    mkdir /tmp/smartrouter
    cp target/router-ext-0.0.1-SNAPSHOT.jar /tmp/smartrouter
    cd /tmp/smartrouter
  5. Authenticate to the registry.redhat.io registry using the podman login command. For instructions about authenticating to the registry, see Red Hat Container Registry Authentication.
  6. To download the supported Smart Router base image, enter the following command:

    podman pull registry.redhat.io/rhpam-7/rhpam-smartrouter-rhel8:7.10.0
  7. Extract the openshift-launch.sh file from the official Smart Router image:

    podman run --rm registry.redhat.io/rhpam-7/rhpam-smartrouter-rhel8:7.10.0 \
       cat /opt/rhpam-smartrouter/openshift-launch.sh > openshift-launch.sh
  8. Edit the openshift-launch.sh file. In the last line of the file, find the exec instruction that looks like the following text:

    exec ${JAVA_HOME}/bin/java ${SHOW_JVM_SETTINGS} ${JAVA_OPTS} ${JAVA_OPTS_APPEND} ${JAVA_PROXY_OPTIONS} "${D_ARR[@]}" -jar /opt/${JBOSS_PRODUCT}/${KIE_ROUTER_DISTRIBUTION_JAR}

    Change the instruction to the following text:

    exec ${JAVA_HOME}/bin/java ${SHOW_JVM_SETTINGS} "${D_ARR[@]}" \
        -cp /opt/${JBOSS_PRODUCT}/router-ext-0.0.1-SNAPSHOT.jar:/opt/${JBOSS_PRODUCT}/${KIE_ROUTER_DISTRIBUTION_JAR} \
        org.kie.server.router.KieServerRouter

    This change adds the extension JAR file to the Java Class Path.

  9. Create a Dockerfile file that defines a custom image based on the base image. The following example shows the content of the Dockerfile file:

    FROM registry.redhat.io/rhpam-7/rhpam-smartrouter-rhel8:7.10.0
    RUN rm -rfv /opt/rhpam-smartrouter/openshift-launch.sh
    COPY openshift-launch.sh  /opt/rhpam-smartrouter/openshift-launch.sh
    COPY router-ext-0.0.1-SNAPSHOT.jar /opt/rhpam-smartrouter/router-ext-0.0.1-SNAPSHOT.jar
    
    USER root
    RUN chown jboss. /opt/rhpam-smartrouter/router-ext-0.0.1-SNAPSHOT.jar /opt/rhpam-smartrouter/openshift-launch.sh
    RUN chmod +x /opt/rhpam-smartrouter/openshift-launch.sh
    USER 185

    This file includes the following actions:

    • Add the JAR file and the new openshift-launch.sh file
    • Change the current user to root
    • Set the necessary permissions for the openshift-launch.sh file
    • Revert to USER 185, the Red Hat JBoss EAP user
  10. Log in to your Red Hat OpenShift Container Platform cluster with the oc command.
  11. Log in to the Red Hat OpenShift Container Platform cluster registry with the podman login command.
  12. Build the custom image using the Dockerfile. Tag the image for your Red Hat OpenShift Container Platform cluster registry and your project namespace. Use a custom name for the image and the same version tag as the version of the base image. To build the image, enter the following command:

    podman build . --tag registry-route/project-name_/image-name:7.10.0

    For example:

    podman build . --tag route-openshift-image-registry.openshift.example.com/rhpam-project/rhpam-smartrouter-rhel8-custom:7.10.0
  13. After the build completes, run the image and verify that the customization was successful. Enter the following command:

    podman run registry-route/project-name/image-name:7.10.0

    For example:

    podman run route-openshift-image-registry.openshift.example.com/rhpam-project/rhpam-smartrouter-rhel8-custom:7.10.0

    Ensure that the output mentions the custom service, as in the following example:

    INFO: Using 'LatestVersionContainerResolver' container resolver and restriction policy 'ByPassUserNotAllowedRestrictionPolicy'
  14. Push the custom image into the registry:

    podman push registry-route/project-name/image-name:7.10.0

    For example:

    podman push route-openshift-image-registry.openshift.example.com/rhpam-project/rhpam-smartrouter-rhel8-custom:7.10.0

Next steps

When deploying Red Hat Process Automation Manager, set the following values in the Smart Router tab:

  • Image context: The project name, for example, rhpam-project
  • Image: The custom image name, for example, rhpam-smartrouter-rhel8-custom

For instructions about deploying the Smart Router using the operator, see Section 4.2.6, “Setting Smart Router configuration for the environment”.

Note

You can also use a custom tag instead of the current version tag. However, if you use the current version tag, you can later create an image for a new version using the version tag for it. Then, when you upgrade the Red Hat Process Automation Manager version, the new image is included automatically. For instructions about upgrading the Red Hat Process Automation Manager version, see Section 4.3, “Modifying an environment that is deployed using operators”.

If you use a custom tag, when deploying Red Hat Process Automation Manager, in the Smart Router tab set the Image Tag value to the custom tag.

Chapter 5. Migration of information from a deployment on Red Hat OpenShift Container Platform 3

If you previously used a Red Hat Process Automation Manager deployment on Red Hat OpenShift Container Platform 3, you can migrate the information from that deployment to a new deployment on Red Hat OpenShift Container Platform 4.

Before migrating information, you must deploy a new Red Hat Process Automation Manager infrastructure on Red Hat OpenShift Container Platform 4 using the operator. Include the same elements in the new infrastructure as those present in the old deployment. For example:

  • For any existing authoring deployment, create a new authoring infrastructure, including Business Central and at least one KIE Server.
  • For any existing immutable KIE Server, deploy a new immutable KIE Server with the same artifacts.
  • For any existing KIE Server with a MySQL or PostgreSQL database pod, deploy a new KIE Server with the same type of database pod.
  • For any existing KIE Server that uses an external database server, deploy a new KIE Server that uses the same external database server with the same credentials. The server connects to the same database and therefore can read the process context state.
Note

If a KIE Server uses the H2 built-in database, migration of the process context state is not supported.

No migration is required for Smart Router. A new deployment of Smart Router automatically works with the services on the new KIE Servers.

5.1. Migrating information in Business Central

If you have an existing authoring environment in Red Hat OpenShift Container Platform 3, you can copy the .niogit repository and the Maven repository from Business Central in this environment to Business Central in a new deployment on Red Hat OpenShift Container Platform 4. This action makes all the same projects and artifacts available in the new deployment.

Prerequisites

  • You must have a machine that has network access to both the Red Hat OpenShift Container Platform 3 and Red Hat OpenShift Container Platform 4 infrastructures.
  • The oc command-line client from Red Hat OpenShift Container Platform 4 must be installed on the machine. For instructions about installing the command-line client, see CLI tools in Red Hat OpenShift Container Platform documentation.

Procedure

  1. Ensure that no web clients and no client applications are connected to any elements of the old and new deployment, including Business Central and KIE Servers.
  2. Create an empty temporary directory and change into it.
  3. Using the oc command, log in to the Red Hat OpenShift Container Platform 3 infrastructure and switch to the project containing the old deployment.
  4. To view the pod names in the old deployment, run the following command:

    oc get pods

    Find the Business Central pod. The name of this pod includes rhpamcentr. In a high-availability deployment, you can use any of the Business Central pods.

  5. Use the oc command to copy the the .niogit repository and the Maven repository from the pod to the local machine, for example:

    oc cp myapp-rhpamcentr-5-689mw:/opt/kie/data/.niogit .niogit
    oc cp myapp-rhpamcentr-5-689mw:/opt/kie/data/maven-repository maven-repository
  6. Using the oc command, log in to the Red Hat OpenShift Container Platform 4 infrastructure and switch to the project containing the new deployment.
  7. To view the pod names in the new deployment, run the following command:

    oc get pods

    Find the Business Central pod. The name of this pod includes rhpamcentr. In a high-availability deployment, you can use any of the Business Central pods.

  8. Use the oc command to copy the the .niogit repository and the Maven repository from the local machine to the pod, for example:

    oc cp .niogit myappnew-rhpamcentr-abd24:/opt/kie/data/.niogit
    oc cp maven-repository myappnew-rhpamcentr-abd24:/opt/kie/data/maven-repository

5.2. Migrating a MySQL database for a KIE Server

If your environment in Red Hat OpenShift Container Platform 3 includes a KIE Server that uses a MySQL database pod, copy the MySQL database content from the old deployment to the new deployment. This action copies the existing process state to the new deployment.

Prerequisites

  • You must have a machine that has network access to both the Red Hat OpenShift Container Platform 3 and Red Hat OpenShift Container Platform 4 infrastructures.
  • The oc command-line client from Red Hat OpenShift Container Platform 4 must be installed on the machine. For instructions about installing the command-line client, see CLI tools in Red Hat OpenShift Container Platform documentation.
  • The mysql and mysqldump client applications provided by MySQL version 8 or later or by MariaDB version 10 or later must be installed.

Procedure

  1. Ensure that no web clients and no client applications are connected to any elements of the old and new deployment, including Business Central and KIE Servers.
  2. Create an empty temporary directory and change into it.
  3. Using the oc command, log in to the Red Hat OpenShift Container Platform 3 infrastructure and switch to the project containing the old deployment.
  4. To view the deployment configuration names in the old deployment, run the following command:

    oc get dc

    Find the mysql deployment configuration that corresponds to the KIE Server.

  5. View the configuration YAML of the deployment configuration, for example:

    oc edit dc/myapp-mysql

    In this file, find the user name (normally rhpam) and password for the database server, for example:

    - name: MYSQL_USER
      value: rhpam
    - name: MYSQL_PASSWORD
      value: NDaJIV7!

    Record the user name and password. Do not make any changes to the file.

    Note

    You can also use the following commands to retrieve the user name and password:

    oc get dc/myapp-mysql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="MYSQL_USER")]}'.value
    
    oc get dc/myapp-mysql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="MYSQL_PASSWORD")]}'.value
  6. To view the service names in the old deployment, run the following command:

    oc get svc

    Find the mysql service that corresponds to the KIE Server.

  7. In a separate terminal window, start port forwarding from the local host to the mysql service, using the name and port number displayed for the service, for example:

    oc port-forward service/myapp-mysql 3306:3306
  8. Create a full database dump using the recorded user name, for example:

    mysqldump --all-databases -u rhpam -p -h 127.0.0.1 > mysqldump.sql

    When prompted, enter the recorded password. The dump creation can take considerable time.

  9. Stop the port forwarding in the separate window using the Ctrl+C key combination.
  10. Using the oc command, log in to the Red Hat OpenShift Container Platform 4 infrastructure and switch to the project containing the new deployment.
  11. To view the deployment configuration names in the new deployment, run the following command:

    oc get dc

    Find the mysql deployment configuration that corresponds to the KIE Server.

  12. View the configuration YAML of the deployment configuration, for example:

    oc edit dc/myappnew-mysql

    In this file, find the user name (normally rhpam) and password for the database server. Record the user name and password. Do not make any changes to the file.

    Note

    You can also use the following commands to retrieve the user name and password:

    oc get dc/myapp-mysql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="MYSQL_USER")]}'.value
    
    oc get dc/myapp-mysql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="MYSQL_PASSWORD")]}'.value
  13. To view the service names in the new deployment, run the following command:

    oc get svc

    Find the mysql service that corresponds to the KIE Server.

  14. In a separate terminal window, start port forwarding from the local host to the mysql service, using the name and port number displayed for the service, for example:

    oc port-forward service/myappnew-mysql 3306:3306
  15. Restore the database dump using the recorded user name, for example:

    mysql -u rhpam -p -h 127.0.0.1 < mysqldump.sql

    When prompted, enter the recorded password. The restoration can take considerable time.

  16. Stop the port forwarding in the separate window using the Ctrl+C key combination.

5.3. Migrating a PostgreSQL database for a KIE Server

If your environment in Red Hat OpenShift Container Platform 3 includes a KIE Server that uses a PostgreSQL database pod, copy the PostgreSQL database content from the old deployment to the new deployment. This action copies the existing process state to the new deployment.

Prerequisites

  • You must have a machine that has network access to both the Red Hat OpenShift Container Platform 3 and Red Hat OpenShift Container Platform 4 infrastructures.
  • The oc command-line client from Red Hat OpenShift Container Platform 4 must be installed on the machine. For instructions about installing the command-line client, see CLI tools in Red Hat OpenShift Container Platform documentation.
  • The psql and pg_dump client applications provided by PostgreSQL version 10 or later must be installed.

Procedure

  1. Ensure that no web clients and no client applications are connected to any elements of the old and new deployment, including Business Central and KIE Servers.
  2. Create an empty temporary directory and change into it.
  3. Using the oc command, log in to the Red Hat OpenShift Container Platform 3 infrastructure and switch to the project containing the old deployment.
  4. To view the deployment configuration names in the old deployment, run the following command:

    oc get dc

    Find the postgresql deployment configuration that corresponds to the KIE Server.

  5. View the configuration YAML of the deployment configuration, for example:

    oc edit dc/myapp-postgresql

    In this file, find the user name (normally rhpam), password, and database name (normally rhpam7) for the database server, for example:

    - name: POSTGRESQL_USER
      value: rhpam
    - name: POSTGRESQL_PASSWORD
      value: NDaJIV7!
    - name: POSTGRESQL_DATABASE
      value: rhpam7

    Record the user name, password, and database name. Do not make any changes to the file.

    Note

    You can also use the following commands to retrieve the user name, password, and database name:

    oc get dc/myapp-postgresql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="POSTGRESQL_USER")]}'.value
    
    oc get dc/myapp-postgresql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="POSTGRESQL_PASSWORD")]}'.value
    
    oc get dc/myapp-postgresql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="POSTGRESQL_DATABASE")]}'.value

    +

  6. To view the service names in the old deployment, run the following command:

    oc get svc

    Find the postgresql service that corresponds to the KIE Server.

  7. In a separate terminal window, start port forwarding from the local host to the postgresql service, using the name and port number displayed for the service, for example:

    oc port-forward service/myapp-postgresql 5432:5432
  8. Create a dump of the database using the recorded user name and database name, for example:

    pg_dump rhpam7 -h 127.0.0.1 -U rhpam -W > pgdump.sql

    When prompted, enter the recorded password. The dump creation can take considerable time.

  9. Stop the port forwarding in the separate window using the Ctrl+C key combination.
  10. Using the oc command, log in to the Red Hat OpenShift Container Platform 4 infrastructure and switch to the project containing the new deployment.
  11. To view the deployment configuration names in the new deployment, run the following command:

    oc get dc

    Find the postgresql deployment configuration that corresponds to the KIE Server.

  12. View the configuration YAML of the deployment configuration, for example:

    oc edit dc/myappnew-postgresql

    In this file, find the user name (normally rhpam), password, , and database name (normally rhpam7) for the database server. Record the user name, password, and database name. Do not make any changes to the file.

    Note

    You can also use the following commands to retrieve the user name, password, and database name:

    oc get dc/myapp-postgresql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="POSTGRESQL_USER")]}'.value
    
    oc get dc/myapp-postgresql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="POSTGRESQL_PASSWORD")]}'.value
    
    oc get dc/myapp-postgresql -ojsonpath='{.spec.template.spec.containers[0].env[?(@.name=="POSTGRESQL_DATABASE")]}'.value
  13. To view the service names in the new deployment, run the command:

    oc get svc

    Find the postgresql service that corresponds to the KIE Server.

  14. In a separate terminal window, start port forwarding from the local host to the postgresql service, using the name and port number displayed for the service, for example:

    oc port-forward service/myappnew-postgresql 5432:5432
  15. Restore the database dump using the recorded user name and database name, for example:

    psql -h 127.0.0.1 -d rhpam7 -U rhpam -W < pgdump.sql

    When prompted, enter the recorded password. The restoration can take considerable time.

    Review any displayed database error messages. Messages about objects that already exist are normal.

  16. Stop the port forwarding in the separate window using the Ctrl+C key combination.

Part II. Deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 3 using templates

As a system engineer, you can deploy a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 3 to provide an infrastructure to develop or execute services, process applications, and other business assets. You can use one of the supplied templates to deploy a predefined Red Hat Process Automation Manager environment to suit your particular needs.

Note

For instructions about deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 4 using Operators, see Deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 4 using Operators.

Prerequisites

  • Red Hat OpenShift Container Platform version 3.11 is deployed.
  • The following resources are available on the OpenShift cluster. Depending on the application load, higher resource allocation might be necessary for acceptable performance.

    • For an authoring environment, 4 gigabytes of memory and 2 virtual CPU cores for the Business Central pod. In a high-availability deployment, these resources are required for each replica and two replicas are created by default.
    • For a production or immutable environment, 2 gigabytes of memory and 1 virtual CPU core for each replica of the Business Central Monitoring pod.
    • 2 gigabytes of memory and 1 virtual CPU core for each replica of each KIE Server pod.
    • 512 megabytes of memory and half a virtual CPU core for each replica of a Smart Router pod.
    • In a high-availability authoring deployment, additional resources according to the configured defaults are required for the MySQL, Red Hat AMQ, and Red Hat Data Grid pods.
  • Dynamic persistent volume (PV) provisioning is enabled. Alternatively, if dynamic PV provisioning is not enabled, enough persistent volumes must be available. By default, the deployed components require the following PV sizes:

    • Each KIE Server deployment by default requires one 1Gi PV for the database. You can change the database PV size. You can deploy multiple KIE Servers; each requires a separate database PV. This requirement does not apply if you use an external database server.
    • By default, Business Central requires one 1Gi PV. You can change the PV size for Business Central persistent storage.
    • Business Central Monitoring requires one 64Mi PV.
    • Smart Router requires one 64Mi PV.
Note

For instructions about checking the capacity of your cluster, see Analyzing cluster capacity in the Red Hat OpenShift Container Platform 3.11 product documentation.

  • The OpenShift project for the deployment is created.
  • You are logged into the project using the oc command. For more information about the oc command-line tool, see the OpenShift CLI Reference. If you want to use the OpenShift Web console to deploy templates, you must also be logged on using the Web console.
  • Dynamic persistent volume (PV) provisioning is enabled. Alternatively, if dynamic PV provisioning is not enabled, enough persistent volumes must be available. By default, the deployed components require the following PV sizes:

    • The replicated set of KIE Server pods requires one 1Gi PV for the database by default. You can change the database PV size in the template parameters. This requirement does not apply if you use an external database server.
    • Business Central requires one 1Gi PV by default. You can change the PV size for Business Central persistent storage in the template parameters.
  • If you intend to scale any of the Business Central or Business Central Monitoring pods, your OpenShift environment supports persistent volumes with ReadWriteMany mode. If your environment does not support this mode, you can use NFS to provision the volumes. However, for best performance and reliability, use GlusterFS to provision persistent volumes for a high-availability authoring environment. For information about access mode support in OpenShift public and dedicated clouds, see Access Modes.
Note

Since Red Hat Process Automation Manager version 7.5, images and templates for Red Hat OpenShift Container Platform 3.x are deprecated. These images and templates do not get new features, but remain supported until the end of full support for Red Hat OpenShift Container Platform 3.x. For more information about the full support lifecycle phase for Red Hat OpenShift Container Platform 3.x, see Red Hat OpenShift Container Platform Life Cycle Policy (non-current versions).

Note

Do not use Red Hat Process Automation Manager templates with Red Hat OpenShift Container Platform 4.x. To deploy Red Hat Process Automation Manager on Red Hat OpenShift Container Platform 4.x, see the instructions in Deploying a Red Hat Process Automation Manager environment on Red Hat OpenShift Container Platform 4 using Operators.

Chapter 6. Overview of Red Hat Process Automation Manager on Red Hat OpenShift Container Platform

You can deploy Red Hat Process Automation Manager into a Red Hat OpenShift Container Platform environment.

In this solution, components of Red Hat Process Automation Manager are deployed as separate OpenShift pods. You can scale each of the pods up and down individually to provide as few or as many containers as required for a particular component. You can use standard OpenShift methods to manage the pods and balance the load.

The following key components of Red Hat Process Automation Manager are available on OpenShift:

  • KIE Server, also known as Execution Server, is the infrastructure element that runs decision services, process applications, and other deployable assets (collectively referred to as services) . All logic of the services runs on execution servers.

    A database server is normally required for KIE Server. You can provide a database server in another OpenShift pod or configure an execution server on OpenShift to use any other database server. Alternatively, KIE Server can use an H2 database; in this case, you cannot scale the pod.

    In some templates, you can scale up a KIE Server pod to provide as many copies as required, running on the same host or different hosts. As you scale a pod up or down, all of its copies use the same database server and run the same services. OpenShift provides load balancing and a request can be handled by any of the pods.

    You can deploy a separate KIE Server pod to run a different group of services. That pod can also be scaled up or down. You can have as many separate replicated KIE Server pods as required.

  • Business Central is a web-based interactive environment used for authoring services. It also provides a management and monitoring console. You can use Business Central to develop services and deploy them to KIE Servers. You can also use Business Central to monitor the execution of processes.

    Business Central is a centralized application. However, you can configure it for high availability, where multiple pods run and share the same data.

    Business Central includes a Git repository that holds the source for the services that you develop on it. It also includes a built-in Maven repository. Depending on configuration, Business Central can place the compiled services (KJAR files) into the built-in Maven repository or (if configured) into an external Maven repository.

  • Business Central Monitoring is a web-based management and monitoring console. It can manage the deployment of services to KIE Servers and provide monitoring information, but does not include authoring capabilities. You can use this component to manage staging and production environments.
  • Smart Router is an optional layer between KIE Servers and other components that interact with them. When your environment includes many services running on different KIE Servers, Smart Router provides a single endpoint to all client applications. A client application can make a REST API call that requires any service. Smart Router automatically calls the KIE Server that can process a particular request.

You can arrange these and other components into various environment configurations within OpenShift.

The following environment types are typical:

  • Trial: an environment for demonstration and evaluation of Red Hat Process Automation Manager. This environment includes Business Central and a KIE Server. You can set it up quickly and use it to evaluate or demonstrate developing and running assets. However, the environment does not use any persistent storage and any work you do in the environment is not saved.
  • Authoring: An environment for creating and modifying services using Business Central. It consists of pods that provide Business Central for the authoring work and a KIE Server for test execution of the services.
  • Managed deployment: An environment for running existing services for staging and production purposes. This environment includes several groups of KIE Server pods; you can deploy and undeploy services on every such group and also scale the group up or down as necessary. Use Business Central Monitoring to deploy, run, and stop the services and to monitor their execution.

    You can deploy two types of managed environment. In a freeform server environment, you initially deploy Business Central Monitoring and one KIE Server. You can additionally deploy any number of KIE Servers. Business Central Monitoring can connect to all servers in the same namespace.

    Alternatively, you can deploy a fixed managed server environment. A single deployment includes Business Central Monitoring, Smart Router, and a preset number of KIE Servers (by default, two servers, but you can modify the template to change the number). You cannot easily add or remove servers at a later time.

  • Deployment with immutable servers: An alternate environment for running existing services for staging and production purposes. In this environment, when you deploy a KIE Server pod, it builds an image that loads and starts a service or group of services. You cannot stop any service on the pod or add any new service to the pod. If you want to use another version of a service or modify the configuration in any other way, you deploy a new server image and displace the old one. In this system, the KIE Server runs like any other pod on the OpenShift environment; you can use any container-based integration workflows and do not need to use any other tools to manage the pods.

    Optionally, you can use Business Central Monitoring to monitor the performance of the environment and to stop and restart some of the service instances, but not to deploy additional services to any KIE Server or undeploy any existing ones (you cannot add or remove containers).

To deploy a Red Hat Process Automation Manager environment on OpenShift, you can use the templates that are provided with Red Hat Process Automation Manager. You can modify some of the templates to ensure that the configuration suits your environment.

6.1. Architecture of an authoring environment

In Red Hat Process Automation Manager, the Business Central component provides a web-based interactive user interface for authoring services. The KIE Server component runs the services.

The KIE Server uses a database server to store the state of process services.

You can also use Business Central to deploy services onto a KIE Server. You can use several KIE Servers to run different services and control the servers from the same Business Central.

Single authoring environment

In a single authoring environment, only one instance of Business Central is running. Multiple users can access its web interface at the same time, however the performance can be limited and there is no failover capability.

Business Central includes a built-in Maven repository that stores the built versions of the services that you develop (KJAR files/artifacts). You can use your continuous integration and continuous deployment (CICD) tools to retrieve these artifacts from the repository and move them as necessary.

Business Central saves the source code in a built-in Git repository, stored in the .niogit directory. It uses a built-in indexing mechanism to index the assets in your services.

Business Central uses persistent storage for the Maven repository and for the Git repository.

A single authoring environment, by default, includes one KIE Server. This KIE Server uses a built-in H2 database engine to store the state of process services.

A single authoring environment, by default, uses the controller strategy. Business Central includes the Controller, a component that can manage KIE Servers. When you configure a KIE Server to connect to Business Central, the KIE Server uses a REST API to connect to the Controller. This connection opens a persistent WebSocket. In an OpenShift deployment that uses the controller strategy, each KIE Server is initially configured to connect to the Business Central Controller.

When you use the Business Central user interface to deploy or manage a service on the KIE Server, the KIE Server receives the request through the Controller connection WebSocket. To deploy a service, the KIE Server requests the necessary artifact from the Maven repository that is a part of Business Central.

Client applications use a REST API to use services that run on the KIE Server.

Figure 6.1. Architecture diagram for a single authoring environment

Clustering KIE Servers and using multiple KIE Servers

You can scale a KIE Server pod to run a clustered KIE Server environment. To scale a KIE Server, you must ensure that it uses a database server in a separate pod or an external database server, and not a built-in H2 database engine.

In a clustered deployment, several instances of the KIE Server run the same services. These servers can connect to the Business Central Controller using the same server ID, so they can receive the same requests from the controller. Red Hat OpenShift Container Platform provides load-balancing between the servers. Decision services and business optimizer services that run on a clustered KIE Server must be stateless, because requests from the same client might be processed by different instances.

You can also deploy several independent KIE Servers to run different services. In this case, the servers connect to the Business Central Controller with different server ID values. You can use the Business Central UI to deploy services to each of the servers.

Smart Router

The optional Smart Router component provides a layer between client applications and KIE Servers. It can be useful if you are using several independent KIE Servers.

The client application can use services running on different KIE Servers, but always connects to the Smart Router. The Smart Router automatically passes the request to the KIE Servers that runs the required service. The Smart Router also enables management of service versions and provides an additional load-balancing layer.

High-availability authoring environment

In a high-availability (HA) authoring environment, the Business Central pod is scaled, so several instances of Business Central are running. Red Hat OpenShift Container Platform provides load balancing for user requests. This environment provides optimal performance for multiple users and supports failover.

Each instance of Business Central includes the Maven repository for the built artifacts and uses the .niogit Git repository for source code. The instances use shared persistent storage for the repositories. A persistent volume with ReadWriteMany access is required for this storage.

An instance of Red Hat DataGrid provides indexing of all projects and assets developed in Business Central.

An instance of Red Hat AMQ propagates Java CDI messages between all instances of Business Central. For example, when a new project is created or when an asset is locked or modified on one of the instances, this information is immediately reflected in all other instances.

The controller strategy is not suitable for clustered deployment. In an OpenShift deployment, a high-availability Business Central must manage KIE Servers using the OpenShift startup strategy.

Each KIE Server deployment (which can be scaled) creates a ConfigMap that reflects its current state. The Business Central discovers all KIE Servers by reading their ConfigMaps.

When the user requests a change in KIE Server configuration (for example, deploys or undeploys a service), Business Central initiates a connection to the KIE Server and sends a REST API request. The KIE Server changes the ConfigMap to reflect the new configuration state and then triggers its own redeployment, so that all instances are redeployed and reflect the new configuration.

You can deploy several independent KIE Servers in your OpenShift environment. Each of the KIE Servers has a separate ConfigMap with the necessary configuration. You can scale each of the KIE Servers separately.

You can include Smart Router in the OpenShift deployment.

Figure 6.2. Architecture diagram for a high-availability authoring environment

Chapter 7. Preparation for deploying Red Hat Process Automation Manager in your OpenShift environment

Before deploying Red Hat Process Automation Manager in your OpenShift environment, you must complete several procedures. You do not need to repeat these procedures if you want to deploy additional images, for example, for new versions of processes or for other processes.

Note

If you are deploying a trial environment, complete the procedure described in Section 7.1, “Ensuring the availability of image streams and the image registry” and do not complete any other preparation procedures.

7.1. Ensuring the availability of image streams and the image registry

To deploy Red Hat Process Automation Manager components on Red Hat OpenShift Container Platform, you must ensure that OpenShift can download the correct images from the Red Hat registry. To download the images, OpenShift requires image streams, which contain the information about the location of images. OpenShift also must be configured to authenticate with the Red Hat registry using your service account user name and password.

Some versions of the OpenShift environment include the required image streams. You must check if they are available. If image streams are available in OpenShift by default, you can use them if the OpenShift infrastructure is configured for registry authentication server. The administrator must complete the registry authentication configuration when installing the OpenShift environment.

Otherwise, you can configure registry authentication in your own project and install the image streams in that project.

Procedure

  1. Determine whether Red Hat OpenShift Container Platform is configured with the user name and password for Red Hat registry access. For details about the required configuration, see Configuring a Registry Location. If you are using an OpenShift Online subscription, it is configured for Red Hat registry access.
  2. If Red Hat OpenShift Container Platform is configured with the user name and password for Red Hat registry access, enter the following commands:

    $ oc get imagestreamtag -n openshift | grep -F rhpam-businesscentral | grep -F 7.10
    $ oc get imagestreamtag -n openshift | grep -F rhpam-kieserver | grep -F 7.10

    If the outputs of both commands are not empty, the required image streams are available in the openshift namespace and no further action is required.

  3. If the output of one or both of the commands is empty or if OpenShift is not configured with the user name and password for Red Hat registry access, complete the following steps:

    1. Ensure you are logged in to OpenShift with the oc command and that your project is active.
    2. Complete the steps documented in Registry Service Accounts for Shared Environments. You must log in to the Red Hat Customer Portal to access the document and to complete the steps to create a registry service account.
    3. Select the OpenShift Secret tab and click the link under Download secret to download the YAML secret file.
    4. View the downloaded file and note the name that is listed in the name: entry.
    5. Enter the following commands:

      oc create -f <file_name>.yaml
      oc secrets link default <secret_name> --for=pull
      oc secrets link builder <secret_name> --for=pull

      Replace <file_name> with the name of the downloaded file and <secret_name> with the name that is listed in the name: entry of the file.

    6. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page and extract the rhpam710-image-streams.yaml file.
    7. Enter the following command:

      $ oc apply -f rhpam710-image-streams.yaml
      Note

      If you complete these steps, you install the image streams into the namespace of your project. In this case, when you deploy the templates, you must set the IMAGE_STREAM_NAMESPACE parameter to the name of this project.

7.2. Creating the secrets for KIE Server

OpenShift uses objects called secrets to hold sensitive information such as passwords or keystores. For more information about OpenShift secrets, see the Secrets chapter in the Red Hat OpenShift Container Platform documentation.

You must create an SSL certificate for HTTP access to KIE Server and provide it to your OpenShift environment as a secret.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for KIE Server.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named kieserver-app-secret from the new keystore file:

    $ oc create secret generic kieserver-app-secret --from-file=keystore.jks

7.3. Creating the secrets for Business Central

If your environment includes Business Central or Business Central Monitoring, you must create an SSL certificate for HTTP access to Business Central and provide it to your OpenShift environment as a secret.

Do not use the same certificate and keystore for Business Central and KIE Server.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for Business Central.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named businesscentral-app-secret from the new keystore file:

    $ oc create secret generic businesscentral-app-secret --from-file=keystore.jks

7.4. Creating the secrets for Smart Router

If your environment includes Smart Router, you must create an SSL certificate for HTTP access to Smart Router and provide it to your OpenShift environment as a secret.

Do not use the same certificate and keystore for Smart Router as the ones used for KIE Server or Business Central.

Procedure

  1. Generate an SSL keystore named keystore.jks with a private and public key for SSL encryption for KIE Server. For more information on how to create a keystore with self-signed or purchased SSL certificates, see Generate a SSL Encryption Key and Certificate.

    Note

    In a production environment, generate a valid signed certificate that matches the expected URL for Smart Router.

  2. Record the name of the certificate. The default value for this name in Red Hat Process Automation Manager configuration is jboss.
  3. Record the password of the keystore file. The default value for this name in Red Hat Process Automation Manager configuration is mykeystorepass.
  4. Use the oc command to generate a secret named smartrouter-app-secret from the new keystore file:

    $ oc create secret generic smartrouter-app-secret --from-file=keystore.jks

7.5. Creating the secret for the administrative user

You must create a generic secret that contains the user name and password for a Red Hat Process Automation Manager administrative user account. This secret is required for deploying Red Hat Process Automation Manager using any template except the trial template.

The secret must contain the user name and password as literals. The key name for the user name is KIE_ADMIN_USER. The key name for the password is KIE_ADMIN_PWD.

If you are using multiple templates to deploy components of Red Hat Process Automation Manager, use the same secret for all these deployments. The components utilize this user account to communicate with each other.

If your environment includes Business Central or Business Central Monitoring, you can also use this user account to log in to Business Central or Business Central Monitoring.

Important

If you use RH-SSO or LDAP authentication, the same user with the same password must be configured in your authentication system with the kie-server,rest-all,admin roles for Red Hat Process Automation Manager.

Procedure

Use the oc command to generate a generic secret named kie-admin-user-secret from the user name and password:

$ oc create secret generic rhpam-credentials --from-literal=KIE_ADMIN_USER=adminUser --from-literal=KIE_ADMIN_PWD=adminPassword

In this command, replace adminPassword with the password for the administrative user. Optionally, you can replace adminUser with another user name for the administrative user.

7.6. Changing GlusterFS configuration

If you are deploying an authoring environment, you must check whether your OpenShift environment uses GlusterFS to provide permanent storage volumes. If it uses GlusterFS, to ensure optimal performance of Business Central, you must tune your GlusterFS storage by changing the storage class configuration.

Procedure

  1. To check whether your environment uses GlusterFS, enter the following command:

    oc get storageclass

    In the results, check whether the (default) marker is on the storage class that lists glusterfs. For example, in the following output the default storage class is gluster-container, which does list glusterfs:

    NAME              PROVISIONER                       AGE
    gluster-block     gluster.org/glusterblock          8d
    gluster-container (default) kubernetes.io/glusterfs 8d

    If the result has a default storage class that does not list glusterfs or if the result is empty, you do not need to make any changes. In this case, skip the rest of this procedure.

  2. To save the configuration of the default storage class into a YAML file, enter the following command:

    oc get storageclass <class-name> -o yaml >storage_config.yaml

    Replace <class-name> with the name of the default storage class. Example:

    oc get storageclass gluster-container -o yaml >storage_config.yaml
  3. Edit the storage_config.yaml file:

    1. Remove the lines with the following keys:

      • creationTimestamp
      • resourceVersion
      • selfLink
      • uid
    2. If you are planning to use Business Central only as a single pod, without high-availability configuration, on the line with the volumeoptions key, add the following options:

      features.cache-invalidation on
      performance.nl-cache on

      For example:

      volumeoptions: client.ssl off, server.ssl off, features.cache-invalidation on, performance.nl-cache on

    3. If you are planning to use Business Central in a high-availability configuration, on the line with the volumeoptions key, add the following options:

      features.cache-invalidation on
      nfs.trusted-write on
      nfs.trusted-sync on
      performance.nl-cache on
      performance.stat-prefetch off
      performance.read-ahead off
      performance.write-behind off
      performance.readdir-ahead off
      performance.io-cache off
      performance.quick-read off
      performance.open-behind off
      locks.mandatory-locking off
      performance.strict-o-direct on

      For example:

      volumeoptions: client.ssl off, server.ssl off, features.cache-invalidation on, nfs.trusted-write on, nfs.trusted-sync on, performance.nl-cache on, performance.stat-prefetch off, performance.read-ahead off, performance.write-behind off, performance.readdir-ahead off, performance.io-cache off, performance.quick-read off, performance.open-behind off, locks.mandatory-locking off, performance.strict-o-direct on

  4. To remove the existing default storage class, enter the following command:

    oc delete storageclass <class-name>

    Replace <class-name> with the name of the default storage class. Example:

    oc delete storageclass gluster-container
  5. To re-create the storage class using the new configuration, enter the following command:

    oc create -f storage_config.yaml

7.7. Provisioning persistent volumes with ReadWriteMany access mode using NFS

If you want to deploy Business Central Monitoring or high-availability Business Central, your environment must provision persistent volumes with ReadWriteMany access mode.

Note

If you want to deploy a high-availability authoring environment, for optimal performance and reliability, provision persistent volumes using GlusterFS. Configure the GlusterFS storage class as described in Section 7.6, “Changing GlusterFS configuration”.

If your configuration requires provisioning persistent volumes with ReadWriteMany access mode but your environment does not support such provisioning, use NFS to provision the volumes. Otherwise, skip this procedure.

Procedure

Deploy an NFS server and provision the persistent volumes using NFS. For information about provisioning persistent volumes using NFS, see the "Persistent storage using NFS" section of the Configuring Clusters guide in the Red Hat OpenShift Container Platform 3.11 documentation.

7.8. Extracting the source code from Business Central for use in an S2I build

If you are planning to create immutable KIE servers using the source-to-image (S2I) process, you must provide the source code for your services in a Git repository. If you are using Business Central for authoring services, you can extract the source code for your service and place it into a separate Git repository, such as GitHub or an on-premise installation of GitLab, for use in the S2I build.

Skip this procedure if you are not planning to use the S2I process or if you are not using Business Central for authoring services.

Procedure

  1. Use the following command to extract the source code:

    git clone https://<business-central-host>:443/git/<MySpace>/<MyProject>

    In this command, replace the following variables:

    • <business-central-host> with the host on which Business Central is running
    • <MySpace> with the name of the Business Central space in which the project is located
    • <MyProject> with the name of the project
    Note

    To view the full Git URL for a project in Business Central, click MenuDesign<MyProject>Settings.

    Note

    If you are using self-signed certificates for HTTPS communication, the command might fail with an SSL certificate problem error message. In this case, disable SSL certificate verification in git, for example, using the GIT_SSL_NO_VERIFY environment variable:

    env GIT_SSL_NO_VERIFY=true git clone https://<business-central-host>:443/git/<MySpace>/<MyProject>
  2. Upload the source code to another Git repository, such as GitHub or GitLab, for the S2I build.

7.9. Preparing a Maven mirror repository for offline use

If your Red Hat OpenShift Container Platform environment does not have outgoing access to the public Internet, you must prepare a Maven repository with a mirror of all the necessary artifacts and make this repository available to your environment.

Note

You do not need to complete this procedure if your Red Hat OpenShift Container Platform environment is connected to the Internet.

Prerequisites

  • A computer that has outgoing access to the public Internet is available.

Procedure

  1. Configure a Maven release repository to which you have write access. The repository must allow read access without authentication and your OpenShift environment must have network access to this repository.

    You can deploy a Nexus repository manager in the OpenShift environment. For instructions about setting up Nexus on OpenShift, see Setting up Nexus in the Red Hat OpenShift Container Platform 3.11 documentation.

    Use this repository as a mirror to host the publicly available Maven artifacts. You can also provide your own services in this repository in order to deploy these services on immutable servers or to deploy them on managed servers using Business Central monitoring.

  2. On the computer that has an outgoing connection to the public Internet, complete the following steps:
  3. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

    • Product: Red Hat Process Automation Manager
    • Version: 7.10

      1. Download and extract the Red Hat Process Automation Manager 7.10.0 Offliner Content List (rhpam-7.10.0-offliner.zip) product deliverable file.
      2. Extract the contents of the rhpam-7.10.0-offliner.zip file into any directory.
      3. Change to the directory and enter the following command:

        ./offline-repo-builder.sh offliner.txt

        This command creates the repository subdirectory and downloads the necessary artifacts into this subdirectory. This is the mirror repository.

        If a message reports that some downloads have failed, run the same command again. If downloads fail again, contact Red Hat support.

      4. Upload all artifacts from the repository subdirectory to the Maven mirror repository that you prepared. You can use the Maven Repository Provisioner utility, available from the Maven repository tools Git repository, to upload the artifacts.
  4. If you developed services outside of Business Central and they have additional dependencies, add the dependencies to the mirror repository. If you developed the services as Maven projects, you can use the following steps to prepare these dependencies automatically. Complete the steps on the computer that has an outgoing connection to the public Internet.

    1. Create a backup of the local Maven cache directory (~/.m2/repository) and then clear the directory.
    2. Build the source of your projects using the mvn clean install command.
    3. For every project, enter the following command to ensure that Maven downloads all runtime dependencies for all the artifacts generated by the project:

      mvn -e -DskipTests dependency:go-offline -f /path/to/project/pom.xml --batch-mode -Djava.net.preferIPv4Stack=true

      Replace /path/to/project/pom.xml with the path of the pom.xml file of the project.

    4. Upload all artifacts from the local Maven cache directory (~/.m2/repository) to the Maven mirror repository that you prepared. You can use the Maven Repository Provisioner utility, available from the Maven repository tools Git repository, to upload the artifacts.

7.10. Building a custom KIE Server extension image for an external database

If you want to use an external database server for a KIE Server and the database server is not a MySQL or PostgreSQL server, you must build a custom KIE Server extension image with drivers for this server before deploying your environment.

Complete the steps in this build procedure to provide drivers for any of the following database servers:

  • Microsoft SQL Server
  • IBM DB2
  • Oracle Database
  • Sybase

Optionally, you can use this procedure to build a new version of drivers for any of the following database servers:

  • MySQL
  • MariaDB
  • PostgreSQL

For the supported versions of the database servers, see Red Hat Process Automation Manager 7 Supported Configurations.

The build procedure creates a custom extension image that extends the existing KIE Server image. You must import this custom extension image into your OpenShift environment and then reference it in the EXTENSIONS_IMAGE parameter.

Prerequisites

  • You are logged in to your OpenShift environment using the oc command. Your OpenShift user must have the registry-editor role.
  • For Oracle Database, IBM DB2, or Sybase, you downloaded the JDBC driver from the database server vendor.
  • You have installed the following required software:

    • Docker: For installation instructions, see Get Docker.
    • Cekit version 3.2: For installation instructions, see Installation.
    • The following libraries and extensions for Cekit. For more information, see Dependencies.

      • docker, provided by the python3-docker package or similar package
      • docker-squash, provided by the python3-docker-squash package or similar package
      • behave, provided by the python3-behave package or similar package

Procedure

  1. For IBM DB2, Oracle Database, or Sybase, provide the JDBC driver JAR file in a local directory.
  2. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  3. Unzip the file and, using the command line, change to the templates/contrib/jdbc/cekit directory of the unzipped file. This directory contains the source code for the custom build.
  4. Enter one of the following commands, depending on the database server type:

    • For Microsoft SQL Server:

      make mssql
    • For MySQL:

      make mysql
    • For PostgreSQL:

      make postgresql
    • For MariaDB:

      make mariadb
    • For IBM DB2:

      make db2 artifact=/tmp/db2jcc4.jar version=10.2

      In this command, replace /tmp/db2jcc4.jar with the path name of the IBM DB2 driver and 10.2 with the version of the driver.

    • For Oracle Database:

      make oracle artifact=/tmp/ojdbc7.jar version=7.0

      In this command, replace /tmp/ojdbc7.jar with the path name of the Oracle Database driver and 7.0 with the version of the driver.

    • For Sybase:

      make build sybase artifact=/tmp/jconn4-16.0_PL05.jar version=16.0_PL05

      In this command, replace /tmp/jconn4-16.0_PL05.jar with the path name of the downloaded Sybase driver and 16.0_PL05 with the version of the driver.

      Alternatively, if you need to update the driver class or driver XA class for the Sybase driver, you can set the DRIVER_CLASS or DRIVER_XA_CLASS variable for this command, for example:

      export DRIVER_CLASS=another.class.Sybase && make sybase artifact=/tmp/jconn4-16.0_PL05.jar version=16.0_PL05
  5. Enter the following command to list the Docker images that are available locally:

    docker images

    Note the name of the image that was built, for example, jboss-kie-db2-extension-openshift-image, and the version tag of the image, for example, 11.1.4.4 (not the latest tag).

  6. Access the registry of your OpenShift environment directly and push the image to the registry. Depending on your user permissions, you can push the image into the openshift namespace or into a project namespace. For instructions about accessing the registry and pushing the images, see Accessing the Registry Directly in the Red Hat OpenShift Container Platform product documentation.
  7. When configuring your KIE Server deployment with a template that supports an external database server, set the following parameters:

    • Drivers Extension Image (EXTENSIONS_IMAGE): The ImageStreamTag definition of the extension image, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    • Drivers ImageStream Namespace (EXTENSIONS_IMAGE_NAMESPACE): The namespace to which you uploaded the extension image, for example, openshift or your project namespace.

Chapter 8. Trial environment

You can deploy a trial (evaluation) Red Hat Process Automation Manager environment. It consists of Business Central for authoring or managing services and KIE Server for test execution of services.

This environment does not include permanent storage. Assets that you create or modify in a trial environment are not saved.

This environment is intended for test and demonstration access. It supports cross-origin resource sharing (CORS). This means that KIE Server endpoints can be accessed using a browser when other resources on the page are provided by other servers. KIE Server endpoints are normally intended for REST calls, but browser access can be needed in some demonstration configurations.

8.1. Deploying a trial environment

The procedure to deploy a trial environment is minimal. There are no required settings and all passwords are set to a single value. The default password is RedHat.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the rhpam710-trial-ephemeral.yaml template file.
  3. Use one of the following methods to deploy the template:

    • In the OpenShift Web UI, select Add to Project → Import YAML / JSON and then select or paste the rhpam710-trial-ephemeral.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/rhpam710-trial-ephemeral.yaml

      In this command line, replace <template-path> with the path to the downloaded template file.

  4. Optional: Set any parameters as described in the template. A typical trial deployment requires only the following parameter:

  5. Complete the creation of the environment, depending on the method that you are using:

    • In the OpenShift Web UI, click Create.

      • A This will create resources that may have security or project behavior implications pop-up message might be displayed. If it is displayed, click Create Anyway.
    • Complete and run the command line.

Chapter 9. Authoring environment

You can deploy an environment for creating and modifying processes using Business Central. It consists of Business Central for the authoring work and KIE Server for test execution of the processes. If necessary, you can connect additional KIE Servers to the Business Central.

Depending on your needs, you can deploy either a single authoring environment template or a high-availability (HA) authoring environment template.

A single authoring environment contains two pods. One of the pods runs Business Central, the other runs KIE Server. The KIE Server by default includes an embedded H2 database engine. This environment is most suitable for single-user authoring or when your OpenShift infrastructure has limited resources. It does not require persistent volumes that support the ReadWriteMany access mode.

In a single authoring environment, you cannot scale Business Central. By default, you also cannot scale KIE Server, as the H2 database engine does not support scaling. However, you can modify the template to use a separate MySQL or PostgreSQL database server pod; in this case, you can scale KIE Server. For instructions about modifying the single authoring environment template, see Section 9.3, “Modifying the template for the single authoring environment”.

In an HA authoring environment, both Business Central and KIE Server are provided in scalable pods. When pods are scaled, persistent storage is shared between the copies. The database is provided by a separate pod.

To enable high-availability functionality in Business Central, additional pods with AMQ and Data Grid are required. These pods are configured and deployed by the high-availability authoring template. Use a high-availability authoring environment to provide maximum reliability and responsiveness, especially if several users are involved in authoring at the same time.

In the current version of Red Hat Process Automation Manager, an HA authoring environment is supported with certain limitations:

  • If a Business Central pod crashes while a user works with it, the user can get an error message and then is redirected to another pod. Logging on again is not required.
  • If a Business Central pod crashes during a user operation, data that was not committed (saved) might be lost.
  • If a Business Central pod crashes during creation of a project, an unusable project might be created.
  • If a Business Central pod crashes during creation of an asset, the asset might be created but not indexed, so it cannot be used. The user can open the asset in Business Central and save it again to make it indexed.
  • When a user deploys a service to the KIE Server, the KIE Server deployment is rolled out again. Users can not deploy another service to the same KIE Server until the roll-out completes.

In a high-availability authoring environment you can also deploy additional managed or immutable KIE Servers, if required. Business Central can automatically discover any KIE Servers in the same namespace, including immutable KIE Servers and managed KIE Servers.

If you want to deploy additional managed or immutable KIE Servers in a single authoring environment, you must complete an additional manual step to enable the OpenShiftStartupStrategy setting in the environment, as described in ]. This setting enables the discovery of other KIE Servers.

For instructions about deploying managed KIE Servers, see Section 11.2, “Deploying an additional managed KIE Server for a freeform environment”.

For instructions about deploying immutable KIE Servers, see Section 10.2, “Deploying an immutable KIE Server using an S2I build” and Section 10.4, “Deploying an immutable KIE Server from KJAR services”.

9.1. Deploying an authoring environment

You can use OpenShift templates to deploy a single or high-availability authoring environment. This environment consists of Business Central and a single KIE Server.

9.1.1. Starting configuration of the template for an authoring environment

If you want to deploy a single authoring environment, use the rhpam710-authoring.yaml template file. By default, the single authoring template uses the H2 database with permanent storage. If you prefer to create a MySQL or PostgreSQL pod or to use an external database server (outside the OpenShift project), modify the template before deploying the environment. For instructions about modifying the template, see Section 9.3, “Modifying the template for the single authoring environment”.

If you want to deploy a high-availability authoring environment, use the rhpam710-authoring-ha.yaml template file. By default, the high-availability authoring template creates a MySQL pod to provide the database server for the KIE Server. If you prefer to use PostgreSQL or to use an external server (outside the OpenShift project) you need to modify the template before deploying the environment. You can also modify the template to change the number of replicas initially created for Business Central. For instructions about modifying the template, see Section 9.4, “Modifying the template for the High Availability authoring environment”.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the required template file.
  3. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the <template-file-name>.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/<template-file-name>.yaml -p BUSINESS_CENTRAL_HTTPS_SECRET=businesscentral-app-secret -p KIE_SERVER_HTTPS_SECRET=kieserver-app-secret -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Replace <template-file-name> with the name of the template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 9.1.2, “Setting required parameters for an authoring environment” to set common parameters. You can view the template file to see descriptions for all parameters.

9.1.2. Setting required parameters for an authoring environment

When configuring the template to deploy an authoring environment, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

9.1.3. Configuring the image stream namespace for an authoring environment

If you created image streams in a namespace that is not openshift, you must configure the namespace in the template.

If all image streams were already available in your Red Hat OpenShift Container Platform environment, you can skip this procedure.

Prerequisites

Procedure

If you installed an image streams file according to instructions in Section 7.1, “Ensuring the availability of image streams and the image registry”, set the ImageStream Namespace (IMAGE_STREAM_NAMESPACE) parameter to the name of your OpenShift project.

9.1.4. Setting an optional Maven repository for an authoring environment

When configuring the template to deploy an authoring environment, if you want to place the built KJAR files into an external Maven repository, you must set parameters to access the repository.

Prerequisites

Procedure

To configure access to a custom Maven repository, set the following parameters:

  • Maven repository URL (MAVEN_REPO_URL): The URL for the Maven repository.
  • Maven repository ID (MAVEN_REPO_ID): An identifier for the Maven repository. The default value is repo-custom.
  • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
  • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

Important

To export or push Business Central projects as KJAR artifacts to the external Maven repository, you must also add the repository information in the pom.xml file for every project. For information about exporting Business Central projects to an external repository, see Packaging and deploying a Red Hat Process Automation Manager project.

9.1.5. Configuring access to a Maven mirror in an environment without a connection to the public Internet for an authoring environment

When configuring the template to deploy an authoring environment, if your OpenShift environment does not have a connection to the public Internet, you must configure access to a Maven mirror that you set up according to Section 7.9, “Preparing a Maven mirror repository for offline use”.

Prerequisites

Procedure

To configure access to the Maven mirror, set the following parameters:

  • Maven mirror URL (MAVEN_MIRROR_URL): The URL for the Maven mirror repository that you set up in Section 7.9, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
  • Maven mirror of (MAVEN_MIRROR_OF): The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*,!repo-rhpamcentr; with this value, Maven retrieves artifacts from the built-in Maven repository of Business Central directly and retrieves any other required artifacts from the mirror. If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

    • If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.
    • If you configure a built-in Business Central Maven repository (BUSINESS_CENTRAL_MAVEN_SERVICE), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.
    • If you configure both repositories, change MAVEN_MIRROR_OF to exclude the artifacts in both repositories from the mirror: external:*,!repo-rhpamcentr,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

9.1.6. Configuring Business Central and KIE Server replicas for a high-availability authoring environment

If you are deploying a high-availability authoring environment, by default two replicas of Business Central and two replicas of the KIE Server are initially created.

Optionally, you can modify the number of replicas.

Skip this procedure for a single authoring environment.

Prerequisites

Procedure

To modify the numbers of initial replicas, set the following parameters:

  • Business Central Container Replicas (BUSINESS_CENTRAL_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for Business Central.
  • KIE Server Container Replicas (KIE_SERVER_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for the KIE Server.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

9.1.7. Specifying the Git hooks directory for an authoring environment

You can use Git hooks to facilitate interaction between the internal Git repository of Business Central and an external Git repository.

If you want to use Git hooks, you must configure a Git hooks directory.

Prerequisites

Procedure

To configure a Git hooks directory, set the following parameter:

  • Git hooks directory (GIT_HOOKS_DIR): The fully qualified path to a Git hooks directory, for example, /opt/kie/data/git/hooks. You must provide the content of this directory and mount it at the specified path. For instructions about providing and mounting the Git hooks directory using a configuration map or a persistent volume, see Section 13.1, “(Optional) Providing the Git hooks directory”.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

9.1.8. Configuring resource usage for a high-availability deployment

If you are deploying the high-availability template (rhpam710-authoring-ha.yaml), you can optionally configure resource usage to optimize performance for your requirements.

If you are deploying the single authoring environment template (rhpam710-authoring.yaml), skip this procedure.

For more information about sizing resources, see the following sections in the Red Hat OpenShift Container Platform 3.11 product documentation:

Prerequisites

Procedure

Set the following parameters of the template as applicable:

  • Business Central Container Memory Limit (BUSINESS_CENTRAL_MEMORY_LIMIT): The amount of memory requested in the OpenShift environment for the Business Central container. The default value is 8Gi.
  • Business Central JVM Max Memory Ratio (BUSINESS_CENTRAL_JAVA_MAX_MEM_RATIO): The percentage of container memory that is used for the Java Virtual Machine for Business Central. The remaining memory is used for the operating system. The default value is 80, for a limit of 80%.
  • Business Central Container CPU Limit (BUSINESS_CENTRAL_CPU_LIMIT): The maximum CPU usage for Business Central. The default value is 2000m.
  • KIE Server Container Memory Limit (KIE_SERVER_MEMORY_LIMIT): The amount of memory requested in the OpenShift environment for the KIE Server container. The default value is 1Gi.
  • KIE Server Container CPU Limit (KIE_SERVER_CPU_LIMIT): The maximum CPU usage for KIE Server. The default value is 1000m.
  • DataGrid Container Memory Limit (DATAGRID_MEMORY_LIMIT): The amount of memory requested in the OpenShift environment for the Red Hat Data Grid container. The default value is 2Gi.
  • DataGrid Container CPU Limit (DATAGRID_CPU_LIMIT): The maximum CPU usage for Red Hat Data Grid. The default value is 1000m.

9.1.9. Setting parameters for RH-SSO authentication for an authoring environment

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy an authoring environment.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

  • A realm for Red Hat Process Automation Manager is created in the RH-SSO authentication system.
  • User names and passwords for Red Hat Process Automation Manager are created in the RH-SSO authentication system. For a list of the available roles, see Chapter 14, Red Hat Process Automation Manager roles and users.

    You must create a user with the username and password configured in the secret for the administrative user, as described in Section 7.5, “Creating the secret for the administrative user”. This user must have the kie-server,rest-all,admin roles.

  • Clients are created in the RH-SSO authentication system for all components of the Red Hat Process Automation Manager environment that you are deploying. The client setup contains the URLs for the components. You can review and edit the URLs after deploying the environment. Alternatively, the Red Hat Process Automation Manager deployment can create the clients. However, this option provides less detailed control over the environment.
  • You started the configuration of the template, as described in Section 9.1.1, “Starting configuration of the template for an authoring environment”.

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central.
      • Business Central RH-SSO Client Secret (BUSINESS_CENTRAL_SSO_SECRET): The secret string that is set in RH-SSO for the client for Business Central.
      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The RH-SSO client name for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string that is set in RH-SSO for the client for KIE Server.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The name of the client to create in RH-SSO for Business Central.
      • Business Central RH-SSO Client Secret (BUSINESS_CENTRAL_SSO_SECRET): The secret string to set in RH-SSO for the client for Business Central.
      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The name of the client to create in RH-SSO for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string to set in RH-SSO for the client for KIE Server.
      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

9.1.10. Setting parameters for LDAP authentication for an authoring environment

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy an authoring environment.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

9.1.11. Setting parameters for using an external database server for an authoring environment

If you modified the template to use an external database server for the KIE Server, as described in Section 9.3, “Modifying the template for the single authoring environment” or Section 9.4, “Modifying the template for the High Availability authoring environment”, complete the following additional configuration when configuring the template to deploy an authoring environment.

Prerequisites

Procedure

  1. Set the following parameters:

    • KIE Server External Database Driver (KIE_SERVER_EXTERNALDB_DRIVER): The driver for the server, depending on the server type:

      • mysql
      • postgresql
      • mariadb
      • mssql
      • db2
      • oracle
      • sybase
    • KIE Server External Database User (KIE_SERVER_EXTERNALDB_USER) and KIE Server External Database Password (KIE_SERVER_EXTERNALDB_PWD): The user name and password for the external database server
    • KIE Server External Database URL (KIE_SERVER_EXTERNALDB_URL): The JDBC URL for the external database server

      Note

      If you are using the EntrepriseDB Postgres database server, use an URL starting with jdbc:postgresql:// and not with jdbc:edb://. Alternatively, do not set the URL and set the host and port parameters instead.

    • KIE Server External Database Host (KIE_SERVER_EXTERNALDB_SERVICE_HOST) and KIE Server External Database Port (KIE_SERVER_EXTERNALDB_SERVICE_PORT): The host name and port number of the external database server. You can set these parameters as an alternative to setting the KIE_SERVER_EXTERNALDB_URL parameter.
    • KIE Server External Database Dialect (KIE_SERVER_EXTERNALDB_DIALECT): The Hibernate dialect for the server, depending on the server type. The common settings are:

      • org.hibernate.dialect.MySQL5InnoDBDialect
      • org.hibernate.dialect.MySQL8Dialect
      • org.hibernate.dialect.MariaDB102Dialect
      • org.hibernate.dialect.PostgreSQL95Dialect
      • org.hibernate.dialect.PostgresPlusDialect (used for EntrepriseDB Postgres Advanced Server)
      • org.hibernate.dialect.SQLServer2012Dialect (used for MS SQL)
      • org.hibernate.dialect.DB2Dialect
      • org.hibernate.dialect.Oracle10gDialect
      • org.hibernate.dialect.SybaseASE15Dialect

        For a complete list of supported dialects, see the Hibernate SQL Dialects table in Hibernate properties in the Red Hat JBoss EAP documentation.

    • KIE Server External Database name (KIE_SERVER_EXTERNALDB_DB): The database name to use on the external database server
    • JDBC Connection Checker class (KIE_SERVER_EXTERNALDB_CONNECTION_CHECKER): The name of the JDBC connection checker class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
    • JDBC Exception Sorter class (KIE_SERVER_EXTERNALDB_EXCEPTION_SORTER): The name of the JDBC exception sorter class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
  2. If you created a custom image for using an external database server, as described in Section 7.10, “Building a custom KIE Server extension image for an external database”, set the following parameters:

    • Drivers Extension Image (EXTENSIONS_IMAGE): The ImageStreamTag definition of the extension image, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    • Drivers ImageStream Namespace (EXTENSIONS_IMAGE_NAMESPACE): The namespace to which you uploaded the extension image, for example, openshift or your project namespace.
  3. If you are using a MySQL version 8 external database server, enable the mysql_native_password plugin and use it for authentication. For instructions about this pluding, see Native Pluggable Authentication in the MySQL 8.0 Reference Manual.

    If you are using a MySQL version 8 image provided by Red Hat on Red Hat OpenShift Container Platform, to enable the plugin, set the MYSQL_DEFAULT_AUTHENTICATION_PLUGIN environment variable to mysql_native_password.

    If you created users on the MySQL version 8 server before enabling the mysql_native_password plugin, you must update the mysql-user table after you enable the plugin.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

9.1.12. Enabling Prometheus metric collection for an authoring environment

If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, enable support for this feature in KIE Server at deployment time.

Prerequisites

Procedure

To enable support for Prometheus metric collection, set the Prometheus Server Extension Disabled (PROMETHEUS_SERVER_EXT_DISABLED) parameter to false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 9.1.13, “Completing deployment of the template for an authoring environment”.

For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.

9.1.13. Completing deployment of the template for an authoring environment

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

9.2. Enabling the OpenShiftStartupStrategy setting to connect additional KIE Servers to Business Central

In an environment deployed using Red Hat Process Automation Manager authoring templates, Business Central manages one KIE Server. If you use the high-avalability authoring template or if you modified the single authoring template to use a database server other than an embedded H2 database, you can scale the KIE Server pod, but all the copies execute the same services.

You can connect additional KIE Servers to Business Central. However, if you deployed a single authoring environment using the rhpam710-authoring.yaml, you must enable the OpenShiftStartupStrategy setting in the environment. When OpenShiftStartupStrategy is enabled, Business Central automatically discovers KIE Servers in the same namespace and these KIE Servers can be configured to connect to the Business Central.

With the OpenShiftStartupStrategy setting, when a user deploys a service to the KIE Server, the KIE Server deployment is rolled out again. Users can not deploy another service to the same KIE Server until the roll-out completes. Because the roll-out might take noticeable time, the OpenShiftStartupStrategy setting might not be suitable for some authoring environments.

Do not complete this procedure if you deployed a high-availability authoring environment using the rhpam710-authoring-ha.yaml template. In this environment, the OpenShiftStartupStrategy setting is enabled by default.

Do not complete this procedure unless you want to connect additional KIE Servers to Business Central.

Prerequisites

  • You deployed an authoring environment using the rhpam710-authoring.yaml template.
  • You are logged in to the OpenShift project where the environment is deployed using the oc tool.

Procedure

  1. Enter the following command to view the deployment configurations that are deployed in the project:

    $ oc get dc
  2. In the output of the command, find the deployment configuration names for the Business Central and KIE Server pods:

    • The name of the deployment configuration for Business Central is myapp-rhpamcentr. Replace myapp with the application name of the environment, which is set in the APPLICATION_NAME parameter of the template.
    • The name of the deployment configuration for KIE Server is myapp-kieserver. Replace myapp with the application name.
  3. Enter the following commands to enable the OpenShiftStartupStrategy setting on the pods:

    $ oc env myapp-rhpamcentr KIE_SERVER_CONTROLLER_OPENSHIFT_ENABLED=true
    $ oc env myapp-kieserver KIE_SERVER_STARTUP_STRATEGY=OpenShiftStartupStrategy

    In these commands, replace myapp-rhpamcentr with the Business Central deployment configuration name and myapp-kieserver with the KIE Server deployment configuration name.

  4. When you enable the OpenShiftStartupStrategy setting, by default Business Central discovers only KIE Servers that are deployed with the same value of the APPLICATION_NAME parameter as the authoring template. If you want to connect KIE Servers with any other application names to the Business Central, enter the following command:

    $ oc env myapp-rhpamcentr KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED=true

    In this command, replace myapp-rhpamcentr with the Business Central deployment configuration name.

9.3. Modifying the template for the single authoring environment

By default, the single authoring template uses the H2 database with permanent storage. If you prefer to create a MySQL or PostgreSQL pod or to use an external database server (outside the OpenShift project), modify the template before deploying the environment.

You must use a MySQL or PostgreSQL pod or an external database server if you want to scale the KIE Server pod. An OpenShift template defines a set of objects that can be created by OpenShift. To change an environment configuration, you need to modify, add, or delete these objects. To simplify this task, comments are provided in the Red Hat Process Automation Manager templates.

Some comments mark blocks within the template, staring with BEGIN and ending with END. For example, the following block is named Sample block:

## Sample block BEGIN
sample line 1
sample line 2
sample line 3
## Sample block END

For some changes, you might need to replace a block in one template file with a block from another template file provided with Red Hat Process Automation Manager. In this case, delete the block, then paste the new block in its exact location.

Procedure

Edit the rhpam710-authoring.yaml template file to make any of the following changes as necessary.

  • If you want to use MySQL instead of the H2 database, you need to replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-mysql.yaml file that are also marked with comments. You also need to remove several other blocks and to add blocks in designated locations:

    1. Replace the block named H2 database parameters with the block named MySQL database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-mysql.yaml file.)
    2. Replace the block named H2 driver settings with the block named MySQL driver settings.
    3. Replace the block named H2 persistent volume claim with the block named MySQL persistent volume claim.
    4. Remove the blocks named H2 volume mount and H2 volume settings.
    5. Under the comment Place to add database service, add the block named MySQL service.
    6. Under the comment Place to add database deployment config, add the block named MySQL deployment config.
  • If you want to use PostgreSQL instead of the H2 database, you need to replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-postgresql.yaml file that are also marked with comments. You also need to remove several other blocks and to add blocks in designated locations:

    1. Replace the block named H2 database parameters with the block named PostgreSQL database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-postgresql.yaml file.)
    2. Replace the block named H2 driver settings with the block named PostgreSQL driver settings.
    3. Replace the block named H2 persistent volume claim with the block named PostgreSQL persistent volume claim.
    4. Remove the blocks named H2 volume mount and H2 volume settings.
    5. Under the comment Place to add database service, add the block named PostgreSQL service.
    6. Under the comment Place to add database deployment config, add the block named PostgreSQL deployment config.
  • If you want to use an external database server, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-externaldb.yaml file, and also remove some blocks:

    1. Replace the block named H2 database parameters with the block named External database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-externaldb.yaml file.)
    2. Replace the block named H2 driver settings with the block named External database driver settings.
    3. Remove the following blocks of the file, marked with comments from BEGIN to END:

      • H2 persistent volume claim
      • H2 volume mount
      • H2 volume settings
Important

The standard KIE Server image includes drivers for MySQL, MariaDB, and PostgreSQL external database servers. If you want to use another database server, you must build a custom KIE Server image. For instructions, see Section 7.10, “Building a custom KIE Server extension image for an external database”.

9.4. Modifying the template for the High Availability authoring environment

By default, the high-availability authoring template creates a MySQL pod to provide the database server for the KIE Server. If you prefer to use PostgreSQL or to use an external server (outside the OpenShift project), you need to modify the template before deploying the environment.

You can also modify the High Availability authoring template to change the number of replicas initially created for Business Central.

An OpenShift template defines a set of objects that can be created by OpenShift. To change an environment configuration, you need to modify, add, or delete these objects. To simplify this task, comments are provided in the Red Hat Process Automation Manager templates.

Some comments mark blocks within the template, staring with BEGIN and ending with END. For example, the following block is named Sample block:

## Sample block BEGIN
sample line 1
sample line 2
sample line 3
## Sample block END

For some changes, you might need to replace a block in one template file with a block from another template file provided with Red Hat Process Automation Manager. In this case, delete the block, then paste the new block in its exact location.

Procedure

Edit the rhpam710-authoring-ha.yaml template file to make any of the following changes as necessary.

  • If you want to use PostgreSQL instead of MySQL, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-postgresql.yaml file:

    1. Replace the block named MySQL database parameters with the block named PostgreSQL database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-postgresql.yaml file.)
    2. Replace the block named MySQL service with the block named PostgreSQL service.
    3. Replace the block named MySQL driver settings with the block named PostgreSQL driver settings.
    4. Replace the block named MySQL deployment config with the block named PostgreSQL deployment config.
    5. Replace the block named MySQL persistent volume claim with the block named PostgreSQL persistent volume claim.
  • If you want to use an external database server, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-externaldb.yaml file, and also remove some blocks:

    1. Replace the block named MySQL database parameters with the block named External database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-externaldb.yaml file.)
    2. Replace the block named MySQL driver settings with the block named External database driver settings.
    3. Remove the following blocks of the file, marked with comments from BEGIN to END:

      • MySQL service
      • MySQL deployment config
      • MySQL persistent volume claim
Important

The standard KIE Server image includes drivers for MySQL, MariaDB, and PostgreSQL external database servers. If you want to use another database server, you must build a custom KIE Server image. For instructions, see Section 7.10, “Building a custom KIE Server extension image for an external database”.

  • If you want to change the number of replicas initially created for Business Central, on the line below the comment ## Replicas for Business Central, change the number of replicas to the desired value.

Chapter 10. Environment with immutable servers

You can deploy an environment that includes one or more pods running immutable KIE Server with preloaded services. The database servers are, by default, also run in pods. Each KIE Server pod can be separately scaled as necessary.

On an immutable KIE Server, any services must be loaded onto the server at the time the image is created. You cannot deploy or undeploy services on a running immutable KIE Server. The advantage of this approach is that the KIE Server with the services in it runs like any other containerized service and does not require specialized management. The KIE Server runs like any other pod on the OpenShift environment; you can use any container-based integration workflows as necessary.

When you create a KIE Server image, you can build your services using S2I (Source to Image). Provide a Git repository with the source of your services and other business assets; if you develop the services or assets in Business Central, copy the source into a separate repository for the S2I build. OpenShift automatically builds the source, installs the services into the KIE Server image, and starts the containers with the services.

If you are using Business Central for authoring services, you can extract the source for your process and place it into a separate Git repository (such as GitHub or an on-premise installation of GitLab) for use in the S2I build.

Alternatively, you can create a similar KIE Server deployment using services that are already built as KJAR files. In this case, you must provide the services in a Maven repository. You can use the built-in repository of the Business Central or your own repository (for example, a Nexus deployment). When the server pod starts, it retrieves the KJAR services from the Maven repository. Services on the pod are never updated or changed. At every restart or scaling of the pod, the server retrieves the files from the repository, so you must ensure they do not change on the Maven repository to keep the deployment immutable.

With both methods of creating immutable images, no further management of the image is required. If you want to use a new version of a service, you can build a new image.

Optionally, you can add Business Central Monitoring and Smart Router to your environment. Use Business Central Monitoring to start, stop, and monitor services on KIE Servers.

10.1. Deploying Business Central Monitoring and Smart Router for an environment with immutable servers

You can deploy Business Central Monitoring and Smart Router for an environment with immutable servers.

You can use Business Central Monitoring to start and stop (but not deploy) services on your KIE Servers and to view monitoring data. The Business Central Monitoring automatically discovers any KIE Servers in the same namespace, including immutable KIE Servers and managed KIE Servers. This feature requires the OpenShiftStartupStrategy setting, which is enabled by default for all KIE Servers except those deployed in a fixed managed infrastructure. For instructions about deploying managed KIE Servers with the OpenShiftStartupStrategy setting enabled, see Section 11.2, “Deploying an additional managed KIE Server for a freeform environment”.

Smart Router is a single endpoint that can receive calls from client applications to any of your services and route each call automatically to the server that runs the service.

If you want to use Business Central Monitoring, you must provide a Maven repository. Your integration process must ensure that all the versions of KJAR files built into any KIE Server image are also available in the Maven repository.

10.1.1. Starting configuration of the template for monitoring and Smart Router

To deploy monitoring and Smart Router for an environment with immutable servers, use the rhpam710-immutable-monitor.yaml template file.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the rhpam710-immutable-monitor.yaml template file.
  3. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the rhpam710-immutable-monitor.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/rhpam710-immutable-monitor.yaml -p BUSINESS_CENTRAL_HTTPS_SECRET=businesscentral-app-secret -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 10.1.2, “Setting required parameters for monitoring and Smart Router” to set common parameters. You can view the template file to see descriptions for all parameters.

10.1.2. Setting required parameters for monitoring and Smart Router

When configuring the template to deploy monitoring and Smart Router for an environment with immutable servers, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

    • Credentials secret (CREDENTIALS_SECRET): The name of the secret containing the administrative user credentials, as created in Section 7.5, “Creating the secret for the administrative user”.
    • Business Central Monitoring Server Keystore Secret Name (BUSINESS_CENTRAL_HTTPS_SECRET): The name of the secret for Business Central, as created in Section 7.3, “Creating the secrets for Business Central”.
    • Smart Router Keystore Secret Name (KIE_SERVER_ROUTER_HTTPS_SECRET): The name of the secret for Smart Router, as created in Section 7.4, “Creating the secrets for Smart Router”.
    • Business Central Monitoring Server Certificate Name (BUSINESS_CENTRAL_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.3, “Creating the secrets for Business Central”.
    • Business Central Monitoring Server Keystore Password (BUSINESS_CENTRAL_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.3, “Creating the secrets for Business Central”.
    • Smart Router Certificate Name (KIE_SERVER_ROUTER_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.4, “Creating the secrets for Smart Router”.
    • Smart Router Keystore Password (KIE_SERVER_ROUTER_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.4, “Creating the secrets for Smart Router”.
    • Application Name (APPLICATION_NAME): The name of the OpenShift application. It is used in the default URLs for Business Central Monitoring and KIE Server. OpenShift uses the application name to create a separate set of deployment configurations, services, routes, labels, and artifacts.
    • Enable KIE server global discovery (KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED): Set this parameter to true if you want Business Central Monitoring to discover all KIE Servers with the OpenShiftStartupStrategy in the same namespace. By default, Business Central Monitoring discovers only KIE Servers that are deployed with the same value of the APPLICATION_NAME parameter as Business Central Monitoring itself.
    • Maven repository URL (MAVEN_REPO_URL): A URL for a Maven repository. You must upload all the processes (KJAR files) that are to be deployed on any KIE Servers in your environment into this repository.
    • Maven repository ID (MAVEN_REPO_ID): An identifier for the Maven repository. The default value is repo-custom.
    • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
    • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.
    • ImageStream Namespace (IMAGE_STREAM_NAMESPACE): The namespace where the image streams are available. If the image streams were already available in your OpenShift environment (see Section 7.1, “Ensuring the availability of image streams and the image registry”), the namespace is openshift. If you have installed the image streams file, the namespace is the name of the OpenShift project.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.1.6, “Completing deployment of the template for monitoring and Smart Router”.

10.1.3. Configuring the image stream namespace for monitoring and Smart Router

If you created image streams in a namespace that is not openshift, you must configure the namespace in the template.

If all image streams were already available in your Red Hat OpenShift Container Platform environment, you can skip this procedure.

Prerequisites

Procedure

If you installed an image streams file according to instructions in Section 7.1, “Ensuring the availability of image streams and the image registry”, set the ImageStream Namespace (IMAGE_STREAM_NAMESPACE) parameter to the name of your OpenShift project.

10.1.4. Setting parameters for RH-SSO authentication for monitoring and Smart Router

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy monitoring and Smart Router for an environment with immutable servers.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

  • A realm for Red Hat Process Automation Manager is created in the RH-SSO authentication system.
  • User names and passwords for Red Hat Process Automation Manager are created in the RH-SSO authentication system. For a list of the available roles, see Chapter 14, Red Hat Process Automation Manager roles and users.

    You must create a user with the username and password configured in the secret for the administrative user, as described in Section 7.5, “Creating the secret for the administrative user”. This user must have the kie-server,rest-all,admin roles.

  • Clients are created in the RH-SSO authentication system for all components of the Red Hat Process Automation Manager environment that you are deploying. The client setup contains the URLs for the components. You can review and edit the URLs after deploying the environment. Alternatively, the Red Hat Process Automation Manager deployment can create the clients. However, this option provides less detailed control over the environment.
  • You started the configuration of the template, as described in Section 10.1.1, “Starting configuration of the template for monitoring and Smart Router”.

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the client for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central Monitoring.
      • Business Central Monitoring RH-SSO Client Secret (BUSINESS_CENTRAL_SSO_SECRET): The secret string that is set in RH-SSO for the client for Business Central Monitoring.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The name of the client to create in RH-SSO for Business Central Monitoring.
      • Business Central Monitoring RH-SSO Client Secret (BUSINESS_CENTRAL_SSO_SECRET): The secret string to set in RH-SSO for the client for Business Central Monitoring.
      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.1.6, “Completing deployment of the template for monitoring and Smart Router”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

10.1.5. Setting parameters for LDAP authentication for monitoring and Smart Router

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy monitoring and Smart Router for an environment with immutable servers.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.1.6, “Completing deployment of the template for monitoring and Smart Router”.

10.1.6. Completing deployment of the template for monitoring and Smart Router

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

10.2. Deploying an immutable KIE Server using an S2I build

You can deploy an immutable KIE Server using an S2I build. When you deploy the server, the deployment procedure retrieves the source code for any services that must run on this server, builds the services, and includes them in the server image.

You cannot deploy or undeploy services on a running immutable KIE Server. You can use Business Central or Business Central Monitoring to view monitoring information. The KIE Server runs like any other pod on the OpenShift environment; you can use any container-based integration workflows as necessary.

You can enable JMS capabilities of the immutable KIE Server. With JMS capabilities you can interact with the server through JMS API using an external AMQ message broker.

By default, this server uses a PostgreSQL database server in a pod. To use a MySQL database server in a pod or an external database server, you can modify the template. For instructions about modifying the template, see Section 10.3, “Modifying the template for deploying an immutable KIE Server using S2I”.

If a Business Central or Business Central Monitoring is deployed in the same namespace, it discovers the immutable KIE Server automatically. You can use Business Central or Business Central Monitoring to start and stop (but not deploy) services on the immutable KIE Server and to view monitoring data.

10.2.1. Starting configuration of the template for an immutable KIE Server using S2I

To deploy an immutable KIE Server using an S2I build, use the rhpam710-prod-immutable-kieserver-amq.yaml template file if you want to enable JMS capabilities. Otherwise, use the rhpam710-prod-immutable-kieserver.yaml template file.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the required template file.
  3. By default, the template includes two KIE Servers. Each of the serves uses a PostgreSQL database server in a pod. To change the number of KIE Servers or to use a MySQL database server in a pod or an external database server, modify the template as described in Section 10.3, “Modifying the template for deploying an immutable KIE Server using S2I”.
  4. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the <template-file-name>.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/<template-file-name>.yaml -p KIE_SERVER_HTTPS_SECRET=kieserver-app-secret -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Replace <template-file-name> with the name of the template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 10.2.2, “Setting required parameters for an immutable KIE Server using S2I” to set common parameters. You can view the template file to see descriptions for all parameters.

10.2.2. Setting required parameters for an immutable KIE Server using S2I

When configuring the template to deploy an immutable KIE Server using an S2I build, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

    • Credentials secret (CREDENTIALS_SECRET): The name of the secret containing the administrative user credentials, as created in Section 7.5, “Creating the secret for the administrative user”.
    • KIE Server Keystore Secret Name (KIE_SERVER_HTTPS_SECRET): The name of the secret for KIE Server, as created in Section 7.2, “Creating the secrets for KIE Server”.
    • KIE Server Certificate Name (KIE_SERVER_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • KIE Server Keystore Password (KIE_SERVER_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • Application Name (APPLICATION_NAME): The name of the OpenShift application. It is used in the default URLs for Business Central Monitoring and KIE Server. OpenShift uses the application name to create a separate set of deployment configurations, services, routes, labels, and artifacts. You can deploy several applications using the same template into the same project, as long as you use different application names. Also, the application name determines the name of the server configuration (server template) that the KIE Server joins on Business Central or Business Central Monitoring. If you are deploying several KIE Servers, you must ensure each of the servers has a different application name.
    • KIE Server Container Deployment (KIE_SERVER_CONTAINER_DEPLOYMENT): The identifying information of the decision service (KJAR file) that the deployment must pull from the local or external repository after building your source. The format is <containerId>=<groupId>:<artifactId>:<version> or, if you want to specify an alias name for the container, <containerId>(<aliasId>)=<groupId>:<artifactId>:<version>. You can provide two or more KJAR files using the | separator, as illustrated in the following example:

      containerId=groupId:artifactId:version|c2(alias2)=g2:a2:v2

      To avoid duplicate container IDs, the artifact ID must be unique for each artifact built or used in your project.

    • Git Repository URL (SOURCE_REPOSITORY_URL): The URL for the Git repository that contains the source for your services.
    • Git Reference (SOURCE_REPOSITORY_REF): The branch in the Git repository.
    • Context Directory (CONTEXT_DIR): The path to the source within the project downloaded from the Git repository.
    • Artifact Directory (ARTIFACT_DIR): The path within the project that contains the required binary files (KJAR files and any other necessary files) after a successful Maven build. Normally this directory is the target directory of the build. However, you can provide prebuilt binaries in this directory in the Git repository.
    • ImageStream Namespace (IMAGE_STREAM_NAMESPACE): The namespace where the image streams are available. If the image streams were already available in your OpenShift environment (see Section 7.1, “Ensuring the availability of image streams and the image registry”), the namespace is openshift. If you have installed the image streams file, the namespace is the name of the OpenShift project.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.3. Configuring the image stream namespace for an immutable KIE Server using S2I

If you created image streams in a namespace that is not openshift, you must configure the namespace in the template.

If all image streams were already available in your Red Hat OpenShift Container Platform environment, you can skip this procedure.

Prerequisites

Procedure

If you installed an image streams file according to instructions in Section 7.1, “Ensuring the availability of image streams and the image registry”, set the ImageStream Namespace (IMAGE_STREAM_NAMESPACE) parameter to the name of your OpenShift project.

10.2.4. Configuring information about a Business Central or Business Central Monitoring instance for an immutable KIE Server using S2I

If you want to enable a connection from a Business Central or Business Central Monitoring instance in the same namespace to the KIE Server, you must configure information about the Business Central or Business Central Monitoring instance.

The Business Central or Business Central Monitoring instance must be configured with the same credentials secret (CREDENTIALS_SECRET) as the KIE Server.

Prerequisites

Procedure

  1. Set the following parameters:

    • Name of the Business Central service (BUSINESS_CENTRAL_SERVICE): The OpenShift service name for the Business Central or Business Central Monitoring.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.5. Setting an optional Maven repository for an immutable KIE Server using S2I

When configuring the template to deploy an immutable KIE Server using an S2I build, if your source build includes dependencies that are not available on the public Maven tree and require a separate custom Maven repository, you must set parameters to access the repository.

Prerequisites

Procedure

To configure access to a custom Maven repository, set the following parameters:

  • Maven repository URL (MAVEN_REPO_URL): The URL for the Maven repository.
  • Maven repository ID (MAVEN_REPO_ID): An identifier for the Maven repository. The default value is repo-custom.
  • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
  • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.6. Configuring access to a Maven mirror in an environment without a connection to the public Internet for an immutable KIE Server using S2I

When configuring the template to deploy an immutable KIE Server using an S2I build, if your OpenShift environment does not have a connection to the public Internet, you must configure access to a Maven mirror that you set up according to Section 7.9, “Preparing a Maven mirror repository for offline use”.

Prerequisites

Procedure

To configure access to the Maven mirror, set the following parameters:

  • Maven mirror URL (MAVEN_MIRROR_URL): The URL for the Maven mirror repository that you set up in Section 7.9, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
  • Maven mirror of (MAVEN_MIRROR_OF): The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

    • If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.
    • If you configure a built-in Business Central Maven repository (BUSINESS_CENTRAL_MAVEN_SERVICE), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.
    • If you configure both repositories, change MAVEN_MIRROR_OF to exclude the artifacts in both repositories from the mirror: external:*,!repo-rhpamcentr,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.7. Configuring communication with an AMQ server for an immutable KIE Server using S2I

If you use the rhpam710-prod-immutable-kieserver-amq.yaml template file, JMS capabilities of the KIE Server are enabled. You can interact with the server through JMS API, using an external AMQ message broker.

If necessary for your environment, you can modify the JMS configuration.

Prerequisites

Procedure

Set any of the following parameters as required for your environment:

  • AMQ Username (AMQ_USERNAME) and AMQ Password (AMQ_PASSWORD): The user name and password of a standard broker user, if user authentication in the broker is required in your environment.
  • AMQ Role (AMQ_ROLE): The user role for the standard broker user. The default role is admin.
  • AMQ Queues (AMQ_QUEUES): AMQ queue names, separated by commas. These queues are automatically created when the broker starts and are accessible as JNDI resources in the JBoss EAP server. If you use custom queue names, you must also set the same queue names in the KIE_SERVER_JMS_QUEUE_RESPONSE, KIE_SERVER_JMS_QUEUE_REQUEST, KIE_SERVER_JMS_QUEUE_SIGNAL, KIE_SERVER_JMS_QUEUE_AUDIT, and KIE_SERVER_JMS_QUEUE_EXECUTOR parameters.
  • AMQ Global Max Size (AMQ_GLOBAL_MAX_SIZE): The maximum amount of memory that message data can consume. If no value is specified, half of the memory available in the pod is allocated.
  • AMQ Protocols (AMQ_PROTOCOL): Broker protocols that the KIE Server can use to communicate with the AMQ server, separated by commas. Allowed values are openwire, amqp, stomp, and mqtt. Only openwire is supported by JBoss EAP. The default value is openwire.
  • AMQ Broker Image (AMQ_BROKER_IMAGESTREAM_NAME): The image stream name for the AMQ broker image.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.8. Setting parameters for RH-SSO authentication for an immutable KIE Server using S2I

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy an immutable KIE Server using an S2I build.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

  • A realm for Red Hat Process Automation Manager is created in the RH-SSO authentication system.
  • User names and passwords for Red Hat Process Automation Manager are created in the RH-SSO authentication system. For a list of the available roles, see Chapter 14, Red Hat Process Automation Manager roles and users.

    You must create a user with the username and password configured in the secret for the administrative user, as described in Section 7.5, “Creating the secret for the administrative user”. This user must have the kie-server,rest-all,admin roles.

  • Clients are created in the RH-SSO authentication system for all components of the Red Hat Process Automation Manager environment that you are deploying. The client setup contains the URLs for the components. You can review and edit the URLs after deploying the environment. Alternatively, the Red Hat Process Automation Manager deployment can create the clients. However, this option provides less detailed control over the environment.
  • You started the configuration of the template, as described in Section 10.2.1, “Starting configuration of the template for an immutable KIE Server using S2I”.

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the client for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central or Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central or Business Central Monitoring.
      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The RH-SSO client name for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string that is set in RH-SSO for the client for KIE Server.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The name of the client to create in RH-SSO for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string to set in RH-SSO for the client for KIE Server.
      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

10.2.9. Setting parameters for LDAP authentication for an immutable KIE Server using S2I

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy an immutable KIE Server using an S2I build.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.10. Setting parameters for using an external database server for an immutable KIE Server using S2I

If you modified the template to use an external database server for the KIE Server, as described in Section 10.3, “Modifying the template for deploying an immutable KIE Server using S2I”, complete the following additional configuration when configuring the template to deploy an immutable KIE Server using an S2I build.

Prerequisites

Procedure

  1. Set the following parameters:

    • KIE Server External Database Driver (KIE_SERVER_EXTERNALDB_DRIVER): The driver for the server, depending on the server type:

      • mysql
      • postgresql
      • mariadb
      • mssql
      • db2
      • oracle
      • sybase
    • KIE Server External Database User (KIE_SERVER_EXTERNALDB_USER) and KIE Server External Database Password (KIE_SERVER_EXTERNALDB_PWD): The user name and password for the external database server
    • KIE Server External Database URL (KIE_SERVER_EXTERNALDB_URL): The JDBC URL for the external database server

      Note

      If you are using the EntrepriseDB Postgres database server, use an URL starting with jdbc:postgresql:// and not with jdbc:edb://. Alternatively, do not set the URL and set the host and port parameters instead.

    • KIE Server External Database Host (KIE_SERVER_EXTERNALDB_SERVICE_HOST) and KIE Server External Database Port (KIE_SERVER_EXTERNALDB_SERVICE_PORT): The host name and port number of the external database server. You can set these parameters as an alternative to setting the KIE_SERVER_EXTERNALDB_URL parameter.
    • KIE Server External Database Dialect (KIE_SERVER_EXTERNALDB_DIALECT): The Hibernate dialect for the server, depending on the server type. The common settings are:

      • org.hibernate.dialect.MySQL5InnoDBDialect
      • org.hibernate.dialect.MySQL8Dialect
      • org.hibernate.dialect.MariaDB102Dialect
      • org.hibernate.dialect.PostgreSQL95Dialect
      • org.hibernate.dialect.PostgresPlusDialect (used for EntrepriseDB Postgres Advanced Server)
      • org.hibernate.dialect.SQLServer2012Dialect (used for MS SQL)
      • org.hibernate.dialect.DB2Dialect
      • org.hibernate.dialect.Oracle10gDialect
      • org.hibernate.dialect.SybaseASE15Dialect

        For a complete list of supported dialects, see the Hibernate SQL Dialects table in Hibernate properties in the Red Hat JBoss EAP documentation.

    • KIE Server External Database name (KIE_SERVER_EXTERNALDB_DB): The database name to use on the external database server
    • JDBC Connection Checker class (KIE_SERVER_EXTERNALDB_CONNECTION_CHECKER): The name of the JDBC connection checker class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
    • JDBC Exception Sorter class (KIE_SERVER_EXTERNALDB_EXCEPTION_SORTER): The name of the JDBC exception sorter class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
  2. If you created a custom image for using an external database server, as described in Section 7.10, “Building a custom KIE Server extension image for an external database”, set the following parameters:

    • Drivers Extension Image (EXTENSIONS_IMAGE): The ImageStreamTag definition of the extension image, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    • Drivers ImageStream Namespace (EXTENSIONS_IMAGE_NAMESPACE): The namespace to which you uploaded the extension image, for example, openshift or your project namespace.
  3. If you are using a MySQL version 8 external database server, enable the mysql_native_password plugin and use it for authentication. For instructions about this pluding, see Native Pluggable Authentication in the MySQL 8.0 Reference Manual.

    If you are using a MySQL version 8 image provided by Red Hat on Red Hat OpenShift Container Platform, to enable the plugin, set the MYSQL_DEFAULT_AUTHENTICATION_PLUGIN environment variable to mysql_native_password.

    If you created users on the MySQL version 8 server before enabling the mysql_native_password plugin, you must update the mysql-user table after you enable the plugin.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

10.2.11. Enabling Prometheus metric collection for an immutable KIE Server using S2I

If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, enable support for this feature in KIE Server at deployment time.

Prerequisites

Procedure

To enable support for Prometheus metric collection, set the Prometheus Server Extension Disabled (PROMETHEUS_SERVER_EXT_DISABLED) parameter to false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.2.12, “Completing deployment of the template for an immutable KIE Server using S2I”.

For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.

10.2.12. Completing deployment of the template for an immutable KIE Server using S2I

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

10.3. Modifying the template for deploying an immutable KIE Server using S2I

By default, the template for deploying an immutable server using S2I creates a separate PostgreSQL pod to provide the database server for each replicable KIE Server. If you prefer to use MySQL or an external server (outside the OpenShift project), modify the rhpam710-prod-immutable-kieserver.yaml or rhpam710-prod-immutable-kieserver-amq.yaml template file before deploying the server.

An OpenShift template defines a set of objects that can be created by OpenShift. To change an environment configuration, you need to modify, add, or delete these objects. To simplify this task, comments are provided in the Red Hat Process Automation Manager templates.

Some comments mark blocks within the template, staring with BEGIN and ending with END. For example, the following block is named Sample block:

## Sample block BEGIN
sample line 1
sample line 2
sample line 3
## Sample block END

For some changes, you might need to replace a block in one template file with a block from another template file provided with Red Hat Process Automation Manager. In this case, delete the block, then paste the new block in its exact location.

Procedure

  • If you want to use MySQL instead of PostgreSQL, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-mysql.yaml file:

    1. Replace the block named PostgreSQL database parameters with the block named MySQL database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-postgresql.yaml file.)
    2. Replace the block named PostgreSQL service with the block named MySQL service.
    3. Replace the block named PostgreSQL driver settings with the block named MySQL driver settings.
    4. Replace the block named PostgreSQL deployment config with the block named MySQL deployment config.
    5. Replace the block named PostgreSQL persistent volume claim with the block named MySQL persistent volume claim.
  • If you want to use an external database server, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-externaldb.yaml file, and also remove some blocks:

    1. Replace the block named PostgreSQL database parameters with the block named External database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-externaldb.yaml file.)
    2. Replace the block named PostgreSQL driver settings with the block named External database driver settings.
    3. Remove the following blocks of the file, marked with comments from BEGIN to END:

      • PostgreSQL service
      • PostgreSQL deployment config
      • PostgreSQL persistent volume claim
Important

The standard KIE Server image includes drivers for MySQL, MariaDB, and PostgreSQL external database servers. If you want to use another database server, you must build a custom KIE Server image. For instructions, see Section 7.10, “Building a custom KIE Server extension image for an external database”.

10.4. Deploying an immutable KIE Server from KJAR services

You can deploy an immutable KIE Server using services that are already built as KJAR files.

You must provide the services in a Maven repository. You can use the built-in repository of the Business Central or your own repository (for example, a Nexus deployment). When the server pod starts, it retrieves the KJAR services from the Maven repository. Services on the pod are never updated or changed. At every restart or scaling of the pod, the server retrieves the files from the repository, so you must ensure they do not change on the Maven repository to keep the deployment immutable.

You cannot deploy or undeploy services on a running immutable KIE Server. You can use Business Central or Business Central Monitoring to view monitoring information. The KIE Server runs like any other pod on the OpenShift environment; you can use any container-based integration workflows as necessary.

If a Business Central or Business Central Monitoring is deployed in the same namespace, it discovers the immutable KIE Server automatically. You can use Business Central or Business Central Monitoring to start and stop (but not deploy) services on the immutable KIE Server and to view monitoring data.

10.4.1. Starting configuration of the template for an immutable KIE Server from KJAR services

To deploy an immutable KIE Server from KJAR services, use one of the following template files:

  • rhpam710-kieserver-postgresql.yaml to use a PostgreSQL pod for persistent storage. Use this template unless you have a specific reason to use another template.
  • rhpam710-kieserver-mysql.yaml to use a MySQL pod for persistent storage.
  • rhpam710-kieserver-externaldb.yaml to use an external database server for persistent storage.

    Important

    The standard KIE Server image for an external database server includes drivers for MySQL and PostgreSQL external database servers. If you want to use another database server, you must build a custom KIE Server image. For instructions, see Section 7.10, “Building a custom KIE Server extension image for an external database”.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the required template file.
  3. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the <template-file-name>.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/<template-file-name>.yaml -p KIE_SERVER_HTTPS_SECRET=kieserver-app-secret -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Replace <template-file-name> with the name of the template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 10.4.2, “Setting required parameters for an immutable KIE Server from KJAR services” to set common parameters. You can view the template file to see descriptions for all parameters.

10.4.2. Setting required parameters for an immutable KIE Server from KJAR services

When configuring the template to deploy an immutable KIE Server from KJAR services, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

    • Credentials secret (CREDENTIALS_SECRET): The name of the secret containing the administrative user credentials, as created in Section 7.5, “Creating the secret for the administrative user”.
    • KIE Server Keystore Secret Name (KIE_SERVER_HTTPS_SECRET): The name of the secret for KIE Server, as created in Section 7.2, “Creating the secrets for KIE Server”.
    • KIE Server Certificate Name (KIE_SERVER_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • KIE Server Keystore Password (KIE_SERVER_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • Application Name (APPLICATION_NAME): The name of the OpenShift application. It is used in the default URLs for Business Central Monitoring and KIE Server. OpenShift uses the application name to create a separate set of deployment configurations, services, routes, labels, and artifacts. You can deploy several applications using the same template into the same project, as long as you use different application names. Also, the application name determines the name of the server configuration (server template) that the KIE Server joins on Business Central or Business Central Monitoring. If you are deploying several KIE Servers, you must ensure each of the servers has a different application name.
    • Maven repository URL (MAVEN_REPO_URL): A URL for a Maven repository. You must upload all the processes (KJAR files) that are to be deployed on the KIE Server into this repository.
    • Maven repository ID (MAVEN_REPO_ID): An identifier for the Maven repository. The default value is repo-custom.
    • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
    • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.
    • KIE Server Container Deployment (KIE_SERVER_CONTAINER_DEPLOYMENT): The identifying information of the decision services (KJAR files) that the deployment must pull from the Maven repository. The format is <containerId>=<groupId>:<artifactId>:<version> or, if you want to specify an alias name for the container, <containerId>(<aliasId>)=<groupId>:<artifactId>:<version>. You can provide two or more KJAR files using the | separator, as illustrated in the following example:

      containerId=groupId:artifactId:version|c2(alias2)=g2:a2:v2
    • KIE Server Mode (KIE_SERVER_MODE): In the rhpam710-kieserver-*.yaml templates the default value is PRODUCTION. In PRODUCTION mode, you cannot deploy SNAPSHOT versions of KJAR artifacts on the KIE Server and cannot change versions of an artifact in an existing container. To deploy a new version with PRODUCTION mode, create a new container on the same KIE Server. To deploy SNAPSHOT versions or to change versions of an artifact in an existing container, set this parameter to DEVELOPMENT.
    • ImageStream Namespace (IMAGE_STREAM_NAMESPACE): The namespace where the image streams are available. If the image streams were already available in your OpenShift environment (see Section 7.1, “Ensuring the availability of image streams and the image registry”), the namespace is openshift. If you have installed the image streams file, the namespace is the name of the OpenShift project.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

10.4.3. Configuring the image stream namespace for an immutable KIE Server from KJAR services

If you created image streams in a namespace that is not openshift, you must configure the namespace in the template.

If all image streams were already available in your Red Hat OpenShift Container Platform environment, you can skip this procedure.

Prerequisites

Procedure

If you installed an image streams file according to instructions in Section 7.1, “Ensuring the availability of image streams and the image registry”, set the ImageStream Namespace (IMAGE_STREAM_NAMESPACE) parameter to the name of your OpenShift project.

10.4.4. Configuring information about a Business Central or Business Central Monitoring instance for an immutable KIE Server from KJAR services

If you want to enable a connection from a Business Central or Business Central Monitoring instance in the same namespace to the KIE Server, you must configure information about the Business Central or Business Central Monitoring instance.

The Business Central or Business Central Monitoring instance must be configured with the same credentials secret (CREDENTIALS_SECRET) as the KIE Server.

Prerequisites

Procedure

  1. Set the following parameters:

    • Name of the Business Central service (BUSINESS_CENTRAL_SERVICE): The OpenShift service name for the Business Central or Business Central Monitoring.
  2. Ensure that the following settings are set to the same value as the same settings for the Business Central or Business Central Monitoring:

    • Maven repository URL (MAVEN_REPO_URL): A URL for the external Maven repository from which services must be deployed.
    • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
    • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

10.4.5. Configuring access to a Maven mirror in an environment without a connection to the public Internet for an immutable KIE Server from KJAR services

When configuring the template to deploy an immutable KIE Server from KJAR services, if your OpenShift environment does not have a connection to the public Internet, you must configure access to a Maven mirror that you set up according to Section 7.9, “Preparing a Maven mirror repository for offline use”.

Prerequisites

Procedure

To configure access to the Maven mirror, set the following parameters:

  • Maven mirror URL (MAVEN_MIRROR_URL): The URL for the Maven mirror repository that you set up in Section 7.9, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
  • Maven mirror of (MAVEN_MIRROR_OF): The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

    • If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.
    • If you configure a built-in Business Central Maven repository (BUSINESS_CENTRAL_MAVEN_SERVICE), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.
    • If you configure both repositories, change MAVEN_MIRROR_OF to exclude the artifacts in both repositories from the mirror: external:*,!repo-rhpamcentr,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

10.4.6. Setting parameters for RH-SSO authentication for an immutable KIE Server from KJAR services

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy an immutable KIE Server from KJAR services.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the client for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central or Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central or Business Central Monitoring.
      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The RH-SSO client name for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string that is set in RH-SSO for the client for KIE Server.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The name of the client to create in RH-SSO for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string to set in RH-SSO for the client for KIE Server.
      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

10.4.7. Setting parameters for LDAP authentication for an immutable KIE Server from KJAR services

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy an immutable KIE Server from KJAR services.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

10.4.8. Setting parameters for using an external database server for an immutable KIE Server from KJAR services

If you are using the rhpam710-kieserver-externaldb.yaml template to use an external database server for the KIE Server, complete the following additional configuration when configuring the template to deploy an immutable KIE Server from KJAR services.

Prerequisites

Procedure

  1. Set the following parameters:

    • KIE Server External Database Driver (KIE_SERVER_EXTERNALDB_DRIVER): The driver for the server, depending on the server type:

      • mysql
      • postgresql
      • mariadb
      • mssql
      • db2
      • oracle
      • sybase
    • KIE Server External Database User (KIE_SERVER_EXTERNALDB_USER) and KIE Server External Database Password (KIE_SERVER_EXTERNALDB_PWD): The user name and password for the external database server
    • KIE Server External Database URL (KIE_SERVER_EXTERNALDB_URL): The JDBC URL for the external database server

      Note

      If you are using the EntrepriseDB Postgres database server, use an URL starting with jdbc:postgresql:// and not with jdbc:edb://. Alternatively, do not set the URL and set the host and port parameters instead.

    • KIE Server External Database Host (KIE_SERVER_EXTERNALDB_SERVICE_HOST) and KIE Server External Database Port (KIE_SERVER_EXTERNALDB_SERVICE_PORT): The host name and port number of the external database server. You can set these parameters as an alternative to setting the KIE_SERVER_EXTERNALDB_URL parameter.
    • KIE Server External Database Dialect (KIE_SERVER_EXTERNALDB_DIALECT): The Hibernate dialect for the server, depending on the server type. The common settings are:

      • org.hibernate.dialect.MySQL5InnoDBDialect
      • org.hibernate.dialect.MySQL8Dialect
      • org.hibernate.dialect.MariaDB102Dialect
      • org.hibernate.dialect.PostgreSQL95Dialect
      • org.hibernate.dialect.PostgresPlusDialect (used for EntrepriseDB Postgres Advanced Server)
      • org.hibernate.dialect.SQLServer2012Dialect (used for MS SQL)
      • org.hibernate.dialect.DB2Dialect
      • org.hibernate.dialect.Oracle10gDialect
      • org.hibernate.dialect.SybaseASE15Dialect

        For a complete list of supported dialects, see the Hibernate SQL Dialects table in Hibernate properties in the Red Hat JBoss EAP documentation.

    • KIE Server External Database name (KIE_SERVER_EXTERNALDB_DB): The database name to use on the external database server
    • JDBC Connection Checker class (KIE_SERVER_EXTERNALDB_CONNECTION_CHECKER): The name of the JDBC connection checker class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
    • JDBC Exception Sorter class (KIE_SERVER_EXTERNALDB_EXCEPTION_SORTER): The name of the JDBC exception sorter class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
  2. If you created a custom image for using an external database server, as described in Section 7.10, “Building a custom KIE Server extension image for an external database”, set the following parameters:

    • Drivers Extension Image (EXTENSIONS_IMAGE): The ImageStreamTag definition of the extension image, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    • Drivers ImageStream Namespace (EXTENSIONS_IMAGE_NAMESPACE): The namespace to which you uploaded the extension image, for example, openshift or your project namespace.
  3. If you are using a MySQL version 8 external database server, enable the mysql_native_password plugin and use it for authentication. For instructions about this pluding, see Native Pluggable Authentication in the MySQL 8.0 Reference Manual.

    If you are using a MySQL version 8 image provided by Red Hat on Red Hat OpenShift Container Platform, to enable the plugin, set the MYSQL_DEFAULT_AUTHENTICATION_PLUGIN environment variable to mysql_native_password.

    If you created users on the MySQL version 8 server before enabling the mysql_native_password plugin, you must update the mysql-user table after you enable the plugin.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

10.4.9. Enabling Prometheus metric collection for an immutable KIE Server from KJAR services

If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, enable support for this feature in KIE Server at deployment time.

Prerequisites

Procedure

To enable support for Prometheus metric collection, set the Prometheus Server Extension Disabled (PROMETHEUS_SERVER_EXT_DISABLED) parameter to false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 10.4.10, “Completing deployment of the template for an immutable KIE Server from KJAR services”.

For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.

10.4.10. Completing deployment of the template for an immutable KIE Server from KJAR services

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

Chapter 11. Freeform managed server environment

You can deploy a freeform server environment that includes several different pods running KIE Server. These KIE Servers can run different services for staging or production purposes. You can add and remove servers as necessary at any time.

You start deploying a freeform managed server environment by deploying Business Central Monitoring and one managed KIE Server. You can use Business Central Monitoring to monitor and, when necessary, manage the execution of services on KIE Servers. This environment does not include Smart Router.

You can also deploy additional managed KIE Servers. Each KIE Server can be separately scaled as necessary.

On a managed KIE Server, no services are initially loaded. Use Business Central Monitoring or the REST API of the KIE Server to deploy and undeploy processes on the server.

You must provide a Maven repository with the processes (KJAR files) that you want to deploy on the servers. Your integration process must ensure that the required versions of the processes are uploaded to the Maven repository. You can use Business Central in a development environment to create the processes and upload them to the Maven repository.

Each KIE Server uses a database server. Usually, the database servers also run in pods, although you can set up a KIE Server to use an external database server.

You can also deploy immutable KIE Servers in the same namespace. You can use Business Central Monitoring to view monitoring information for all KIE Servers in the environment, including immutable servers. For instructions about deploying immutable KIE Servers, see Section 10.2, “Deploying an immutable KIE Server using an S2I build” and Section 10.4, “Deploying an immutable KIE Server from KJAR services”..

11.1. Deploying monitoring and a single KIE Server for a freeform environment

To start deploying a freeform environment, deploy Business Central Monitoring and a single managed KIE Server, which uses a PostgreSQL database server in a pod. No services are loaded on the KIE Server. Use Business Central Monitoring to deploy and undeploy services on the server.

You can then add more KIE Servers as necessary.

11.1.1. Starting configuration of the template for monitoring and a single KIE Server

To deploy Business Central Monitoring and a single managed KIE Server, use the rhpam710-managed.yaml template file.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the rhpam710-managed.yaml template file.
  3. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the rhpam710-managed.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/rhpam710-managed.yaml -p BUSINESS_CENTRAL_HTTPS_SECRET=businesscentral-app-secret -p KIE_SERVER_HTTPS_SECRET=kieserver-app-secret -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 11.1.2, “Setting required parameters for monitoring and a single KIE Server” to set common parameters. You can view the template file to see descriptions for all parameters.

11.1.2. Setting required parameters for monitoring and a single KIE Server

When configuring the template to deploy Business Central Monitoring and a single managed KIE Server, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

    • Credentials secret (CREDENTIALS_SECRET): The name of the secret containing the administrative user credentials, as created in Section 7.5, “Creating the secret for the administrative user”.
    • Business Central Monitoring Server Keystore Secret Name (BUSINESS_CENTRAL_HTTPS_SECRET): The name of the secret for Business Central, as created in Section 7.3, “Creating the secrets for Business Central”.
    • KIE Server Keystore Secret Name (KIE_SERVER_HTTPS_SECRET): The name of the secret for KIE Server, as created in Section 7.2, “Creating the secrets for KIE Server”.
    • Business Central Monitoring Server Certificate Name (BUSINESS_CENTRAL_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.3, “Creating the secrets for Business Central”.
    • Business Central Monitoring Server Keystore Password (BUSINESS_CENTRAL_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.3, “Creating the secrets for Business Central”.
    • KIE Server Certificate Name (KIE_SERVER_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • KIE Server Keystore Password (KIE_SERVER_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • Application Name (APPLICATION_NAME): The name of the OpenShift application. It is used in the default URLs for Business Central Monitoring and KIE Server. OpenShift uses the application name to create a separate set of deployment configurations, services, routes, labels, and artifacts.
    • Enable KIE server global discovery (KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED): Set this parameter to true if you want Business Central Monitoring to discover all KIE Servers with the OpenShiftStartupStrategy in the same namespace. By default, Business Central Monitoring discovers only KIE Servers that are deployed with the same value of the APPLICATION_NAME parameter as Business Central Monitoring itself.
    • Maven repository URL (MAVEN_REPO_URL): A URL for a Maven repository. You must upload all the processes (KJAR files) that are to be deployed on any KIE Servers in your environment into this repository.
    • Maven repository ID (MAVEN_REPO_ID): An identifier for the Maven repository. The default value is repo-custom.
    • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
    • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.
    • KIE Server Mode (KIE_SERVER_MODE): In the rhpam710-managed.yaml template the default value is PRODUCTION. In PRODUCTION mode, you cannot deploy SNAPSHOT versions of KJAR artifacts on the KIE Server and cannot change versions of an artifact in an existing container. To deploy a new version with PRODUCTION mode, create a new container on the same KIE Server. To deploy SNAPSHOT versions or to change versions of an artifact in an existing container, set this parameter to DEVELOPMENT.
    • ImageStream Namespace (IMAGE_STREAM_NAMESPACE): The namespace where the image streams are available. If the image streams were already available in your OpenShift environment (see Section 7.1, “Ensuring the availability of image streams and the image registry”), the namespace is openshift. If you have installed the image streams file, the namespace is the name of the OpenShift project.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.1.8, “Completing deployment of the template for monitoring and a single KIE Server”.

11.1.3. Configuring pod replica numbers for monitoring and a single KIE Server

When configuring the template to deploy Business Central Monitoring and a single managed KIE Server, you can set the initial number of replicas for KIE Server and Business Central Monitoring.

Prerequisites

Procedure

To configure the numbers of replicas, set the following parameters:

  • Business Central Monitoring Container Replicas (BUSINESS_CENTRAL_MONITORING_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for Business Central Monitoring. If you do not want to use a high-availability configuration for Business Central Monitoring, set this number to 1.
  • KIE Server Container Replicas (KIE_SERVER_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for KIE Server.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.1.8, “Completing deployment of the template for monitoring and a single KIE Server”.

11.1.4. Configuring access to a Maven mirror in an environment without a connection to the public Internet for monitoring and a single KIE Server

When configuring the template to deploy Business Central Monitoring and a single managed KIE Server, if your OpenShift environment does not have a connection to the public Internet, you must configure access to a Maven mirror that you set up according to Section 7.9, “Preparing a Maven mirror repository for offline use”.

Prerequisites

Procedure

To configure access to the Maven mirror, set the following parameters:

  • Maven mirror URL (MAVEN_MIRROR_URL): The URL for the Maven mirror repository that you set up in Section 7.9, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
  • Maven mirror of (MAVEN_MIRROR_OF): The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

    • If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.
    • If you configure a built-in Business Central Maven repository (BUSINESS_CENTRAL_MAVEN_SERVICE), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.
    • If you configure both repositories, change MAVEN_MIRROR_OF to exclude the artifacts in both repositories from the mirror: external:*,!repo-rhpamcentr,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.1.8, “Completing deployment of the template for monitoring and a single KIE Server”.

11.1.5. Setting parameters for RH-SSO authentication for monitoring and a single KIE Server

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy Business Central Monitoring and a single managed KIE Server.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

  • A realm for Red Hat Process Automation Manager is created in the RH-SSO authentication system.
  • User names and passwords for Red Hat Process Automation Manager are created in the RH-SSO authentication system. For a list of the available roles, see Chapter 14, Red Hat Process Automation Manager roles and users.

    You must create a user with the username and password configured in the secret for the administrative user, as described in Section 7.5, “Creating the secret for the administrative user”. This user must have the kie-server,rest-all,admin roles.

  • Clients are created in the RH-SSO authentication system for all components of the Red Hat Process Automation Manager environment that you are deploying. The client setup contains the URLs for the components. You can review and edit the URLs after deploying the environment. Alternatively, the Red Hat Process Automation Manager deployment can create the clients. However, this option provides less detailed control over the environment.
  • You started the configuration of the template, as described in Section 11.1.1, “Starting configuration of the template for monitoring and a single KIE Server”.

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central Monitoring.
      • Business Central Monitoring RH-SSO Client Secret (BUSINESS_CENTRAL_SSO_SECRET): The secret string that is set in RH-SSO for the client for Business Central Monitoring.
      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The RH-SSO client name for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string that is set in RH-SSO for the client for KIE Server.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The name of the client to create in RH-SSO for Business Central Monitoring.
      • Business Central Monitoring RH-SSO Client Secret (BUSINESS_CENTRAL_SSO_SECRET): The secret string to set in RH-SSO for the client for Business Central Monitoring.
      • KIE Server RH-SSO Client name (KIE_SERVER_SSO_CLIENT): The name of the client to create in RH-SSO for KIE Server.
      • KIE Server RH-SSO Client Secret (KIE_SERVER_SSO_SECRET): The secret string to set in RH-SSO for the client for KIE Server.
      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.1.8, “Completing deployment of the template for monitoring and a single KIE Server”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

11.1.6. Setting parameters for LDAP authentication for monitoring and a single KIE Server

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy Business Central Monitoring and a single managed KIE Server.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.1.8, “Completing deployment of the template for monitoring and a single KIE Server”.

11.1.7. Enabling Prometheus metric collection for monitoring and a single KIE Server

If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, enable support for this feature in KIE Server at deployment time.

Prerequisites

Procedure

To enable support for Prometheus metric collection, set the Prometheus Server Extension Disabled (PROMETHEUS_SERVER_EXT_DISABLED) parameter to false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.1.8, “Completing deployment of the template for monitoring and a single KIE Server”.

For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.

11.1.8. Completing deployment of the template for monitoring and a single KIE Server

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

11.2. Deploying an additional managed KIE Server for a freeform environment

You can add a managed KIE Server to a freeform environment. This server can use a PostgreSQL or MySQL database server in a pod or an external database server.

Deploy the server in the same project as the Business Central Monitoring deployment.

The KIE Server loads services from a Maven repository.

The server starts with no loaded services. Use Business Central Monitoring or the REST API of the KIE Server to deploy and undeploy services on the server.

11.2.1. Starting configuration of the template for an additional managed KIE Server

To deploy an additional managed KIE Server, use the {template_name} template file.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the {template_name} template file.
  3. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the {template_name} file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/{template_name}  -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 11.2.2, “Setting required parameters for an additional managed KIE Server” to set common parameters. You can view the template file to see descriptions for all parameters.

11.2.2. Setting required parameters for an additional managed KIE Server

When configuring the template to deploy an additional managed KIE Server, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

    • Credentials secret (CREDENTIALS_SECRET): The name of the secret containing the administrative user credentials, as created in Section 7.5, “Creating the secret for the administrative user”.
    • Application Name (APPLICATION_NAME): The name of the OpenShift application. It is used in the default URLs for Business Central Monitoring and KIE Server. OpenShift uses the application name to create a separate set of deployment configurations, services, routes, labels, and artifacts.
    • ImageStream Namespace (IMAGE_STREAM_NAMESPACE): The namespace where the image streams are available. If the image streams were already available in your OpenShift environment (see Section 7.1, “Ensuring the availability of image streams and the image registry”), the namespace is openshift. If you have installed the image streams file, the namespace is the name of the OpenShift project.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

11.2.3. Configuring the image stream namespace for an additional managed KIE Server

If you created image streams in a namespace that is not openshift, you must configure the namespace in the template.

If all image streams were already available in your Red Hat OpenShift Container Platform environment, you can skip this procedure.

Prerequisites

Procedure

If you installed an image streams file according to instructions in Section 7.1, “Ensuring the availability of image streams and the image registry”, set the ImageStream Namespace (IMAGE_STREAM_NAMESPACE) parameter to the name of your OpenShift project.

11.2.4. Configuring information about a Business Central Monitoring instance for an additional managed KIE Server

If you want to enable a connection from a Business Central Monitoring instance in the same namespace to the KIE Server, you must configure information about the Business Central Monitoring instance.

The Business Central Monitoring instance must be configured with the same credentials secret (CREDENTIALS_SECRET) as the KIE Server.

Prerequisites

Procedure

  1. Set the following parameters:

    • Name of the Business Central service (BUSINESS_CENTRAL_SERVICE): The OpenShift service name for the Business Central Monitoring.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

11.2.5. Configuring access to a Maven mirror in an environment without a connection to the public Internet for an additional managed KIE Server

When configuring the template to deploy an additional managed KIE Server, if your OpenShift environment does not have a connection to the public Internet, you must configure access to a Maven mirror that you set up according to Section 7.9, “Preparing a Maven mirror repository for offline use”.

Prerequisites

Procedure

To configure access to the Maven mirror, set the following parameters:

  • Maven mirror URL (MAVEN_MIRROR_URL): The URL for the Maven mirror repository that you set up in Section 7.9, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
  • Maven mirror of (MAVEN_MIRROR_OF): The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

    • If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.
    • If you configure a built-in Business Central Maven repository (BUSINESS_CENTRAL_MAVEN_SERVICE), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.
    • If you configure both repositories, change MAVEN_MIRROR_OF to exclude the artifacts in both repositories from the mirror: external:*,!repo-rhpamcentr,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

11.2.6. Setting parameters for RH-SSO authentication for an additional managed KIE Server

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy an additional managed KIE Server.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

  • A realm for Red Hat Process Automation Manager is created in the RH-SSO authentication system.
  • User names and passwords for Red Hat Process Automation Manager are created in the RH-SSO authentication system. For a list of the available roles, see Chapter 14, Red Hat Process Automation Manager roles and users.

    You must create a user with the username and password configured in the secret for the administrative user, as described in Section 7.5, “Creating the secret for the administrative user”. This user must have the kie-server,rest-all,admin roles.

  • Clients are created in the RH-SSO authentication system for all components of the Red Hat Process Automation Manager environment that you are deploying. The client setup contains the URLs for the components. You can review and edit the URLs after deploying the environment. Alternatively, the Red Hat Process Automation Manager deployment can create the clients. However, this option provides less detailed control over the environment.
  • You started the configuration of the template, as described in Section 11.2.1, “Starting configuration of the template for an additional managed KIE Server”.

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central Monitoring.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

11.2.7. Setting parameters for LDAP authentication for an additional managed KIE Server

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy an additional managed KIE Server.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

11.2.8. Setting parameters for using an external database server for an additional managed KIE Server

If you are using the rhpam710-kieserver-externaldb.yaml template to use an external database server for the KIE Server, complete the following additional configuration when configuring the template to deploy an additional managed KIE Server.

Prerequisites

Procedure

  1. Set the following parameters:

    • KIE Server External Database Driver (KIE_SERVER_EXTERNALDB_DRIVER): The driver for the server, depending on the server type:

      • mysql
      • postgresql
      • mariadb
      • mssql
      • db2
      • oracle
      • sybase
    • KIE Server External Database User (KIE_SERVER_EXTERNALDB_USER) and KIE Server External Database Password (KIE_SERVER_EXTERNALDB_PWD): The user name and password for the external database server
    • KIE Server External Database URL (KIE_SERVER_EXTERNALDB_URL): The JDBC URL for the external database server

      Note

      If you are using the EntrepriseDB Postgres database server, use an URL starting with jdbc:postgresql:// and not with jdbc:edb://. Alternatively, do not set the URL and set the host and port parameters instead.

    • KIE Server External Database Host (KIE_SERVER_EXTERNALDB_SERVICE_HOST) and KIE Server External Database Port (KIE_SERVER_EXTERNALDB_SERVICE_PORT): The host name and port number of the external database server. You can set these parameters as an alternative to setting the KIE_SERVER_EXTERNALDB_URL parameter.
    • KIE Server External Database Dialect (KIE_SERVER_EXTERNALDB_DIALECT): The Hibernate dialect for the server, depending on the server type. The common settings are:

      • org.hibernate.dialect.MySQL5InnoDBDialect
      • org.hibernate.dialect.MySQL8Dialect
      • org.hibernate.dialect.MariaDB102Dialect
      • org.hibernate.dialect.PostgreSQL95Dialect
      • org.hibernate.dialect.PostgresPlusDialect (used for EntrepriseDB Postgres Advanced Server)
      • org.hibernate.dialect.SQLServer2012Dialect (used for MS SQL)
      • org.hibernate.dialect.DB2Dialect
      • org.hibernate.dialect.Oracle10gDialect
      • org.hibernate.dialect.SybaseASE15Dialect

        For a complete list of supported dialects, see the Hibernate SQL Dialects table in Hibernate properties in the Red Hat JBoss EAP documentation.

    • KIE Server External Database name (KIE_SERVER_EXTERNALDB_DB): The database name to use on the external database server
    • JDBC Connection Checker class (KIE_SERVER_EXTERNALDB_CONNECTION_CHECKER): The name of the JDBC connection checker class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
    • JDBC Exception Sorter class (KIE_SERVER_EXTERNALDB_EXCEPTION_SORTER): The name of the JDBC exception sorter class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
  2. If you created a custom image for using an external database server, as described in Section 7.10, “Building a custom KIE Server extension image for an external database”, set the following parameters:

    • Drivers Extension Image (EXTENSIONS_IMAGE): The ImageStreamTag definition of the extension image, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    • Drivers ImageStream Namespace (EXTENSIONS_IMAGE_NAMESPACE): The namespace to which you uploaded the extension image, for example, openshift or your project namespace.
  3. If you are using a MySQL version 8 external database server, enable the mysql_native_password plugin and use it for authentication. For instructions about this pluding, see Native Pluggable Authentication in the MySQL 8.0 Reference Manual.

    If you are using a MySQL version 8 image provided by Red Hat on Red Hat OpenShift Container Platform, to enable the plugin, set the MYSQL_DEFAULT_AUTHENTICATION_PLUGIN environment variable to mysql_native_password.

    If you created users on the MySQL version 8 server before enabling the mysql_native_password plugin, you must update the mysql-user table after you enable the plugin.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

11.2.9. Enabling Prometheus metric collection for an additional managed KIE Server

If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, enable support for this feature in KIE Server at deployment time.

Prerequisites

Procedure

To enable support for Prometheus metric collection, set the Prometheus Server Extension Disabled (PROMETHEUS_SERVER_EXT_DISABLED) parameter to false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 11.2.10, “Completing deployment of the template for an additional managed KIE Server”.

For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.

11.2.10. Completing deployment of the template for an additional managed KIE Server

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

Chapter 12. Fixed managed server environment

You can deploy a fixed managed server environment that, in a single deployment, includes several different pods running KIE Server. No processes are initially loaded on the servers. The database servers are, by default, also run in pods. Each KIE Server pod can be separately scaled as necessary.

A pod with Business Central Monitoring and a pod with Smart Router are also deployed. You must use Business Central Monitoring to deploy, load, and unload processes on your KIE Servers. You can also use it to view monitoring information.

Smart Router is a single endpoint that can receive calls from client applications to any of your processes and route each call automatically to the server that runs the process.

By default, the templates create two independent KIE Servers. You can modify the template to change the number of KIE Servers before deployment. You cannot easily add or remove KIE Servers at a later time.

You must provide a Maven repository with the processes (KJAR files) that you want to deploy on the servers. Your integration process must ensure that the required versions of the processes are uploaded to the Maven repository. You can use Business Central in a development environment to create the processes and upload them to the Maven repository.

12.1. Deploying a fixed managed server environment

You can deploy a fixed managed server environment using a single template. The name of the template file is rhpam710-prod.yaml.

The template includes two KIE Server pods (with PostgreSQL database pods), Smart Router in a high-availability configuration, and Business Central Monitoring in a high-availability configuration.

You can change the number of replicas of all components when configuring the deployment. If you want to modify the number of independent KIE Server pods or to use a different database server, you must modify the template. For instructions about modifying the template, see Section 12.2, “Modifying a template for a fixed managed environment”.

Note

The fixed managed environment template is deprecated in Red Hat Process Automation Manager 7.10. It will be removed in a future release.

12.1.1. Starting configuration of the template for a fixed managed server environment

To deploy a fixed managed server environment, use the rhpam710-prod.yaml template file.

Procedure

  1. Download the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
  2. Extract the rhpam710-prod.yaml template file.
  3. By default, the template includes two KIE Servers. Each of the serves uses a PostgreSQL database server in a pod. To change the number of KIE Servers or to use a MySQL database server in a pod or an external database server, modify the template as described in Section 12.2, “Modifying a template for a fixed managed environment”.
  4. Use one of the following methods to start deploying the template:

    • To use the OpenShift Web UI, in the OpenShift application console select Add to Project → Import YAML / JSON and then select or paste the rhpam710-prod.yaml file. In the Add Template window, ensure Process the template is selected and click Continue.
    • To use the OpenShift command line console, prepare the following command line:

      oc new-app -f <template-path>/rhpam710-prod.yaml -p BUSINESS_CENTRAL_HTTPS_SECRET=businesscentral-app-secret -p KIE_SERVER_HTTPS_SECRET=kieserver-app-secret -p PARAMETER=value

      In this command line, make the following changes:

      • Replace <template-path> with the path to the downloaded template file.
      • Use as many -p PARAMETER=value pairs as needed to set the required parameters.

Next steps

Set the parameters for the template. Follow the steps in Section 12.1.2, “Setting required parameters for a fixed managed server environment” to set common parameters. You can view the template file to see descriptions for all parameters.

12.1.2. Setting required parameters for a fixed managed server environment

When configuring the template to deploy a fixed managed server environment, you must set the following parameters in all cases.

Prerequisites

Procedure

  1. Set the following parameters:

    • Credentials secret (CREDENTIALS_SECRET): The name of the secret containing the administrative user credentials, as created in Section 7.5, “Creating the secret for the administrative user”.
    • Business Central Monitoring Server Keystore Secret Name (BUSINESS_CENTRAL_HTTPS_SECRET): The name of the secret for Business Central, as created in Section 7.3, “Creating the secrets for Business Central”.
    • KIE Server Keystore Secret Name (KIE_SERVER_HTTPS_SECRET): The name of the secret for KIE Server, as created in Section 7.2, “Creating the secrets for KIE Server”.
    • Smart Router Keystore Secret Name (KIE_SERVER_ROUTER_HTTPS_SECRET): The name of the secret for Smart Router, as created in Section 7.4, “Creating the secrets for Smart Router”.
    • Business Central Monitoring Server Certificate Name (BUSINESS_CENTRAL_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.3, “Creating the secrets for Business Central”.
    • Business Central Monitoring Server Keystore Password (BUSINESS_CENTRAL_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.3, “Creating the secrets for Business Central”.
    • KIE Server Certificate Name (KIE_SERVER_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • KIE Server Keystore Password (KIE_SERVER_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.2, “Creating the secrets for KIE Server”.
    • Smart Router Certificate Name (KIE_SERVER_ROUTER_HTTPS_NAME): The name of the certificate in the keystore that you created in Section 7.4, “Creating the secrets for Smart Router”.
    • Smart Router Keystore Password (KIE_SERVER_ROUTER_HTTPS_PASSWORD): The password for the keystore that you created in Section 7.4, “Creating the secrets for Smart Router”.
    • Application Name (APPLICATION_NAME): The name of the OpenShift application. It is used in the default URLs for Business Central Monitoring and KIE Server. OpenShift uses the application name to create a separate set of deployment configurations, services, routes, labels, and artifacts. You can deploy several applications using the same template into the same project, as long as you use different application names. Also, the application name determines the name of the server configuration (server template) that the KIE Server joins on Business Central Monitoring. If you are deploying several KIE Servers, you must ensure each of the servers has a different application name.
    • Maven repository URL (MAVEN_REPO_URL): A URL for a Maven repository. You must upload all the processes (KJAR files) that are to be deployed on the KIE Server into this repository.
    • Maven repository ID (MAVEN_REPO_ID): An identifier for the Maven repository. The default value is repo-custom.
    • Maven repository username (MAVEN_REPO_USERNAME): The user name for the Maven repository.
    • Maven repository password (MAVEN_REPO_PASSWORD): The password for the Maven repository.
    • KIE Server Mode (KIE_SERVER_MODE): In the rhpam710-kieserver-*.yaml templates the default value is PRODUCTION. In PRODUCTION mode, you cannot deploy SNAPSHOT versions of KJAR artifacts on the KIE Server and cannot change versions of an artifact in an existing container. To deploy a new version with PRODUCTION mode, create a new container on the same KIE Server. To deploy SNAPSHOT versions or to change versions of an artifact in an existing container, set this parameter to DEVELOPMENT.
    • ImageStream Namespace (IMAGE_STREAM_NAMESPACE): The namespace where the image streams are available. If the image streams were already available in your OpenShift environment (see Section 7.1, “Ensuring the availability of image streams and the image registry”), the namespace is openshift. If you have installed the image streams file, the namespace is the name of the OpenShift project.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

12.1.3. Configuring the image stream namespace for a fixed managed server environment

If you created image streams in a namespace that is not openshift, you must configure the namespace in the template.

If all image streams were already available in your Red Hat OpenShift Container Platform environment, you can skip this procedure.

Prerequisites

Procedure

If you installed an image streams file according to instructions in Section 7.1, “Ensuring the availability of image streams and the image registry”, set the ImageStream Namespace (IMAGE_STREAM_NAMESPACE) parameter to the name of your OpenShift project.

12.1.4. Configuring pod replica numbers for a fixed managed server environment

When configuring the template to deploy a fixed managed server environment, you can set the initial number of replicas for KIE Server, Business Central Monitoring, and Smart Router.

Prerequisites

Procedure

To configure the numbers of replicas, set the following parameters:

  • Business Central Monitoring Container Replicas (BUSINESS_CENTRAL_MONITORING_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for Business Central Monitoring. If you do not want to use a high-availability configuration for Business Central Monitoring, set this number to 1.
  • KIE Server Container Replicas (KIE_SERVER_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for KIE Server.
  • Smart Router Container Replicas (SMART_ROUTER_CONTAINER_REPLICAS): The number of replicas that the deployment initially creates for Smart Router.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

12.1.5. Configuring access to a Maven mirror in an environment without a connection to the public Internet for a fixed managed server environment

When configuring the template to deploy a fixed managed server environment, if your OpenShift environment does not have a connection to the public Internet, you must configure access to a Maven mirror that you set up according to Section 7.9, “Preparing a Maven mirror repository for offline use”.

Prerequisites

Procedure

To configure access to the Maven mirror, set the following parameters:

  • Maven mirror URL (MAVEN_MIRROR_URL): The URL for the Maven mirror repository that you set up in Section 7.9, “Preparing a Maven mirror repository for offline use”. This URL must be accessible from a pod in your OpenShift environment.
  • Maven mirror of (MAVEN_MIRROR_OF): The value that determines which artifacts are to be retrieved from the mirror. For instructions about setting the mirrorOf value, see Mirror Settings in the Apache Maven documentation. The default value is external:*. With this value, Maven retrieves every required artifact from the mirror and does not query any other repositories.

    • If you configure an external Maven repository (MAVEN_REPO_URL), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror, for example, external:*,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.
    • If you configure a built-in Business Central Maven repository (BUSINESS_CENTRAL_MAVEN_SERVICE), change MAVEN_MIRROR_OF to exclude the artifacts in this repository from the mirror: external:*,!repo-rhpamcentr.
    • If you configure both repositories, change MAVEN_MIRROR_OF to exclude the artifacts in both repositories from the mirror: external:*,!repo-rhpamcentr,!repo-custom. Replace repo-custom with the ID that you configured in MAVEN_REPO_ID.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

12.1.6. Setting parameters for RH-SSO authentication for a fixed managed server environment

If you want to use RH-SSO authentication, complete the following additional configuration when configuring the template to deploy a fixed managed server environment.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

  • A realm for Red Hat Process Automation Manager is created in the RH-SSO authentication system.
  • User names and passwords for Red Hat Process Automation Manager are created in the RH-SSO authentication system. For a list of the available roles, see Chapter 14, Red Hat Process Automation Manager roles and users.

    You must create a user with the username and password configured in the secret for the administrative user, as described in Section 7.5, “Creating the secret for the administrative user”. This user must have the kie-server,rest-all,admin roles.

  • Clients are created in the RH-SSO authentication system for all components of the Red Hat Process Automation Manager environment that you are deploying. The client setup contains the URLs for the components. You can review and edit the URLs after deploying the environment. Alternatively, the Red Hat Process Automation Manager deployment can create the clients. However, this option provides less detailed control over the environment.
  • You started the configuration of the template, as described in Section 12.1.1, “Starting configuration of the template for a fixed managed server environment”.

Procedure

  1. Set the following parameters:

    • RH-SSO URL (SSO_URL): The URL for RH-SSO.
    • RH-SSO Realm name (SSO_REALM): The RH-SSO realm for Red Hat Process Automation Manager.
    • RH-SSO Disable SSL Certificate Validation (SSO_DISABLE_SSL_CERTIFICATE_VALIDATION): Set to true if your RH-SSO installation does not use a valid HTTPS certificate.
  2. Complete one of the following procedures:

    1. If you created the client for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • Business Central Monitoring RH-SSO Client name (BUSINESS_CENTRAL_SSO_CLIENT): The RH-SSO client name for Business Central Monitoring.
      • For each KIE Server defined in the template:

        • KIE Server n RH-SSO Client name (KIE_SERVERn_SSO_CLIENT): The RH-SSO client name for this KIE Server.
        • KIE Server n RH-SSO Client Secret (KIE_SERVERn_SSO_SECRET): The secret string that is set in RH-SSO for the client for this KIE Server.
    2. To create the clients for Red Hat Process Automation Manager within RH-SSO, set the following parameters in the template:

      • For each KIE Server defined in the template:

        • KIE Server n RH-SSO Client name (KIE_SERVERn_SSO_CLIENT): The name of the client to create in RH-SSO for this KIE Server.
        • KIE Server n RH-SSO Client Secret (KIE_SERVERn_SSO_SECRET): The secret string to set in RH-SSO for the client for this KIE Server.
      • RH-SSO Realm Admin Username (SSO_USERNAME) and RH-SSO Realm Admin Password (SSO_PASSWORD): The user name and password for the realm administrator user for the RH-SSO realm for Red Hat Process Automation Manager. You must provide this user name and password in order to create the required clients.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

After completing the deployment, review the URLs for components of Red Hat Process Automation Manager in the RH-SSO authentication system to ensure they are correct.

12.1.7. Setting parameters for LDAP authentication for a fixed managed server environment

If you want to use LDAP authentication, complete the following additional configuration when configuring the template to deploy a fixed managed server environment.

Important

Do not configure LDAP authentication and RH-SSO authentication in the same deployment.

Prerequisites

Procedure

  1. Set the AUTH_LDAP* parameters of the template. These parameters correspond to the settings of the LdapExtended Login module of Red Hat JBoss EAP. For instructions about using these settings, see LdapExtended login module.

    Note

    If you want to enable LDAP failover, you can put set or more LDAP server addresses in the AUTH_LDAP_URL parameter, separated by a space.

    If the LDAP server does not define all the roles required for your deployment, you can map LDAP groups to Red Hat Process Automation Manager roles. To enable LDAP role mapping, set the following parameters:

    • RoleMapping rolesProperties file path (AUTH_ROLE_MAPPER_ROLES_PROPERTIES): The fully qualified path name of a file that defines role mapping, for example, /opt/eap/standalone/configuration/rolemapping/rolemapping.properties. You must provide this file and mount it at this path in all applicable deployment configurations; for instructions, see Section 13.3, “(Optional) Providing the LDAP role mapping file”.
    • RoleMapping replaceRole property (AUTH_ROLE_MAPPER_REPLACE_ROLE): If set to true, mapped roles replace the roles defined on the LDAP server; if set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

12.1.8. Setting parameters for using an external database server for a fixed managed server environment

If you modified the template to use an external database server for the KIE Server, as described in Section 12.2, “Modifying a template for a fixed managed environment”, complete the following additional configuration when configuring the template to deploy a fixed managed server environment.

Prerequisites

Procedure

  1. Set the following parameters:

    • KIE Server External Database Driver (KIE_SERVER_EXTERNALDB_DRIVER): The driver for the server, depending on the server type:

      • mysql
      • postgresql
      • mariadb
      • mssql
      • db2
      • oracle
      • sybase
    • KIE Server External Database User (KIE_SERVER_EXTERNALDB_USER) and KIE Server External Database Password (KIE_SERVER_EXTERNALDB_PWD): The user name and password for the external database server
    • KIE Server External Database URL (KIE_SERVER_EXTERNALDB_URL): The JDBC URL for the external database server

      Note

      If you are using the EntrepriseDB Postgres database server, use an URL starting with jdbc:postgresql:// and not with jdbc:edb://. Alternatively, do not set the URL and set the host and port parameters instead.

    • KIE Server External Database Host (KIE_SERVER_EXTERNALDB_SERVICE_HOST) and KIE Server External Database Port (KIE_SERVER_EXTERNALDB_SERVICE_PORT): The host name and port number of the external database server. You can set these parameters as an alternative to setting the KIE_SERVER_EXTERNALDB_URL parameter.
    • KIE Server External Database Dialect (KIE_SERVER_EXTERNALDB_DIALECT): The Hibernate dialect for the server, depending on the server type. The common settings are:

      • org.hibernate.dialect.MySQL5InnoDBDialect
      • org.hibernate.dialect.MySQL8Dialect
      • org.hibernate.dialect.MariaDB102Dialect
      • org.hibernate.dialect.PostgreSQL95Dialect
      • org.hibernate.dialect.PostgresPlusDialect (used for EntrepriseDB Postgres Advanced Server)
      • org.hibernate.dialect.SQLServer2012Dialect (used for MS SQL)
      • org.hibernate.dialect.DB2Dialect
      • org.hibernate.dialect.Oracle10gDialect
      • org.hibernate.dialect.SybaseASE15Dialect

        For a complete list of supported dialects, see the Hibernate SQL Dialects table in Hibernate properties in the Red Hat JBoss EAP documentation.

    • KIE Server External Database name (KIE_SERVER_EXTERNALDB_DB): The database name to use on the external database server
    • JDBC Connection Checker class (KIE_SERVER_EXTERNALDB_CONNECTION_CHECKER): The name of the JDBC connection checker class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
    • JDBC Exception Sorter class (KIE_SERVER_EXTERNALDB_EXCEPTION_SORTER): The name of the JDBC exception sorter class for the database server. Without this information, a database server connection cannot be restored after it is lost, for example, if the database server is rebooted.
  2. If you created a custom image for using an external database server, as described in Section 7.10, “Building a custom KIE Server extension image for an external database”, set the following parameters:

    • Drivers Extension Image (EXTENSIONS_IMAGE): The ImageStreamTag definition of the extension image, for example, jboss-kie-db2-extension-openshift-image:11.1.4.4
    • Drivers ImageStream Namespace (EXTENSIONS_IMAGE_NAMESPACE): The namespace to which you uploaded the extension image, for example, openshift or your project namespace.
  3. If you are using a MySQL version 8 external database server, enable the mysql_native_password plugin and use it for authentication. For instructions about this pluding, see Native Pluggable Authentication in the MySQL 8.0 Reference Manual.

    If you are using a MySQL version 8 image provided by Red Hat on Red Hat OpenShift Container Platform, to enable the plugin, set the MYSQL_DEFAULT_AUTHENTICATION_PLUGIN environment variable to mysql_native_password.

    If you created users on the MySQL version 8 server before enabling the mysql_native_password plugin, you must update the mysql-user table after you enable the plugin.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

12.1.9. Enabling Prometheus metric collection for a fixed managed server environment

If you want to configure your KIE Server deployment to use Prometheus to collect and store metrics, enable support for this feature in KIE Server at deployment time.

Prerequisites

Procedure

To enable support for Prometheus metric collection, set the Prometheus Server Extension Disabled (PROMETHEUS_SERVER_EXT_DISABLED) parameter to false.

Next steps

If necessary, set additional parameters.

To complete the deployment, follow the procedure in Section 12.1.10, “Completing deployment of the template for a fixed managed server environment”.

For instructions about configuring Prometheus metrics collection, see Managing and monitoring KIE Server.

12.1.10. Completing deployment of the template for a fixed managed server environment

After setting all the required parameters in the OpenShift Web UI or in the command line, complete deployment of the template.

Procedure

Depending on the method that you are using, complete the following steps:

  • In the OpenShift Web UI, click Create.

    • If the This will create resources that may have security or project behavior implications message appears, click Create Anyway.
  • Complete the command line and press Enter.

Next steps

Depending on your needs for the environment, optionally complete procedures described in Chapter 13, Optional procedures after deploying your environment.

12.2. Modifying a template for a fixed managed environment

To adjust the fixed managed environment to your needs, you need to modify the rhpam710-prod.yaml template before deploying the environment.

By default, the templates create two replicated KIE Server pods. You can deploy separate processes on each of the pods. To add more replicated KIE Server pods, you need to modify the template before deploying the environment.

By default, the templates create a PostgreSQL pod to provide the database server for each replicated KIE Server. If you prefer to use PostgreSQL or to use an external server (outside the OpenShift project), you need to modify the template before deploying the environment.

For the rhpam710-prod.yaml template you can also adjust the initial number of replicas for Business Central Monitoring.

An OpenShift template defines a set of objects that can be created by OpenShift. To change an environment configuration, you need to modify, add, or delete these objects. To simplify this task, comments are provided in the Red Hat Process Automation Manager templates.

Some comments mark blocks within the template, staring with BEGIN and ending with END. For example, the following block is named Sample block:

## Sample block BEGIN
sample line 1
sample line 2
sample line 3
## Sample block END

For some changes, you might need to replace a block in one template file with a block from another template file provided with Red Hat Process Automation Manager. In this case, delete the block, then paste the new block in its exact location.

Note that named blocks can be nested.

Procedure

  • If you want to add more replicated KIE Server pods, repeat the following actions for every additional pod:

    1. Pick a number for the new pod. The default pods have the numbers 1 and 2, so you can use 3 for the first new pod, then 4 and so on.
    2. Copy the following blocks of the file, marked with comments from BEGIN to END, into the end of the file:

      • KIE server services 1
      • PostgreSQL service 1
      • KIE server routes 1
      • KIE server deployment config 1
      • PostgreSQL deployment config 1
      • PostgreSQL persistent volume claim 1
    3. In the new copies, replace all instances of -1 with the new pod number, for example, -3.
  • If you want to use MySQL instead of PostgreSQL, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-postgresql.yaml file, then modify some of the newly added blocks:

    1. Replace the block named MySQL database parameters with the block named PostgreSQL database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-postgresql.yaml file.)

      Repeat the following actions for every replicated KIE Server pod number, for example, 1 and 2 in the unmodified template. N refers to the pod number, for example, 1.

      • Replace the block named PostgreSQL service N with the block named MySQL service.
      • Replace the block named PostgreSQL driver settings N with the block named MySQL driver settings.
      • Replace the block named PostgreSQL deployment config N with the block named MySQL deployment config.
      • Replace the block named PostgreSQL persistent volume claim N with the block named MySQL persistent volume claim.
      • In all the newly added blocks, make the following replacements manually, where N is the pod number:

        • -mysql with -mysql-N, except in -mysql-pvol and in -mysql-claim
        • -mysql-claim with -mysql-claim-N
  • If you want to use an external database server, replace several blocks of the file, marked with comments from BEGIN to END, with blocks from the rhpam710-kieserver-externaldb.yaml file, remove some blocks, and modify some of the newly added blocks:

    1. Replace the block named MySQL database parameters with the block named External database parameters. (Take this block and all subsequent replacement blocks from the rhpam710-kieserver-external.yaml file.)

      Repeat the following actions for every replicated KIE Server pod number, for example, 1 and 2 in the unmodified template. N refers to the pod number, for example, 1.

      • Remove the block named PostgreSQL service N
      • Remove the block named PostgreSQL deployment config N
      • Remove the block named PostgreSQL persistent volume claim N
      • Replace the block named PostgreSQL driver settings N with the block named External database driver settings.
      • In the new External database driver settings block, if any of the following values are different for different KIE Server pods in the infrastructure, set the values for this particular pod:

        • RHPAM_USERNAME: The user name for logging in to the database server
        • RHPAM_PASSWORD: The password for logging in to the database server
        • RHPAM_XA_CONNECTION_PROPERTY_URL: The full URL for logging in to the database server
        • RHPAM_SERVICE_HOST: The host name of the database server
        • RHPAM_DATABASE: The database name
Important

The standard KIE Server image includes drivers for MySQL, MariaDB, and PostgreSQL external database servers. If you want to use another database server, you must build a custom KIE Server image. For instructions, see Section 7.10, “Building a custom KIE Server extension image for an external database”.

  • If you want to change the number of replicas initially created for Business Central Monitoring, on the line below the comment ## Replicas for Business Central Monitoring, change the number of replicas to the desired value.

Chapter 13. Optional procedures after deploying your environment

Depending on the needs for your environment, you might need to complete certain optional procedures after deploying it.

13.1. (Optional) Providing the Git hooks directory

If you deploy an authoring enviropnent and configure the GIT_HOOKS_DIR parameter, you must provide a directory of Git hooks and must mount this directory on the Business Central deployment.

The typical use of Git hooks is interaction with an upstream repository. To enable Git hooks to push commits into an upstream repository, you must also provide a secret key that corresponds to a public key configured on the upstream repository.

Prerequisites

  • You deployed a Red Hat Process Automation Manager authoring environment using templates
  • You set the GIT_HOOKS_DIR parameter in the deployment

Procedure

  1. If interaction with an upstream repository using SSH authentication is required, complete the following steps to prepare and mount a secret with the necessary files:

    1. Prepare the id_rsa file with a private key that matches a public key stored in the repository.
    2. Prepare the known_hosts file with the correct name, address, and public key for the repository.
    3. Create a secret with the two files using the oc command, for example:

      oc create secret git-hooks-secret --from-file=id_rsa=id_rsa --from-file=known_hosts=known_hosts
    4. Mount the secret in the SSH key path of the Business Central deployment, for example:

      oc set volume dc/<myapp>-rhpamcentr --add --type secret --secret-name git-hooks-secret --mount-path=/home/jboss/.ssh --name=ssh-key

      Replace <myapp> with the application name that you set when configuring the template.

  2. Create the Git hooks directory. For instructions, see the Git hooks reference documentation.

    For example, a simple Git hooks directory can provide a post-commit hook that pushes the changes upstream. If the project was imported into Business Central from a repository, this repository remains configured as the upstream repository. Create a file named post-commit with permission values 755 and the following content:

    git push
    Note

    A pre-commit script is not supported in Business Central. Use a post-commit script.

  3. Supply the Git hooks directory to the Business Central deployment. You can use a configuration map or a persistent volume.

    1. If the Git hooks consist of one or several fixed script files, use a configuration map. Complete the following steps:

      1. Change into the Git hooks directory that you have created.
      2. Create an OpenShift configuration map from the files in the directory. Run the following command:

        oc create configmap git-hooks --from-file=<file_1>=<file_1> --from-file=<file_2>=<file_2> ...

        Replace file_1, file_2, and so on with Git hook script file names. Example:

        oc create configmap git-hooks --from-file=post-commit=post-commit
      3. Mount the configuration map on the Business Central deployment in the path that you have configured:

        oc set volume dc/<myapp>-rhpamcentr --add --type configmap --configmap-name git-hooks  --mount-path=<git_hooks_dir> --name=git-hooks

        Replace <myapp> with the application name that was set when configuring the template and <git_hooks_dir> is the value of GIT_HOOKS_DIR that was set when configuring the template.

    2. If the Git hooks consist of long files or depend on binaries, such as executable or KJAR files, use a persistence volume. You must create a persistent volume, create a persistent volume claim and associate the volume with the claim, transfer files to the volume, and mount the volume in the myapp-rhpamcentr deployment configuration (replace myapp with the application name). For instructions about creating and mounting persistence volumes, see Using persistent volumes. For instructions about copying files onto a persistent volume, see Transferring files in and out of containers.
  4. Wait a few minutes, then review the list and status of pods in your project. Because Business Central does not start until you provide the Git hooks directory, the KIE Server might not start at all. To see if it has started, check the output of the following command:

    oc get pods

    If a working KIE Server pod is not present, start it:

    oc rollout latest dc/<myapp>-kieserver

    Replace <myapp> with the application name that was set when configuring the template.

13.2. (Optional) Providing a truststore for accessing HTTPS servers with self-signed certificates

Components of your Red Hat Process Automation Manager infrastructure might need to use HTTPS access to servers that have a self-signed HTTPS certificate. For example, Business Central, Business Central Monitoring, and KIE Server might need to interact with an internal Nexus repository that uses a self-signed HTTPS server certificate.

In this case, to ensure that HTTPS connections complete successfully, you must provide client certificates for these services using a truststore.

Skip this procedure if you do not need Red Hat Process Automation Manager components to communicate with servers that use self-signed HTTPS server certificates.

Prerequisites

  • You deployed a Red Hat Process Automation Manager environment using templates
  • You have the client certificates that you want to add to the deployment

Procedure

  1. Prepare a truststore with the certificates. Use the following command to create a truststore or to add a certificate to an existing truststore. Add all the necessary certificates to one truststore.

    keytool -importcert -file certificate-file -alias alias -keyalg algorithm -keysize size -trustcacerts -noprompt -storetype JKS -keypass truststore-password -storepass truststore-password -keystore keystore-file

    Replace the following values:

    • certificate-file: The pathname of the certificate that you want to add to the truststore.
    • alias: The alias for the certificate in the truststore. If you are adding more than one certificate to the truststore, every certificate must have a unique alias.
    • algorithm: The encryption algorithm used for the certificate, typically RSA.
    • size: The size of the certificate key in bytes, for example, 2048.
    • truststore-password: The password for the truststore.
    • keystore-file: The pathname of the truststore file. If the file does not exist, the command creates a new truststore.

      The following example command adds a certificate from the /var/certs/nexus.cer file to a truststore in the /var/keystores/custom-trustore.jks file. The truststore password is mykeystorepass.

      keytool -importcert -file /var/certs/nexus.cer -alias nexus-cert -keyalg RSA -keysize 2048 -trustcacerts -noprompt -storetype JKS -keypass mykeystorepass -storepass mykeystorepass -keystore /var/keystores/custom-trustore.jks
  2. Create a secret with the truststore file using the oc command, for example:

    oc create secret generic truststore-secret --from-file=/var/keystores/custom-trustore.jks
  3. In the deployment for the necessary components of your infrastructure, mount the secret and then set the JAVA_OPTS_APPEND option to enable the Java application infrastructure to use the trast store, for example:

    oc set volume dc/myapp-rhpamcentr --add --overwrite --name=custom-trustore-volume --mount-path /etc/custom-secret-volume --secret-name=custom-secret
    
    oc set env dc/myapp-rhpamcentr JAVA_OPTS_APPEND='-Djavax.net.ssl.trustStore=/etc/custom-secret-volume/custom-trustore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=mykeystorepass'
    oc set volume dc/myapp-kieserver --add --overwrite --name=custom-trustore-volume --mount-path /etc/custom-secret-volume --secret-name=custom-secret
    
    oc set env dc/myapp-kieserver JAVA_OPTS_APPEND='-Djavax.net.ssl.trustStore=/etc/custom-secret-volume/custom-trustore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=mykeystorepass'

    Replace myapp with the application name that you set when configuring the template.

13.3. (Optional) Providing the LDAP role mapping file

If you configure the AUTH_ROLE_MAPPER_ROLES_PROPERTIES parameter, you must provide a file that defines the role mapping. Mount this file on all affected deployment configurations.

Prerequisites

  • You deployed a Red Hat Process Automation Manager environment using templates
  • You set the AUTH_ROLE_MAPPER_ROLES_PROPERTIES parameter in the deployment

Procedure

  1. Create the role mapping properties file, for example, my-role-map. The file must contain entries in the following format:

    ldap_role = product_role1, product_role2...

    For example:

    admins = kie-server,rest-all,admin
  2. Create an OpenShift configuration map from the file by entering the following command:

    oc create configmap ldap-role-mapping --from-file=<new_name>=<existing_name>

    Replace <new_name> with the name that the file is to have on the pods (it must be the same as the name specified in the AUTH_ROLE_MAPPER_ROLES_PROPERTIES file) and <existing_name> with the name of the file that you created. Example:

    oc create configmap ldap-role-mapping --from-file=rolemapping.properties=my-role-map
  3. Mount the configuration map on every deployment configuration that is configured for role mapping.

    The following deployment configurations can be affected in this environment:

    Replace myapp with the application name. Sometimes, several KIE Server deployments can be present under different application names.

    For every deployment configuration, run the command:

     oc set volume dc/<deployment_config_name> --add --type configmap --configmap-name ldap-role-mapping --mount-path=<mapping_dir> --name=ldap-role-mapping

    Replace <mapping_dir> with the directory name (without file name) set in the AUTH_ROLE_MAPPER_ROLES_PROPERTIES parameter, for example, /opt/eap/standalone/configuration/rolemapping .

Chapter 14. Red Hat Process Automation Manager roles and users

To access Business Central or KIE Server, you must create users and assign them appropriate roles before the servers are started. You can create users and roles when you install Business Central or KIE Server.

Business Central and KIE Server use the Java Authentication and Authorization Service (JAAS) login module to authenticate users. If both Business Central and KIE Server are running on a single instance, then they share the same JAAS subject and security domain. Therefore, a user who is authenticated for Business Central can also access KIE Server.

However, if Business Central and KIE Server are running on different instances, then the JAAS login module is triggered for both individually. Therefore, a user who is authenticated for Business Central must be authenticated separately to access KIE Server. For example, if a user who is authenticated on Business Central but not authenticated on KIE Server tries to view or manage process definitions in Business Central, a 401 error is logged in the log file and the Invalid credentials to load data from remote server. Contact your system administrator. message appears in Business Central.

This section describes Red Hat Process Automation Manager user roles.

Note

The admin, analyst, developer, manager, process-admin, user, and rest-all roles are reserved for Business Central. The kie-server role is reserved for KIE Server. For this reason, the available roles can differ depending on whether Business Central, KIE Server, or both are installed.

  • admin: Users with the admin role are the Business Central administrators. They can manage users and create, clone, and manage repositories. They have full access to make required changes in the application. Users with the admin role have access to all areas within Red Hat Process Automation Manager.
  • analyst: Users with the analyst role have access to all high-level features. They can model and execute their projects. However, these users cannot add contributors to spaces or delete spaces in the Design → Projects view. Access to the Deploy → Execution Servers view, which is intended for administrators, is not available to users with the analyst role. However, the Deploy button is available to these users when they access the Library perspective.
  • developer: Users with the developer role have access to almost all features and can manage rules, models, process flows, forms, and dashboards. They can manage the asset repository, they can create, build, and deploy projects. Only certain administrative functions such as creating and cloning a new repository are hidden from users with the developer role.
  • manager: Users with the manager role can view reports. These users are usually interested in statistics about the business processes and their performance, business indicators, and other business-related reporting. A user with this role has access only to process and task reports.
  • process-admin: Users with the process-admin role are business process administrators. They have full access to business processes, business tasks, and execution errors. These users can also view business reports and have access to the Task Inbox list.
  • user: Users with the user role can work on the Task Inbox list, which contains business tasks that are part of currently running processes. Users with this role can view process and task reports and manage processes.
  • rest-all: Users with the rest-all role can access Business Central REST capabilities.
  • kie-server: Users with the kie-server role can access KIE Server REST capabilities. This role is mandatory for users to have access to Manage and Track views in Business Central.

Chapter 15. OpenShift template reference information

Red Hat Process Automation Manager provides the following OpenShift templates. To access the templates, download and extract the rhpam-7.10.0-openshift-templates.zip product deliverable file from the Software Downloads page of the Red Hat customer portal.

  • rhpam710-trial-ephemeral.yaml provides a Business Central and a KIE Server connected to the Business Central. This environment uses an ephemeral configuration without any persistent storage. For details about this template, see Section 15.1, “rhpam710-trial-ephemeral.yaml template”.
  • rhpam710-authoring.yaml provides a Business Central and a KIE Server connected to the Business Central. The KIE Server uses an H2 database with persistent storage. You can use this environment to author processes, services, and other business assets. For details about this template, see Section 15.2, “rhpam710-authoring.yaml template”.
  • rhpam710-authoring-ha.yaml provides a high-availability Business Central, a KIE Server connected to the Business Central, and a MySQL instance that the KIE Server uses. You can use this environment to author processes, services, and other business assets. For details about this template, see Section 15.3, “rhpam710-authoring-ha.yaml template”.
  • rhpam710-prod-immutable-monitor.yaml provides a Business Central Monitoring instance and a Smart Router that you can use with immutable KIE Servers. When you deploy this template, OpenShift displays the settings that you must then use for deploying the rhpam710-prod-immutable-kieserver.yaml template. For details about this template, see Section 15.4, “rhpam710-prod-immutable-monitor.yaml template”.
  • rhpam710-prod-immutable-kieserver.yaml provides an immutable KIE Server. When you deploy this template, a source-to-image (S2I) build is triggered for one or several services that are to run on the KIE Server. The KIE Server can optionally be configured to connect to the Business Central Monitoring and Smart Router provided by rhpam710-prod-immutable-monitor.yaml. For details about this template, see Section 15.5, “rhpam710-prod-immutable-kieserver.yaml template”.
  • rhpam710-prod-immutable-kieserver-amq.yaml provides an immutable KIE Server. When you deploy this template, a source-to-image (S2I) build is triggered for one or several services that are to run on the KIE Server. The KIE Server can optionally be configured to connect to the Business Central Monitoring and Smart Router provided by rhpam710-prod-immutable-monitor.yaml. This version of the template includes JMS integration. For details about this template, see Section 15.6, “rhpam710-prod-immutable-kieserver-amq.yaml template”.
  • rhpam710-kieserver-externaldb.yaml provides a KIE Server that uses an external database. You can configure the KIE Server to connect to a Business Central. Also, you can copy sections from this template into another template to configure a KIE Server in the other template to use an external database. For details about this template, see Section 15.7, “rhpam710-kieserver-externaldb.yaml template”.
  • rhpam710-kieserver-mysql.yaml provides a KIE Server and a MySQL instance that the KIE Server uses. You can configure the KIE Server to connect to a Business Central. Also, you can copy sections from this template into another template to configure a KIE Server in the other template to use MySQL and to provide the MySQL instance. For details about this template, see Section 15.8, “rhpam710-kieserver-mysql.yaml template”.
  • rhpam710-kieserver-postgresql.yaml provides a KIE Server and a PostgreSQL instance that the KIE Server uses. You can configure the KIE Server to connect to a Business Central. Also, you can copy sections from this template into another template to configure a KIE Server in the other template to use PostgreSQL and to provide the PostgreSQL instance. For details about this template, see Section 15.8, “rhpam710-kieserver-mysql.yaml template”.
  • rhpam710-managed.yaml provides a high-availability Business Central Monitoring instance, a KIE Server, and a PostgreSQL instance that the KIE Server uses. OpenShiftStartupStrategy is enabled, ensuring that the Business Central Monitoring instance can connect to other KIE Server instances in the same project automatically, as long as these instances have OpenShiftStartupStrategy enabled as well.
  • rhpam710-prod.yaml provides a high-availability Business Central Monitoring instance, a Smart Router, two distinct KIE Servers connected to the Business Central and to the Smart Router, and two PostgreSQL instances. Each KIE Server uses its own PostgreSQL instance. You can use this environment to execute business assets in a production or staging environment. You can configure the number of replicas for each component. For details about this template, see Section 15.11, “rhpam710-prod.yaml template”.

15.1. rhpam710-trial-ephemeral.yaml template

Application template for an ephemeral authoring and testing environment, for Red Hat Process Automation Manager 7.10 - Deprecated

15.1.1. Parameters

Templates allow you to define parameters that take on a value. That value is then substituted wherever the parameter is referenced. References can be defined in any text field in the objects list field. See the Openshift documentation for more information.

Variable nameImage Environment VariableDescriptionExample valueRequired

APPLICATION_NAME

 — 

The name for the application.

myapp

True

DEFAULT_PASSWORD

KIE_ADMIN_PWD

Default password used for multiple components for user convenience in this trial environment.

RedHat

True

KIE_ADMIN_USER

KIE_ADMIN_USER

KIE administrator user name.

adminUser

False

KIE_SERVER_BYPASS_AUTH_USER

KIE_SERVER_BYPASS_AUTH_USER

Allows the KIE Server to bypass the authenticated user for task-related operations e.g. queries. (Sets the org.kie.server.bypass.auth.user system property)

false

False

KIE_SERVER_MODE

KIE_SERVER_MODE

The KIE Server mode. Valid values are 'DEVELOPMENT' or 'PRODUCTION'. In production mode, you can not deploy SNAPSHOT versions of artifacts on the KIE Server and can not change the version of an artifact in an existing container. (Sets the org.kie.server.mode system property).

DEVELOPMENT

False

KIE_MBEANS

KIE_MBEANS

KIE Server mbeans enabled/disabled. (Sets the kie.mbeans and kie.scanner.mbeans system properties)

enabled

False

DROOLS_SERVER_FILTER_CLASSES

DROOLS_SERVER_FILTER_CLASSES

KIE Server class filtering. (Sets the org.drools.server.filter.classes system property)

true

False

PROMETHEUS_SERVER_EXT_DISABLED

PROMETHEUS_SERVER_EXT_DISABLED

If set to false, the prometheus server extension will be enabled. (Sets the org.kie.prometheus.server.ext.disabled system property)

false

False

KIE_SERVER_HOSTNAME_HTTP

HOSTNAME_HTTP

Custom hostname for http service route. Leave blank for default hostname, e.g.: insecure-<application-name>-kieserver-<project>.<default-domain-suffix>

 — 

False

KIE_SERVER_ACCESS_CONTROL_ALLOW_ORIGIN

AC_ALLOW_ORIGIN_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Origin response header value in the KIE Server (useful for CORS support).

*

False

KIE_SERVER_ACCESS_CONTROL_ALLOW_METHODS

AC_ALLOW_METHODS_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Methods response header value in the KIE Server (useful for CORS support).

GET, POST, OPTIONS, PUT

False

KIE_SERVER_ACCESS_CONTROL_ALLOW_HEADERS

AC_ALLOW_HEADERS_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Headers response header value in the KIE Server (useful for CORS support).

Accept, Authorization, Content-Type, X-Requested-With

False

KIE_SERVER_ACCESS_CONTROL_ALLOW_CREDENTIALS

AC_ALLOW_CREDENTIALS_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Credentials response header value in the KIE Server (useful for CORS support).

true

False

KIE_SERVER_ACCESS_CONTROL_MAX_AGE

AC_MAX_AGE_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Max-Age response header value in the KIE Server (useful for CORS support).

1

False

BUSINESS_CENTRAL_HOSTNAME_HTTP

HOSTNAME_HTTP

Custom hostname for http service route for Business Central. Leave blank for default hostname, e.g.: insecure-<application-name>-rhpamcentr-<project>.<default-domain-suffix>

 — 

False

KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED

KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED

If set to true, turns on KIE Server global discovery feature (Sets the org.kie.server.controller.openshift.global.discovery.enabled system property)

false

False

KIE_SERVER_CONTROLLER_OPENSHIFT_PREFER_KIESERVER_SERVICE

KIE_SERVER_CONTROLLER_OPENSHIFT_PREFER_KIESERVER_SERVICE

If OpenShift integration of Business Central is turned on, setting this parameter to true enables connection to KIE Server via an OpenShift internal Service endpoint. (Sets the org.kie.server.controller.openshift.prefer.kieserver.service system property)

true

False

KIE_SERVER_CONTROLLER_TEMPLATE_CACHE_TTL

KIE_SERVER_CONTROLLER_TEMPLATE_CACHE_TTL

KIE ServerTemplate Cache TTL in milliseconds. (Sets the org.kie.server.controller.template.cache.ttl system property)

5000

False

IMAGE_STREAM_NAMESPACE

 — 

Namespace in which the ImageStreams for Red Hat Process Automation Manager images are installed. These ImageStreams are normally installed in the openshift namespace. You need to modify this parameter only if you installed the ImageStream in a different namespace/project. Default is "openshift".

openshift

True

KIE_SERVER_IMAGE_STREAM_NAME

 — 

The name of the image stream to use for KIE Server. Default is "rhpam-kieserver-rhel8".

rhpam-kieserver-rhel8

True

IMAGE_STREAM_TAG

 — 

A named pointer to an image in an image stream. Default is "7.10.0".

7.10.0

True

KIE_SERVER_CONTAINER_DEPLOYMENT

KIE_SERVER_CONTAINER_DEPLOYMENT

KIE Server Container deployment configuration with optional alias. Format: containerId=groupId:artifactId:version|c2(alias2)=g2:a2:v2

 — 

False

MAVEN_REPO_ID

MAVEN_REPO_ID

The id to use for the maven repository, if set. Default is generated randomly.

repo-custom

False

MAVEN_REPO_URL

MAVEN_REPO_URL

Fully qualified URL to a Maven repository or service.

http://nexus.nexus-project.svc.cluster.local:8081/nexus/content/groups/public/

False

MAVEN_REPO_USERNAME

MAVEN_REPO_USERNAME

User name for accessing the Maven repository, if required.

 — 

False

MAVEN_REPO_PASSWORD

MAVEN_REPO_PASSWORD

Password to access the Maven repository, if required.

 — 

False

GIT_HOOKS_DIR

GIT_HOOKS_DIR

The directory to use for git hooks, if required.

/opt/kie/data/git/hooks

False

BUSINESS_CENTRAL_MEMORY_LIMIT

 — 

Business Central Container memory limit.

2Gi

False

KIE_SERVER_MEMORY_LIMIT

 — 

KIE Server Container memory limit.

1Gi

False

SSO_URL

SSO_URL

RH-SSO URL.

https://rh-sso.example.com/auth

False

SSO_REALM

SSO_REALM

RH-SSO Realm name.

 — 

False

BUSINESS_CENTRAL_SSO_CLIENT

SSO_CLIENT

Business Central RH-SSO Client name.

 — 

False

BUSINESS_CENTRAL_SSO_SECRET

SSO_SECRET

Business Central RH-SSO Client Secret.

252793ed-7118-4ca8-8dab-5622fa97d892

False

KIE_SERVER_SSO_CLIENT

SSO_CLIENT

KIE Server RH-SSO Client name.

 — 

False

KIE_SERVER_SSO_SECRET

SSO_SECRET

KIE Server RH-SSO Client Secret.

252793ed-7118-4ca8-8dab-5622fa97d892

False

SSO_USERNAME

SSO_USERNAME

RH-SSO Realm admin user name for creating the Client if it doesn’t exist.

 — 

False

SSO_PASSWORD

SSO_PASSWORD

RH-SSO Realm Admin Password used to create the Client.

 — 

False

SSO_DISABLE_SSL_CERTIFICATE_VALIDATION

SSO_DISABLE_SSL_CERTIFICATE_VALIDATION

RH-SSO Disable SSL Certificate Validation.

false

False

SSO_PRINCIPAL_ATTRIBUTE

SSO_PRINCIPAL_ATTRIBUTE

RH-SSO Principal Attribute to use as user name.

preferred_username

False

AUTH_LDAP_URL

AUTH_LDAP_URL

LDAP endpoint to connect for authentication. For failover, set two or more LDAP endpoints separated by space.

ldap://myldap.example.com:389

False

AUTH_LDAP_BIND_DN

AUTH_LDAP_BIND_DN

Bind DN used for authentication.

uid=admin,ou=users,ou=example,ou=com

False

AUTH_LDAP_BIND_CREDENTIAL

AUTH_LDAP_BIND_CREDENTIAL

LDAP Credentials used for authentication.

Password

False

AUTH_LDAP_LOGIN_MODULE

AUTH_LDAP_LOGIN_MODULE

A flag to set login module to optional. The default value is required

optional

False

AUTH_LDAP_JAAS_SECURITY_DOMAIN

AUTH_LDAP_JAAS_SECURITY_DOMAIN

The JMX ObjectName of the JaasSecurityDomain used to decrypt the password.

 — 

False

AUTH_LDAP_BASE_CTX_DN

AUTH_LDAP_BASE_CTX_DN

LDAP Base DN of the top-level context to begin the user search.

ou=users,ou=example,ou=com

False

AUTH_LDAP_BASE_FILTER

AUTH_LDAP_BASE_FILTER

LDAP search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).

(uid={0})

False

AUTH_LDAP_SEARCH_SCOPE

AUTH_LDAP_SEARCH_SCOPE

The search scope to use.

SUBTREE_SCOPE

False

AUTH_LDAP_SEARCH_TIME_LIMIT

AUTH_LDAP_SEARCH_TIME_LIMIT

The timeout in milliseconds for user or role searches.

10000

False

AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE

AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE

The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters, backslash for example, that prevent correct user mapping. If the attribute does not exist, the entry’s DN is used.

distinguishedName

False

AUTH_LDAP_PARSE_USERNAME

AUTH_LDAP_PARSE_USERNAME

A flag indicating if the DN is to be parsed for the user name. If set to true, the DN is parsed for the user name. If set to false the DN is not parsed for the user name. This option is used together with usernameBeginString and usernameEndString.

true

False

AUTH_LDAP_USERNAME_BEGIN_STRING

AUTH_LDAP_USERNAME_BEGIN_STRING

Defines the String which is to be removed from the start of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

 — 

False

AUTH_LDAP_USERNAME_END_STRING

AUTH_LDAP_USERNAME_END_STRING

Defines the String which is to be removed from the end of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

 — 

False

AUTH_LDAP_ROLE_ATTRIBUTE_ID

AUTH_LDAP_ROLE_ATTRIBUTE_ID

Name of the attribute containing the user roles.

memberOf

False

AUTH_LDAP_ROLES_CTX_DN

AUTH_LDAP_ROLES_CTX_DN

The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.

ou=groups,ou=example,ou=com

False

AUTH_LDAP_ROLE_FILTER

AUTH_LDAP_ROLE_FILTER

A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

(memberOf={1})

False

AUTH_LDAP_ROLE_RECURSION

AUTH_LDAP_ROLE_RECURSION

The number of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.

1

False

AUTH_LDAP_DEFAULT_ROLE

AUTH_LDAP_DEFAULT_ROLE

A role included for all authenticated users.

user

False

AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID

AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID

Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object’s name attribute.

name

False

AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN

AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN

A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameAttributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.

false

False

AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN

AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN

Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.

false

False

AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK

AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK

If you are not using referrals, you can ignore this option. When using referrals, this option denotes the attribute name which contains users defined for a certain role, for example member, if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

 — 

False

AUTH_ROLE_MAPPER_ROLES_PROPERTIES

AUTH_ROLE_MAPPER_ROLES_PROPERTIES

When present, the RoleMapping Login Module will be configured to use the provided file. This parameter defines the fully-qualified file path and name of a properties file or resource which maps roles to replacement roles. The format is original_role=role1,role2,role3

 — 

False

AUTH_ROLE_MAPPER_REPLACE_ROLE

AUTH_ROLE_MAPPER_REPLACE_ROLE

Whether to add to the current roles, or replace the current roles with the mapped ones. Replaces if set to true.

 — 

False

15.1.2. Objects

The CLI supports various object types. A list of these object types as well as their abbreviations can be found in the Openshift documentation.

15.1.2.1. Services

A service is an abstraction which defines a logical set of pods and a policy by which to access them. See the container-engine documentation for more information.

ServicePortNameDescription

${APPLICATION_NAME}-rhpamcentr

8080

http

All the Business Central web server’s ports.

${APPLICATION_NAME}-kieserver

8080

 — 

All the KIE Server web server’s ports.

15.1.2.2. Routes

A route is a way to expose a service by giving it an externally reachable hostname such as www.example.com. A defined route and the endpoints identified by its service can be consumed by a router to provide named connectivity from external clients to your applications. Each route consists of a route name, service selector, and (optionally) security configuration. See the Openshift documentation for more information.

ServiceSecurityHostname

insecure-${APPLICATION_NAME}-rhpamcentr-http

none

${BUSINESS_CENTRAL_HOSTNAME_HTTP}

insecure-${APPLICATION_NAME}-kieserver-http

none

${KIE_SERVER_HOSTNAME_HTTP}

15.1.2.3. Deployment Configurations

A deployment in OpenShift is a replication controller based on a user-defined template called a deployment configuration. Deployments are created manually or in response to triggered events. See the Openshift documentation for more information.

15.1.2.3.1. Triggers

A trigger drives the creation of new deployments in response to events, both inside and outside OpenShift. See the Openshift documentation for more information.

DeploymentTriggers

${APPLICATION_NAME}-rhpamcentr

ImageChange

${APPLICATION_NAME}-kieserver

ImageChange

15.1.2.3.2. Replicas

A replication controller ensures that a specified number of pod "replicas" are running at any one time. If there are too many, the replication controller kills some pods. If there are too few, it starts more. See the container-engine documentation for more information.

DeploymentReplicas

${APPLICATION_NAME}-rhpamcentr

1

${APPLICATION_NAME}-kieserver

1

15.1.2.3.3. Pod Template
15.1.2.3.3.1. Service Accounts

Service accounts are API objects that exist within each project. They can be created or deleted like any other API object. See the Openshift documentation for more information.

DeploymentService Account

${APPLICATION_NAME}-rhpamcentr

${APPLICATION_NAME}-rhpamsvc

${APPLICATION_NAME}-kieserver

${APPLICATION_NAME}-rhpamsvc

15.1.2.3.3.2. Image
DeploymentImage

${APPLICATION_NAME}-rhpamcentr

rhpam-businesscentral-rhel8

${APPLICATION_NAME}-kieserver

${KIE_SERVER_IMAGE_STREAM_NAME}

15.1.2.3.3.3. Readiness Probe

${APPLICATION_NAME}-rhpamcentr

Http Get on http://localhost:8080/rest/ready

${APPLICATION_NAME}-kieserver

Http Get on http://localhost:8080/services/rest/server/readycheck

15.1.2.3.3.4. Liveness Probe

${APPLICATION_NAME}-rhpamcentr

Http Get on http://localhost:8080/rest/healthy

${APPLICATION_NAME}-kieserver

Http Get on http://localhost:8080/services/rest/server/healthcheck

15.1.2.3.3.5. Exposed Ports
DeploymentsNamePortProtocol

${APPLICATION_NAME}-rhpamcentr

jolokia

8778

TCP

http

8080

TCP

${APPLICATION_NAME}-kieserver

jolokia

8778

TCP

http

8080

TCP

15.1.2.3.3.6. Image Environment Variables
DeploymentVariable nameDescriptionExample value

${APPLICATION_NAME}-rhpamcentr

WORKBENCH_ROUTE_NAME

 — 

insecure-${APPLICATION_NAME}-rhpamcentr

KIE_ADMIN_USER

KIE administrator user name.

${KIE_ADMIN_USER}

KIE_ADMIN_PWD

Default password used for multiple components for user convenience in this trial environment.

${DEFAULT_PASSWORD}

KIE_MBEANS

KIE Server mbeans enabled/disabled. (Sets the kie.mbeans and kie.scanner.mbeans system properties)

${KIE_MBEANS}

KIE_SERVER_CONTROLLER_OPENSHIFT_ENABLED

 — 

true

KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED

If set to true, turns on KIE Server global discovery feature (Sets the org.kie.server.controller.openshift.global.discovery.enabled system property)

${KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED}

KIE_SERVER_CONTROLLER_OPENSHIFT_PREFER_KIESERVER_SERVICE

If OpenShift integration of Business Central is turned on, setting this parameter to true enables connection to KIE Server via an OpenShift internal Service endpoint. (Sets the org.kie.server.controller.openshift.prefer.kieserver.service system property)

${KIE_SERVER_CONTROLLER_OPENSHIFT_PREFER_KIESERVER_SERVICE}

KIE_SERVER_CONTROLLER_TEMPLATE_CACHE_TTL

KIE ServerTemplate Cache TTL in milliseconds. (Sets the org.kie.server.controller.template.cache.ttl system property)

${KIE_SERVER_CONTROLLER_TEMPLATE_CACHE_TTL}

MAVEN_REPO_ID

The id to use for the maven repository, if set. Default is generated randomly.

${MAVEN_REPO_ID}

MAVEN_REPO_URL

Fully qualified URL to a Maven repository or service.

${MAVEN_REPO_URL}

MAVEN_REPO_USERNAME

User name for accessing the Maven repository, if required.

${MAVEN_REPO_USERNAME}

MAVEN_REPO_PASSWORD

Password to access the Maven repository, if required.

${MAVEN_REPO_PASSWORD}

GIT_HOOKS_DIR

The directory to use for git hooks, if required.

${GIT_HOOKS_DIR}

KUBERNETES_NAMESPACE

 — 

 — 

SSO_URL

RH-SSO URL.

${SSO_URL}

SSO_OPENIDCONNECT_DEPLOYMENTS

 — 

ROOT.war

SSO_REALM

RH-SSO Realm name.

${SSO_REALM}

SSO_SECRET

Business Central RH-SSO Client Secret.

${BUSINESS_CENTRAL_SSO_SECRET}

SSO_CLIENT

Business Central RH-SSO Client name.

${BUSINESS_CENTRAL_SSO_CLIENT}

SSO_USERNAME

RH-SSO Realm admin user name for creating the Client if it doesn’t exist.

${SSO_USERNAME}

SSO_PASSWORD

RH-SSO Realm Admin Password used to create the Client.

${SSO_PASSWORD}

SSO_DISABLE_SSL_CERTIFICATE_VALIDATION

RH-SSO Disable SSL Certificate Validation.

${SSO_DISABLE_SSL_CERTIFICATE_VALIDATION}

SSO_PRINCIPAL_ATTRIBUTE

RH-SSO Principal Attribute to use as user name.

${SSO_PRINCIPAL_ATTRIBUTE}

HOSTNAME_HTTP

Custom hostname for http service route for Business Central. Leave blank for default hostname, e.g.: insecure-<application-name>-rhpamcentr-<project>.<default-domain-suffix>

${BUSINESS_CENTRAL_HOSTNAME_HTTP}

AUTH_LDAP_URL

LDAP endpoint to connect for authentication. For failover, set two or more LDAP endpoints separated by space.

${AUTH_LDAP_URL}

AUTH_LDAP_BIND_DN

Bind DN used for authentication.

${AUTH_LDAP_BIND_DN}

AUTH_LDAP_BIND_CREDENTIAL

LDAP Credentials used for authentication.

${AUTH_LDAP_BIND_CREDENTIAL}

AUTH_LDAP_LOGIN_MODULE

A flag to set login module to optional. The default value is required

${AUTH_LDAP_LOGIN_MODULE}

AUTH_LDAP_JAAS_SECURITY_DOMAIN

The JMX ObjectName of the JaasSecurityDomain used to decrypt the password.

${AUTH_LDAP_JAAS_SECURITY_DOMAIN}

AUTH_LDAP_BASE_CTX_DN

LDAP Base DN of the top-level context to begin the user search.

${AUTH_LDAP_BASE_CTX_DN}

AUTH_LDAP_BASE_FILTER

LDAP search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).

${AUTH_LDAP_BASE_FILTER}

AUTH_LDAP_SEARCH_SCOPE

The search scope to use.

${AUTH_LDAP_SEARCH_SCOPE}

AUTH_LDAP_SEARCH_TIME_LIMIT

The timeout in milliseconds for user or role searches.

${AUTH_LDAP_SEARCH_TIME_LIMIT}

AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE

The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters, backslash for example, that prevent correct user mapping. If the attribute does not exist, the entry’s DN is used.

${AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE}

AUTH_LDAP_PARSE_USERNAME

A flag indicating if the DN is to be parsed for the user name. If set to true, the DN is parsed for the user name. If set to false the DN is not parsed for the user name. This option is used together with usernameBeginString and usernameEndString.

${AUTH_LDAP_PARSE_USERNAME}

AUTH_LDAP_USERNAME_BEGIN_STRING

Defines the String which is to be removed from the start of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

${AUTH_LDAP_USERNAME_BEGIN_STRING}

AUTH_LDAP_USERNAME_END_STRING

Defines the String which is to be removed from the end of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

${AUTH_LDAP_USERNAME_END_STRING}

AUTH_LDAP_ROLE_ATTRIBUTE_ID

Name of the attribute containing the user roles.

${AUTH_LDAP_ROLE_ATTRIBUTE_ID}

AUTH_LDAP_ROLES_CTX_DN

The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.

${AUTH_LDAP_ROLES_CTX_DN}

AUTH_LDAP_ROLE_FILTER

A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

${AUTH_LDAP_ROLE_FILTER}

AUTH_LDAP_ROLE_RECURSION

The number of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.

${AUTH_LDAP_ROLE_RECURSION}

AUTH_LDAP_DEFAULT_ROLE

A role included for all authenticated users.

${AUTH_LDAP_DEFAULT_ROLE}

AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID

Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object’s name attribute.

${AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID}

AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN

A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameAttributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.

${AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN}

AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN

Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.

${AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN}

AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK

If you are not using referrals, you can ignore this option. When using referrals, this option denotes the attribute name which contains users defined for a certain role, for example member, if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

${AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK}

AUTH_ROLE_MAPPER_ROLES_PROPERTIES

When present, the RoleMapping Login Module will be configured to use the provided file. This parameter defines the fully-qualified file path and name of a properties file or resource which maps roles to replacement roles. The format is original_role=role1,role2,role3

${AUTH_ROLE_MAPPER_ROLES_PROPERTIES}

AUTH_ROLE_MAPPER_REPLACE_ROLE

Whether to add to the current roles, or replace the current roles with the mapped ones. Replaces if set to true.

${AUTH_ROLE_MAPPER_REPLACE_ROLE}

${APPLICATION_NAME}-kieserver

WORKBENCH_SERVICE_NAME

 — 

${APPLICATION_NAME}-rhpamcentr

KIE_ADMIN_USER

KIE administrator user name.

${KIE_ADMIN_USER}

KIE_ADMIN_PWD

Default password used for multiple components for user convenience in this trial environment.

${DEFAULT_PASSWORD}

KIE_SERVER_MODE

The KIE Server mode. Valid values are 'DEVELOPMENT' or 'PRODUCTION'. In production mode, you can not deploy SNAPSHOT versions of artifacts on the KIE Server and can not change the version of an artifact in an existing container. (Sets the org.kie.server.mode system property).

${KIE_SERVER_MODE}

KIE_MBEANS

KIE Server mbeans enabled/disabled. (Sets the kie.mbeans and kie.scanner.mbeans system properties)

${KIE_MBEANS}

DROOLS_SERVER_FILTER_CLASSES

KIE Server class filtering. (Sets the org.drools.server.filter.classes system property)

${DROOLS_SERVER_FILTER_CLASSES}

PROMETHEUS_SERVER_EXT_DISABLED

If set to false, the prometheus server extension will be enabled. (Sets the org.kie.prometheus.server.ext.disabled system property)

${PROMETHEUS_SERVER_EXT_DISABLED}

KIE_SERVER_BYPASS_AUTH_USER

Allows the KIE Server to bypass the authenticated user for task-related operations e.g. queries. (Sets the org.kie.server.bypass.auth.user system property)

${KIE_SERVER_BYPASS_AUTH_USER}

KIE_SERVER_ID

 — 

 — 

KIE_SERVER_ROUTE_NAME

 — 

insecure-${APPLICATION_NAME}-kieserver

KIE_SERVER_STARTUP_STRATEGY

 — 

OpenShiftStartupStrategy

KIE_SERVER_CONTAINER_DEPLOYMENT

KIE Server Container deployment configuration with optional alias. Format: containerId=groupId:artifactId:version|c2(alias2)=g2:a2:v2

${KIE_SERVER_CONTAINER_DEPLOYMENT}

MAVEN_REPOS

 — 

RHPAMCENTR,EXTERNAL

RHPAMCENTR_MAVEN_REPO_ID

 — 

repo-rhpamcentr

RHPAMCENTR_MAVEN_REPO_SERVICE

 — 

${APPLICATION_NAME}-rhpamcentr

RHPAMCENTR_MAVEN_REPO_PATH

 — 

/maven2/

RHPAMCENTR_MAVEN_REPO_USERNAME

KIE administrator user name.

${KIE_ADMIN_USER}

RHPAMCENTR_MAVEN_REPO_PASSWORD

Default password used for multiple components for user convenience in this trial environment.

${DEFAULT_PASSWORD}

EXTERNAL_MAVEN_REPO_ID

The id to use for the maven repository, if set. Default is generated randomly.

${MAVEN_REPO_ID}

EXTERNAL_MAVEN_REPO_URL

Fully qualified URL to a Maven repository or service.

${MAVEN_REPO_URL}

EXTERNAL_MAVEN_REPO_USERNAME

User name for accessing the Maven repository, if required.

${MAVEN_REPO_USERNAME}

EXTERNAL_MAVEN_REPO_PASSWORD

Password to access the Maven repository, if required.

${MAVEN_REPO_PASSWORD}

KUBERNETES_NAMESPACE

 — 

 — 

SSO_URL

RH-SSO URL.

${SSO_URL}

SSO_OPENIDCONNECT_DEPLOYMENTS

 — 

ROOT.war

SSO_REALM

RH-SSO Realm name.

${SSO_REALM}

SSO_SECRET

KIE Server RH-SSO Client Secret.

${KIE_SERVER_SSO_SECRET}

SSO_CLIENT

KIE Server RH-SSO Client name.

${KIE_SERVER_SSO_CLIENT}

SSO_USERNAME

RH-SSO Realm admin user name for creating the Client if it doesn’t exist.

${SSO_USERNAME}

SSO_PASSWORD

RH-SSO Realm Admin Password used to create the Client.

${SSO_PASSWORD}

SSO_DISABLE_SSL_CERTIFICATE_VALIDATION

RH-SSO Disable SSL Certificate Validation.

${SSO_DISABLE_SSL_CERTIFICATE_VALIDATION}

SSO_PRINCIPAL_ATTRIBUTE

RH-SSO Principal Attribute to use as user name.

${SSO_PRINCIPAL_ATTRIBUTE}

HOSTNAME_HTTP

Custom hostname for http service route. Leave blank for default hostname, e.g.: insecure-<application-name>-kieserver-<project>.<default-domain-suffix>

${KIE_SERVER_HOSTNAME_HTTP}

AUTH_LDAP_URL

LDAP endpoint to connect for authentication. For failover, set two or more LDAP endpoints separated by space.

${AUTH_LDAP_URL}

AUTH_LDAP_BIND_DN

Bind DN used for authentication.

${AUTH_LDAP_BIND_DN}

AUTH_LDAP_BIND_CREDENTIAL

LDAP Credentials used for authentication.

${AUTH_LDAP_BIND_CREDENTIAL}

AUTH_LDAP_LOGIN_MODULE

A flag to set login module to optional. The default value is required

${AUTH_LDAP_LOGIN_MODULE}

AUTH_LDAP_JAAS_SECURITY_DOMAIN

The JMX ObjectName of the JaasSecurityDomain used to decrypt the password.

${AUTH_LDAP_JAAS_SECURITY_DOMAIN}

AUTH_LDAP_BASE_CTX_DN

LDAP Base DN of the top-level context to begin the user search.

${AUTH_LDAP_BASE_CTX_DN}

AUTH_LDAP_BASE_FILTER

LDAP search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).

${AUTH_LDAP_BASE_FILTER}

AUTH_LDAP_SEARCH_SCOPE

The search scope to use.

${AUTH_LDAP_SEARCH_SCOPE}

AUTH_LDAP_SEARCH_TIME_LIMIT

The timeout in milliseconds for user or role searches.

${AUTH_LDAP_SEARCH_TIME_LIMIT}

AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE

The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters, backslash for example, that prevent correct user mapping. If the attribute does not exist, the entry’s DN is used.

${AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE}

AUTH_LDAP_PARSE_USERNAME

A flag indicating if the DN is to be parsed for the user name. If set to true, the DN is parsed for the user name. If set to false the DN is not parsed for the user name. This option is used together with usernameBeginString and usernameEndString.

${AUTH_LDAP_PARSE_USERNAME}

AUTH_LDAP_USERNAME_BEGIN_STRING

Defines the String which is to be removed from the start of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

${AUTH_LDAP_USERNAME_BEGIN_STRING}

AUTH_LDAP_USERNAME_END_STRING

Defines the String which is to be removed from the end of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

${AUTH_LDAP_USERNAME_END_STRING}

AUTH_LDAP_ROLE_ATTRIBUTE_ID

Name of the attribute containing the user roles.

${AUTH_LDAP_ROLE_ATTRIBUTE_ID}

AUTH_LDAP_ROLES_CTX_DN

The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.

${AUTH_LDAP_ROLES_CTX_DN}

AUTH_LDAP_ROLE_FILTER

A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

${AUTH_LDAP_ROLE_FILTER}

AUTH_LDAP_ROLE_RECURSION

The number of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.

${AUTH_LDAP_ROLE_RECURSION}

AUTH_LDAP_DEFAULT_ROLE

A role included for all authenticated users.

${AUTH_LDAP_DEFAULT_ROLE}

AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID

Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object’s name attribute.

${AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID}

AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN

A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameAttributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.

${AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN}

AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN

Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.

${AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN}

AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK

If you are not using referrals, you can ignore this option. When using referrals, this option denotes the attribute name which contains users defined for a certain role, for example member, if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

${AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK}

AUTH_ROLE_MAPPER_ROLES_PROPERTIES

When present, the RoleMapping Login Module will be configured to use the provided file. This parameter defines the fully-qualified file path and name of a properties file or resource which maps roles to replacement roles. The format is original_role=role1,role2,role3

${AUTH_ROLE_MAPPER_ROLES_PROPERTIES}

AUTH_ROLE_MAPPER_REPLACE_ROLE

Whether to add to the current roles, or replace the current roles with the mapped ones. Replaces if set to true.

${AUTH_ROLE_MAPPER_REPLACE_ROLE}

FILTERS

 — 

AC_ALLOW_ORIGIN,AC_ALLOW_METHODS,AC_ALLOW_HEADERS,AC_ALLOW_CREDENTIALS,AC_MAX_AGE

AC_ALLOW_ORIGIN_FILTER_RESPONSE_HEADER_NAME

 — 

Access-Control-Allow-Origin

AC_ALLOW_ORIGIN_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Origin response header value in the KIE Server (useful for CORS support).

${KIE_SERVER_ACCESS_CONTROL_ALLOW_ORIGIN}

AC_ALLOW_METHODS_FILTER_RESPONSE_HEADER_NAME

 — 

Access-Control-Allow-Methods

AC_ALLOW_METHODS_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Methods response header value in the KIE Server (useful for CORS support).

${KIE_SERVER_ACCESS_CONTROL_ALLOW_METHODS}

AC_ALLOW_HEADERS_FILTER_RESPONSE_HEADER_NAME

 — 

Access-Control-Allow-Headers

AC_ALLOW_HEADERS_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Headers response header value in the KIE Server (useful for CORS support).

${KIE_SERVER_ACCESS_CONTROL_ALLOW_HEADERS}

AC_ALLOW_CREDENTIALS_FILTER_RESPONSE_HEADER_NAME

 — 

Access-Control-Allow-Credentials

AC_ALLOW_CREDENTIALS_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Allow-Credentials response header value in the KIE Server (useful for CORS support).

${KIE_SERVER_ACCESS_CONTROL_ALLOW_CREDENTIALS}

AC_MAX_AGE_FILTER_RESPONSE_HEADER_NAME

 — 

Access-Control-Max-Age

AC_MAX_AGE_FILTER_RESPONSE_HEADER_VALUE

Sets the Access-Control-Max-Age response header value in the KIE Server (useful for CORS support).

${KIE_SERVER_ACCESS_CONTROL_MAX_AGE}

15.1.2.4. External Dependencies

15.1.2.4.1. Secrets

This template requires the following secrets to be installed for the application to run.

15.2. rhpam710-authoring.yaml template

Application template for a non-HA persistent authoring environment, for Red Hat Process Automation Manager 7.10 - Deprecated

15.2.1. Parameters

Templates allow you to define parameters that take on a value. That value is then substituted wherever the parameter is referenced. References can be defined in any text field in the objects list field. See the Openshift documentation for more information.

Variable nameImage Environment VariableDescriptionExample valueRequired

APPLICATION_NAME

 — 

The name for the application.

myapp

True

CREDENTIALS_SECRET

 — 

Secret containing the KIE_ADMIN_USER and KIE_ADMIN_PWD values.

rhpam-credentials

True

KIE_SERVER_CONTROLLER_TOKEN

KIE_SERVER_CONTROLLER_TOKEN

KIE Server controller token for bearer authentication. (Sets the org.kie.server.controller.token system property)

 — 

False

KIE_SERVER_BYPASS_AUTH_USER

KIE_SERVER_BYPASS_AUTH_USER

Allows the KIE Server to bypass the authenticated user for task-related operations, for example, queries. (Sets the org.kie.server.bypass.auth.user system property)

false

False

KIE_SERVER_PERSISTENCE_DS

RHPAM_JNDI

KIE Server persistence datasource. (Sets the org.kie.server.persistence.ds system property)

java:/jboss/datasources/rhpam

False

KIE_SERVER_H2_USER

RHPAM_USERNAME

KIE Server H2 database user name.

sa

False

KIE_SERVER_H2_PWD

RHPAM_PASSWORD

KIE Server H2 database password.

 — 

False

KIE_SERVER_MODE

KIE_SERVER_MODE

The KIE Server mode. Valid values are 'DEVELOPMENT' or 'PRODUCTION'. In production mode, you can not deploy SNAPSHOT versions of artifacts on the KIE Server and can not change the version of an artifact in an existing container. (Sets the org.kie.server.mode system property)

DEVELOPMENT

False

KIE_MBEANS

KIE_MBEANS

KIE Server mbeans enabled/disabled. (Sets the kie.mbeans and kie.scanner.mbeans system properties)

enabled

False

DROOLS_SERVER_FILTER_CLASSES

DROOLS_SERVER_FILTER_CLASSES

KIE Server class filtering. (Sets the org.drools.server.filter.classes system property)

true

False

PROMETHEUS_SERVER_EXT_DISABLED

PROMETHEUS_SERVER_EXT_DISABLED

If set to false, the prometheus server extension will be enabled. (Sets the org.kie.prometheus.server.ext.disabled system property)

false

False

BUSINESS_CENTRAL_HOSTNAME_HTTP

HOSTNAME_HTTP

Custom hostname for the http service route for Business Central. Leave blank for default hostname, e.g.: insecure-<application-name>-rhpamcentr-<project>.<default-domain-suffix>

 — 

False

BUSINESS_CENTRAL_HOSTNAME_HTTPS

HOSTNAME_HTTPS

Custom hostname for the https service route for Business Central. Leave blank for default hostname, e.g.: <application-name>-rhpamcentr-<project>.<default-domain-suffix>

 — 

False

KIE_SERVER_HOSTNAME_HTTP

HOSTNAME_HTTP

Custom hostname for the http service route for KIE Server. Leave blank for default hostname, e.g.: insecure-<application-name>-kieserver-<project>.<default-domain-suffix>

 — 

False

KIE_SERVER_HOSTNAME_HTTPS

HOSTNAME_HTTPS

Custom hostname for the https service route for KIE Server. Leave blank for default hostname, e.g.: <application-name>-kieserver-<project>.<default-domain-suffix>

 — 

False

BUSINESS_CENTRAL_HTTPS_SECRET

 — 

The name of the secret containing the keystore file for Business Central.

businesscentral-app-secret

True

BUSINESS_CENTRAL_HTTPS_KEYSTORE

HTTPS_KEYSTORE

The name of the keystore file within the secret.

keystore.jks

False

BUSINESS_CENTRAL_HTTPS_NAME

HTTPS_NAME

The name associated with the server certificate.

jboss

False

BUSINESS_CENTRAL_HTTPS_PASSWORD

HTTPS_PASSWORD

The password for the keystore and certificate.

mykeystorepass

False

KIE_SERVER_HTTPS_SECRET

 — 

The name of the secret containing the keystore file for KIE Server.

kieserver-app-secret

True

KIE_SERVER_HTTPS_KEYSTORE

HTTPS_KEYSTORE

The name of the keystore file within the secret.

keystore.jks

False

KIE_SERVER_HTTPS_NAME

HTTPS_NAME

The name associated with the server certificate.

jboss

False

KIE_SERVER_HTTPS_PASSWORD

HTTPS_PASSWORD

The password for the keystore and certificate.

mykeystorepass

False

DB_VOLUME_CAPACITY

 — 

Size of persistent storage for the database volume.

1Gi

True

KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED

KIE_SERVER_CONTROLLER_OPENSHIFT_GLOBAL_DISCOVERY_ENABLED

If set to true, turns on KIE Server global discovery feature (Sets the org.kie.server.controller.openshift.global.discovery.enabled system property)

false

False

KIE_SERVER_CONTROLLER_OPENSHIFT_PREFER_KIESERVER_SERVICE

KIE_SERVER_CONTROLLER_OPENSHIFT_PREFER_KIESERVER_SERVICE

If OpenShift integration of Business Central is turned on, setting this parameter to true enables connection to KIE Server via an OpenShift internal Service endpoint. (Sets the org.kie.server.controller.openshift.prefer.kieserver.service system property)

true

False

KIE_SERVER_CONTROLLER_TEMPLATE_CACHE_TTL

KIE_SERVER_CONTROLLER_TEMPLATE_CACHE_TTL

KIE ServerTemplate Cache TTL in milliseconds. (Sets the org.kie.server.controller.template.cache.ttl system property)

5000

False

IMAGE_STREAM_NAMESPACE

 — 

Namespace in which the ImageStreams for Red Hat Process Automation Manager images are installed. These ImageStreams are normally installed in the openshift namespace. You need to modify this parameter only if you installed the ImageStream in a different namespace/project. Default is "openshift".

openshift

True

KIE_SERVER_IMAGE_STREAM_NAME

 — 

The name of the image stream to use for KIE Server. Default is "rhpam-kieserver-rhel8".

rhpam-kieserver-rhel8

True

IMAGE_STREAM_TAG

 — 

A named pointer to an image in an image stream. Default is "7.10.0".

7.10.0

True

MAVEN_MIRROR_URL

MAVEN_MIRROR_URL

Maven mirror that Business Central and KIE Server must use. If you configure a mirror, this mirror must contain all artifacts that are required for building and deploying your services.

 — 

False

MAVEN_MIRROR_OF

MAVEN_MIRROR_OF

Maven mirror configuration for KIE Server.

external:*,!repo-rhpamcentr

False

MAVEN_REPO_ID

MAVEN_REPO_ID

The id to use for the maven repository. If set, it can be excluded from the optionally configured mirror by adding it to MAVEN_MIRROR_OF. For example: external:*,!repo-rhpamcentr,!repo-custom. If MAVEN_MIRROR_URL is set but MAVEN_MIRROR_ID is not set, an id will be generated randomly, but won’t be usable in MAVEN_MIRROR_OF.

repo-custom

False

MAVEN_REPO_URL

MAVEN_REPO_URL

Fully qualified URL to a Maven repository or service.

http://nexus.nexus-project.svc.cluster.local:8081/nexus/content/groups/public/

False

MAVEN_REPO_USERNAME

MAVEN_REPO_USERNAME

User name for accessing the Maven repository, if required.

 — 

False

MAVEN_REPO_PASSWORD

MAVEN_REPO_PASSWORD

Password to access the Maven repository, if required.

 — 

False

GIT_HOOKS_DIR

GIT_HOOKS_DIR

The directory to use for git hooks, if required.

/opt/kie/data/git/hooks

False

BUSINESS_CENTRAL_VOLUME_CAPACITY

 — 

Size of the persistent storage for Business Central runtime data.

1Gi

True

BUSINESS_CENTRAL_MEMORY_LIMIT

 — 

Business Central Container memory limit.

4Gi

True

BUSINESS_CENTRAL_CPU_LIMIT

 — 

Business Central Container CPU limit.

2

True

BUSINESS_CENTRAL_CPU_REQUEST

 — 

Business Central Container CPU Request.

1500m

True

BUSINESS_CENTRAL_MEMORY_REQUEST

 — 

Business Central Container Memory Request.

3Gi

True

KIE_SERVER_MEMORY_LIMIT

 — 

KIE Server Container memory limit.

2Gi

True

KIE_SERVER_MEMORY_REQUEST

 — 

KIE Server Container memory Request.

1.5Gi

True

KIE_SERVER_CPU_LIMIT

 — 

KIE Server Container CPU limit.

1

True

KIE_SERVER_CPU_REQUEST

 — 

KIE Server Container CPU Request.

750m

True

SSO_URL

SSO_URL

RH-SSO URL.

https://rh-sso.example.com/auth

False

SSO_REALM

SSO_REALM

RH-SSO Realm name.

 — 

False

BUSINESS_CENTRAL_SSO_CLIENT

SSO_CLIENT

Business Central RH-SSO Client name.

 — 

False

BUSINESS_CENTRAL_SSO_SECRET

SSO_SECRET

Business Central RH-SSO Client Secret.

252793ed-7118-4ca8-8dab-5622fa97d892

False

KIE_SERVER_SSO_CLIENT

SSO_CLIENT

KIE Server RH-SSO Client name.

 — 

False

KIE_SERVER_SSO_SECRET

SSO_SECRET

KIE Server RH-SSO Client Secret.

252793ed-7118-4ca8-8dab-5622fa97d892

False

SSO_USERNAME

SSO_USERNAME

RH-SSO Realm admin user name for creating the Client if it doesn’t exist.

 — 

False

SSO_PASSWORD

SSO_PASSWORD

RH-SSO Realm Admin Password used to create the Client.

 — 

False

SSO_DISABLE_SSL_CERTIFICATE_VALIDATION

SSO_DISABLE_SSL_CERTIFICATE_VALIDATION

RH-SSO Disable SSL Certificate Validation.

false

False

SSO_PRINCIPAL_ATTRIBUTE

SSO_PRINCIPAL_ATTRIBUTE

RH-SSO Principal Attribute to use as user name.

preferred_username

False

AUTH_LDAP_URL

AUTH_LDAP_URL

LDAP endpoint to connect for authentication. For failover, set two or more LDAP endpoints separated by space.

ldap://myldap.example.com:389

False

AUTH_LDAP_BIND_DN

AUTH_LDAP_BIND_DN

Bind DN used for authentication.

uid=admin,ou=users,ou=example,ou=com

False

AUTH_LDAP_BIND_CREDENTIAL

AUTH_LDAP_BIND_CREDENTIAL

LDAP Credentials used for authentication.

Password

False

AUTH_LDAP_LOGIN_MODULE

AUTH_LDAP_LOGIN_MODULE

A flag to set login module to optional. The default value is required

optional

False

AUTH_LDAP_JAAS_SECURITY_DOMAIN

AUTH_LDAP_JAAS_SECURITY_DOMAIN

The JMX ObjectName of the JaasSecurityDomain used to decrypt the password.

 — 

False

AUTH_LDAP_BASE_CTX_DN

AUTH_LDAP_BASE_CTX_DN

LDAP Base DN of the top-level context to begin the user search.

ou=users,ou=example,ou=com

False

AUTH_LDAP_BASE_FILTER

AUTH_LDAP_BASE_FILTER

LDAP search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).

(uid={0})

False

AUTH_LDAP_SEARCH_SCOPE

AUTH_LDAP_SEARCH_SCOPE

The search scope to use.

SUBTREE_SCOPE

False

AUTH_LDAP_SEARCH_TIME_LIMIT

AUTH_LDAP_SEARCH_TIME_LIMIT

The timeout in milliseconds for user or role searches.

10000

False

AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE

AUTH_LDAP_DISTINGUISHED_NAME_ATTRIBUTE

The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters, backslash for example, that prevent correct user mapping. If the attribute does not exist, the entry’s DN is used.

distinguishedName

False

AUTH_LDAP_PARSE_USERNAME

AUTH_LDAP_PARSE_USERNAME

A flag indicating if the DN is to be parsed for the user name. If set to true, the DN is parsed for the user name. If set to false the DN is not parsed for the user name. This option is used together with usernameBeginString and usernameEndString.

true

False

AUTH_LDAP_USERNAME_BEGIN_STRING

AUTH_LDAP_USERNAME_BEGIN_STRING

Defines the String which is to be removed from the start of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

 — 

False

AUTH_LDAP_USERNAME_END_STRING

AUTH_LDAP_USERNAME_END_STRING

Defines the String which is to be removed from the end of the DN to reveal the user name. This option is used together with usernameEndString and only taken into account if parseUsername is set to true.

 — 

False

AUTH_LDAP_ROLE_ATTRIBUTE_ID

AUTH_LDAP_ROLE_ATTRIBUTE_ID

Name of the attribute containing the user roles.

memberOf

False

AUTH_LDAP_ROLES_CTX_DN

AUTH_LDAP_ROLES_CTX_DN

The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.

ou=groups,ou=example,ou=com

False

AUTH_LDAP_ROLE_FILTER

AUTH_LDAP_ROLE_FILTER

A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).

(memberOf={1})

False

AUTH_LDAP_ROLE_RECURSION

AUTH_LDAP_ROLE_RECURSION

The number of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.

1

False

AUTH_LDAP_DEFAULT_ROLE

AUTH_LDAP_DEFAULT_ROLE

A role included for all authenticated users

user

False

AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID

AUTH_LDAP_ROLE_NAME_ATTRIBUTE_ID

Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object’s name attribute.

name

False

AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN

AUTH_LDAP_PARSE_ROLE_NAME_FROM_DN

A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameAttributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.

false

False

AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN

AUTH_LDAP_ROLE_ATTRIBUTE_IS_DN

Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.

false

False

AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK

AUTH_LDAP_REFERRAL_USER_ATTRIBUTE_ID_TO_CHECK

If you are not using referrals, you can ignore this option. When using referrals, this option denotes the attribute name which contains users defined for a certain role, for example member, if the role object is inside the referral. Users are checked against the content of this attribute name. If this option is not set, the check will always fail, so role objects cannot be stored in a referral tree.

 — 

False

AUTH_ROLE_MAPPER_ROLES_PROPERTIES

AUTH_ROLE_MAPPER_ROLES_PROPERTIES

When present, the RoleMapping Login Module will be configured to use the provided file. This parameter defines the fully-qualified file path and name of a properties file or resource which maps roles to replacement roles. The format is original_role=role1,role2,role3

 — 

False

AUTH_ROLE_MAPPER_REPLACE_ROLE

AUTH_ROLE_MAPPER_REPLACE_ROLE

Whether to add to the current roles, or replace the current roles with the mapped ones. Replaces if set to true.

 — 

False

15.2.2. Objects

The CLI supports various object types. A list of these object types as well as their abbreviations can be found in the Openshift documentation.

15.2.2.1. Services

A service is an abstraction which defines a logical set of pods and a policy by which to access them. See the container-engine documentation for more information.

ServicePortNameDescription

${APPLICATION_NAME}-rhpamcentr

8080

http

All the Business Central web server’s ports.

8443

https

${APPLICATION_NAME}-kieserver

8080

http

All the KIE Server web server’s ports.

8443

https

15.2.2.2. Routes

A route is a way to expose a service by giving it an externally reachable hostname such as www.example.com. A defined route and the endpoints identified by its service can be consumed by a router to provide named connectivity from external clients to your applications. Each route consists of a route name, service selector, and (optionally) security configuration. See the Openshift documentation for more information.

ServiceSecurityHostname

insecure-${APPLICATION_NAME}-rhpamcentr-http

none

${BUSINESS_CENTRAL_HOSTNAME_HTTP}

${APPLICATION_NAME}-rhpamcentr-https

TLS passthrough

${BUSINESS_CENTRAL_HOSTNAME_HTTPS}

insecure-${APPLICATION_NAME}-kieserver-http

none

${KIE_SERVER_HOSTNAME_HTTP}

${APPLICATION_NAME}-kieserver-https

TLS passthrough

${KIE_SERVER_HOSTNAME_HTTPS}

15.2.2.3. Deployment Configurations

A deployment in OpenShift is a replication controller based on a user-defined template called a deployment configuration. Deployments are created manually or in response to triggered events. See the Openshift documentation for more information.

15.2.2.3.1. Triggers

A trigger drives the creation of new deployments in response to events, both inside and outside OpenShift. See the Openshift documentation for more information.

DeploymentTriggers

${APPLICATION_NAME}-rhpamcentr

ImageChange

${APPLICATION_NAME}-kieserver

ImageChange

15.2.2.3.2. Replicas

A replication controller ensures that a specified number of pod "replicas" are running at any one time. If there are too many, the replication controller kills some pods. If there are too few, it starts more. See the container-engine documentation for more information.

DeploymentReplicas

${APPLICATION_NAME}-rhpamcentr

1

${APPLICATION_NAME}-kieserver

1

15.2.2.3.3. Pod Template
15.2.2.3.3.1. Service Accounts

Service accounts are API objects that exist within each project. They can be created or deleted like any other API object. See the Openshift documentation for more information.

DeploymentService Account

${APPLICATION_NAME}-rhpamcentr

${APPLICATION_NAME}-rhpamsvc

${APPLICATION_NAME}-kieserver

${APPLICATION_NAME}-rhpamsvc

15.2.2.3.3.2. Image
DeploymentImage

${APPLICATION_NAME}-rhpamcentr

rhpam-businesscentral-rhel8

${APPLICATION_NAME}-kieserver

${KIE_SERVER_IMAGE_STREAM_NAME}

15.2.2.3.3.3. Readiness Probe

${APPLICATION_NAME}-rhpamcentr

Http Get on http://localhost:8080/rest/ready

${APPLICATION_NAME}-kieserver

Http Get on http://localhost:8080/services/rest/server/readycheck

15.2.2.3.3.4. Liveness Probe

${APPLICATION_NAME}-rhpamcentr

Http Get on http://localhost:8080/rest/healthy

${APPLICATION_NAME}-kieserver

Http Get on http://localhost:8080/services/rest/server/healthcheck

15.2.2.3.3.5. Exposed Ports
DeploymentsNamePortProtocol

${APPLICATION_NAME}-rhpamcentr

jolokia

8778

TCP

http

8080

TCP

https

8443

TCP

${APPLICATION_NAME}-kieserver

jolokia

8778

TCP

http

8080

TCP

https

8443

TCP

15.2.2.3.3.6. Image Environment Variables
DeploymentVariable nameDescriptionExample value

${APPLICATION_NAME}-rhpamcentr

APPLICATION_USERS_PROPERTIES

 — 

/opt/kie/data/configuration/application-users.properties

APPLICATION_ROLES_PROPERTIES

 — 

/opt/kie/data/configuration/application-roles.properties

KIE_ADMIN_USER

Admin user name

Set according to the credentials secret

KIE_ADMIN_PWD