Recommended: Preparing databases and secrets for your chosen capabilities by running a script

Using the OpenShift CLI:

oc login https://<cluster-ip>:<port> -u <cluster-user> -p <password>

On ROKS, if you are not already logged in:

oc login --token=<token> --server=https://<cluster-ip>:<port>

./cp4a-prerequisites.sh -m property -n <CP4BA_NAMESPACE>

The <CP4BA_NAMESPACE> is the target project for the CP4BA deployment.

Follow the prompts in the command window to enter the required information.

1. Select the Cloud Pak for Business Automation capabilities that you want to install.
   Restriction:

   • If you previously installed another component that contains Business Automation Studio, and you select Workflow Process Service Authoring, then you can continue to use the same database that you already configured for Business Automation Studio.
   • If you select Workflow Process Service Authoring by itself, then you must select PostgreSQL as the database type.
   • If you select Workflow Process Service Authoring and another component that contains Business Automation Studio, then you must select PostgreSQL as the database type.
   • If you select Workflow Process Service Authoring and ODM or FNCM or BAW runtime, then you must select PostgreSQL as the database type.
   Important: If you select "FileNet Content Manager" with no other capabilities, then the script assumes that the CP4BA FileNet Content Manager operator (ibm-content-operator) is used. The custom resource in this case sets the Kind parameter to Content instead of ICP4ACluster.

   Kind: Content

   When you generate the custom resource with the cp4a-deployment.sh script, the custom resource file is named ibm_content_cr_final.yaml.

2. Select the optional components that you want to include.
3. Select Yes if you want to enable FIPS for your Cloud Pak for Business Automation deployment.
   Tip: The script asks this question only if you asked to check that FIPS is enabled on the cluster in the cluster admin script. The response is stored in the cp4ba-fips-status configMap.

   If you select Yes, the script creates the CP4BA.ENABLE_FIPS property in the cp4ba_user_profile.property file and records your selection.

   CP4BA.ENABLE_FIPS="true"

   If you select No, the value is stored as false.

   The property determines the value of the shared_configuration.enable_fips parameter in the custom resource.

4. Choose the LDAP type that you want to use for the CP4BA deployment.

   By default, the LDAP is SSL enabled. You can disable SSL for the LDAP when you edit the LDAP property file. The script shows the following message:

   [*] You can change the property "LDAP_SSL_ENABLED" in the property file "cp4ba_LDAP.property" later. "LDAP_SSL_ENABLED" is "TRUE" by default.

5. Enter your dynamic storage classes for slow, medium, fast file storage (RWX).
6. Enter a block storage class name (RWO).
7. Select a deployment profile size from small, medium, or large [1 to 3]. The default is small (1).
8. Choose the database type that you want to use for the CP4BA deployment.
   Note: If you select EDB Postgres, the CP4BA operator creates and initializes the database instances.

   The script sets the following fields in the cp4ba_db_server.property file.

   • postgresql-edb.DATABASE_SERVERNAME="postgres-cp4ba-rw.{{ meta.namespace }}.svc"
   • postgresql-edb.DATABASE_PORT="5432"
   • postgresql-edb.DATABASE_SSL_SECRET_NAME="{{ meta.name }}-pg-client-cert-secret"

   The CP4BA operator creates a cluster custom resource (CR) so that the EDB Postgres operator can create the EDB Postgres instance. The CP4BA operator generates the secret "{{ meta.name }}-pg-client-cert-secret" based on the root CA, which is set in the shared_configuration.root_ca_secret parameter.

   The script also generates the cp4ba_db_name_user.property file, which is used to define the database server name, username, and password. The script uses this property file to create the datasource section in the CP4BA CR and generate the secret templates. If the database names are not specified in the CR, the operator uses the default database names for each datasource that uses the EDB Postgres instance. The same applies to the username and password for each database. If the username and password exists in the secret for each component, then the operator creates the user in the EDB Postgres instance with the password that is specified in the secret. If the username or password, or both, do not exist in the secret for a component, then a default username and password are used for that database. If the operator uses the default username and password, it also updates the secrets for each component.

   After the EDB Postgres operator is created, the CP4BA operator does not manage the EDB Postgres instance and does not change it in any way. Your system administrator can manage the EDB cluster instance by following the EDB Postgres documentation. For more information about backing up the EDB Postgres instance, see Backing up EDB Postgres.

   By default, the databases are SSL enabled. You can disable SSL for a database when you edit the database property file. The script shows the following message:

   [*] You can change the property "DATABASE_SSL_ENABLE" in the property file "cp4ba_db_server.property" later. "DATABASE_SSL_ENABLE" is "TRUE" by default.

   Restriction: If you want to use Oracle or another custom database (a database that is not in the list) for Operational Decision Manager, then you must follow the steps to manually create the database and the secret for the odm_configuration.externalCustomDatabase.datasourceRef custom resource parameter. For more information, see Configuring a custom external database.
