Preparing LDAP secrets for BAI by running a script

The bai-prerequisites.sh script is provided in the cert-kubernetes-bai repository to help you prepare for an installation of Business Automation Insights. The script generates property files for BAI in your deployment and must be run before your deployment is installed.

Before you begin

The bai-prerequisites.sh script uses the following utility tools and needs them to be installed on your client machine.

Note: If the script detects that any of the required tools are missing on the client, it reports the names and versions of the tools that are needed. It then provides a choice for you to install them.

kubectl (on OpenShift® the version must match your cluster version)
If you prepared your client machine for an online deployment, then kubectl is already installed. For more information, see Preparing a client to connect to the cluster.
Java™ runtime environment (JRE 8.x is installed by the script if it is not found)
OpenSSL

About this task

Instead of going through the many documented steps to create the secrets for ldap in your Business Automation Insights deployment, you can use the script to generate the YAML template files for the secrets.

The bai-prerequisites.sh script has three modes.

property: The property mode supports the generation of property files. The script creates the user property files (bai_user_profile.property and bai_LDAP.property). Review and modify these files to match your infrastructure. Add values for LDAP server name, and LDAP attributes.
generate: The generate mode uses the modified property files to generate the YAML template for the secret.
validate: The validate mode checks whether the generated secrets are correct and ready to use in a BAI deployment.

For more information about downloading cert-kubernetes-bai, see Preparing a client to connect to the cluster.

The script can be run from this location and has the following options:

./bai-prerequisites.sh
Usage: bai-prerequisites.sh -m [modetype] -n [BAI-NAMESPACE] Options:
  -h  Display help
  -m  The valid mode types are: [property], [generate], or [validate]
  -n  The target namespace of the BAI deployment.  
  STEP1: Run the script in [property] mode. It creates property files (LDAP property file) with default values (BASE DN/BIND DN ...).
  STEP2: Modify the LDAP/user property files with your values.
  STEP3: Run the script in [generate] mode. Generates the YAML templates for the secrets based on the values in the property files.
  STEP4: Create the secrets by using the modified YAML templates for the secrets.
  STEP5: Run the script in [validate] mode. Checks the secrets are created before you install IBM Business Automation Insights.

All three modes can be run on the same client machine, but you can also run the property and generate modes on different clients. If you want to use different clients, then copy the temporary property file from the property mode with the output folder to the other client. Make a copy of the following files and put them into the downloaded cert-kubernetes-bai folder on the other client:

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

Note: Some properties use an absolute path in their values. If you do copy the script to a different machine, make sure that the absolute paths are updated to match the location of the copied script.

The values of the following properties need to be modified after you copy the bai-prerequisites folder to a different client.

********bai_LDAP_server.property*************
LDAP_SSL_CERT_FILE_FOLDER

If you ran the bai-prerequisites.sh -m generate command on the original client, you must run the command again after you modified the property files to re-create the SSL secret templates with the updated absolute paths.

Procedure

Make sure that you downloaded the cert-kubernetes-bai repository to a Linux® based machine (CentOS Stream/RHEL/MacOS) or a client to a Linux-based machine.
Make sure that you are in the scripts folder under cert-kubernetes-bai.

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>

Run the script in all modes.
```
./bai-prerequisites.sh -m property -n <namespace>
./bai-prerequisites.sh -m generate -n <namespace>
./bai-prerequisites.sh -m validate -n <namespace>
```
Follow the prompts in the command window to enter the required information.
1. Accept the license. Agree to the license that is displayed.
2. Select the platform type: ROKS (1), OCP (2) or Other (3) that you want to install.
3. Enter Yes or No to configure LDAP or not.
  1. If you enter Yes for LDAP configuration, then provide an LDAP username.
  2. Select the LDAP type that you want to use for BAI deployment: Microsoft Active Directory (1) or IBM Tivoli Directory Server (2).
    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 "bai_LDAP.property" later. "LDAP_SSL_ENABLED" is "TRUE" by default.
