MAS 9.1 Upgrade Playbook: A Practitioner's Guide to the Continuous Delivery Model

# MAS 9.1 Upgrade Playbook: A Practitioner's Guide to the Continuous Delivery Model

Upgrading to IBM Maximo Application Suite 9.1 is not a traditional Maximo 7.6.x patch. The containerized delivery model, suite-level licensing, and continuous delivery cadence demand a different operating discipline. This playbook distills the patterns that experienced MAS platform teams use to execute clean, low-risk upgrades, and it highlights the configuration drift that most often causes rollback events.

If you are planning an upgrade, treating MAS 9.1 as a Kubernetes application first and a Maximo deployment second will save you weeks of pain. The good news is that the platform also gives you better tools than ever before: declarative configuration, cluster-aware operators, and the ability to roll individual applications back independently. The bad news is that the same complexity that gives you those tools also gives you more ways to fail.

This article assumes you are coming from MAS 8.x or from a recent Maximo 7.6.1.x deployment. The mechanics differ in detail, but the discipline is the same: plan thoroughly, rehearse in lower environments, verify obsessively, and keep the rollback path warm.

Why MAS 9.1 Is Different From a Classic Maximo Patch

Maximo Asset Management 7.6.1.x deployments were largely self-contained: a WebSphere or WebLogic application server, a database, an integration layer, and a static file system. Operators and DBAs knew exactly where the binary lived, where the logs were written, and how to restart the application. Upgrades were installer-driven, with explicit screens and explicit confirmation steps.

MAS replaces that mental model with a Red Hat OpenShift Container Platform deployment. Every workload runs as a pod, configuration is stored as Kubernetes resources, and licensing is enforced at the suite level through AppPoints. The shift has five operational consequences:

1. Upgrades are operator-driven, not installer-driven. You upgrade by changing the CatalogSource and letting the Maximo operator reconcile. There is no `installed_images` directory to manage, and there is no installer GUI to step through.
2. Licensing is unified. AppPoints replace the old per-product licensing model. Concurrent and Authorized users are configured once in the Suite Administration console, and license consumption is monitored there.
3. Customizations live in customization archives. Maximo Archiving is not supported in MAS. Your custom Java classes and database scripts are packaged into a customization archive and applied through the Manage deployment.
4. System properties are UI-managed. The traditional `maximo.properties` file is replaced by the System Properties application in Maximo Manage. Bootstrap properties (database credentials, encryption keys) are set in the deployment custom resource. Bundle-level properties are stored as Kubernetes ConfigMaps.
5. Integration is API-first. Remote Method Invocation (RMI) is gone. Service Integration (SI) buses have been replaced by Apache Kafka or other supported JMS providers. REST APIs are the supported integration surface.

These are improvements, but they require the team to develop Kubernetes fluency alongside traditional Maximo knowledge. The teams that succeed in MAS are the ones that invest in cross-training their Maximo DBAs and developers in OpenShift fundamentals.

Pre-Upgrade Checklist: OpenShift, Database, and Identity

Before you schedule a single minute of downtime, walk through this checklist. Each item has caused a real upgrade to stall for one team or another. Treat the checklist as a gating gate: do not proceed to the upgrade window until every item is green.

OpenShift Platform Requirements

MAS 9.1 supports Red Hat OpenShift Container Platform 4.16 and later. OpenShift 4.20 support has been added across recent MAS versions, and the platform team should confirm both the OCP version and the storage configuration.

| Check | Command | Pass Condition |
|-------|---------|----------------|
| OCP version | `oc get clusterversion` | 4.16 or higher |
| Cluster operators healthy | `oc get co` | All AVAILABLE=True, DEGRADED=False |
| Storage class default | `oc get sc` | At least one default RWX-capable class |
| Node resources | `oc describe nodes` | Memory and CPU headroom for new pods |
| Cluster Insights | Optional | No critical security findings |
| Image registry | `oc get imagestreams` | Reachable from the cluster |
| Ingress | `oc get ingresses.config/cluster` | Functional with valid certificates |
| Pod security standards | `oc get ns -o yaml` | Restricted or Baseline profile |

OpenShift 4.20 support is the headline here. If you are on an older OCP release, plan the OCP upgrade as a separate, isolated change window. Mixing an OCP upgrade with a MAS upgrade is one of the most common root causes of failed deployments, because two large state changes happening at once make it nearly impossible to identify which change introduced a problem.

The storage class check is the second most common source of upgrade pain. MAS Manage requires a ReadWriteMany (RWX) capable storage class for the documents and attachments directory. If the default storage class is ReadWriteOnce (RWO), the operator will refuse to start the pod, and the error message is not always obvious. Validate the storage class before the upgrade window, not during it.

Database and External Services

