Deploying Z Understand on IBM Software Hub

Prerequisites

Before beginning, ensure the following tools are installed locally:

• openssl - for certificate creation.

• keytool - for managing keystores.

• jq - to parse JSON.

• oc (OpenShift CLI) - to interact with the OpenShift cluster.

• Set your namespace: export NAMESPACE={cpd-inst-namespace}

Deploying the Z Understand container on IBM Software Hub

Complete the following steps to deploy and configure the Z Understand container.

1. Create OpenShift passthrough routes for Z Understand.
   • UI route - Exposes the Z Understand service externally.

     oc create route passthrough ibm-wca-z-understand \
       --service=ibm-wca-z-understand \
       --port=9443 \
       --namespace=$NAMESPACE

   • Graph database route - Provides external access to the OrientDB graph database.

     oc create route passthrough ibm-wca-z-understand-graphdb \
       --service=ibm-wca-z-understand \
       --port=2424 \
       --namespace=$NAMESPACE

2. Patch the CR (understandagentorchestrator) with the newly generated route hostnames so the container restarts with the correct endpoints.
   • Patch UI Route

     oc patch understandagentorchestrator \
       $(oc get understandagentorchestrator -n $NAMESPACE -o jsonpath='{.items[0].metadata.name}') \
       -n $NAMESPACE \
       --type=merge \
       -p "{\"spec\":{\"understandRouteHostname\":\"$(oc get route ibm-wca-z-understand -n $NAMESPACE -o jsonpath='{.spec.host}')\"}}"

   • Patch GraphDB Route

     oc patch understandagentorchestrator \
       $(oc get understandagentorchestrator -n $NAMESPACE -o jsonpath='{.items[0].metadata.name}') \
       -n $NAMESPACE \
       --type=merge \
     -p "{\"spec\":{\"understandGraphdbRouteHostname\":\"$(oc get route ibm-wca-z-understand-graphdb -n $NAMESPACE -o jsonpath='{.spec.host}')\"}}"

3. Ensure that the container is running and all pods are ready.

   oc get pods -n $NAMESPACE -l app=ibm-wca-z-understand

4. Retrieve the pod name.

   POD_NAME=$(oc get pods -n $NAMESPACE -l app=ibm-wca-z-understand -o jsonpath='{.items[0].metadata.name}')

5. Extract the setup.json file from the Z Understand secret.

   • SQL Server

     oc get secret wca-z-understand-setup -n $NAMESPACE -o jsonpath='{.data.setup-sqlserver\.json}' | base64 -d | jq > setup-sqlserver.json

   • Db2

     oc get secret wca-z-understand-setup -n $NAMESPACE -o jsonpath='{.data.setup-db2\.json}' | base64 -d | jq > setup-db2.json

   Update hostnames, usernames, ports, and other configuration details as required.
6. Open the .JSON file and update hostnames, usernames, ports, and other configuration details as required.

   • SQL Server

     vi setup-sqlserver.json

   • Db2

     vi setup-db2.json

7. Patch the Z Understand secret with the updated file.
   • SQL Server

     oc patch secret wca-z-understand-setup \
       -n $NAMESPACE \
       --type='json' \
       -p="[{'op': 'replace', 'path': '/data/setup-sqlserver.json', 'value':'$(base64 -w 0 < setup-sqlserver.json)'}]"

   • Db2

     oc patch secret wca-z-understand-setup \
       -n $NAMESPACE \
       --type='json' \
       -p="[{'op': 'replace', 'path': '/data/setup-db2.json', 'value':'$(base64 -w 0 < setup-db2.json)'}]"

8. Verify the updated secret.

   • SQL Server

     oc get secret wca-z-understand-setup -n $NAMESPACE -o jsonpath='{.data.setup-sqlserver\.json}' | base64 -d | jq .

   • Db2

     oc get secret wca-z-understand-setup -n $NAMESPACE -o jsonpath='{.data.setup-db2\.json}' | base64 -d | jq .

9. Wait up to one minute for the container to sync. Confirm the setup file inside the pod.
   • SQL Server

     oc exec -n $NAMESPACE -it $POD_NAME -c wca4z-understand -- cat /wca4z-understand/setup/setup-sqlserver.json

   • Db2

     oc exec -n $NAMESPACE -it $POD_NAME -c wca4z-understand -- cat /wca4z-understand/setup/setup-db2.json

10. Execute the config.sh script with the updated setup file.

    • SQL Server

      oc exec -it $POD_NAME -n $NAMESPACE -c wca4z-understand -- /wca4z-understand/config.sh setup/setup-sqlserver.json

    • Db2

      oc exec -it $POD_NAME -n $NAMESPACE -c wca4z-understand -- /wca4z-understand/config.sh setup/setup-db2.json

Deploying Refactor on IBM Software Hub

Complete these steps to deploy and configure Refactor on IBM Software Hub.

1. Set the following environment variables:

   
   export NAMESPACE=<cpd-inst-namespace>
   export ENVIRONMENT_ID=<from Understand dashboard>
   export CERTS_LOCATION="./certs-folder"
   export ORIENTDB_PASSWORD=<your password>
   mkdir -p $CERTS_LOCATION
   

