Option 1: Upgrading a CP4BA deployment that uses EDB Postgres

Upgrade the Cloud Pak for Business Automation 24.0.1 deployment that uses an EDB Postgres database to 25.0.0.

About this task

If your current Cloud Pak for Business Automation deployment is using an EDB Postgres database, then you can upgrade the Cloud Pak for Business Automation by using the upgrade script. The upgrade script checks for the capabilities included in the Cloud Pak for Business Automation deployment and if the script detects either IBM Automation Document Processing or Automation Decision Services, then the script migrates the data from MongoDB to the EDB Postgres database. The migration of data happens when the Git Gateway pods are up and ready after you complete applying the custom resource.

Procedure

  1. Log in to the target cluster from a client. 
    oc login https://<CLUSTERIP>:<port> -u <ADMINISTRATOR>
  2. Set the following environment variable. 
    export projectName=<cp4ba-ns>

    Where <cp4ba-ns> is the target namespace.

  3. Run the following script to upgrade the Cloud Pak for Business Automation deployment. 
    ./cp4a-deployment.sh -m upgradeDeployment -n $projectName

    The ./cp4a-deployment.sh script in the upgradeDeployment mode automatically creates a backup of the custom resource in this path <cert-kubernetes>/scripts/cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/backup.

    Attention: The script provides a list of Next Actions in a set of steps in the output. The commands that are generated in the steps can be used in your cluster as the script adds the correct values to the commands.
  4. If required: When your Cloud Pak for Business Automation includes Automation Decision Services, then the script outputs the following text to summarize the next actions that you need to take. 
    Automation Decision Services capability is installed in this CP4BA deployment:
Step 1: You are upgrading from 24.0.1 to 25.0.0, and EDB Postgres instance "<database-name>" is already installed for IBM Cloud Pak for Business Automation. Before proceeding, make sure you:
            a. (Required) create ADS designer and/or runtime database(s) on this EDB Postgres instance (from https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=automation-upgrading, navigate to "Upgrading your IBM Cloud Pak deployment from 24.0.1 -> Option 1" for the sample scripts).
            b. (Required) create ADS database_instance_secret secret(s) for ADS designer/runtime database's username and password (from https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=automation-upgrading, navigate to "Upgrading your IBM Cloud Pak deployment from 24.0.1 -> Option 1" for the sample scripts).
            c. (Required) review and modify dc_ads_designer_datasource and/or dc_ads_runtime_datasource section(s) in the custom resource file "./cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml" to match your Postgres configuration.

Step 2: oc apply -f /home/cert-kubernetes/scripts/cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml -n <cp4ba-ns>

How to check the overall upgrade status for CP4BA/zenService/IM.
The [upgradeDeploymentStatus] option will start necessary CP4BA operators (ibm-cp4a-operator/icp4a-foundation-operator) first to upgrade zenService, and then will start all other CP4BA operators when zenService upgrade done.

Step 3: ./cp4a-deployment.sh -m upgradeDeploymentStatus -n <cp4ba-ns>

The zenService will be ready in about 120 minutes after the new version (25.0.0) of CP4BA custom resource was applied.
When run the script in [upgradeDeploymentStatus] mode, the script will detect the Zen/IM ready or not.
After the Zen/IM ready, the script will start up all CP4BA operators automatically.
If the script run in [upgradeDeploymentStatus] mode for checking the Zen/IM timeout, you could check status follow below command.
How to check zenService version manually:
oc get zenService iaf-zen-cpdservice --no-headers --ignore-not-found -n <cp4ba-ns> -o jsonpath='{.status.currentVersion}'

How to check zenService status and progress manually: 
oc get zenService iaf-zen-cpdservice --no-headers --ignore-not-found -n <cp4ba-ns> -o jsonpath='{.status.zenStatus}'
oc get zenService iaf-zen-cpdservice --no-headers --ignore-not-found -n <cp4ba-ns> -o jsonpath='{.status.Progress}'
    The following are the steps that are mentioned in STEP 1 in the script output:
    1. Create new EDB Postgres databases for Automation Decision Services. The default database names are adsdesignerdb and adsruntimedb.
      The following script is a sample to create the adsdesingerdb EDB Postgres database. You need to run the script inside the primary pod of the EDB Postgres cluster.
      dbuser=adsdesigner
dbname=adsdesignerdb
dbpassword=adsdesignerpwd
location='/var/lib/postgresql/data/adsdesignerdb/'
dbtablespace=adsdesignerdb_tbs