9. If required: If you selected a database type other than EDB Postgres, then enter the alias names for all the database servers to be used by the CP4BA deployment. For example, dbserver1,dbserver2 sets two database servers. The first server is named dbserver1 and the second server is named dbserver2.
   Note: The database server names cannot contain a dot (.) character.
10. If required: If you selected FileNet Content Manager, then enter the number of object stores of a FileNet P8 domain to configure for the CP4BA deployment.
11. If the script asks to enter the name for an existing project (namespace), then enter an existing project name.
12. Choose whether to restrict the egress access to external systems for your CP4BA deployment. By default, the script restricts egress access. If you select No, egress access to external systems is unrestricted. If you select Yes, customize the egress access by adding network policies for known external systems post-installation. For more information, see Network policies to manage access to external services (egress).
    Attention: From 24.0.0-IF005 You no longer need to create the following network policy.

    If your deployment includes any capability other than Workflow Process Service Authoring and your target platform is Azure Red Hat OpenShift (ARO), then create the following network policy before you create your deployment.

    kind: NetworkPolicy
    apiVersion: networking.k8s.io/v1
    metadata:
      name: ibm-content-operator-aro
      namespace: <CP4BA_NAMESPACE>
    spec:
      podSelector:
        matchLabels:
          name: ibm-content-operator
      egress:
        - {}
      policyTypes:
        - Egress

    The <CP4BA_NAMESPACE> is the target project for the CP4BA deployment.

13. Choose whether to use an external Postgres DB or an embedded cloud-native Postgresql DB for Platform UI (Zen) and Identity Management (IM) as the metastore DB.

    If you plan to select an external Postgres DB for Cloud Pak foundational services, collect the relevant database information so you can enter the required values in the generated property files. For more information, see Setting up an external PostgreSQL database server for IM and Configuring an external PostgreSQL database for Zen.

    Remember: Zen stores users, groups, service instances, vault integration, and secret references in the metastore DB.
    Note: If you select Yes to choose an external Postgres DB, the script generates properties with the prefix CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE in the cp4ba_user_profile.property file.
14. Choose whether to use an external TLS certificate for the OpenSearch and Kafka deployments. The OpenSearch and Kafka operators can be configured to use an external TLS certificate instead of the default root CA. Copy the certificates into the dedicated folder for your database (cert-kubernetes/scripts/cp4ba-prerequisites/propertyfile/cert/db/<database folder>).

    If you select No, the CP4BA operator creates the leaf certificates based on the default root CA. The CP4BA operator checks the namespace for the cp4ba-tls-issuer resource, and if it exists, it then creates the necessary certificates for Kafka and OpenSearch.

When the script is finished, the messages include some actions. Read the next actions carefully and make sure that you complete them all before you go to the next step.

============== Created all property files for CP4BA ==============
[NEXT ACTIONS]
Enter the <Required> values in the property files under <extracted_cert-kubernetes_archive>/cert-kubernetes/scripts/cp4ba-prerequisites/propertyfile
[*] The key name in the property file is created by the cp4a-prerequisites.sh and is NOT EDITABLE.
[*] The value in the property file must be within double quotes.
[*] The value for User/Password in [cp4ba_db_name_user.property] [cp4ba_user_profile.property] file should NOT include special characters: single quotation "'"
[*] The value in [cp4ba_LDAP.property] or [cp4ba_External_LDAP.property] [cp4ba_user_profile.property] file should NOT include special character '"'