```
4. Enter your dynamic storage classes for medium, fast file storage (RWX), and a block storage class name (RWO).
5. Select a deployment profile size from small, medium, or large [1 to 3]. The default is small.
6. Enter Yes or No to change the default IAM admin user or not.
  If you enter No, then provide the non-default IAM Admin username.
7. If any deny-all network policies exist in the BAI namespaces, they must be removed first. You can re-create them after the installation. If you plan to create network policies, and want the operators to generate sample network policies templates, select Yes (default is No). You can run the bai-network-policies.sh to copy the network policies templates from the operators to a local location.
  The bai-network-policies.sh must be executed after you confirm that all components are successfully installed. For more information, see Installing network policies.
8. Choose whether to use an external PostgreSQL or embedded EDB Postgres for the IM/Platform UI (Zen)/BTS metastore DB.
  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 EDB PostgreSQL database server and Configuring an external PostgreSQL database for Zen .
  
  Remember: IM/Zen/BTS stores users, groups, service instances, vault integration, and secret references in the metastore DB.
  
  Note: If you select Yes to choose an external Postgresql DB, the script generates properties with the prefix BAI.IM_EXTERNAL_POSTGRES_DATABASE /BAI.ZEN_EXTERNAL_POSTGRES_DATABASE /BAI.BTS_EXTERNAL_POSTGRES_DATABASE in the bai_user_profile.property file.
9. Choose the Flink job that you want to install.
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 BAI stand-alone ==============
[NEXT ACTIONS]
Enter the <Required> values in the property files under /home/olm-dev/operator/cert-kubernetes-bai/scripts/bai-prerequisites/<namespace>/secret_template
[*] The key name in the property file is created by the bai-prerequisites.sh and is NOT EDITABLE.
[*] The value in the property file must be within double quotes.
[*] The value for User/Password in [bai_user_profile.property] file should NOT include special characters: single quotation "'"
[*] The value in [bai_LDAP.property] [bai_user_profile.property] file should NOT include special character '"'
* [bai_LDAP.property]:
- Properties for the LDAP server that is used by the BAI stand-alone deployment, such as LDAP_SERVER/LDAP_PORT/LDAP_BASE_DN/LDAP_BIND_DN/LDAP_BIND_DN_PASSWORD.

* [bai_user_profile.property]:
- Properties for the global value used by the BAI stand-alone deployment, such as "sc_deployment_license".

- Properties for the value used by each component of BAI stand-alone, such as "sc_deployment_profile_size"
```
The propertyfile directory has the following file structure:
```
├── cert
    └── ldap
├── bai_LDAP.property
└── bai_user_profile.property
```

Make sure that you are in the propertyfile folder under bai-prerequisites and edit the property files as indicated by the NEXT ACTIONS messages from the script. Update the ( bai_LDAP.property, bai_user_profile.property) with the values in your environment.

Important: If it has special characters, use the {xor} prefix for the LDAP_BIND_DN password. The following example shows the {xor} prefix must be used and the password must be encoded when it has a special character.

LDAP_BIND_DN_PASSWORD="{xor}Dz4sLCgwLTt7"  # Which is "Password$" when the xor string is decoded.

Edit the global section in the bai_user_profile.property file.

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


####################################################
## USER Property for BAI stand-alone ##
####################################################
## Use this parameter to specify the license for the BAI stand-alone 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.
BAI_STANDALONE.BAI_LICENSE="<Required>"

## The platform to be deployed specified by the user. Possible values are: OCP and ROKS and other
BAI_STANDALONE.PLATFORM_TYPE="OCP"

## On OCP 3.x and 4.x, the User script will populate these three (3) parameters based on your input for "production" deployment.
## If you manually deploying without using the User script, then you would provide the different storage classes for the slow, medium
## and fast storage parameters below. If you only have 1 storage class defined, then you can use that 1 storage class for all 3 parameters.
## sc_block_storage_classname is for Zen, Zen requires/recommends block storage (RWO) for metastoreDB
BAI_STANDALONE.MEDIUM_FILE_STORAGE_CLASSNAME="qwe"
BAI_STANDALONE.FAST_FILE_STORAGE_CLASSNAME="qwe"
BAI_STANDALONE.BLOCK_STORAGE_CLASS_NAME="qwe"

## Specify a profile size for BAI stand-alone deployment (valid values are small,medium,large - default is small).
BAI_STANDALONE.DEPLOYMENT_PROFILE_SIZE="small"

## Provide non default admin user for IAM in case you do not want to use "cpadmin".
BAI_STANDALONE.IAM_ADMIN_USER_NAME="cpadmin"

## For BAI stand-alone, if you select LDAP, then provide one ldap user here for onborading ZEN.
BAI_STANDALONE.LDAP_USER_NAME_ONBORADING_ZEN="CEAdmin"

## The Flink job for processing BPMN events.
## Set to true to enable the Flink job for BAW.
BAI_STANDALONE.FLINK_JOB_BPMN="False"

## The Flink job for processing BAW Advanced events..
## Set to true to enable the Flink job for BAWAdv.
BAI_STANDALONE.FLINK_JOB_BAWADV="False"

## The Flink job for processing ICM events.
## Set to true to enable the Flink job for ICM.
BAI_STANDALONE.FLINK_JOB_ICM="False"

## The Flink job for processing ODM events..
## Set to true to enable the Flink job for ODM.
BAI_STANDALONE.FLINK_JOB_ODM="False"

## The Flink job for processing Content events.
## Set to true to enable the Flink job for Content.
BAI_STANDALONE.FLINK_JOB_CONTENT="True"

## The Flink job for processing ADS events.
## Set to true to enable the Flink job for ADS.
BAI_STANDALONE.FLINK_JOB_ADS="False"

## The Flink job for processing Navigator events.
## Set to true to enable the Flink job for Navigator.
BAI_STANDALONE.FLINK_JOB_NAVIGATOR="False"

