Cloud Pak for Business Automation

Come for answers. Stay for best practices. All we’re missing is you.

View Only

Back to Blog List

CP4BA 26.0.0: Hashicorp Vault Integration for Fresh Deployments

By Amrita Nanda posted 07/31/26 01:52 PM

Co-Author: Darren Ma

Objective

This document explains how to configure and validate HashiCorp Vault integration for IBM CP4BA 26.0.0 during fresh deployments (Only supported for Production deployments).

CP4BA 26.0.0 introduces full HashiCorp Vault support across all CP4BA capabilities, enabling centralized, secure, auditable, and rotatable secret management through Vault while integrating seamlessly with the CP4BA deployment workflow.

What's New in 26.0.0

The biggest enhancement is that Vault support has been expanded from Content (FNCM) only in 25.0.1 to all CP4BA capabilities in 26.0.0, including:

Content Cortex
BAN
BAW
ADP
DICMS
ODM (supported starting from CP4BA 26.0.0-IF001)
Shared configuration secrets

Note:

Support for storing the Zen database secret in HashiCorp Vault is available starting from CP4BA 26.0.0-IF001 onwards. In the CP4BA 26.0.0 GA release, the Zen database secret is supported only as a Kubernetes Secret.

Operational Decision Manager (ODM) Vault integration has a known issue in the CP4BA 26.0.0 GA release. This issue has been resolved starting with CP4BA 26.0.0-IF001 onwards.

Prerequisites for Deployment

Prepare a CP4BA Production deployment environment. (In the Cluster )
Install and configure HashiCorp Vault with Kubernetes authentication enabled. (In the vault server) (Note: these instructions are only for setting up Hashicorp Vault for dev and testing purposes. To setup HashiCorp Vault for production use, they should consult the official Hashicorp documentation.)
Install the Secrets Store CSI Driver and Vault CSI Provider in the cluster. (In the Cluster )
Configure the required Vault roles, policies, and service account access. (In the vault server)
Vault integration is supported only for script-based deployments and is not supported when deploying CP4BA through the OpenShift Console Form UI.
HashiCorp Vault is the only external secret management provider that has been tested and validated.

Prerequisites for Vault integration:

Configure Vault Policy and Role

Run the following commands on a machine that has network access to the Vault server and where the Vault CLI is installed and authenticated.

Create a Vault policy that grants CP4BA read access to the required secrets.

vault policy write cp4a-vault-policy - << EOF
path "secret/data/cp4ba/*" {
  capabilities = ["read"]
}
EOF

Create a Vault Kubernetes role and associate it with the required CP4BA service accounts and namespace.

cat <<EOF | vault write auth/kubernetes/role/cp4a-vault-role \
  bound_service_account_names="<meta.name>-aca-service-account, \
                               <meta.name>-adp-sa, \
                               <meta.name>-ads-sa, \
                               <meta.name>-bastudio-sa, \
                               <meta.name>-<baw-instance-name>-baw-server-ltpa-sa, \
                               <meta.name>-<baw-instance-name>-baw-server-sa, \
                               <meta.name>-fncm-service-account, \
                               <meta.name>-gitgateway-service-account, \
                               <meta.name>-iccsap-service-account, \
                               <meta.name>-ier-service-account, \
                               <meta.name>-insights-engine-sa, \
                               <meta.name>-ibm-odm-prod-service-account, \
                               <meta.name>-pbk-ae-sa, \
                               <meta.name>-rr-sa, \
                               <meta.name>-workspace-aae-ae-sa, \
                               <pfs-cr-name>-pfs-service-account, \
                               <wfps-cr-name>-sa, \
                               ibm-ads-operator-sa, \
                               ibm-ai-services-sa, \
                               ibm-bts-operator, \
                               ibm-ccx-ai-services-operator-sa, \
                               ibm-cp4a-content-operator, \                  
                               ibm-cp4a-dpe-operator, \
                               ibm-cp4a-operator, \
                               ibm-cp4a-wfps-operator-sa, \
                               ibm-iam-operand-restricted, \
                               ibm-im-operand, \
                               ibm-insights-engine-operator, \
                               ibm-odm-operator-controller-manager, \
                               ibm-pfs-operator-sa, \
                               ibm-workflow-operator-sa, \
                               icp4a-foundation-operator, \
                               platform-identity-management, \
                               platform-identity-provider, \
                               zen-admin-sa, \
                               zen-editor-sa, \
                               zen-norbac-sa" \
  bound_service_account_namespaces=<cp4ba-project> \
  policies=cp4a-vault-policy \
  ttl=20m
EOF

Important:

Replace <meta.name> with the name of your CP4BA custom resource (CR). By default, the CR name is icp4adeploy. For a Content-only deployment, the default CR name is content.
Replace <cp4ba-project> with the namespace where CP4BA is deployed.
If you install the CP4BA operators using Separation of Duty, include both the operator and operand namespaces in the bound_service_account_namespaces parameter.
The following three service account names must be included in the bound_service_account_names parameter starting with CP4BA 26.0.0-IF001:
```
zen-admin-sa, \
zen-editor-sa, \
zen-norbac-sa, \
```

Additional Service Accounts for Optional Capabilities:

If your CP4BA deployment includes any of the following optional capabilities, add the corresponding service accounts to the bound_service_account_names list.

If Business Automation Workflow (BAW) is included in your CP4BA deployment