The propertyfile directory has the following file structure:

├── cert
    ├── db
        └── <db_server_alias1>
        └── ...
    └── ldap
├── cp4ba_LDAP.property
├── cp4ba_db_name_user.property
├── cp4ba_db_server.property
└── cp4ba_user_profile.property

1. Edit the global section in the cp4ba_user_profile.property file, and then the other sections for each capability that you selected.

   The global section contains license properties and the needed storage classes. The FIPS enablement property and the egress property to restrict access to the internet are also present. The BAN section is always included, and the users and groups must be from your LDAP.

   ####################################################
   ## USER Property for CP4BA ##
   ####################################################
   ## Use this parameter to specify the license for the CP4A deployment and
   ## the possible values are: non-production and production and if not set, the license will
   ## be defaulted to production.  This value could be different from the other licenses in the CR.
   CP4BA.CP4BA_LICENSE="<Required>"
   ## On OCP, the script populates these three (3) parameters based on your input for "production" deployment.
   ## The script populates the storage parameters based on your input.
   ## If you manually deploy without using the deployment script, then you must enter the different storage classes for the slow, medium,
   ## and fast storage parameters. If you only have 1 storage class defined, then you can use that 1 storage class for all 3 parameters.
   ## The sc_block_storage_classname is for Zen. Zen requires block storage (RWO) for the metastore DB.
   CP4BA.SLOW_FILE_STORAGE_CLASSNAME="<my_file_classname>"
   CP4BA.MEDIUM_FILE_STORAGE_CLASSNAME="<my_file_classname>"
   CP4BA.FAST_FILE_STORAGE_CLASSNAME="<my_file_classname>"
   CP4BA.BLOCK_STORAGE_CLASS_NAME="<my_block_classname>"
   
   ## Enable/disable FIPS mode for the deployment (default value is "false").
   CP4BA.ENABLE_FIPS="false"
   
   ## Enable or disable egress access to external systems.
   CP4BA.ENABLE_RESTRICTED_INTERNET_ACCESS="true"
   
   ####################################################
   ## USER Property for BAN ##
   ####################################################
   ## Provide the user name for BAN. For example: "BANAdmin"
   BAN.APPLOGIN_USER="<Required>"
   ## Provide the user password for BAN.
   BAN.APPLOGIN_PASSWORD="<Required>"
   ## Provide LTPA key password for BAN deployment.
   BAN.LTPA_PASSWORD="<Required>"
   ## Provide keystore password for BAN deployment.
   BAN.KEYSTORE_PASSWORD="<Required>"
   ## Provide the user name for jMail used by BAN. For example: "jMailAdmin"
   BAN.JMAIL_USER_NAME="<Optional>"
   ## Provide the user password for jMail used by BAN.
   BAN.JMAIL_USER_PASSWORD="<Optional>"

   Some values like a connection point name and table spaces for the Workflow object store initialization of Content can be any string, but are needed for the deployment to identify them.

   Important: The passwords that are used for CONTENT.LTPA_PASSWORD and BAN.LTPA_PASSWORD must be the same in the cp4ba_user_profile.property file.