Follow the instructions in the bai_user_profile.property file to enter all the <Required> values for the external Postgresql 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-bai/scripts/bai-prerequisites/propertyfile/cert/zen_external_db".
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_SSL_CERT_FILE_FOLDER="/home/cert-kubernetes-bai/scripts/bai-prerequisites/propertyfile/cert/zen_external_db"

## Name of the schema to store monitoring data. The default value is "watchdog".
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_MONITORING_SCHEMA="watchdog"

## Name of the database. The default value is "zencnpdb".
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_NAME="zencnpdb"

## Database port number. The default value is "5432".
BAI.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.
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_R_ENDPOINT="<Required>"

## Name of the database host.
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_RW_ENDPOINT="<Required>"

## Name of the schema to store zen metadata. The default value is "public".
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_SCHEMA="public"

## Name of the database user. The default value is "zencnp_user".
BAI.ZEN_EXTERNAL_POSTGRES_DATABASE_USER="zencnp_user"

Enter the required values for the LDAP variables in the bai_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 bai_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.

When the user property files are complete and ready, make sure that you are in the scripts folder under cert-kubernetes-bai, and run the bai-prerequisites.sh script in the "generate" mode.
```
./bai-prerequisites.sh -m generate -n <namespace>
```
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:
```
* Enter the <Required> values in the YAML templates for the secrets under /home/operator/cert-kubernetes-bai/scripts/bai-prerequisites/<namespace>/secret_template * Get the "ldap-cert.crt" from the remote LDAP server <Required>, and copy it into the folder /home/operator/cert-kubernetes-bai/scripts/bai-prerequisites/<namespace>/propertyfile/cert/ldap before you create the Kubernetes secret for the LDAP SS
```
The /bai-prerequisites/<namespace> directory has the following structure and varies depending on the capabilities that you selected when you ran the script:
```
├── create_secret.sh
├── propertyfile
├── secret_template
    ├── bai_ldap_ssl_secret
        └── ibm-bai-ldap-ssl-cert-secret.sh
    └── ldap-bind-secret.yaml
```
If you chose an external Postgresql DB for Zen in the property mode, then the bai_user_profile.property file under the propertyfile folder contains the following files.
- 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.
Check that you have all the necessary files for your BAI deployment. Copy the required 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 .
Create the necessary secrets in your Kubernetes cluster.
1. Run the following command to go to the target BAI namespace.
```
kubectl config set-context --current --namespace=<namespace>
```
  Note: If you deployed the operators in a separate namespace to the target BAI namespace, you must create the secrets in the BAI namespace.
2. Make sure that you are in the scripts folder under cert-kubernetes-bai 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 bai-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.
```
./bai-prerequisites/<namespace>/create_secret.sh
```
Optional: Before you validate your database and LDAP connections, you can set values for your language and country. If no values are set, English (-Duser.language=en) is set as the language, and the United States (-Duser.country=US) is set as the country.
Run the export command to set the values for a language and country as environment variables before you run the bai-prerequisites.sh script in the "validate" mode. The following variables set the language to Hindi and the country to India.
```
export BAI_AUTO_LANGUAGE="HI"
export BAI_AUTO_REGION="IN"
```
Optional: When all the required secrets are created, make sure that you are in the scripts folder under cert-kubernetes-bai, and run the bai-prerequisites.sh script again in the "validate" mode.
```
./bai-prerequisites.sh -m validate -n <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. If you chose an external Postgresql 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.
Note: The bai-prerequisites.sh -m validate command uses Java command to validate the LDAP connection. If Java does not exist, it requests to download it.

Results

You can rerun the script in the "property" mode to create new property files. When the script detects it ran before, the previous property folder is renamed into a new time-stamped folder. The name of the backed-up folder is cert-kubernetes-bai/scripts/bai-prerequisites-backup/propertyfile_%Y-%m-%d-%H:%M:%S.

Use the following steps to update your property files to include your new change:

Copy the file .tmp/.TEMPORARY.property into a back up file, for example .TEMPORARY.property.backup.
Rerun the bai-prerequisites.sh script in the "property" mode, and choose a different selection.
Restore the bai_LDAP.property file from the backup folder by copying and pasting them into the new folder.
Merge the new bai_user_profile.property files with the backed-up property files.
Rerun the bai-prerequisites.sh script in the "generate" mode to update the YAML templates for the secrets.
Compare and merge the .TEMPORARY.property.backup file with the .tmp/.TEMPORARY.property file for the new change.
Re-create the secrets.

If you already installed a BAI deployment and want to update it with the new secrets, you must run the bai-deployment.sh again to update the custom resource. Do not forget to verify the custom resource YAML before you scale down the deployment, apply the new custom resource with the --overwrite=true parameter, and scale the deployment back up.

What to do next

The next task to complete is Creating a production deployment.

Remember: When you run the bai-deployment.sh script from the location that outputs the bai-prerequisites folder, the values that are defined in your property files are used in the custom resource file.