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

To deploy a Red Hat Process Automation Manager environment using OpenShift Operators, you must provide settings for the environment as a YAML source.

When Red Hat OpenShift Container Platform deploys the environment, it creates a YAML description of the environment, and then ensures that the environment is coherent with the description at all times. You can edit the description to modify the environment.

3.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. If the operator is not available in the catalog, you must download and install it.

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.

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

After subscribing to the operator, you can create an application to deploy an environment.

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

You can view other configuration samples, for example, for servers that use differen database servers, at https://github.com/kiegroup/kie-cloud-operator/tree/1.0.1/deploy/examples

3.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 pod, 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 Process Servers, and scale Process Servers.

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.

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

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 .