Chapter 3. Deploying and managing a Red Hat Process Automation Manager environment using OpenShift Operators

Procedure

1. Enter your project in the OpenShift Web cluster console.
2. In the OpenShift Web console navigation panel, select Operators and then Catalog Sources.
3. Search for Business Automation. If you find it, click Create Subscription next to it.

4. If the Business Automation entry is not available, complete the following steps:

   1. Log in to the OpenShift environment as an administrator.

   2. Enter the following command:

      $ oc create -f https://raw.githubusercontent.com/kiegroup/kie-cloud-operator/1.0.1/deploy/catalog_resources/redhat/catalog-source.yaml

   3. Refresh the OpenShift Web console in the browser.
   4. Search for Business Automation again. Click Create Subscription next to it.
5. A YAML description of the new subscription is displayed. Click Create to create the subscription.

Procedure

1. Enter your project in the OpenShift Web cluster console.
2. In the OpenShift Web console navigation panel, select Operators and then Subscriptions.
3. Click the name of the subscription that contains businessautomation. Information about this subscription is displayed.
4. Under the Installed version heading, click the version name of the subscription. An overview of the subscription is displayed.
5. Click Create KieApp. A YAML source is displayed.
6. Set the name field to an application name that is unique in the project.

7. Set the environment field to the required environment type. Each of the types is a default deployment pattern. You can modify the pattern by editing this YAML source; you can also modify the deployment after it is completed. The following types are available:

   • 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 Process Server. This environment does not use any persistent storage, and any work you do in the environment is not saved.
   • 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 Process 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. This environment includes Business Central Monitoring. You can configure one or more Process Server replicated pods that build a service from source. In this environment, when you deploy a Process 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 Process 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.
   • 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 Process 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 Process Server for test execution of the services. This version of the authoring environment supports scaling the Business Central pod to ensure high availability.

8. Add lines to the YAML source to modify the environment, using the snippets listed in this document as a reference:

   • The following snippet adds an immutable Process Server pod that builds a service from source. You must add at least one copy of this snippet when creating an immutable environment.

       objects:
         servers:
           - 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.

   • The following snippet configures the number and settings of Process Servers that are managed by Business Central or Business Central Monitoring in your environment, as well as a Smart Router. Six servers, under three different name sets, are included in the snippet.

     apiVersion: app.kiegroup.org/v1
     kind: KieApp
     metadata:
       name: server-config
     spec:
       environment: <environment_type>
       objects:
         console:
           env:
             - name: MY_VALUE
               value: "example"
         servers:
           # Kieserver sets will be named sequentially server-config-kieserver1, server-config-kieserver1-2
           - deployments: 2
             # Env variables that will be added to all the kie servers in this set
             env:
               - name: MY_VALUE
                 value: "example"
             # Override default memory limits for all the kie servers in this set
             resources:
               limits:
                 memory: 2Gi
           # Kieserver sets will be named sequentially server-config-kieserver2, server-config-kieserver2-2
           - deployments: 2
             # Env variables that will be added to all the kie servers in this set
             env:
               - name: MY_VALUE
                 value: "example"
           # Kieserver sets will be named sequentially server, server-2
           - name: server
             deployments: 2
             env:
               - name: MY_VALUE
                 value: "example"
             # Override default memory limits for all the kie servers in this set
             resources:
               limits:
                 memory: 2Gi
       smartRouter:
         env:
           - name: MY_VALUE
             value: "example"

     Replace <environment_type> with the type of environment that you want to configure.

   • The following snippet configures Process Servers, a Business Central or Business Central Monitoring, and a Smart Router using existing secrets for HTTPS communication, as required for a production environment. In this example, two servers are created with the server-a-keystore secret. (For instructions about creating the secrets, see Section 2.3, “Creating the secrets for Business Central”, Section 2.2, “Creating the secrets for Process Server”, and Section 2.4, “Creating the secrets for Smart Router”.)

     apiVersion: app.kiegroup.org/v1
     kind: KieApp
     metadata:
       name: keystore-config
     spec:
       environment: <environment_type>
       objects:
         console:
           keystoreSecret: console-keystore
         servers:
           - name: server-a
             deployments: 2
             keystoreSecret: server-a-keystore
           - name: server-b
             keystoreSecret: server-b-keystore
         smartRouter:
           keystoreSecret: smartrouter-keystore

     Replace <environment_type> with the type of environment that you want to configure.

   • The following snippet sets the password for the administrator user (admin) and the application name (app2):

       commonConfig:
         adminPassword: password
         applicationName: app2

   • The following snippet sets up LDAP authentication. The 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.

     auth:
       ldap:
         url: ldaps://myldap.example.com
         bindDN: uid=admin,ou=users,ou=exmample,ou=com
         bindCredential: s3cret
         baseCtxDN: ou=users,ou=example,ou=com
         baseFilter: (uid={0})
         searchScope: SUBTREE_SCOPE
         roleAttributeID: memberOf
         rolesCtxDN: ou=groups,ou=example,ou=com
         roleFilter: (memberOf={1})
         defaultRole: guest
       roleMapper:
         rolesProperties: /conf/roleMapper.properties
         replaceRole: true

     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 rolesProperties value to the fully qualified pathname 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 about providing this file, see Section 3.4, “Providing the LDAP role mapping file”.

     If the replaceRole parameter is set to true, mapped roles replace the roles defined on the LDAP server. It the parameter is set to false, both mapped roles and roles defined on the LDAP server are set as user application roles. The default setting is false.

9. After completing the modification of the YAML source, click Create to create the application.

Procedure

1. Enter your project in the OpenShift Web cluster console.
2. In the OpenShift Web console navigation panel, select Operators and then Subscriptions.
3. Click the name of the subscription that contains businessautomation. Information about this subscription is displayed.
4. Under the Installed version heading, click the version name of the subscription. An overview of the subscription is displayed.
5. Select the Instances tab.
6. Click the name of a deployed environment.
7. Select the YAML tab. A YAML source is displayed.
8. If you want to change common settings, such as passwords, edit the values under commonConfig:.

9. If you want to add new Process 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 Process 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ю
10. If you want to scale a Process 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.
11. Click Save Changes.
12. Wait for a This object has been updated pop-up message.
13. Click Reload to view the new YAML description of the environment.

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. For 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.

   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 .