Replace <baw-instance-name> with the BAW instance name specified in the baw_configuration section of your CP4BA custom resource. If multiple BAW instances are configured, add the service accounts for each instance.

If Process Federation Server (PFS) is included in your CP4BA deployment

Add the following service account to your vault role:

<pfs-cr-name>-pfs-service-account

Where <pfs-cr-name> refers to the name of the ProcessFederationServer custom resource.

If Workflow Process Service (WfPS) is included in your CP4BA deployment

Add the following service account to your vault role:

<wfps-cr-name>-sa

Where <wfps-cr-name> refers to the name of the WfPSRuntime custom resource.

Step-by-Step Instructions to install Operator and CP4BA deployment with Vault enabled:

Clone cert-kubernetes repo for the release you want to install.
Navigate to cert-kubernetes/scripts/directory
Run cp4a-clusteradmin-setup.sh for operator Installation and follow the steps

Follow Preparing your cluster for an online deployment

After the operator installation is successfully completed using cp4a-clusteradmin-setup.sh, run the cp4a-prerequisites.sh script in property mode.
Select all the CP4BA required components in the next step, and then proceed to answer the next prompts
Enter Yes when it asks “Do you want to enable external secret management (Hashicorp Vault) integration for your custom secrets?”
Proceed with answering the next prompts in property mode till the end.
Update all four .property files generated in the property modes. For vault integration, update the “cp4ba_user_profile.property” file with the following parameters as per the vault setup.
If you plan to use a custom shared secret, update the following parameters in the cp4ba_user_profile.property file, as shown in the image below. Also, place the corresponding certificate files in the /cert-kubernetes/scripts/cp4ba-prerequisites/project/cp4ba-2600/propertyfile/cert directory.

Shared Secret

Required Content

root_ca_secret link

tls.crt, tls.key

trusted_certificate_listlink

tls.crt

external_tls_certificate_secretlink

tls.crt, tls.key
After updating all the required parameters in the four property files, run the cp4a-prerequisites.sh script in generate mode.
Vault-specific secret template and SecretProviderClass template files are generated under the "/cert-kubernetes/scripts/cp4ba-prerequisites/project/<Project_name>/propertyfile/cert " directory when running in generate mode:

The generated secret template files are in JSON format. Refer to these files and manually create the corresponding secrets in your Vault instance under the path specified by the CP4BA.VAULT_PATH parameter in the cp4ba_user_profile.property file.

Secret created in vault Instance:
Every SecretProviderClass template maps into corresponding secrets in vault to files that can be mounted into pods. It includes the secretPath (Vault secret path), secretKey (key within the secret), and objectName (file name created in the pod). The roleName, vaultAddress, and common Vault path are populated from the generated properties file.
Run the script "/cert-kubernetes/scripts/cp4ba-prerequisites/project/<Project_name>/create_secret.sh" to create the 'SecretProviderClasses' in your cluster.

NOTE: This script only creates the 'SecretProviderClasses', it will NOT create secrets in Vault.

You must manually create them using the provided JSON templates mentioned.
Run the cp4a-vault.sh Script to patch the Operator CSV(s) for Vault integration. After execution, the script log is generated and stored at: /cert-kubernetes/scripts/.tmp./cp4a-vault.sh -m patch --csv "ibm-ads-operator.v26.0.0,ibm-content-operator.v26.0.0,ibm-cp4a-operator.v26.0.0,ibm-cp4a-wfps-operator.v26.0.0,ibm-dpe-operator.v26.0.0,ibm-insights-engine-operator.v26.0.0,ibm-odm-operator.v26.0.0,ibm-pfs-operator.v26.0.0,ibm-workflow-operator.v26.0.0,icp4a-foundation-operator.v26.0.0" -n cp4ba-2600

Shared Secret	Required Content
`root_ca_secret link`	`tls.crt`, `tls.key`
`trusted_certificate_listlink`	`tls.crt`
`external_tls_certificate_secretlink`	`tls.crt`, `tls.key`

The cp4a-vault.sh script patches the CP4BA Operator CSV by adding:

- - Non-certificate secrets: /tmp/secrets/<secret_name>
  - Certificate secrets: /tmp/certificates/<secret_name>
  - A volume for each generated SecretProviderClass.
  - A corresponding volumeMount to mount the secret into the operator pod (for example, /tmp/secrets/<SECRET_NAME> or /tmp/certificates/<SECRET_NAME>), allowing the operator to read the secret from the mounted file.

Vault secrets are mounted in the operator pod using the following standard paths:

...
    spec:
      deployments:
      - name: ibm-cp4a-operator
        spec:
          template:
            spec:
              containers:
              - name: operator
                volumeMounts:
                - name: ldap-bind-secret
                  mountPath: /tmp/secrets/ldap-bind-secret
                  readOnly: true
              volumes:
              - name: ldap-bind-secret
                csi:
                  driver: secrets-store.csi.k8s.io
                  readOnly: true
                  volumeAttributes:
                    secretProviderClass: ldap-bind-secret

Check the operator pod to verify the secret is mounted

Ensure all the operator CSV is in the Succeeded state after the patch is applied
Create all the required databases in the database server. Refer to the database scripts located under:/cert-kubernetes/scripts/cp4ba-prerequisites/project/<Project_name>/dbscrip

After the databases are created

Run the script ./cp4a-prerequisites.sh in validate mode.
If all the validation is successful Proceed with the cp4a-deployment.sh script to generate the CP4BA CR
Answer all the prompts in cp4a-deployment.sh till the CR file is generated