How To
Summary
Apply this hotfix after completing the watsonx Orchestrate installation for Version 5.3.1, or after upgrading from a previous release to Version 5.3.1.
Objective
export PROJECT_CPD_INST_OPERATORS=<enter your IBM Software Hub operator project>
export PROJECT_CPD_INST_OPERANDS=<enter your IBM Software Hub operand project>Install skopeo: https://github.com/containers/skopeo/blob/main/install.md
export LOCAL_REGISTRY="your_local_registry"
export LOCAL_USER="your_local_registry_username"
export LOCAL_PASS="your_local_registry_password"
export IBM_ENTITLEMENT_KEY="your_ibm_entitlement_key"
export AUTH_JSON_PATH="${HOME}/.airgap/auth.json"
mkdir -p "$(dirname "${AUTH_JSON_PATH}")"
skopeo login cp.icr.io --username cp --password "${IBM_ENTITLEMENT_KEY}" --authfile "${AUTH_JSON_PATH}"
skopeo login "${LOCAL_REGISTRY}" --username "${LOCAL_USER}" --password "${LOCAL_PASS}" --authfile "${AUTH_JSON_PATH}"Copy operator images
# ibm-watsonx-orchestrate-operator (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://icr.io/cpopen/ibm-watsonx-orchestrate-operator@sha256:37eb8050e251894cba7b11757133e59f9a6cb96ca0c9b1e3d36f7aebfda7727e \
docker://$LOCAL_REGISTRY/cpopen/ibm-watsonx-orchestrate-operator@sha256:37eb8050e251894cba7b11757133e59f9a6cb96ca0c9b1e3d36f7aebfda7727e
# ibm-wxo-component-operator (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://icr.io/cpopen/ibm-wxo-component-operator@sha256:deb6fcc3ba617e0e8df1e09c8d73e47e74a696303cc63ee6862cdc5d33cb6c5d \
docker://$LOCAL_REGISTRY/cpopen/ibm-wxo-component-operator@sha256:deb6fcc3ba617e0e8df1e09c8d73e47e74a696303cc63ee6862cdc5d33cb6c5d
Copy operand images
# agent-analytics(chnaged)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/agent-analytics@sha256:c33fb77bc077dfa5e21da855f992e900e205191c9c19135d1c51060184286259 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/agent-analytics@sha256:c33fb77bc077dfa5e21da855f992e900e205191c9c19135d1c51060184286259
# ai-gateway
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/ai-gateway@sha256:93bda853a0c7d9ea764c739c3fdfc3b73ef55df21d2c4ed1ab1588172f5d7064 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/ai-gateway@sha256:93bda853a0c7d9ea764c739c3fdfc3b73ef55df21d2c4ed1ab1588172f5d7064
# channel-integrations
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/channel-integrations@sha256:5db27d33535eb84857888ce5e74c9ec8b7a594e203d5b2265ffb45a25081df9d \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/channel-integrations@sha256:5db27d33535eb84857888ce5e74c9ec8b7a594e203d5b2265ffb45a25081df9d
# data-exhaust-producer
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/data-exhaust-producer@sha256:924b0e206d6c3937c700710c457f19e5cc8b220e8b44541e19b5d453ae945316 \
docker://${LOCAL_REGISTRY}/cp/data-exhaust-producer@sha256:924b0e206d6c3937c700710c457f19e5cc8b220e8b44541e19b5d453ae945316
# platformuiproxy
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/platformuiproxy@sha256:a784ce03cf7094a8424d73505bfc4db1effb1d48e1a1348f61aa32c79a98ddfc \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/platformuiproxy@sha256:a784ce03cf7094a8424d73505bfc4db1effb1d48e1a1348f61aa32c79a98ddfc
# skill-server
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/skill-server@sha256:1c09616441bd87e0bd983900098e078efb188f7c2122df615dbc4d0e00c26418 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/skill-server@sha256:1c09616441bd87e0bd983900098e078efb188f7c2122df615dbc4d0e00c26418
# socket-handler
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/socket-handler@sha256:a6097d3383d3737563b782e25bb7486d4019d88f7a3d82020f49bbe3c407f7b6 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/socket-handler@sha256:a6097d3383d3737563b782e25bb7486d4019d88f7a3d82020f49bbe3c407f7b6
# tools-runtime (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/tools-runtime@sha256:73d537c466e52f0207dec2f353b42ec2c47fa1562fd5e1d1a0674b11511d937c \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/tools-runtime@sha256:73d537c466e52f0207dec2f353b42ec2c47fa1562fd5e1d1a0674b11511d937c
# tools-runtime-manager (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/tools-runtime-manager@sha256:2ebed56581235ea0cf5e67170affc083acde4906012800c73b858cf5f7b67135 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/tools-runtime-manager@sha256:2ebed56581235ea0cf5e67170affc083acde4906012800c73b858cf5f7b67135
# tools-runtime-scheduler (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/tools-runtime-scheduler@sha256:56761b91d664dceab293a7c533382bdf7062b318aec08a8d45adb1436ba5b2c6 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/tools-runtime-scheduler@sha256:56761b91d664dceab293a7c533382bdf7062b318aec08a8d45adb1436ba5b2c6
# wo-ootb-primitive-skills
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wo-ootb-primitive-skills@sha256:faabf8d9626ced20e9d7df15924e0fa5668708ffff828fe104db056a449ab435 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wo-ootb-primitive-skills@sha256:faabf8d9626ced20e9d7df15924e0fa5668708ffff828fe104db056a449ab435
# wxo-builder (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-builder@sha256:e82d782102ffc1ec09c797c2a70ca9f008ed972fe2ce0bd4d5f9f57c89cff0a6 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-builder@sha256:e82d782102ffc1ec09c797c2a70ca9f008ed972fe2ce0bd4d5f9f57c89cff0a6
# wxo-chat
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-chat@sha256:7a31b346c68fbe93c6e5d0c871799ac32922aa54f90ba64a4c78de7ad4c7913a \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-chat@sha256:7a31b346c68fbe93c6e5d0c871799ac32922aa54f90ba64a4c78de7ad4c7913a
# wxo-connections
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-connections@sha256:f2bc260c3df0047a934de7a5824a7084c56d9606614d7a0e7884a6520edaea32 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-connections@sha256:f2bc260c3df0047a934de7a5824a7084c56d9606614d7a0e7884a6520edaea32
# wxo-flow-runtime
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-flow-runtime@sha256:3f00fe511a696d430f1b839adf1be520adae43b36bf844923b13eafc858e27a1 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-flow-runtime@sha256:3f00fe511a696d430f1b839adf1be520adae43b36bf844923b13eafc858e27a1
# wxo-server-conversation_controller (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-server-conversation_controller@sha256:be6e9cf0dfe8931e41b26fd0de5f565323984750665031a4c7fdd84e8f4c1e23 \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-server-conversation_controller@sha256:be6e9cf0dfe8931e41b26fd0de5f565323984750665031a4c7fdd84e8f4c1e23
# wxo-server-server (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-server-server@sha256:3973886a0acbaa14d8bf8d9796b7ac957be024500cdd8fd088977f8aa73461ea \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-server-server@sha256:3973886a0acbaa14d8bf8d9796b7ac957be024500cdd8fd088977f8aa73461ea
# wxo-server-voice (changed)
skopeo copy --all --authfile "${AUTH_JSON_PATH}" --dest-tls-verify=false --src-tls-verify=false \
docker://cp.icr.io/cp/watsonx-orchestrate/wxo-server-voice@sha256:31c238d890fb9e15f96cfe821a0dba515d7e5be1b869ec216ebd33d0456d568e \
docker://${LOCAL_REGISTRY}/cp/watsonx-orchestrate/wxo-server-voice@sha256:31c238d890fb9e15f96cfe821a0dba515d7e5be1b869ec216ebd33d0456d568eAfter copying, verify the images exist in $LOCAL_REGISTRY.
Create hotfix5311.sh with the contents below.
#!/bin/bash
# -----------------------------------------------------------------------------
# watsonx Orchestrate 5.3.1 Hotfix
# - Verifies watsonx Orchestrate version from .status.versionStatus.status.
# - Images of Operators are replaced with the image from hotfix script.
# * HOTFIX_LABEL_VALUE for hotfix 0 is 5.3.1.0
# * If an existing label value matches x.x.x.x and is higher than HOTFIX_LABEL_VALUE,
# the script exits early after informing you
# - Deletes a fixed set of Jobs in the operands namespace and waits for all to reappear with
# new UIDs and succeed
# -----------------------------------------------------------------------------
# -----------------------------
# Helpers
# -----------------------------
ts() { date +"%Y-%m-%d %H:%M:%S"; }
require() {
command -v "$1" >/dev/null 2>&1 || { echo "[$(ts)] Missing required command: $1"; exit 1; }
}
get_wo_version() {
ns="$1"
oc get wo -n "$ns" -o jsonpath='{.items[0].status.versionStatus.status}' 2>/dev/null || true
}
get_wo_cr_version() {
ns="$1"
oc get wo -n "$ns" -o jsonpath='{.items[0].spec.version}' 2>/dev/null || true
}
# -----------------------------
# Patch operator deployment images
# -----------------------------
OPERATOR_IMAGES="icr.io/cpopen/ibm-watsonx-orchestrate-operator@sha256:37eb8050e251894cba7b11757133e59f9a6cb96ca0c9b1e3d36f7aebfda7727e
icr.io/cpopen/ibm-wxo-component-operator@sha256:deb6fcc3ba617e0e8df1e09c8d73e47e74a696303cc63ee6862cdc5d33cb6c5d"
if [ -z "${PROJECT_CPD_INST_OPERATORS:-}" ]; then
echo "[ERROR] PROJECT_CPD_INST_OPERATORS is not set. Exiting."
exit 1
fi
# Required WO version
REQUIRED_WO_VERSION="${REQUIRED_WO_VERSION:-5.3.1}"
REQUIRED_WO_CR_VERSION="${REQUIRED_WO_CR_VERSION:-7.1.0}"
# -----------------------------
# Validations and version check
# -----------------------------
require oc
# Make sure oc login is done
if ! oc whoami &>/dev/null; then
echo "[$(ts)] Error: Not logged in to OpenShift"
exit 1
fi
echo "[$(ts)] Checking wo.status.versionStatus.status in ${PROJECT_CPD_INST_OPERANDS}"
WO_VER="$(get_wo_version "$PROJECT_CPD_INST_OPERANDS")"
WO_CR_VER="$(get_wo_cr_version "$PROJECT_CPD_INST_OPERANDS")"
# Check if versions match required versions
if [ "$WO_VER" != "$REQUIRED_WO_VERSION" ] || [ "$WO_CR_VER" != "$REQUIRED_WO_CR_VERSION" ]; then
echo "[$(ts)] Error: Version mismatch!"
echo "[$(ts)] WO Version: $WO_VER (required: $REQUIRED_WO_VERSION)"
echo "[$(ts)] WO CR Version: $WO_CR_VER (required: $REQUIRED_WO_CR_VERSION)"
exit 1
else
echo "[$(ts)] Version check passed: $WO_VER , CR version: $WO_CR_VER"
fi
# Hotfix label configuration
HOTFIX_LABEL_KEY="${HOTFIX_LABEL_KEY:-hotfix}"
HOTFIX_LABEL_VALUE="${HOTFIX_LABEL_VALUE:-5.3.1.1}"
WO_CR_NAME=wo
is_semver4() {
v="$1"
printf '%s' "$v" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$'
}
# Backup dir for deployments
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CLUSTER_NAME="$(oc whoami --show-console | sed 's/.*console-openshift-console\.apps\.\([^.]*\)\..*/\1/')"
BACKUP_DIR="${SCRIPT_DIR}/wxo_deployment_backups/$CLUSTER_NAME"
mkdir -p "$BACKUP_DIR"
if [ -n "${OPERATOR_IMAGES:-}" ]; then
echo "[$(ts)] Updating operator deployment images in ${PROJECT_CPD_INST_OPERATORS}"
patched_deps=""
# Use a here-document to avoid subshell so patched_deps is preserved
while IFS= read -r img; do
[ -z "$img" ] && continue
# Extract base image name (e.g., ibm-wxo-component-operator)
base="$(basename "$img" | cut -d'@' -f1)"
echo "[$(ts)] Processing image: $img (base=$base)"
dep=""
case "$base" in
ibm-watsonx-orchestrate-operator)
dep="wo-operator"
;;
ibm-wxo-component-operator)
dep="ibm-wxo-componentcontroller-manager"
;;
*)
dep="$(oc -n "$PROJECT_CPD_INST_OPERATORS" get deploy --no-headers 2>/dev/null \
| grep "$base" | awk 'NR==1{print $1}')"
;;
esac
# Skip bundle/catalog images if they ever slip in
if echo "$base" | grep -Eq 'bundle|catalog'; then
echo "[$(ts)] Skipping $base (bundle/catalog image – not tied to deployment)"
continue
fi
if [ -z "$dep" ]; then
echo "[$(ts)] WARNING: no matching deployment found for $base — skipping"
continue
fi
# -----------------------------
# Backup deployment YAML
# -----------------------------
backup_file="${BACKUP_DIR}/${dep}-$(date +%Y%m%d%H%M%S).yaml"
if oc -n "$PROJECT_CPD_INST_OPERATORS" get deploy "$dep" -o yaml > "$backup_file" 2>/dev/null; then
echo "[$(ts)] Backed up deployment/$dep → $backup_file"
else
echo "[$(ts)] WARNING: failed to back up deployment/$dep"
fi
# Determine container name (assume first container is operator)
cname="$(oc -n "$PROJECT_CPD_INST_OPERATORS" get deploy "$dep" \
-o jsonpath='{.spec.template.spec.containers[0].name}' 2>/dev/null)"
if [ -z "$cname" ]; then
echo "[$(ts)] WARNING: cannot determine container name for $dep — skipping"
continue
fi
echo "[$(ts)] Patching deployment/$dep container '$cname' → $img"
if oc -n "$PROJECT_CPD_INST_OPERATORS" set image "deployment/$dep" "$cname=$img" >/dev/null 2>&1; then
echo "[$(ts)] ✓ Image updated for $dep"
patched_deps="$patched_deps $dep"
else
echo "[$(ts)] ✗ ERROR: failed to patch $dep"
fi
done <<EOF
$OPERATOR_IMAGES
EOF
# -----------------------------
# Label WO CR with configurable label and value
# -----------------------------
if [ -n "$WO_CR_NAME" ]; then
current_label="$(oc -n "$PROJECT_CPD_INST_OPERANDS" get wo "$WO_CR_NAME" -o jsonpath="{.metadata.labels.${HOTFIX_LABEL_KEY}}" 2>/dev/null || true)"
if [ "$current_label" = "$HOTFIX_LABEL_VALUE" ]; then
echo "[$(ts)] WO CR ${WO_CR_NAME} already labeled ${HOTFIX_LABEL_KEY}=${HOTFIX_LABEL_VALUE}"
else
echo "[$(ts)] Setting label ${HOTFIX_LABEL_KEY}=${HOTFIX_LABEL_VALUE} on WO CR ${WO_CR_NAME} in ns ${PROJECT_CPD_INST_OPERANDS}"
oc -n "$PROJECT_CPD_INST_OPERANDS" label wo "$WO_CR_NAME" "${HOTFIX_LABEL_KEY}=${HOTFIX_LABEL_VALUE}" --overwrite >/dev/null 2>&1 || true
new_label="$(oc -n "$PROJECT_CPD_INST_OPERANDS" get wo "$WO_CR_NAME" -o jsonpath="{.metadata.labels.${HOTFIX_LABEL_KEY}}" 2>/dev/null || true)"
if [ "$new_label" = "$HOTFIX_LABEL_VALUE" ]; then
echo "[$(ts)] Label set: ${HOTFIX_LABEL_KEY}=${HOTFIX_LABEL_VALUE}"
else
echo "[$(ts)] WARNING: could not confirm ${HOTFIX_LABEL_KEY}=${HOTFIX_LABEL_VALUE} label was set"
fi
fi
else
echo "[$(ts)] No WO CR found in ns ${PROJECT_CPD_INST_OPERANDS}, skipping label."
fi
# -----------------------------
# Verify patched deployments are healthy (1/1 or 2/2)
# -----------------------------
if [ -n "${patched_deps// /}" ]; then
echo "[$(ts)] Verifying rollout status for patched deployments..."
for dep in $patched_deps; do
echo "[$(ts)] Checking deployment/$dep..."
# Wait for rollout to complete
if oc -n "$PROJECT_CPD_INST_OPERATORS" rollout status deploy/"$dep" --timeout=300s; then
# Check Ready/Desired replica ratio
ratio="$(oc -n "$PROJECT_CPD_INST_OPERATORS" get deploy "$dep" \
-o jsonpath='{.status.readyReplicas}/{.status.replicas}' 2>/dev/null || echo '0/0')"
echo "[$(ts)] Ready/Desired: $ratio"
if [ "$ratio" = "1/1" ] || [ "$ratio" = "2/2" ]; then
echo "[$(ts)] ✓ Deployment $dep is healthy (pods up and running)."
else
echo "[$(ts)] ⚠ WARNING: Deployment $dep is not at 1/1 or 2/2; current $ratio"
fi
else
echo "[$(ts)] ✗ ERROR: rollout status for deployment/$dep did not complete successfully."
fi
done
else
echo "[$(ts)] No deployments were patched; skipping health verification."
fi
else
echo "[$(ts)] No OPERATOR_IMAGES specified — skipping operator image patch."
fi
# Let's delete the redis cronjob and and allow the operator to create a new equivalent one.
oc delete cronjob wo-watson-orchestrate-redis-cronjob --ignore-not-found
# -----------------------------
# Final message
# -----------------------------
echo "------------------------------------------------------------------"
echo "[$(ts)] 5.3.1 Hotfix steps completed."
echo "Backups saved under ${BACKUP_DIR}"
echo "Monitor the watsonx Orchestrate CR status by running:"
echo " oc get wo -n ${PROJECT_CPD_INST_OPERANDS} -o yaml | grep -E 'watsonxOrchestrateStatus|${HOTFIX_LABEL_KEY}'"
echo "Ensure the watsonx Orchestrate CR status is 'Completed' and label ${HOTFIX_LABEL_KEY}=${HOTFIX_LABEL_VALUE} is present."
echo "It will take another 15–20 minutes for the updated components to be applied and restarted."
echo "------------------------------------------------------------------"
Make the script executable:
chmod 775 hotfix5311.shRun the script:
nohup sh hotfix5311.sh &Watch progress:
tail -f nohup.outVerify CR status and label:
oc get wo -n "${PROJECT_CPD_INST_OPERANDS}" -o yaml | grep hotfix
hotfix: 5.3.1.1Document Location
Worldwide
[{"Type":"MASTER","Line of Business":{"code":"LOB76","label":"Data Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSVAUS","label":"IBM watsonx Orchestrate Cartridge for IBM Cloud Pak for Data"},"ARM Category":[{"code":"a8mKe0000008OVAIA2","label":"Operate-\u003EInstall"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":""}]
Was this topic helpful?
Document Information
Modified date:
01 April 2026
UID
ibm17268050