watsonx Orchestrate

watsonx Orchestrate

Connect with experts and peers to elevate technical expertise, solve problems and share insights.

 View Only

IBM watsonx Orchestrate Extras

By Enrico Monteleone posted 08/27/26 01:08 PM

  

IBM watsonx Orchestrate  ·  On-Premises Deployment

IBM watsonx Orchestrate Extras

A community toolkit that facilitates installing, operating, and troubleshooting watsonx Orchestrate on OpenShift.

⚠ Community resource — not an official IBM product

These tools are experimental, community-contributed utilities. They are not part of any IBM product release and are not covered by IBM Support. Use at your own risk, always review the code before running it in your environment, and test in a non-production cluster first. See the Apache 2.0 license for the full disclaimer of warranties and liabilities.

This version of Extras was developed and tested for IBM watsonx Orchestrate version 5.4.0 installed on Red Hat version OpenShift 4.18. The tools may work on other versions but have not been tested.

What is "Extras"?

Installing and operating IBM watsonx Orchestrate on premises is a multi-stage process that requires coordinating a large number of OpenShift operators, storage systems, custom resources, and datastores. The official documentation covers every step, but the day-to-day reality — variable cluster configurations, silent failures, hard-to-correlate logs — often means practitioners spend significant time bridging the gap between the docs and the live cluster.

watsonx Orchestrate Extras is a container image you deploy to your OpenShift cluster. It surfaces a set of practitioner-built tools directly in your browser via an OpenShift route, covering the full lifecycle: pre-installation checks, guided notebook-based installation, post-installation health verification, log analysis, and hot-patch detection.

Who is this for?

OpenShift cluster administrators and platform engineers who are deploying or maintaining IBM watsonx Orchestrate on Red Hat OpenShift, non-GPU clusters with internet-connected environments using the OpenShift internal registry.

The Guided Notebook Installer — wxo540-ocp418-install

The headline tool in this release is a Jupyter notebook that walks you through a complete, end-to-end watsonx Orchestrate 5.4.0 installation on OpenShift 4.18. Rather than juggling dozens of CLI commands across multiple terminal windows, you work through a single document — reading the explanation, inspecting the code block, running it, and confirming the output — before advancing to the next step.

Why a notebook?

Notebooks combine documentation and execution in one place. Each cell shows exactly what it will do before you run it, the output is captured inline so you have a permanent record, and you can re-run any individual step if something needs to be retried — without starting over. For a complex installation with ~15 sequential phases, this dramatically reduces the chance of skipping a step or misreading the current state.

What the notebook covers

1. IBM Entitlement Key

Guidance on retrieving your key from myibm.ibm.com for access to cp.icr.io.

2. Cluster variables (cpd_vars.sh)

Interactive Python script prompts for your cluster name, OpenShift password, and entitlement key, then generates the environment file that every subsequent step sources.

3. OpenShift login

Runs both OC_LOGIN (standard admin) and CPDM_OC_LOGIN (IBM Software Hub / CP4D CLI) in a single cell.

4. ODF Storage

Installs OpenShift Data Foundation with LocalStorage and Ceph, including the udev MachineConfig workaround for the "No SSD/NVMe disks detected" known issue. MCPcheck script confirms all worker nodes have rebooted and are ready before proceeding.

5–6. cert-manager and CPD Licensing Service

Operator Hub installations with verification steps for pod readiness.

7–15. IBM Software Hub → watsonx Orchestrate

Installs the IBM Software Hub control plane, configures the NooBaa/MCG secrets, deploys the watsonx Orchestrate operator and instance, runs the prerequisite validation script, and performs a final end-to-end health check confirming all wo-* pods and Custom Resources are healthy.

⚠ Before you run the notebook

This notebook executes live oc commands against your cluster. Read every cell before running it. Disconnect the notebook from your environment after installation completes. The procedure is validated for non-GPU clusters with internet access using the OpenShift internal registry; GPU and air-gapped steps must be completed manually outside the notebook.

Supporting scripts

