Troubleshooting

It is necessary to collect specific information about your deployments to measure their well-being and to diagnose a problem before you open a support case on Cloud Pak for Business Automation.

Collect specific data about your environment and your Cloud Pak installation before you contact IBM® support for assistance with a Cloud Pak for Business Automation issue. Always provide a detailed description of the problem and your environment.

When you run diagnostic commands, run them from an empty directory to package the files more cleanly. Run the commands from the namespace in which you observe the problematic container or component. For more information, see Mustgather: Collecting data to diagnose issues External link opens a new window or tab.

Collecting data

If you see any issues during the upgrade, collect the following information that might help with the troubleshooting.
  • Collect the following information from the scripts directory.
    • <location of cert-kubernetes>/scripts/cp4a-script-logs
    • <location of cert-kubernetes>/scripts/cpfs/installer_scripts/cp3pt0-deployment/logs
    • <location of cert-kubernetes>/scripts/cp4ba-upgrade
    • <location of cert-kubernetes>/scripts/.tmp
    • <location of cert-kubernetes>/scripts/*.log
    • <location of cert-kubernetes>/scripts/*.yaml
  • Collect the output from the console where you run the upgrade script.
  • Screenshot of the error messages if applicable.
  • Run the Cloud Pak for Business Automation Mustgather External link opens a new window or tab.

Resolving issues

The ibm-common-service-operator operator fails to upgrade
When you run the cp4a-deployment.sh in the upgradeOperator mode, the ibm-common-service-operator operator fails to upgrade and displays the following message:

RETRYING: Waiting for operator ibm-common-service-operator to be upgraded

To resolve the issue, do the following steps:
  1. Run the following command and check for failed jobs.
    oc get job
  2. Run the following command to restart the failed job.
    oc get job <job-name> -o json | jq 'del(.spec.selector)' | jq 'del(.spec.template.metadata.labels)' | oc replace --force -f -
  3. Rerun the cp4a-deployment.sh in the upgradeOperator mode.
    ./cp4a-deployment.sh -m upgradeOperator -n <namespace> --cpfs-upgrade-mode <migration mode> --original-cp4ba-csv-ver <cp4ba-csv-version-before-upgrade>

    Where <namespace> is the CP4BA namespace, <migration mode> is the migration mode for Cloud Pak foundational services and <cp4ba-csv-version-before-upgrade> is the version of csv of CP4BA operator before upgrade.

    The following command is an example.
    ./cp4a-deployment.sh -m upgradeOperator -n a1 --cpfs-upgrade-mode dedicated2dedicated --original-cp4ba-csv-ver 24.1.0
Upgrade blocked due to missing ibm-cp4ba-common-config ConfigMap

If the Not found "ibm-cp4ba-common-config" configMap error message is encountered when the upgrade script runs, the ibm-cp4ba-common-config ConfigMap is missing from the namespace for the CP4BA deployment.

To resolve the issue, follow the steps in either Option 1 or Option 2.

Option 1: Create the missing ConfigMap manually

Use the following steps to re-create the ConfigMap.

  1. Find the namespace where the CommonService CR is installed by running the following command. The namespace of the CommonService deployment is where all the Cloud Pak foundational services and CP4BA operators are installed.
    oc get CommonService -A
    Note: If you have multiple deployments, make sure that you locate the namespace that you are upgrading before you complete the next steps.
  2. Run the following commands to retrieve the values needed to create the ibm-cp4ba-common-config ConfigMap.
    oc get CommonService -o yaml | grep 'operatorNamespace:' | head -n 1 | awk '{print $2}'
oc get CommonService -o yaml | grep 'servicesNamespace:' | head -n 1 | awk '{print $2}'
  3. Create the ibm-cp4ba-common-config ConfigMap in the target CommonService namespace.
    kind: ConfigMap
apiVersion: v1
metadata:
  name: ibm-cp4ba-common-config
  namespace: <namespace>
data:
  operators_namespace: "<operator-namespace>"
  services_namespace: "<service-namespace>"

    Where the value of <namespace> and <operator-namespace> is provided by the first command in the previous step. The value of <service-namespace> is provided by the second command.

  4. If you created a YAML file in the previous step, for example ibm-cp4ba-common-config.yaml, then run the following command to apply the ConfigMap to the CommonService namespace from the command window. 
    oc apply -f ibm-cp4ba-common-config.yaml -n <namespace>

    If you prefer to use the OCP console, then apply the ConfigMap manually.

  5. After you created the ibm-cp4ba-common-config ConfigMap, return to upgrading the deployment by running the cp4a-deployment.sh script in upgradeOperator mode.

Option 2: Run the cp4a-clusteradmin-setup.sh script to create the missing ConfigMap

  1. Run the cp4a-clusteradmin-setup.sh script from the local directory where you downloaded the cert-kubernetes repository, and follow the prompts in the command window.
    cd cert-kubernetes/scripts
./cp4a-clusteradmin-setup.sh -fix_configmap
  2. After you created the ibm-cp4ba-common-config ConfigMap, return to upgrading the deployment by running the cp4a-deployment.sh script in upgradeOperator mode.

Troubleshooting capabilities

The custom resource can be configured to enable and disable specific logging parameters, log levels, log formats, and where these logs are stored for the various capabilities. If you need more information about specific Cloud Pak capabilities, go to the relevant troubleshooting topics.