Installing Process Federation Server for Business Automation Workflow on containers

Edit online

Process Federation Server helps you create a federated process environment. It provides business users with a single point of access to their list of tasks, list of process instances, list of case instances, and list of launchable workflows. This accessibility is available regardless of the type of process that they are working on and the backend system where the process artifacts are stored. Process Federation Server containers include indexers, retrievers, REST services, and integrate with a Federated Data Repository (Elasticsearch or OpenSearch) cluster where it stores both federated data and saved searches.

For more information about Process Federation Server containers, see Administering and operating IBM® Process Federation Server Containers External link opens a new window or tab

This Process Federation Server deployment can be set up to federate traditional (on premise) Business Automation Workflow servers and Business Automation Workflow on containers servers. For Business Automation Workflow running in Cloud Pak for Business Automation or running in a Kubernetes cluster, they can only be federated if they are running in the same namespace as Process Federation Server.

To install Process Federation Server, complete the following steps.

Preparing for a Process Federation Server deployment

Process Federation Server requires a Business Automation Workflow on containers installation, and integrates with components in Business Automation Workflow.

Process Federation Server is deployed by the Process Federation Server operator, which processes custom resources (CRs) of type ProcessFederationServer. A ProcessFederationServer CR defines the deployment properties of the Process Federation Server servers, and pfs_configuration is the top-level configuration property in a ProcessFederationServer CR.

Plan and prepare your deployment on your cluster before you create an instance of the operator and the CR.
  1. Make sure that you have the resources for your deployment. See Planning for a CP4BA Process Federation Server production deployment External link opens a new window or tab.
  2. Prepare storage, including the persistent volumes (PVs) and persistent volume claim (PVCs) for Process Federation Server.
    Process Federation Server requires a PV for logs to be created before you can deploy. You have the following options, depending on whether your Kubernetes environment supports dynamic provisioning. You can optionally choose to persist dump files by setting pfs_configuration.dump.persistent to true.
    • Option 1: If your environment supports dynamic provisioning:

      Enable dynamic provisioning by setting pfs_configuration.logs.storage.use_dynamic_provisioning to true and provide the storage class name of pfs_configuration.logs.storage.storage_class in the CR file.

      If you also want to persist dump files, set pfs_configuration.dump.persistent to true.

    • Option 2: If your environment does not support dynamic provisioning:

      Disable dynamic provisioning by setting pfs_configuration.logs.storage.use_dynamic_provisioning to false. Then, create a PV manually and set pfs_configuration.logs.storage.existing_pvc_name in the CR file to the value of the name property of your PV.

      To persist dump files, disable dynamic provisioning by setting pfs_configuration.dump.storage.use_dynamic_provisioning to false. Then, create a PV manually and set pfs_configuration.dump.storage.existing_pvc_name in the CR file to the value of the name property of your PV.

  3. Prepare storage for the Federated Data Repository (Elasticsearch or OpenSearch) cluster that is deployed for Process Federation Server. See Preparing storage for a Federated Data Repository.
    If you prefer, you can also use your own external federated data repository. See Referencing an external federated data repository.
    Note: Linux® on IBM Z must use an external Federated Data Repository.
  4. Set up SCC for a Federated Data Repository. See Setting up the security context constraint for a Federated Data Repository.
  5. If you set the Process Federation Server admin secret name in pfs_configuration.admin_secret_name, the operator creates this secret automatically. However, if you want to create it manually, use the following content:
    apiVersion: v1
kind: Secret
metadata:
  name: ibm-pfs-admin-secret
type: Opaque
data:
  ltpaPassword: <LTPA_PASSWORD>
  sslKeyPassword: <SSL_KEY_PASSWORD>
    • ltpaPassword is used to set the LTPA password
    • sslKeyPassword is used as the keystore and truststore password
    • All values under data are Base64-encoded.

Deploying required components

To install Process Federation Server, you must use the operator to configure the root Certificate Authority (CA), Cloud Pak foundational services, and optionally Business Automation Application, and Business Teams service.

If you already installed Business Automation Workflow on containers with the required components, you can proceed directly to the next step. For instructions about installing Business Automation Workflow on containers, see Preparing to install Business Automation Workflow on containers, Installing the prerequisites for Business Automation Workflow on containers, and Installing Business Automation Workflow on containers.
Important: If you want your Process Federation Server deployment to use an OpenSearch instance that is deployed as part of Business Automation Workflow, make sure that you already configured shared_configuration.sc_optional_components: opensearch in a custom resource (CR). For more information about OpenSearch options, see Using OpenSearch provided by IBM Cloud Pak® foundational services External link opens a new window or tab.
  1. Run the command kubectl get icp4acluster -o yaml to make sure that Cloud Pack foundation services, root Certificate Authority, Business Automation Workflow (optional), Business Teams service (optional), and Business Automation Application (optional) are ready.. Make sure that .status.components.prereq.rootCAStatus is Ready and .status.components.prereq.rootCASecretName has the correct secret name.

    For any issues with the resources, check the pod logs by following the instructions in Troubleshooting your Process Federation Server deployment.

  2. Make sure that the expected pods are listed in the kubectl get pods command result.
    For example, the results of kubectl get pods with label selector might look similar to:
    [root@XXXXXXX ~]# kubectl get pods -l  app.kubernetes.io/name=Opensearch
