MAS 9.1

Upgrading to MAS 9.1 Without Guesswork: A Production Runbook for Platform Teams

An IBM Maximo Application Suite upgrade is not a single software installation. It is a coordinated change across OpenShift, operators, Suite core services, databases, storage, identity, Manage, add-ons, integrations, and operational procedures. That distinction matters because a technically successful operator reconciliation can still leave the business with broken mobile synchronization, stale integration endpoints, inaccessible attachments, or unacceptable response times.

MAS 9.1 adds another reason to treat the work as a program rather than a maintenance window. IBM documents changes that include Java 17 for Maximo Manage, BIRT 4.16 support, additional infrastructure options, online-upgrade rollback behavior, externally built Manage images, and configuration changes for products such as Health and Collaborate. IBM's release information also shows a continuing stream of 9.1.x updates. As of June 25, 2026, that page lists MAS Core 9.1.19 and Manage 9.1.18. Those numbers are useful planning inputs, but the correct target must still be selected from IBM's current compatibility, lifecycle, and support documentation when the change is approved.

The safest approach is evidence-driven. Every phase should answer a specific question: Is the source environment understood? Is the target combination supported? Can the data be restored? Do critical business paths work? Can operations detect failure before users do? The result is a series of go or no-go gates, not a long checklist whose boxes can be marked without proving anything.

This runbook provides that structure. It does not replace IBM documentation or product-specific instructions. It shows how to turn those instructions into an executable production plan with owners, measurable acceptance criteria, and a rollback boundary that everyone understands before the first change begins.

1. Establish the Supported Target and the Real Upgrade Scope

Start by defining the target as a complete bill of materials, not simply “MAS 9.1.” Record the exact intended versions of OpenShift Container Platform, MAS Core, Manage, every deployed application, supported operators, database engines, MongoDB, storage classes, ingress components, identity provider integration, and relevant client software. Include external dependencies such as SMTP, object storage, GIS, ERP, document repositories, and enterprise integration middleware.

IBM's MAS 9.1 documentation identifies configuration-dependent upgrade paths. For example, either Manage or the foundation service is required when upgrading to 9.1. It also notes that a stand-alone Health deployment has a specific transition path because Health is no longer offered as a stand-alone Suite configuration in 9.1. Collaborate, formerly Assist, includes changes such as CouchDB replacement by MongoDB and centralized authorization. These are not release-note trivia. They can change sequencing, prerequisite capacity, backup scope, and acceptance testing.

Create a source-to-target matrix like this:

|---|---|---|---|---|

Then map upgrade scope to business capabilities. A Maximo Spatial deployment needs GIS validation. A Mobile estate needs app, device, authentication, offline, and synchronization testing. A Health deployment needs score, dashboard, meter, and work-queue validation. A heavily customized Manage environment needs image-build and regression evidence.

The gate is simple: do not schedule production until every installed component has a documented path to the selected target. “We do not use that feature” is acceptable only when the component is genuinely absent or disabled and the fact is verified. Unknown dependencies are work items, not assumptions.

2. Baseline the Environment Before Touching It

A rollback is credible only when the team knows what must be restored. Capture both configuration and behavior. Configuration evidence should include custom resources, operator subscriptions, namespaces, routes, secrets inventory, persistent volume claims, storage classes, certificates, identity configuration, network policies, resource quotas, Manage workspace settings, database configuration, cron tasks, integration endpoints, and custom image references. Protect secret values, but record where they are managed and how they will be recovered.

Use supported tools and your organization's security controls to collect a timestamped baseline. The following command pattern illustrates the type of evidence a platform team might retain. Namespaces and resource types must be adapted to the actual installation.

mkdir -p evidence/pre-upgrade
oc get clusterversion -o yaml > evidence/pre-upgrade/clusterversion.yaml
oc get subscriptions.operators.coreos.com -A -o yaml \
  > evidence/pre-upgrade/operator-subscriptions.yaml
oc get csv -A -o wide > evidence/pre-upgrade/csv.txt
oc get routes -A -o wide > evidence/pre-upgrade/routes.txt
oc get pvc -A -o wide > evidence/pre-upgrade/pvc.txt
oc get pods -A -o wide > evidence/pre-upgrade/pods.txt
oc get events -A --sort-by=.lastTimestamp \
  > evidence/pre-upgrade/events.txt