mkdir $location
psql_cmd="psql -U postgres -c "
$psql_cmd "create user \"$dbuser\" with login;"
$psql_cmd "alter user  \"$dbuser\" with encrypted password 'adsdesignerpwd';"
$psql_cmd "create tablespace \"$dbtablespace\" owner \"$dbuser\" location '$location';"
## In case the user changes
$psql_cmd "alter tablespace \"$dbtablespace\" owner to \"$dbuser\";"

$psql_cmd "grant create on tablespace \"$dbtablespace\" to \"$dbuser\";"
$psql_cmd "create database \"$dbname\"  owner \"$dbuser\" tablespace \"$dbtablespace\" template template0 encoding 'UTF8';"

## In case the user changes
$psql_cmd "alter database \"$dbname\" owner to \"$dbuser\";"
$psql_cmd "grant all privileges on database \"$dbname\" to \"$dbuser\";"
$psql_cmd "revoke connect on database \"$dbname\" from public;"
$psql_cmd "grant all privileges on database \"$dbname\" to \"$dbuser\";"
$psql_cmd "grant connect, temp, create on database \"$dbname\" to \"$dbuser\";"
psql_cmd="psql -d $dbname -U postgres -c "
$psql_cmd "create schema if not exists authorization \"$dbuser\";"
$psql_cmd "set role \"$dbuser\""
      The following script is a sample to create the adsruntimedb EDB Postgres database. You need to run the script inside the primary pod of the EDB Postgres cluster.
      dbuser=adsruntime
dbname=adsruntimedb
dbpassword=adsruntimepwd
location='/var/lib/postgresql/data/adsruntimedb/'
dbtablespace=adsruntimedb_tbs

mkdir $location
psql_cmd="psql -U postgres -c "
$psql_cmd "create user \"$dbuser\" with login;"
$psql_cmd "alter user  \"$dbuser\" with encrypted password 'adsruntimepwd';"
$psql_cmd "create tablespace \"$dbtablespace\" owner \"$dbuser\" location '$location';"
## In case the user changes
$psql_cmd "alter tablespace \"$dbtablespace\" owner to \"$dbuser\";"

$psql_cmd "grant create on tablespace \"$dbtablespace\" to \"$dbuser\";"
$psql_cmd "create database \"$dbname\"  owner \"$dbuser\" tablespace \"$dbtablespace\" template template0 encoding 'UTF8';"

## In case the user changes
$psql_cmd "alter database \"$dbname\" owner to \"$dbuser\";"
$psql_cmd "grant all privileges on database \"$dbname\" to \"$dbuser\";"
$psql_cmd "revoke connect on database \"$dbname\" from public;"
$psql_cmd "grant all privileges on database \"$dbname\" to \"$dbuser\";"
$psql_cmd "grant connect, temp, create on database \"$dbname\" to \"$dbuser\";"
psql_cmd="psql -d $dbname -U postgres -c "
$psql_cmd "create schema if not exists authorization \"$dbuser\";"
$psql_cmd "set role \"$dbuser\""
    2. Create the database secrets. The default secret names are ibm-ads-designer-database and ibm-ads-runtime-database.
      The following YAML file is a sample to create the Automation Decision Services EDB Postgres secret.
      kind: Secret
apiVersion: v1
metadata: 
    name: "ibm-ads-runtime-database"
    namespace: "<cp4ba-ns>"
type: Opaque
stringData: 
    username: adsruntime
    password: adsruntimepwd

---
kind: Secret
apiVersion: v1
metadata: 
    name: "ibm-ads-designer-database"
    namespace: "<cp4ba-ns>"
type: Opaque
stringData: 
    username: adsdesigner
    password: adsdesignerpwd
      Where <cp4ba-ns> is the target namespace. For more information on creating the EDB Postgres databases and secrets, see Configuring PostgreSQL storage.
    3. Review and modify the dc_ads_designer_datasource and dc_ads_runtime_datasource sections in the custom resource file in ./cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml to match your EDB Postgres configurations.
      Note: Do not remove the spec.ads_configuration.mongo parameter from the custom resource and the ibm-dba-ads-mongo-secret. The Git service requires these parameters to connect to MongoDB and to migrate data from MongoDB to EDB Postgres database.
  5. If required: When the CP4BA deployment has the sc_deployment_fncm_license custom resource parameter set to "concurrent-user" or "authorized-user", two other RBAC resources are needed to give the Content operator access to secrets. If your custom resource has either license type, create the Role and RoleBinding resources from the provided template.

    Replace <CP4BA-OPERATORS-NAMESPACE> with the name of the target namespace.

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ibm-licensing-secret-reader
  namespace: ibm-licensing
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ibm-cp4a-content-operator-licensing-access
  namespace: ibm-licensing