2. Follow the instructions in the cp4ba_user_profile.property file to enter all the <Required> values for the external Postgres DB.

   ## Please get "<your-server-certification: root.crt>" "<your-client-certification: client.crt>" "<your-client-key: client.key>" 
   from server and client, and copy into this directory.
   Default value is "/home/cert-kubernetes/scripts/cp4ba-prerequisites/project/<CP4BA_NAMESPACE>/propertyfile/cert/zen_external_db".
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_SSL_CERT_FILE_FOLDER="/home/cert-kubernetes/scripts/cp4ba-prerequisites/project/<CP4BA_NAMESPACE>/propertyfile/cert/zen_external_db"
   
   ## Name of the schema to store monitoring data. The default value is "watchdog".
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_MONITORING_SCHEMA="watchdog"
   
   ## Name of the database. The default value is "zencnpdb".
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_NAME="zencnpdb"
   
   ## Database port number. The default value is "5432".
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_PORT="5432"
   
   ## Name of the read database host cloud-native-postgresql on k8s provides this endpoint. If DB is not running on k8s then same hostname as DB host.
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_R_ENDPOINT="<Required>"
   
   ## Name of the database host.
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_RW_ENDPOINT="<Required>"
   
   ## Name of the schema to store zen metadata. The default value is "public".
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_SCHEMA="public"
   
   ## Name of the database user. The default value is "zencnp_user".
   CP4BA.ZEN_EXTERNAL_POSTGRES_DATABASE_USER="zencnp_user"