Behavioral baselines are equally important. Record response times for a small set of repeatable transactions: sign in, open Work Order Tracking, query a known record set, save a controlled work order, upload and retrieve an attachment, process a test inbound integration message, publish an outbound event, generate a representative BIRT report, and synchronize a controlled mobile account. Do not claim universal performance from a single measurement. Use the same scripts, data, user permissions, and network path before and after the upgrade so the comparison is meaningful.

Inventory customizations by deployment mechanism. Separate supported configuration, automation scripts, application XML or role-based app changes, reports, integration processing rules, Java extensions, and externally built images. Java 17 makes this especially important. A customization that compiled against an older runtime can fail at build time or behave differently at run time. Record the source repository, build pipeline, artifact digest, dependency versions, and test owner for each custom component.

Finally, freeze uncontrolled drift. Set a change cutoff for schema changes, new integrations, security-group redesigns, and mobile configuration changes. Emergency changes should be logged and ported into the rehearsal environment. The readiness gate requires a signed baseline, successful backups, demonstrated restore steps, and no unexplained unhealthy operators or workloads.

3. Rehearse the Upgrade as a Recoverable Data Change

The best rehearsal is a production-like clone using recent, sanitized data and the same topology classes, operators, storage behavior, and external-service patterns. A small development namespace can reveal syntax errors, but it cannot prove production duration, database migration behavior, storage throughput, or integration volume. Where a full clone is impossible, document each fidelity gap and compensate with targeted tests.

Treat backup and restore as one procedure. Confirm database-native backups for Manage, MongoDB protection for Suite services that require it, and protection for file or object-based attachments. Include encryption keys, certificates, and external configuration needed to make restored data usable. A snapshot that has never been restored is not proven recovery. Restore into an isolated environment, start the relevant services, and validate known records and attachments.

Build a timed rehearsal log. Record the start and finish of every stage: backup quiescence, operator updates, Core reconciliation, application updates, Manage administrative image build, bundle image build, database updates, pod stabilization, smoke tests, and integration replay. Distinguish elapsed time from hands-on time. The production window must include decision time and recovery time, not just the fastest successful execution.

A useful gate table is:

| Gate | Evidence | Failure response |

|---|---|---|

| Backup complete | Job IDs, checksums, restore test reference | Stop |

| Operators healthy | Expected CSVs succeeded, no blocking conditions | Diagnose within timebox |

| Core ready | Custom resource status and functional login | Stop or roll back per IBM guidance |

| Manage ready | Build complete, bundles healthy, schema stage complete | Apply documented failure control |

| Business smoke tests | Signed test results | Hold user release |

| Integrations stable | Queue depth and error sample acceptable | Pause producers or roll back |

MAS 9.1 documentation describes improved online-upgrade rollback behavior for Manage. If an online upgrade fails and rollback is configured for failureControl, the operator can stop servers, roll back the database, and restart bundles with the older image. That capability is valuable, but it must not be interpreted as a universal undo button. It does not automatically reverse every external transaction, client update, credential change, or adjacent application transition.

During rehearsal, force controlled failures where safe. Test a failed image build, unavailable endpoint, full integration queue, and a smoke-test rejection. The team should practice who calls the decision, which evidence is preserved, and where rollback becomes more dangerous than completing the forward fix.

4. Execute with Explicit Gates, Observability, and Change Control

Production execution should follow one authoritative runbook with command ownership and evidence locations. Avoid copying commands from chat messages. Store reviewed commands in version control or an approved change record, parameterize environment-specific values, and require a second person to validate destructive or state-changing operations. The incident lead should be separate from the engineer typing commands whenever staffing permits.

Before the window, confirm that monitoring covers cluster capacity, operator conditions, pod restarts, persistent storage, database health, route availability, certificate validity, build progress, JVM behavior, integration queues, and application response. Define thresholds that trigger investigation. A red dashboard after the change is not useful if nobody knows whether it represents a known transient condition or a rollback signal.

Sequence external traffic deliberately. Pause or drain inbound integrations according to the tested plan. Account for messages generated during the window and decide whether they will queue, retry, or require replay. Notify mobile users of the connectivity and client-version plan. Prevent schedulers and cron tasks from creating avoidable load during database or image transitions. Resume each producer only after its consumer path passes a focused test.

At each gate, capture status instead of relying on visual confidence. For example, verify expected custom-resource conditions, operator versions, pod readiness, routes, logs, and application-level transactions. Do not use Running as the only success criterion. A running pod can serve errors, fail downstream calls, or hold stale configuration.