The notebook delegates some heavier logic to companion scripts in the BashScripts/ and PythonScripts/ folders:

  • wxo-pre-requisite-script.sh — validates cluster resources, storage classes, entitlement secrets, IAM integration, Knative Eventing, MCG, and OpenShift AI readiness, in both install and upgrade modes.
  • createVars.py / createOptions.py — interactive variable collection and operator configuration helpers.
  • hotfix540_0.sh / hotfix540_0.py — applies a known hotfix for the 5.4.0 release.
  • checkMCP.sh — polls MachineConfigPool status and blocks the notebook until all nodes are updated.

Getting Started — Deploy the Extras Image

All tools, including the notebook installer, are packaged inside a single container image and exposed via an OpenShift route. Deploying takes two minutes:

  1. Confirm you have cluster-admin privileges
    The image deploys resources cluster-wide. You must be logged in as a cluster administrator.
  2. Download the YAML manifest
    Download extras-wxo540-ocp418.yaml from the Library section of the IBM Community to your bastion node or local machine.

    Namespace conflict check

    The YAML creates a namespace named extras. If that namespace already exists in your cluster, edit the file and replace every occurrence of extras with a unique name before applying.
  3. Import the manifest into your cluster 
    oc apply -f extras-wxo540-ocp418.yaml

    Or using the OpenShift web console:
    • In the OpenShift web console, select the Quick create icon [+] > Import YAML.
    • On the Import YAML page, copy and paste the contents of YAML file.
    • Select Create.

    This creates the extras namespace, deploys the container, and creates an OpenShift Route.

  4. Open the route
    Retrieve the URL with: 
    oc get route -n extras
    Open the URL in your browser. The Extras landing page lists all available tools, including the notebook installer.
  5. Open the notebook and start the installation
    Select wxo540-ocp418-install from the landing page, open the Jupyter notebook, and follow the cells from top to bottom.

What Else Is in the Toolkit?

Beyond the notebook installer, Extras includes a collection of operational tools you'll reach for throughout the lifetime of your deployment:

Tool What it does
check_orchestrate_health POSIX shell script that auto-detects namespaces, checks all wo-* pods, and validates every key Custom Resource (WO, WA, IFM, DocumentProcessing, DigitalEmployees, UAB ADS) plus datastores (EDB Postgres, Kafka, Redis, WXD engines).
wxo-health-check Targeted health-check scripts for four subsystems: agent runtime, observability stack, Milvus vector store, and PostgreSQL / pgBouncer.
wxo-observability-diagnostics Comprehensive diagnostics for the CPD observability stack — Jaeger, OpenSearch, OpenTelemetry, WXO-server, and TRM — with pass/fail/warning counters.
log_analyzer Python CLI that searches log folders for an event string, correlates related entries by a key (e.g. transaction-id), produces a time-sorted journey, and ranks root causes across 20 failure signal patterns.
root_cause_solution_finder watsonx Orchestrate agent that takes an error keyword, searches IBM documentation across three sources, ranks results by relevance, and returns the top solutions with troubleshooting steps.
wxo_openshift_hotpatch_detector Python tool that diffs the live cluster state against the operator baseline to surface any undocumented container image changes, ConfigMap edits, env-var overrides, PVC mounts, or resource limit adjustments.
useful-commands Curated oc one-liners for common day-two operations: checking WA/WO status, listing failing pods, force-restarting unhealthy components.

Summary

If you are installing or operating IBM watsonx Orchestrate on OpenShift, the Extras toolkit can save you meaningful time at every stage — from the first prerequisite check through to production health monitoring. The guided notebook installer is the quickest path to a working deployment on a non-GPU cluster. The surrounding operational scripts give you persistent, reusable tools for the day-two experience.

To get started, download the extras-wxo540-ocp418.yaml file from the IBM Community Library, import it into your cluster, and open the route.

Disclaimer: These tools are experimental, community-contributed utilities and are not an official IBM product or part of any IBM product release. They are provided under the Apache License 2.0, without warranty of any kind. IBM Support does not cover these tools. Always review scripts before running them against production systems.

0 comments
32 views

Permalink

https://community.ibm.com/community/user/blogs/enrico-monteleone/2026/08/27/ibm-watsonx-orchestrate-extras