Installing a CP4BA Process Federation Server production deployment

Process Federation Server helps you create a federated process environment that provides business users with a single point of access to their task list and launch list, regardless of the type of process that they are working on and the back-end system on which the process artifacts are stored. Process Federation Server containers include indexers, retrievers, REST services, and integrates with an Elasticsearch 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.

You can install Process Federation Server on Red Hat OpenShift Container Platform (OCP). The OCP OperatorHub provides a user interface for you to install a deployment with operator lifecycle manager (OLM).

This Process Federation Server deployment can be set up to federate traditional (on premise) IBM Business Automation Workflow servers, IBM Business Automation Workflow servers, and IBM Workflow Process Service instances. For IBM Business Automation Workflow servers and IBM Workflow Process Service instances, they need to be installed in the same namespace as Process Federation Server.

To install Process Federation Server on Kubernetes, complete the following procedures:
  1. Deploy required IBM Cloud Pak for Business Automation components
  2. Prepare for a Process Federation Server deployment
  3. Deploy Process Federation Server
  4. Complete post-deployment tasks for Process Federation Server
  5. Verify your Process Federation Server deployment
  6. Configure your workflow for federation
  7. Troubleshoot your Process Federation Server deployment
  8. Uninstall your Process Federation Server deployment

Deploy required IBM Cloud Pak for Business Automation components

To install Process Federation Server, you must use the Cloud Pak for Business Automation operator to configure Resource Registry, root Certificate Authority (CA), Cloud Pack foundation services, and optionally IBM Business Automation Application and Business Teams Service for Workplace UI. Process Federation Server configuration of Workplace, Application Engine data persistence, and Access Control List (ACL) through IBM Navigator is not supported.

If you already installed a Cloud Pak for Business Automation deployment pattern with the required components, you can proceed directly to the next step. For instructions to install a deployment pattern, see Creating a production deployment.
Important: If you want your Process Federation Server deployment to use an Elasticsearch instance that is deployed as part of Cloud Pak for Business Automation, make sure that one of the following conditions is met:
  • IBM Business Automation Insights is enabled
  • You selected the IBM Business Automation Workflow or IBM Automation Workstream Services pattern is selected
  • You already configured shared_configuration.sc_optional_components: elasticsearch in a custom resource (CR).
For more information about Elasticsearch options, see Using Elasticsearch provided by IBM Cloud Pak foundational services.
  1. If you have not already installed a Cloud Pak for Business Automation deployment pattern, configure the ICP4ACluster custom resource (CR) to deploy the components required by Process Federation Server.
    1. Create the following cp4ba.yaml file, and replace the values of <Required>. Refer to the following documentation for more information about configuring parameters: If you want to use an Elasticsearch cluster provided separately rather than a Cloud Pak for Business Automation Elasticsearch instance, you do not need the line sc_optional_components: elasticsearch.
      apiVersion: icp4a.ibm.com/v1
kind: ICP4ACluster
metadata:
  name: icp4deploy
  labels:
    app.kubernetes.io/instance: ibm-dba
    app.kubernetes.io/managed-by: ibm-dba
    app.kubernetes.io/name: ibm-dba
    release: 23.2.0