3. If you entered a single database server, then the DB_ALIAS_NAME is set automatically. If you need more than one server, edit the <DB_ALIAS_NAME> property prefixes in the cp4ba_db_name_user.property file to assign each component to a database server name defined in the DB_SERVER_LIST key name in the cp4ba_db_server.property file. The value of a <DB_ALIAS_NAME> in the username property file must match a value that is defined in the DB_SERVER_LIST.

   Note: If you see a section that is commented out with a single hash (#), verify that the capability is enabled and then uncomment these parameter lines. Enter the correct values for the username and password.

   The following example shows the commented lines for the Case History database parameters.

   ## Provide the name of the database for Case History when Case History Emitter is enabled. For example: "CHOS"
   # <DB_ALIAS_NAME>.CHOS_DB_NAME="CHOS"
   ## Provide database schema name. This parameter is optional. If not set, the schema name is the same as database user name.
   ## For DB2, the schema name is case-sensitive, and must be specified in uppercase characters.
   # <DB_ALIAS_NAME>.CHOS_DB_CURRENT_SCHEMA="<Optional>"
   ## Provide the user name for the object store database required by Case History when Case History Emitter is enabled. For example: "dbuser1"
   # <DB_ALIAS_NAME>.CHOS_DB_USER_NAME="<youruser1>"
   ## Provide the password (if password has special characters then Base64 encoded with {Base64} prefix, otherwise use plain text) for the user of Object Store of P8Domain.
   # <DB_ALIAS_NAME>.CHOS_DB_USER_PASSWORD="{Base64}<yourpassword>"

4. Enter the required values for the LDAP variables in the cp4ba_LDAP.property file.

   Replace the <Required> string with your existing LDAP server parameters, its query objects, users, and groups.

   Important: If your target platform is ROKS Virtual Private Cloud (VPC), you can validate the connection to your LDAP only by using a VM client of the ROKS VPC. Set the LDAP server to the internal IP address or DNS of the ROKS VPC. For example, if the IP address of your LDAP is 10.240.0.16, then change the LDAP_SERVER property in the cp4ba_LDAP.property file to this address.

   ## The name of the LDAP server to connect
   LDAP_SERVER="10.240.0.16"

   If your client is not connected to the ROKS VPC, you can still set the IP address to propagate the value to the custom resource.

5. All names and passwords in the cp4ba_db_name_user.property file must be entered manually.

   Replace the <yourpassword> strings with your database user passwords.

   Restriction: The username values cannot contain special characters. Special characters include the equal sign (=), a forward slash (/), a colon (:), a single dot (.), single quotation marks ('), and double quotation marks ("). If a value does contain a special character, the script fails to parse the value.

   The password can contain special characters, except the single quotation mark ('). The single quotation is used to enclose the string that contains special characters. If you have a password without special characters use the string as plain text. For example, if you want the password to be mypassword, specify the password as "mypassword".

   dbserver1.GCD_DB_USER_NAME="GCDDB"
   dbserver1.GCD_DB_USER_PASSWORD="mypassword"

   If you have a password with special characters (&passw0rd), you must encode this string and add {Base64} before you add the value to the property. To encode the password on Linux, run the following command:

   # echo -n '&passw0rd' | base64
   JnBhc3N3MHJk

   Add the encoded value to the property with the {Base64} prefix.

   dbserver1.GCD_DB_USER_NAME="GCDDB"
   dbserver1.GCD_DB_USER_PASSWORD="{Base64}JnBhc3N3MHJk"

./cp4a-prerequisites.sh -m generate -n <CP4BA_NAMESPACE>

Change the prefix "<DB_ALIAS_NAME>" in propertyfile/cp4ba_db_name_user.property to assign which database is used by the component.
Found invalid value(s) "<Required>" in property file "propertyfile/cp4ba_db_name_user.property". Enter the correct value.

The following messages are displayed at the end of the execution:

[INFO] The DB SQL statement files for CP4BA are in directory <extracted_cert-kubernetes_archive>/cert-kubernetes/scripts/cp4ba-prerequisites/dbscript, you can modify or use the default settings to create the database. (DO NOT CHANGE DBNAME/DBUSER/DBPASSWORD DIRECTLY)
[NEXT ACTIONS]
Enter the correct values in the YAML templates for the secrets under <extracted_cert-kubernetes_archive>/cert-kubernetes/scripts/cp4ba-prerequisites/secret_template
...

The /cp4ba-prerequisites directory has the following structure and varies depending on the capabilities that you selected when you ran the script:

├── create_secret.sh
├── dbscript
    ├── <component>
        ├── <database_type>
            ├── <db_server_alias>
                └── <sql_template>
├── propertyfile
├── secret_template
    ├── <component>
        └── <yaml_secret> 
    └── ibm-ldap-bind-secret.yaml

If you chose an external PostgreSQL for Zen and IM in the property mode, then the generate mode creates the following files under the propertyfile folder.

• zen_external_db/ibm-zen-metastore-edb-cm.yaml: Use the generated YAML file to create a configMap.
• im_external_db/ibm-im-metastore-edb-cm.yaml: Use the generated YAML file to create a configMap.
• zen_external_db/ibm-zen-metastore-edb-secret.sh: Use the generated script to create the secret.
• im_external_db/ibm-im-metastore-edb-secret.sh: Use the generated script to create the secret.

1. Run the following command to go to the target CP4BA namespace.

   oc project <namespace>

   Note: If you deployed the operators in a separate namespace to the target CP4BA namespace, you must create the secrets in the CP4BA namespace.
2. Make sure that you are in the scripts folder under cert-kubernetes and run the create_secret.sh script to apply all the YAML template files that you generated.
   Important: All the password fields in the secret template files that the cp4a-prerequisites.sh script generated are Base64 encoded and put in the data: section in the files. If you need to modify any password in the secret template files before you create the secret in your cluster, then make sure that the updated fields are in the right format.

   • If an updated value is in the data: section of a file, it must be Base64 encoded. A Base64 encoded value can be retrieved by running the following command.

     echo "<value-to-update>" | base64

   • If an updated value is in the stringData: section of a file, it can be in plain text.

   ./cp4ba-prerequisites/create_secret.sh

Run the export command to set the values for a language and country as environment variables before you run the cp4a-prerequisites.sh script in the "validate" mode. The following variables set the language to Hindi and the country to India.

export CP4BA_AUTO_LANGUAGE="HI"
export CP4BA_AUTO_REGION="IN"

./cp4a-prerequisites.sh -m validate -n <CP4BA_NAMESPACE>

The command validates that the storage classes that you entered in the property mode meet the RWX and RWO requirements. If the validation is successful, it is marked as PASSED!

The command also checks that the required secrets are found and submits a validation query to the LDAP server and the list of remote database servers. If you chose an external Postgres DB used for the Zen metastore, then the connection is also checked. If the operations succeed within the timeout threshold, the validation is marked as PASSED! No queries are run and no data is changed, the script just reports that the connection succeeded.

If a connection is not successful, then a message informs you which connection failed. To resolve the issue, check the values in your property files so that you can correct them and try again.