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:
| Layer | Current state | Target state | Validation source | Owner |
|---|---|---|---|---|
| OpenShift | Exact z-stream and topology | Approved supported release | IBM and Red Hat matrices | Platform |
| MAS Core | Installed channel and version | Exact 9.1.x release | IBM release information | MAS admin |
| Manage | Version, industry solutions, customizations | Exact 9.1.x release | IBM compatibility docs | Manage lead |
| Data | Db2 or Oracle, MongoDB, object/file storage | Supported versions and layout | Product prerequisites | DBA |
| Integrations | MIF, REST, JMS, Kafka, files | Tested endpoint inventory | Interface catalog | Integration lead |
| Clients | Mobile versions, browsers, report tooling | Supported client set | IBM documentation | Workplace tech |
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.
code blockBehavioral 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:
code blockKeep 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, improv
...