Use a decision record with four fields:

Gate: Manage post-upgrade smoke test
Decision time: 01:40 CDT
Evidence: test set M91-PROD-SMOKE, monitoring snapshot 0140
Decision: GO / HOLD / ROLLBACK
Approvers: technical lead, business owner, change manager

Keep the rollback deadline visible. The deadline should be based on demonstrated recovery duration, data divergence, external transaction exposure, and the end of the approved outage, not optimism. If diagnosis consumes the allotted timebox, execute the predefined decision. Long, improvised troubleshooting often converts a recoverable outage into an extended one.

After technical readiness, release users in controlled cohorts if operations permit. Start with the support team and designated business testers, then broaden access. This exposes permission, personalization, reporting, and workload issues before the entire user population arrives at once.

5. Validate the Business System and Stabilize the New Baseline

Post-upgrade validation must prove business outcomes across layers. Begin with platform health, then Core authentication and navigation, then application functions, integrations, reporting, mobile, and specialized products. Use named test records so the service desk can distinguish planned activity from real production work.

For Manage, test at least one complete work-management flow: create or select a work order, apply status changes, plan labor or material, record actuals, complete the work, and verify related transactions. Exercise security with multiple user personas. Test attachments in both directions, representative reports using BIRT 4.16-compatible tooling, automation scripts, workflow assignments, escalations, and any custom Java or UI components. Verify API keys and certificates, especially if keys were recreated or expiry controls changed.

For integrations, validate more than HTTP status. Confirm field mapping, site and organization context, transaction identity, duplicate handling, error routing, and outbound acknowledgement. Compare queue depth and processing latency with the baseline. Reconcile messages held during the outage. A successful replay count should match the planned inventory, with exceptions individually explained.

Establish a stabilization period with tighter monitoring and a clear ownership roster. Track:

Operator and pod instability

Database locks, expensive statements, and connection pressure

JVM memory and restart patterns

Integration errors and queue growth

Attachment failures

Mobile synchronization errors

Report failures and abnormal runtimes

Service desk cases grouped by capability and user persona

Update the configuration baseline only after acceptance. Export the final version inventory, custom resources, routes, storage state, image digests, and test results. Record temporary workarounds with owners and expiration dates. Remove paused schedules and traffic controls carefully, verifying each restoration step.

Close the change with a factual review. Compare actual duration with rehearsal, list unexpected conditions, document which alerts were useful, and update the runbook. Also review IBM's current APAR and known-issue material for the exact installed maintenance levels. Because 9.1.x updates continue, the operational product is not merely “9.1.” It is a specific set of levels and configuration decisions that must remain visible to support teams.

Practical Implications

For most organizations, the largest improvement is organizational rather than technical: make each risk belong to one person and one piece of evidence. The platform team owns operator and cluster readiness. The DBA owns recoverable data. Application leads own critical transactions. Integration owners reconcile queued messages. Business testers decide whether the service is usable, not merely available.

A practical minimum package contains the version bill of materials, dependency map, customization inventory, backup and tested-restore evidence, timed rehearsal, production runbook, rollback decision tree, smoke-test pack, communication plan, and post-change baseline. Smaller teams can combine roles, but they should not omit the responsibilities.

Use current IBM documentation at approval time. IBM's “What's new in Maximo Application Suite 9.1,” “What's new in Maximo Manage 9.1,” and MAS release-information pages are good starting points. Cross-check them against prerequisites, compatibility details, application-specific upgrade instructions, APARs, and known issues for the selected releases.

Most importantly, budget for remediation after installation. Java 17, reporting changes, application transitions, client behavior, and custom-image pipelines can require work even when the core upgrade is supported. A project plan that ends when operators report Ready excludes the very validation that protects operations.

Bottom Line

A safe MAS 9.1 upgrade is a sequence of proven state transitions. Define the complete target, baseline the current environment, rehearse with production-like data, validate restoration, execute through explicit gates, and test the business system from end to end. Treat rollback as a bounded engineering procedure with known limits, not a promise that every change can be reversed automatically.

MAS 9.1 brings meaningful platform and application changes, while IBM continues to publish 9.1.x maintenance releases. That makes precision essential. Record exact versions, verify support at the time of change, and preserve the evidence that explains what was installed and why.

Teams that follow this model gain more than a successful weekend. They create a reusable operating discipline for subsequent updates: smaller unknowns, faster decisions, defensible recovery, and a production baseline that support engineers can trust.