2. Create OpenShift passthrough route for Refactor.

   oc create route passthrough ibm-wca-z-understand-refactor \
     --service=ibm-wca-z-understand-refactor \
     --port=9080 \
     --namespace=$NAMESPACE

3. Update the understandagentorchestrator CR with Refactor hostname. This will restart and update the Understand container.

   oc patch understandagentorchestrator \
     $(oc get understandagentorchestrator -n $NAMESPACE -o jsonpath='{.items[0].metadata.name}') \
     -n $NAMESPACE \
     --type=merge \
     -p "{\"spec\":{\"refactorRouteHostname\":\"$(oc get route ibm-wca-z-understand-refactor -n $NAMESPACE -o jsonpath='{.spec.host}')\"}}"

4. Wait until the Understand container is running.

   oc get pods -n $NAMESPACE -l app=ibm-wca-z-understand

5. Retrieve the pod name.

   
   POD_NAME=$(oc get pods -n $NAMESPACE -l app=ibm-wca-z-understand -o jsonpath='{.items[0].metadata.name}')

6. Create the certificates folder.

   mkdir -p $CERTS_LOCATION

7. Copy the Understand certificate file to your certs location as wca4z-understand.crt.

   oc cp $NAMESPACE/$POD_NAME:/wca4z-understand/security/$(oc exec -n $NAMESPACE $POD_NAME -- sh -c 'ls /wca4z-understand/security/ | grep "self_signed_server_certificate.*\.crt$" | head -1') "$CERTS_LOCATION/wca4z-understand.crt" -c wca4z-understand

8. Download the script to create Refactor secret with the generated self-signed certificates and the required setup values.

   oc get configmap wca-z-understand-refactor-scripts -n $NAMESPACE -o jsonpath='{.data.generate-refactor-secret\.sh}' > generate-refactor-secret.sh

9. Run the script with the required parameters to the create Refactor secret.

   chmod +x generate-refactor-secret.sh
   ./generate-refactor-secret.sh --environment-id $ENVIRONMENT_ID --namespace $NAMESPACE --certs-location $CERTS_LOCATION --orientdb-password $ORIENTDB_PASSWORD

10. Navigate to /ad/admin/dashboard via the Z Understand Container web UI and add the root.crt of Refactor to Understand container.
11. Patch the CR with the newly created Refactor secret.

    oc patch understandagentorchestrator \
      $(oc get understandagentorchestrator -n $NAMESPACE -o jsonpath='{.items[0].metadata.name}') \
      -n $NAMESPACE \
      --type=merge \
      -p '{"spec":{"refactorSecret":"wca-z-understand-refactor-config"}}'

Using the deployed Z Understand container (Create Projects)

1. Set the following environment variables.

   export NAMESPACE=cpd-inst-und-531
   POD_NAME=$(oc get pods -n $NAMESPACE -l app=ibm-wca-z-understand -o jsonpath='{.items[0].metadata.name}')

2. Retrieve the cli.sh script:

   oc get configmap wca-z-understand-scripts -n $NAMESPACE -o jsonpath='{.data.cli\.sh}' > cli.sh
   chmod +x cli.sh

3. From the /config/projects/samples folder, copy a target configuration file for project creation.

   oc exec -n $NAMESPACE $POD_NAME -c wca4z-understand -- ls "/wca4z-understand/IBM Application Discovery Build Client CLI/config/projects/samples" oc exec -n $NAMESPACE $POD_NAME -c wca4z-understand -- cat "/wca4z-understand/IBM Application Discovery Build Client CLI/config/projects/samples/new_proj_sql.ini" > ./new_proj_sql.ini
   

4. Edit the configuration file (new_proj_sql.ini) with the required project details and upload it to the container.

   oc cp ./new_proj_sql.ini "$NAMESPACE/$POD_NAME:/wca4z-understand/IBM Application Discovery Build Client CLI/config/projects/new_proj_sql.ini" -c wca4z-understand

5. Verify that the changes are synced and appear in the Understand container.

   oc exec -n $NAMESPACE -it $POD_NAME -c wca4z-understand -- cat "/wca4z-understand/IBM Application Discovery Build Client CLI/config/projects/new_proj_sql.ini"

6. Run the CLI script to create a new project.

   PROJECT_NAME={PROJECT NAME}
   ./cli.sh -c new_proj_sql.ini $PROJECT_NAME

7. Add project files by copying files to the Understand container using oc cp or oc rsync.
8. Build the project using the cli.sh script. The script also supports additional operations such as build, analyze, and list projects similar to on‑premise installations.

Refactor: Streamlining program structure

Complete these steps to streamline program structure using Refactor.

1. Retrieve the configure.sh script from the cluster.

   oc get configmap wca-z-understand-refactor-scripts -n $NAMESPACE -o jsonpath='{.data.configure\.sh}' > configure.sh

2. Complete the steps to perform one-time configuration.