NAME                             READY   STATUS      RESTARTS       AGE
opensearch-all-000               1/1     Running     1 (4d2h ago)   7d5h
opensearch-all-001               1/1     Running     1 (4d2h ago)   7d5h
opensearch-all-002               1/1     Running     1 (4d2h ago)   7d5h
opensearch-snapshot-repo-krhfx   0/1     Completed   0              17m

    If you are using a Business Automation Workflow OpenSearch instance, then all opensearch-all-XXX pods need to be ready.

    For more information about OpenSearch options, see Using OpenSearch provided by IBM Cloud Pak foundational services External link opens a new window or tab.

Deploying Process Federation Server

After you configure the required components, you can deploy Process Federation Server.
  1. Configure your ProcessFederationServer CR. Your starting CR might look similar to:
    apiVersion: icp4a.ibm.com/v1
kind: ProcessFederationServer
metadata:
  name: pfsdeploy
spec:
  appVersion: 25.0.0
  license:
    accept: true
  shared_configuration: 
    sc_deployment_license: production
    storage_configuration:
      sc_medium_file_storage_classname: <Required>
      sc_slow_file_storage_classname: <Required>
  pfs_configuration:
    replicas: 1

    In a production deployment cluster, for the pfs_configuration.replicas parameter, it is recommended that you set a value of 2 or higher.

    For more information, see the Process Federation Server configuration section in IBM Business Automation Workflow Runtime and Workstream Services parameters External link opens a new window or tab.
  2. Apply your custom resource by running the following command.
    kubectl apply -f your_custom_resource_name

Completing post-deployment tasks for Process Federation Server

  1. Add LDAP users in Zen.
    1. Connect to the URL: https://cluster_address, where cluster_address is the IBM Cloud Pak console route. You can get the console route by running the command: 
      kubectl get ingress zen-ingress -o jsonpath='{.spec.rules[0].host}' && echo
      The output might look similar to: 
      cpd-namespace_name.apps.mycluster.mydomain
      Using the example output, the console URL would look similar to: 
      https://cpd-namespace_name.apps.mycluster.mydomain/zen
    2. To retrieve credentials for Zen, run 
      kubectl get secret platform-auth-idp-credentials -o jsonpath=\{.data.admin_password} | base64 --decode && echo

kubectl get secret platform-auth-idp-credentials -o jsonpath=\{.data.admin_username} | base64 --decode && echo
    3. Log in to the IBM Cloud Pak dashboard using the URL from step 1a and the credentials from step 1b.
    4. Go to Manage users > Add users.
    5. Type the names of users that you want to add, and click Next.
    6. Assign the users to roles, or add them to a group. You can add your LDAP user under Users or you can add your LDAP user group under User groups. For both users and user groups, make sure that at least one role is selected. For example, roles include administrator, automation administrator, automation analyst, automation developer, automation operator, and user.
    7. Click Add to register the users.

Verifying your Process Federation Server deployment

  1. Get your Process Federation Server REST base URL by running the command: 
    kubectl get pfs cr_name -o=jsonpath='{.status.endpoints[?(@.name=="Process Federation Server External base URL")].uri}'
  2. To access Process Federation Server REST, see Process Federation Server REST APIs.

To add custom configuration for Process Federation Server, see Customizing Process Federation Server External link opens a new window or tab.

Configuring your workflow for federation

Configure your Process Federation Server instance to federate a workflow in the same namespace:

A dedicated custom resource (CR) called the FederatedSystem CR is provided. Each server to be federated into the Process Federation Server container applies the dedicated FederatedSystem CR. The full parameter list for the CR is found in Federated system parameters External link opens a new window or tab.

Troubleshooting your Process Federation Server deployment

If you encounter problems with your Process Federation Server deployment, you can troubleshoot by checking the Process Federation Server operator log.
  1. Get the Process Federation Server operator pod name by running the following command.
    kubectl get pods|grep pfs-operator
  2. Using the pod name, get the Process Federation Server operator log by running the following command.
    kubectl logs pfs_operator_pod_name

Uninstalling your Process Federation Server deployment

  1. Delete your Process Federation Server instance by running the following command.
    kubectl delete processfederationserver pfs_cr_name