MAS 9.1 allows Db2 and MongoDB to run as external services. If you are bringing your own database, the database requirements are more nuanced than the documentation suggests.

| Component | Supported Version | Notes |
|-----------|-------------------|-------|
| Db2 | 11.5.7 or later | Required for MAS 9.1 release line |
| MongoDB | 6.0 or later | External only; embedded MongoDB removed |
| Oracle | 19c | Supported with manual driver configuration |

Before the upgrade, confirm:

- The database is at a supported version. The operator will refuse to start if the database version is below the supported minimum.
- Backups completed successfully within 24 hours of the upgrade window. The upgrade performs DDL changes that the existing schema user must be authorized to execute. If the upgrade fails partway through, you will need a clean backup to roll back.
- The database user has CREATE, ALTER, and DROP privileges on the Maximo schema. Do not assume that the production user has all the required privileges; some organizations grant schema privileges on a per-feature basis.
- Replication is paused or in a known good state. If you are running database replication for disaster recovery, pause the replica during the upgrade so that the upgrade does not race with the replication stream.

Identity Provider Configuration

User authentication is now managed at the suite level. The choice of identity provider is one of the highest-leverage decisions in the upgrade, because getting it wrong creates user access issues that are difficult to diagnose after the fact.

The supported options are:

- Single LDAP registry synchronization for traditional environments. This is the most common configuration and is appropriate for organizations that have a single corporate directory.
- Multiple LDAP registries for mergers, acquisitions, and divested business units. MAS 9.1 added support for multiple LDAP user registry synchronizations, which lets you synchronize users and groups from more than one LDAP server to your local Maximo Application Suite user registry.
- SCIM 2.0 synchronization for cloud identity providers. SCIM is the right choice for organizations that use Okta, Azure AD, or similar platforms.
- OpenID Connect (OIDC) SSO for modern identity stacks. OIDC is appropriate for organizations that want to delegate authentication entirely to a third-party provider.

Whichever model you choose, test the synchronization in a non-production environment first. Misconfigured LDAP filters are the single most common cause of "missing users" after a MAS upgrade. The symptom is users that appear in the source directory but not in Maximo, and the root cause is almost always a filter that excludes the user records unintentionally.

Executing the Upgrade: A Step-by-Step Sequence

The MAS 9.1 upgrade follows a well-defined sequence. Skipping steps is the primary driver of post-upgrade incidents. The sequence below assumes a standard upgrade from MAS 8.x to MAS 9.1; the mechanics for a 7.6.x migration are different and are covered in a separate section.

1. Capture the Baseline

Before you touch anything, capture the current state. The community-recommended verification routine, originally published by Diego Visentin of Tempestive, looks like this:

code block

A clean upgrade is one where all three lines report consistent versions. If they do not, stop and reconcile before proceeding. Inconsistent versions are a sign that a previous upgrade did not complete cleanly, and stacking a new upgrade on top of a half-finished one is a recipe for a long outage.

Save the output of the verification routine to a file with a timestamp. After the upgrade, you will compare the new output to the saved baseline to confirm that the version transition happened as expected.

2. Update the CatalogSource and Operator

Change the CatalogSource to point to the MAS 9.1 channel, then let the operator reconcile. Watch the operator logs:

code block

Do not proceed to the next step until the operator reports the new version as available and the previous version as no longer recommended. The operator will reconcile the catalog automatically, and the reconciliation is what makes the new versions visible to the rest of the system.

If the operator logs show repeated reconciliation failures, the most common cause is a misconfigured CatalogSource. Validate the CatalogSource URL, the channel name, and the namespace before you escalate.

3. Apply the Workspace Upgrade

Trigger the workspace upgrade through the Suite Administration UI or by patching the ManageWorkspace custom resource. The operator will then:

- Pull the new images for the Manage, IoT, Monitor, Health, Predict, and any other installed applications.
- Run pre-upgrade hooks (database validation, customization archive staging).
- Roll the pods in a controlled sequence.

The rolling update is the longest part of the upgrade. For a large Manage deployment, expect 30 to 60 minutes of pod churn. During this time, the application is technically available, but performance may be inconsistent. Communicate this to the operations team so they do not mistake the rolling restart for an application problem.

4. Verify the Post-Upgrade State

After the operator reports success, run the same verification routine from step 1. The reconciled version on the ManageWorkspace and AppCfg should match the new release. If they do not, the upgrade is not complete even if the operator reports success.

code block

If any of these commands return the old version, the upgrade is not complete. Investigate the operator logs to find the cause before declaring the upgrade done.

5. Validate Application Health

Open the Suite Administration console, navigate to Health, and check that:

- The Suite Core and each installed application report the expected version.
- The AppPoint consumption dashboard shows a sensible baseline.
- The Foundation service (introduced in 9.1) is reachable.
- Each applica

...