spec:
  appVersion: 23.2.0
  ibm_license: accept
  resource_registry_configuration:
    replica_size: 1
  shared_configuration:
    sc_deployment_context: CP4A
    sc_deployment_license: production
    sc_deployment_platform: OCP
    sc_deployment_type: custom
    sc_optional_components: elasticsearch
    sc_image_tag: <required>
    sc_image_repository: <required>
    image_pull_secrets: <required>
    root_ca_secret: icp4a-root-ca
    storage_configuration:
      sc_block_storage_classname: "<Required>"
      sc_fast_file_storage_classname: "<Required>"
      sc_medium_file_storage_classname: "<Required>"
      sc_slow_file_storage_classname: "<Required>"

  ldap_configuration:
    lc_selected_ldap_type: "<Required>"
    lc_ldap_server: "<Required>"
    lc_ldap_port: "<Required>"
    lc_bind_secret: ldap-bind-secret
    lc_ldap_base_dn: "<Required>"
    lc_ldap_ssl_enabled: true
    lc_ldap_ssl_secret_name: "<Required>"
    lc_ldap_user_name_attribute: "<Required>"
    lc_ldap_user_display_name_attr: "<Required>"
    lc_ldap_group_base_dn: "<Required>"
    lc_ldap_group_name_attribute: "*:cn"
    lc_ldap_group_display_name_attr: "cn"
    lc_ldap_group_membership_search_filter: "<Required>"
    lc_ldap_group_member_id_map: "<Required>"
    lc_ldap_recursive_search: false
    lc_ldap_max_search_results: 4500
    lc_use_ldap_entity_type:
    lc_ldap_login_property:
    lc_ldap_entity_type_user:
      object_class:
      search_base:
      search_filter:
    lc_ldap_entity_type_group:
      object_class:
      search_base:
      search_filter:
    lc_ldap_group_properties:
    2. Deploy the CR by running the command:
      oc apply -f cp4ba.yaml
  2. Wait a few minutes for your resources to initiate. Run the command oc get icp4acluster -o yaml to make sure that Cloud Pack foundation services, root Certificate Authority, Resource Registry, Business Teams Service (optional) and IBM Business Automation Application (optional) are ready. Make sure that .status.components.prereq.rootCAStatus is Ready and .status.components.prereq.rootCASecretName is filled with the correct secret name.

    If there is an issue with the resources, check the pod logs by following the instructions in Troubleshoot your Process Federation Server deployment.

  3. Make sure that .status.endpoints["Resource Registry"] appears in the endpoints list. For example: 
    status:
    components:
      ...
      prereq:
        conditions: []
        encryptionKeySecret: ibm-iaws-shared-key-secret
        iafStatus: Ready
        iamIntegrationStatus: Ready
        rootCASecretName: icp4a-root-ca
        rootCAStatus: Ready
      resource-registry:
        rrAdminSecret: resource-registry-admin-secret
        rrCluster: Ready
        rrService: Ready
      ...
    endpoints:
    - name: Resource Registry
      scope: Internal
      type: gRPC
      uri: icp4adeploy-dba-rr-client:2379
  4. Make sure that Zen and Resource Registry pods are listed in the oc get pods command result.
    For Resource Registry, there is at least one pod with names similar to:
    • icp4adeploy-dba-rr-*
    • icp4adeploy-rr-backup-*
    • icp4adeploy-rr-setup-pod
    There will be operator pods with names similar to:
    • ibm-commonui-operator-84db8dc65c-hh7m4
    • ibm-mongodb-operator-c466f9487-xxtbb
    • ibm-zen-operator-76dd498b9d-m72k8
    • ibm-iam-operator-6b5fc9d67d-j2554
    • ibm-elastic-operator-controller-manager-68897448fb-g7869
    • ibm-cp4a-wfps-operator-57c5969c6d-2chlj
    • ibm-content-operator-75c9f4555c-95z2g
    • ibm-cp4a-operator-f76f564d9-mf48k
    • ibm-pfs-operator-79544b5945-fgqqp
    • ibm-insights-engine-operator-56568b5769-hjb5b
    • ibm-odm-operator-5f68487fc5-rq2vc
    • ibm-dpe-operator-66f8f68f89-w6bpf
    • icp4a-foundation-operator-788c7f8f6f-vswj8
    • ibm-common-service-operator-8687dddb66-gkqmb
    • ibm-ads-operator-67f9d85c67-mgd2k
    For example, the results of oc get pods might look similar to: 
    [root@xxxxxx]# oc get pods
