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

The cp4a-prerequisites.sh script is provided in the cert-kubernetes archive of the CASE package to help you prepare for an installation of Cloud Pak for Business Automation. The script generates property files for the selected capabilities in your deployment and must be run before your deployment is installed.

./cp4a-prerequisites.sh
Usage: cp4a-prerequisites.sh -m [modetype]
Options:
  -h  Display help
  -m  The valid mode types are: [property], [generate], or [validate]
      STEP 1: Run the script in [property] mode. Creates property files (DB/LDAP property file) with default values (database name/user).
      STEP 2: Modify the DB/LDAP/user property files with your values.
      STEP 3: Run the script in [generate] mode. Generates the DB SQL statement files and YAML templates for the secrets based on the values in the property files.
      STEP 4: Create the databases and secrets by using the modified DB SQL statement files and YAML templates.
      STEP 5: Run the script in [validate] mode. Checks whether the databases and the secrets are created before you install CP4BA.

cert-kubernetes/scripts/.tmp/.TEMPORARY.property
cert-kubernetes/cp4ba-prerequisites

********cp4ba_db_server.property*************
<DB_PREFIX_NAME>.DATABASE_SSL_CERT_FILE_FOLDER

********cp4ba_LDAP_server.property*************
LDAP_SSL_CERT_FILE_FOLDER

************cp4ba_user_profile.property******************
APP_ENGINE.SESSION_REDIS_SSL_CERT_FILE_FOLDER

1. Make sure that you downloaded the cert-kubernetes repository to a Linux® based machine (CentOS Stream/RHEL/MacOS) or a client to a Linux-based machine.
2. Make sure that you are in the scripts folder under cert-kubernetes.
3. Log in to the target cluster as the <cluster-admin> user.

   Using the OpenShift CLI:

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

   On ROKS, if you are not already logged in:

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

4. Run the script in the "property" mode.

   ./cp4a-prerequisites.sh -m property

   Note: If the script detects that the client does not have the right versions of Java, kubectl, keytool, and OpenSSL installed, then it offers to install the missing tools for you. If you choose not to allow the script to install them, you must install the missing tools yourself before you run the script again.

   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 Automation Document Processing, then you must select Db2 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. 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.

   4. Enter your dynamic storage classes for slow, medium, fast file storage (RWX).
   5. Enter a block storage class name (RWO).
   6. Choose the database type that you want to use for the CP4BA deployment.

      By default, the database is SSL enabled. You can disable SSL for the 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 configuration parameter. For more information, see Configuring a custom external database.
   7. Enter the alias names for all of 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.
   8. Enter the number of object stores of a FileNet P8 domain to configure for the CP4BA deployment.

   When the script is finished, the messages include a number of 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 values in the property files must be inside double quotes ("").
   [*] The values for the usernames and passwords in the cp4ba_db_name_user.property file CANNOT include special characters. For example: "=" "." "\".
   [*] The values in the cp4ba_LDAP.property, cp4ba_External_LDAP.property, and cp4ba_user_profile.property files CANNOT include special characters. 

   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

   Note: The db directory contains one or more db server alias names that you specified.
5. You must then edit the property files as indicated by the NEXT ACTIONS messages from the script. Update the (cp4ba_db_name_user.property, cp4ba_db_server.property, cp4ba_LDAP.property, cp4ba_user_profile.property, and optionally cp4ba_External_LDAP.property) with the values in your environment,

   1. Edit the global section in the cp4ba_user_profile.property file as well as the other sections for each capability that you selected.

      The global section contains license properties and the needed storage classes. The BAN section is also always included, and the users and groups must be from your LDAP.

      ####################################################
      ## USER Property for CP4BA ##
      ####################################################
      CP4BA.CP4BA_LICENSE="<Required>"
      ## The script populates these three (3) parameters based on your input.
      ## If you manually deploy without using the 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 metastoreDB.
      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>"
      ####################################################
      ## 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.

   2. If you entered a single database server, then the DB_SERVER_NAME is set automatically. If you need more than one server, edit the <DB_SERVER_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_SERVER_NAME> in the username property file must match a value that is defined in the DB_SERVER_LIST.

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

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

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

      Restriction: The username and password 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. If you want your password to start with a special character other than =,",/, :, and ', you need to add a backslash (\) before the special character for CP4BA to accept the password. For example, if you want the password to be &passw0rd, you must specify the password as \&passw0rd.
6. When the user property files are complete and ready, run the cp4a-prerequisites.sh script in the "generate" mode.

   ./cp4a-prerequisites.sh -m generate

   Note: If the script detects that the property files do not have custom values, the script stops and displays messages to help identify the missing values:

   Change the prefix "<DB_SERVER_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", please input 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. (PLEASE 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

7. Check that you have all the necessary files for your CP4BA deployment. Copy the required database and LDAP certificates into the target directories as indicated by the NEXT ACTIONS messages from the script. Make sure that the scripts and the YAML files have the correct values.

   For more information, see Importing the certificate of an external service.

   Note: If you selected Operational Decision Manager, it is important to note that the chosen database tables are automatically created when the pods are started. Therefore, the createODMDB.sql script does not include these commands.
8. When you are ready, you or a database administrator can then run the DB scripts against your database servers and use the YAML files to create the necessary secrets in your OpenShift Container Platform cluster.
   Remember: The target databases must meet the requirements of the capabilities that you want to install. Review the preparing sections for each capability before you go ahead and create the databases. For more information, see Preparing your chosen capabilities.

   Run the create_secret.sh script to apply all the YAML template files that you generated.

   ./cp4ba-prerequisites/create_secret.sh

9. Optional: When all of the required databases and secrets are created, you can run the cp4a-prerequisites.sh script again in the "validate" mode.

   ./cp4a-prerequisites.sh -m validate

   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 all of the required secrets are found and submits a validation query to the LDAP server and the list of remote database servers. If the operation succeeds 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.

   Note: The cp4a-prerequisites.sh -m validate command uses a simple JDBC method to test the connection to the remote database servers with the Cloud Pak for Business Automation default JDBC drivers.

   If you need to use customized JDBC drivers in your production deployment, you can locate these drivers by using the sc_drivers_url parameter during the configuration of the custom resource. For more information, see Optional: Preparing customized versions of JDBC drivers and ICCSAP libraries.