subjects:
- kind: ServiceAccount
  name: ibm-cp4a-content-operator
  namespace: <CP4BA-OPERATORS-NAMESPACE>
roleRef:
  kind: Role
  name: ibm-licensing-secret-reader
  apiGroup: rbac.authorization.k8s.io
  6. If required: When your Cloud Pak for Business Automation includes IBM Automation Document Processing, then the script outputs the following text to summarize the next actions that you need to take. 
    Automation Document Processing capability is installed in this CP4BA deployment:
STEP 1 (Required): Upgrade the Automation Document Processing databases
        - If you are upgrading from 24.0.1, refer to the Knowledge Center topic: "Upgrading your Automation Document Processing databases" https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=deployment-upgrading-automation-document-processing#tasktask_upgrd_adp__postreq__1
        - You are upgrading from 24.0.1 to 25.0.0, and EDB Postgres instance "postgres-cp4ba" is already installed for IBM Cloud Pak for Business Automation. Before proceeding, make sure you:
            a. (Required) create ADPGG database on this EDB Postgres instance (from https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=automation-upgrading, navigate to "Upgrading your IBM Cloud Pak deployment from 24.0.1 -> Option 1" for the sample scripts).
            b. (Required) update ibm-adp-secret to include adpggDBUsername and adpggDBPassword (the ADPGG database's username and password).
            c. (Required) do NOT delete mongoUri key from ibm-adp-secret.
            d. (Required) review and modify dc_adp_datasource section in the custom resource file "/home/cert-kubernetes/scripts/cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml" to match your Postgres configuration- Refer to the Knowledge Center: "Updating the custom resource for each capability in your deployment" topic to complete REQUIRED steps for the installed pattern(s).
        - If upgrading from 24.0.1: https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/25.0.0?topic=uycpdf2-updating-custom-resource-each-capability-in-your-deployment 
          After reviewing or modifying the custom resource file "home/cert-kubernetes/scripts/cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml", you need to follow the steps below to upgrade this CP4BA deployment.

Step 2 (Required): oc apply -f /root/aria-dev/Github/25.0.0/GM/cert-kubernetes-master/cert-kubernetes-master/scripts/cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml -n <cp4ba-ns>
How to check the overall upgrade status for CP4BA/zenService/IM.
[TIPS]: The [upgradeDeploymentStatus] option will start necessary CP4BA operators (ibm-cp4a-operator/icp4a-foundation-operator) first to upgrade zenService, and then will start all other CP4BA operators when zenService upgrade done.

Step 3 (Required): ./cp4a-deployment.sh -m upgradeDeploymentStatus -n <cp4ba-ns>

The zenService will be ready in about 120 minutes after the new version (25.0.0) of CP4BA custom resource was applied.
When run the script in [upgradeDeploymentStatus] mode, the script will detect the Zen/IM ready or not.
After the Zen/IM ready, the script will start up all CP4BA operators automatically.
If the script run in [upgradeDeploymentStatus] mode for checking the Zen/IM timeout, you could check status follow below command.
How to check zenService version manually:
oc get zenService iaf-zen-cpdservice --no-headers --ignore-not-found -n <cp4ba-ns> -o jsonpath='{.status.currentVersion}'

How to check zenService status and progress manually: 
oc get zenService iaf-zen-cpdservice --no-headers --ignore-not-found -n <cp4ba-ns> -o jsonpath='{.status.zenStatus}'
oc get zenService iaf-zen-cpdservice --no-headers --ignore-not-found -n <cp4ba-ns> -o jsonpath='{.status.Progress}'
    The following are the steps that are mentioned in STEP 1 in the script output:
    1. Upgrade your IBM Automation Document Processing database.

      Get the most current PostgreSQL scripts for the new version from the updated /ACA/configuration-ha directory in the cert-kubernetes repository. The PostgreSQL scripts are located in the PG subdirectory.

      1. Get the CP4BA EDB Postgres connection information. 
        oc extract -n $projectName secret/postgres-cp4ba-superuser --to=-

        You need to use the host and port values when you run the script later.

      2. Get the database information for IBM Automation Document Processing. 
        oc extract -n $projectName secret/aca-basedb --to=-
        The following command is an example: 
        oc extract -n cp4ba secret/aca-basedb --to=-
# PROJ2_DB_CONFIG
acauser
# BASE_DB_CONFIG
acauser
# BASE_DB_USER
acauser
# PROJ1_DB_CONFIG
acauser
        From the example, the details are:
        • The BASEDB username and password (for BASE_DB_USER and BASE_DB_CONFIG) are acauser/acauser.
        • The Project1 username and password (for PROJ1_DB_CONFIG) are proj1/acauser.
        • The Project2 username and password (for PROJ2_DB_CONFIG) are proj2/acauser.
        Note: The Project database username is predefined based on the PROJ<x>_DB_CONFIG key. In this example, they are proj1 and proj2.
        The database names are predefined.
        • The IBM Automation Document Processing base database name is adpbase.
        • The IBM Automation Document Processing project database names are based on the PROJ<x>_DB_CONFIG key. If you have PROJ1_DB_CONFIG and PROJ2_DB_CONFIG in the secret, then you have proj1 and proj2 as project databases.

        The ontology name follows the same convention as the project database name. In this example, the ontology names are proj1 and proj2.

      3. Note the location of the clientcert.pem and clientkey.pem certificates:
        • /var/lib/postgresql/data/CA_DB_scripts/PG/clientcert.pem
        • /var/lib/postgresql/data/CA_DB_scripts/PG/clientkey.pem
      4. Copy the PostgreSQL script into the postgres pod with the following commands.
        1. Access the postgres-cp4ba-1 pod and create a temporary directory. 
          oc rsh postgres-cp4ba-1
mkdir -p /var/lib/postgresql/data/adp_2500
exit
        2. From the ACA/configuration-ha directory, copy the PG directory into the directory that you created in the previous step. 
          oc cp PG postgres-cp4ba-1:/var/lib/postgresql/data/adp_2500
        3. Access the postgres-cp4ba-1 pod and go to the /var/lib/postgresql/data/adp_2500/PG directory.
          1. Upgrade the IBM Automation Document Processing base database by running UpgradeBaseDB.sh
          2. Upgrade the IBM Automation Document Processing project databases by running UpgradeTenantDB.sh for each of your project databases.
    2. Create new EDB Postgres databases for IBM Automation Document Processing. The default database name is adpggdb.
      The following script is a sample to create the adpggdb EDB Postgres database. You can create this script under a location such as /var/lib/postgresql/data.
      dbuser=adpuser
dbname=adpggdb
dbpassword=adpuserpwd
location='/var/lib/postgresql/data/adpggdb/'
dbtablespace=adpggdb_tbs

mkdir $location
psql_cmd="psql -U postgres -c "
$psql_cmd "create user \"$dbuser\" with login;"
$psql_cmd "alter user  \"$dbuser\" with encrypted password 'adpuserpwd';"
$psql_cmd "create tablespace \"$dbtablespace\" owner \"$dbuser\" location '$location';"
## In case the user changes
$psql_cmd "alter tablespace \"$dbtablespace\" owner to \"$dbuser\";"

$psql_cmd "grant create on tablespace \"$dbtablespace\" to \"$dbuser\";"
$psql_cmd "create database \"$dbname\"  owner \"$dbuser\" tablespace \"$dbtablespace\" template template0 encoding 'UTF8';"

## In case the user changes
$psql_cmd "alter database \"$dbname\" owner to \"$dbuser\";"
$psql_cmd "grant all privileges on database \"$dbname\" to \"$dbuser\";"
$psql_cmd "revoke connect on database \"$dbname\" from public;"
$psql_cmd "grant all privileges on database \"$dbname\" to \"$dbuser\";"
$psql_cmd "grant connect, temp, create on database \"$dbname\" to \"$dbuser\";"
psql_cmd="psql -d $dbname -U postgres -c "
$psql_cmd "create schema if not exists authorization \"$dbuser\";"
$psql_cmd "set role \"$dbuser\""

      For more information, see Preparing the PostgreSQL databases.

    3. Update the existing IBM Automation Document Processing ibm-adp-secret to include adpggDBUsername and adpggDBPassword key and value pairs. For more information, see Creating secrets to protect sensitive Document Processing configuration data.
      Note: Do not remove the mongoUri parameter from ibm-adp-secret. The Git Gateway requires the mongoUri parameter to connect to MongoDB and to migrate data from MongoDB to EDB Postgres database.
    4. Review and modify the dc_adp_datasource section in the custom resource file in ./cp4ba-upgrade/project/<cp4ba-ns>/custom_resource/icp4acluster.yaml to match your EDB Postgres configurations.

What to do next

If you want to make further edits to the custom resource, go to and complete the steps in Updating the custom resource for each capability in your deployment. After you complete the edits to the custom resource, you can apply the custom resource by following the steps in Applying the updated custom resource.