NAME                                                             READY   STATUS      RESTARTS        AGE
common-web-ui-86c6f7c575-vb787                                   1/1     Running     0               17h
create-postgres-license-config-47sc7                             0/1     Completed   0               16h
create-postgres-license-config-k5ncx                             0/1     Completed   0               17h
create-secrets-job-w2gvv                                         0/1     Completed   0               17h
iaf-system-elasticsearch-es-data-0                               2/2     Running     0               17h
iam-config-job-2qd46                                             0/1     Completed   0               16h
ibm-ads-operator-67f9d85c67-mgd2k                                1/1     Running     0               17h
ibm-common-service-operator-8687dddb66-gkqmb                     1/1     Running     0               17h
ibm-commonui-operator-84db8dc65c-hh7m4                           1/1     Running     0               17h
ibm-content-operator-75c9f4555c-95z2g                            1/1     Running     0               17h
ibm-cp4a-operator-f76f564d9-mf48k                                1/1     Running     0               17h
ibm-cp4a-wfps-operator-57c5969c6d-2chlj                          1/1     Running     0               17h
ibm-dpe-operator-66f8f68f89-w6bpf                                1/1     Running     0               17h
ibm-elastic-operator-controller-manager-68897448fb-g7869         1/1     Running     0               17h
ibm-iam-operator-6b5fc9d67d-j2554                                1/1     Running     0               17h
ibm-insights-engine-operator-56568b5769-hjb5b                    1/1     Running     0               17h
ibm-mongodb-operator-c466f9487-xxtbb                             1/1     Running     0               17h
ibm-nginx-8688c589fb-t7jhg                                       2/2     Running     0               16h
ibm-nginx-tester-54fc64cdb6-dt8hn                                2/2     Running     0               16h
ibm-odm-operator-5f68487fc5-rq2vc                                1/1     Running     0               17h
ibm-pfs-operator-79544b5945-fgqqp                                1/1     Running     0               17h
ibm-zen-operator-76dd498b9d-m72k8                                1/1     Running     0               17h
icp-mongodb-0                                                    1/1     Running     0               17h
icp4a-foundation-operator-788c7f8f6f-vswj8                       1/1     Running     0               17h
meta-api-deploy-6d6d8fc75-5q6dw                                  1/1     Running     0               17h
oidc-client-registration-wptvc                                   0/1     Completed   0               17h
operand-deployment-lifecycle-manager-56f79b879c-69sp8            1/1     Running     0               17h
icp4adeploy-dba-rr-c62f427d1b                                    1/1     Running     0               16h
icp4adeploy-rr-backup-28063430-wnfjp                             0/1     Completed   0               4m2s
icp4adeploy-rr-setup-pod                                         0/1     Completed   0               16h
platform-auth-service-5dc7bf9c74-vhrp7                           1/1     Running     0               17h
platform-identity-management-7d89f8b4dd-75kdx                    1/1     Running     0               17h
platform-identity-provider-fc7c8456d-2254h                       1/1     Running     0               17h
postgresql-operator-controller-manager-1-19-1-6599c8855d-h9lnw   1/1     Running     0               16h
pre-zen-operand-config-job-924g2                                 0/1     Completed   0               17h
pre-zen-operand-config-job-q2jr4                                 0/1     Completed   0               17h
setup-job-s9kq5                                                  0/1     Completed   0               17h
usermgmt-b887c5bc6-4tnlj                                         1/1     Running     0               16h
usermgmt-ensure-tables-job-f6fc9                                 0/1     Completed   0               17h
zen-audit-c84d4546-9pgjm                                         1/1     Running     0               16h
zen-core-84699fd5c5-48q2w                                        2/2     Running     0               16h
zen-core-api-695f7bb678-7dwtl                                    2/2     Running     0               16h
zen-core-create-tables-job-hhcb9                                 0/1     Completed   0               17h
zen-core-pre-requisite-job-5mdzn                                 0/1     Completed   0               16h
zen-metastore-edb-1                                              1/1     Running     0               17h
zen-minio-0                                                      1/1     Running     0               17h
zen-minio-1                                                      1/1     Running     0               17h
zen-minio-2                                                      1/1     Running     0               17h
zen-minio-create-buckets-job-h9lwl                               0/1     Completed   0               17h
zen-pre-requisite-job-h48s6                                      0/1     Completed   0               17h
zen-validate-metastore-edb-connection-job-n8nhj                  0/1     Completed   0               6h43m
zen-watcher-5df7d775b9-86tzr                                     2/2     Running     0               16h
    If you are using a Cloud Pak for Business Automation Elasticsearch instance, there is at least one pod with the following names:
    • iaf-system-elasticsearch-es-data-0
    • iaf-system-elasticsearch-es-data-1
    For more information about Elasticsearch options, see Using Elasticsearch when running Process Federation Server with IBM Cloud Pak for Business Automation.

Prepare for a Process Federation Server deployment

Process Federation Server requires an IBM Cloud Pak® for Business Automation installation, and integrates with components in Cloud Pak for Business Automation.

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

Plan and prepare your deployment on your cluster before you create an instance of the operator and the Cloud Pak custom resource.
  1. Make sure that you have the resources for your deployment. See Planning for Process Federation Server.
  2. Plan and prepare your deployment on your cluster by completing the steps in Preparing for a production deployment.

  3. Prepare storage for Process Federation Server.

    The Process Federation Server component 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 custom resource 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 custom resource 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 custom resource file to the value of the name property of your PV.

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

Deploy Process Federation Server

After configuring IBM Cloud Pak for Business Automation components, you can deploy Process Federation Server.
  1. Configure your ProcessFederationServer custom resource. Your starting custom resource might look similar to:
    apiVersion: icp4a.ibm.com/v1
kind: ProcessFederationServer
metadata:
  name: pfsdeploy
spec:
  appVersion: 23.0.1  
  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 information about parameters, see the Process Federation Server configuration section in IBM Business Automation Workflow and Workstream Services parameters.
  2. Apply your custom resource by running the command:
    oc apply -f your_custom_resource_name

Complete post-deployment tasks for Process Federation Server

  1. Add LDAP users in Cloud Pak Platform UI.
    1. Connect to the URL: https://cluster_address, where cluster_address is the IBM Cloud Pak console route. You can get the IBM Cloud Pak console route by running the command: 
      oc get route cpd -o jsonpath='{.spec.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. Log in to the IBM Cloud Pak dashboard and select OpenShift authentication for kubeadmin, or log in with the IBM provided credentials from step 1a if you are an admin.
    3. Go to Manage users > Add users.
    4. Type the names of users you want to add, and click Next.
    5. 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.
    6. Click Add to register the users.

Verify your Process Federation Server deployment

  1. Get your Process Federation Server REST base URL by running the command: 
    oc 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.

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

Troubleshoot 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 command:
    oc get pods|grep pfs-operator
  2. Using the pod name, get the Process Federation Server operator log by running the command:
    oc logs pfs_operator_pod_name

Uninstall your Process Federation Server deployment

  1. Delete your Process Federation Server instance by running the command:
    oc delete processfederationserver pfs_cr_name
  2. Uninstall your IBM Cloud Pak for Business Automation environment by following the steps in Uninstalling capabilities.