Maximo Manage 9.2: The ManageWorkspace Custom Resource, Attachment Storage, and Build Configuration Deep Dive

Maximo Manage in MAS 9.2 is not the Maximo 7.6.x that most administrators grew up with. The shift to the Application Suite architecture changed how the application is deployed, configured, and operated. At the center of that change is the ManageWorkspace custom resource, a Kubernetes-native configuration object that defines how a Maximo Manage instance runs inside an OpenShift cluster. Every aspect of the Manage runtime, from database configuration to attachment storage to build behavior, is controlled through this custom resource.

This deep dive is for the administrators and DevOps engineers who have to configure and operate Manage 9.2 in production. We will cover the ManageWorkspace custom resource in detail, including the attachment configuration types that were introduced in the feature channel and promoted to production in 9.2, the build-config pod template enhancements that give you control over resource allocation, the BIRT 4.16 reporting integration, the new CSV export capability via REST APIs, the Operational Dashboard configuration model, the practical split between suite-level and Manage-level administration that continues to catch teams off guard, and the field-tested patterns that separate smooth operations from constant firefighting. This is practitioner-level content, not a feature overview.

The ManageWorkspace Custom Resource: Architecture and Configuration

The ManageWorkspace custom resource is the single source of truth for a Maximo Manage deployment. It is a Kubernetes custom resource definition (CRD) that the Maximo Manage operator watches and reconciles. When you create or update a ManageWorkspace, the operator translates the specification into Kubernetes resources: pods, services, routes, config maps, secrets, and database connections. The operator handles the deployment lifecycle, including build, configure, and runtime phases. Understanding the ManageWorkspace is not optional for MAS administrators. It is the primary mechanism through which all Manage configuration flows.

The ManageWorkspace specification includes several key sections that control different aspects of the deployment. The spec.fqdn field defines the fully qualified domain name for the Manage instance, which determines the URL that users access. The spec.license section specifies the license type (Full, Limited, or IoT), which controls which features are available. The spec.versions section pins the application and image versions, ensuring that the operator deploys the correct version of Manage. The spec.database section configures the Db2 connection, including database name, host, port, and credentials. The spec.attachments section, which was expanded in 9.2, defines how file attachments are stored. The spec.podTemplates section, also expanded in 9.2, configures resource limits and node selectors for the build, configure, and runtime pods.

A typical ManageWorkspace for a production environment looks like this:

apiVersion: maximo.ibm.com/v1
kind: ManageWorkspace
metadata:
  name: manage-prod
  namespace: mas-manage
spec:
  fqdn: manage.mas.example.com
  license:
    type: Full
  versions:
    application: 9.2.0
  database:
    type: db2
    name: MXPROD
    host: db2u-cluster.mas-db2.svc.cluster.local
    port: 50000
    credentials:
      secretName: manage-db-secret
  attachments:
    type: object
    storage:
      bucket: mas-manage-attachments
      endpoint: s3.us-east.cloud-object-storage.appdomain.cloud
      credentialsSecret: s3-attachment-secret
  podTemplates:
    build-config:
      resources:
        requests:
          cpu: "2"
          memory: "4Gi"
          ephemeral-storage: "10Gi"
        limits:
          cpu: "4"
          memory: "8Gi"
      nodeSelector:
        node-role.kubernetes.io/worker: ""

This YAML is not a complete example, but it shows the structure that most production deployments follow. The attachments section with type: object is one of the new capabilities in 9.2. The podTemplates.build-config section with resources and nodeSelector is another. Both deserve closer examination because they represent configuration decisions that have long-term operational impact.

The operator reconciliation loop is the mechanism that keeps the Manage deployment in sync with the ManageWorkspace specification. When you update the specification, the operator detects the change and begins a reconciliation cycle. For changes that require a rebuild (such as version changes or build-config modifications), the operator triggers a new build. For changes that require a restart (such as database configuration changes), the operator restarts the application pods. For changes that are purely configuration (such as attachment storage settings), the operator may apply the changes without a restart. Understanding which changes trigger which actions is critical for planning maintenance windows and minimizing downtime.

Attachment Storage: File-Based vs Object-Based

One of the most significant configuration decisions in Manage 9.2 is the attachment storage type. Prior to the feature channel update that introduced this capability, Manage stored attachments in the file system of the application server. This is the "file-based" storage type, and it remains the default for backward compatibility. The new "object-based" storage type uses an S3-compatible object store, which can be IBM Cloud Object Storage, AWS S3, MinIO, or any S3-compatible provider. This is not a minor configuration toggle. It is a fundamental architectural decision that affects storage capacity, backup strategy, multi-pod deployment, and cost.

The file-based approach has limitations that become apparent at scale. Attachments are stored on the pod's persistent volume, which means storage capacity is tied to the persistent volume claim size. Adding storage requires resizing the PVC, which may or may not be supported depending on the storage class. Backups must include the attachment volume, and recovery requires restoring both the database and the file system. In a multi-pod deployment, file-based attachments require a shared persistent volume (ReadWriteMany), which not all storage classes support. NFS is the most common RWX storage class, but it introduces its own performance and reliability concerns.

The object-based approach addresses these limitations comprehensively. Attachments are stored in an S3 bucket, which is effectively unlimited in capacity. Backups are handled through S3 lifecycle policies and cross-region replication, which are native S3 features that do not require additional backup tooling. Multi-pod deployments do not require shared storage, since all pods access the same S3 endpoint independently. And the storage cost is typically lower than block storage, especially for large files that are accessed infrequently.

The configuration for object-based storage is straightforward. The attachments.type field is set to object, and the storage section specifies the bucket name, endpoint, and credentials secret. The credentials secret must contain the access key and secret key for the S3 provider. Once configured, Manage routes all attachment uploads and downloads through the S3 API, transparently to the end user. No application code changes are required.

The transition from file-based to object-based storage is not automatic. If you are upgrading from a previous version with file-based attachments, the existing attachments remain on the file system. New attachments go to the object store. You can migrate existing attachments using the attachment migration tool that IBM provides, but this is a separate process that must be planned and executed independently of the upgrade. The migration tool reads attachments from the file system and uploads them to the S3 bucket, updating the database references along the way. For environments with thousands of attachments, this migration can take several hours and should be done during a maintenance window.

Build Configuration: Pod Templates, Resources, and Node Selectors

The Maximo Manage build process is one of the most resource-intensive operations in the MAS lifecycle. When you install or upgrade Manage, the operator triggers a build that compiles the Maximo EAR, runs database configuration scripts, and packages the deployment. This build runs in a pod called the build-config pod, and in 9.2, you now have control over the resources and scheduling of that pod through the ManageWorkspace specification.

The podTemplates.build-config section allows you to define resource requests and limits for CPU, memory, and ephemeral storage. This is critical for two reasons. First, the build process can consume significant resources, and without limits, it can starve other workloads on the same node. Second, without adequate resources, the build can fail with out-of-memory errors or disk space exhaustion, leaving the deployment in a failed state that requires manual intervention and potentially a rollback.

The recommended resource allocation for the build-config pod depends on the size of your Maximo environment. For a typical production environment with a few hundred thousand work orders and a moderate number of customizations, the following resource configuration is a reasonable starting point:

podTemplates:
  build-config:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
        ephemeral-storage: "10Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
        ephemeral-storage: "20Gi"
    nodeSelector:
      node-role.kubernetes.io/worker: ""

The nodeSelector field allows you to target specific nodes for the build. This is useful if you have nodes with more CPU or memory that you want to reserve for build operations, or if you want to keep the build off nodes that are running production application pods. The build is a transient operation, but it can take 30 to 90 minutes for a large environment, and during that time, it will consume the resources you allocate. Teams that run builds on shared nodes without resource limits frequently report interference with production workloads, especially during upgrade windows.

The ephemeral storage allocation is particularly important and frequently underestimated. The build process writes temporary files, compiled classes, and packaged artifacts to the pod's ephemeral storage. If the ephemeral storage fills up, the build fails with a disk pressure error. The 10Gi request and 20Gi limit in the example above are appropriate for a medium-sized environment. Large environments with extensive customization, multiple integration extensions, and large Maximo EAR files may require 30Gi or more of ephemeral storage. Monitor the build pod's storage usage during the first build to calibrate the allocation for your specific environment.

BIRT 4.16 and the Reporting Stack

Maximo Manage 9.2 supports BIRT 4.16 for reporting. This is a significant version jump from the BIRT 4.9 that was supported in earlier MAS releases, and it brings several improvements that report developers should be aware of. The upgrade is handled automatically during the Manage build process, but the implications for custom reports require attention.

BIRT 4.16 includes updated charting libraries, improved PDF rendering, better handling of large datasets, and compatibility with JDK 17. The JDK 17 compatibility is particularly important, since MAS 9.2 runs on JDK 17, and the previous BIRT version had known issues with certain chart rendering operations under JDK 17. Specifically, reports that used complex cross-tab charts or custom JavaScript expressions in chart data sets could produce rendering errors or blank charts under JDK 17 with BIRT 4.9. These issues are resolved in 4.16.

The migration from BIRT 4.9 to 4.16 is handled as part of the Manage upgrade. The build process replaces the BIRT runtime libraries, and existing report designs (.rptdesign files) are compatible with the new version. However, IBM recommends testing all custom reports in a non-production environment after the upgrade, since the updated charting libraries can produce slightly different visual output. Font rendering, color gradients, and chart label positioning may shift marginally. For organizations with heavily branded reports (company logos, specific color schemes, precise formatting), a visual review of the top 20 most-used reports after upgrade is a worthwhile investment.

For organizations with extensive custom BIRT reports, the upgrade to BIRT 4.16 is an opportunity to review and optimize report performance. The new version includes improved streaming for large datasets, which can reduce memory consumption for reports that query large tables. Report developers can also take advantage of new chart types and formatting options that were not available in 4.9, including improved waterfall charts, enhanced bubble chart labeling, and better control over axis scaling.

The reporting configuration in Manage 9.2 is controlled through the mxe.report.birt.enabled system property and the report library path in the ManageWorkspace specification. The default configuration enables BIRT and points to the bundled BIRT runtime. Custom report libraries can be deployed through the Manage administration interface or through the integration framework. The report library path should be verified after upgrade, since the build process can reset library paths to defaults if the ManageWorkspace specification does not explicitly define them.

CSV Export via REST APIs: The Asynchronous Export Pipeline

A quietly significant addition in Manage 9.2 is the ability to export flat files (CSV) from role-based applications using REST APIs. This capability, which leverages the Graphite technology that underpins the new role-based application framework, provides an asynchronous export pipeline that writes CSV content to an S3 bucket or to the Maximo integration framework global directory.

The export process works as follows. When a user initiates a CSV export from a role-based application, the system creates an export job that runs asynchronously. The job reads the contents of the user interface table page by page, writes each page to a temporary CSV file, and uploads the file to the configured destination. This approach avoids the timeout and memory issues that plagued the synchronous export functionality in earlier versions of Maximo, where large exports could freeze the browser or exhaust server memory.

The destination is configured in the ManageWorkspace specification. If object-based attachment storage is enabled, the export files can be written to the same S3 bucket or to a separate bucket dedicated to exports. If object-based storage is not enabled, the files are written to the Maximo integration framework global directory on the application server's file system. The S3 destination is strongly recommended for production environments, since it provides better scalability and does not consume application server storage.

For administrators, this capability means that large data exports no longer require custom automation scripts or external reporting tools. Users can export work order lists, asset records, or any role-based application table directly to CSV through the UI, and the asynchronous pipeline handles the data volume without impacting application performance. The export job status is visible in the UI, and users receive a notification when the export is complete.

The Admin Layer: Suite-Level vs Manage-Level Administration

One of the most persistent sources of confusion in MAS 9.x is the split between suite-level administration and Manage-level administration. The suite-level admin tools are in the MAS Core application, and they handle user management, OAuth configuration, SMTP settings, and suite-wide security. The Manage-level admin tools are the traditional Maximo administration applications that have existed for years: Database Configuration, Application Designer, Security Groups, Domains, Workflow Designer, and Cron Tasks. New MAS administrators consistently look for configuration in the wrong place, and the confusion is understandable because the boundary is not always intuitive.

The Manage-level admin layer in 9.2 retains the core configuration tools that Maximo practitioners know. Database Configuration continues to be where you define objects, attributes, and relationships. Application Designer continues to be where you modify application UIs. Security Groups continues to be where you define permissions and access controls. These tools are functionally the same as they were in 7.6.x, with incremental enhancements but no fundamental changes. The muscle memory that experienced Maximo administrators have built over years still applies.

The new admin responsibilities in 9.2 are primarily at the suite level. The Operational Dashboard configuration is a new admin responsibility that lives in the MAS Core admin interface. Administrators create dashboard templates, assign them to security groups, and configure the data sources (SQL queries or REST API calls) that feed the dashboard widgets. This is not done in the traditional Maximo admin tools, and administrators who are new to MAS often look for it in Application Designer or the System Properties application. The dashboard configuration surface is separate, and it requires a different set of skills than traditional Maximo administration.

The in-MAS Application Configuration tool is another new admin surface. It allows administrators to configure application-level settings such as UI themes, navigation, default values, and field labels without using Application Designer. This is a significant change from the 7.6.x model, where every UI modification required Application Designer and an understanding of the application XML structure. The Application Configuration tool is designed for lightweight changes that do not require structural modifications to the application. For deeper customizations, Application Designer remains the tool of choice.

The practical guidance for administrators new to MAS 9.2 is to learn the boundary between suite-level and Manage-level administration before making changes. User management is at the suite level. Security groups are at the Manage level. OAuth and SSO are at the suite level. Application permissions are at the Manage level. SMTP is at the suite level. Cron tasks are at the Manage level. Dashboard templates are at the suite level. Workflow design is at the Manage level. Knowing where each configuration lives will save you hours of searching and prevent misconfigurations that can be difficult to trace.

Common Pitfalls and Field-Tested Patterns

After working with MAS 9.x through multiple upgrade cycles, several patterns have emerged that can help administrators avoid common pitfalls. These are not theoretical risks. Each one has been observed in production environments and has caused measurable downtime or user impact.

The first pitfall is underestimating the build resource requirements. Teams that allocate minimal resources to the build-config pod consistently report build failures, especially during upgrades. The build is a resource-intensive operation that compiles the entire Maximo EAR and runs database scripts. Allocate generously, and use the nodeSelector to target capable nodes. A build failure during an upgrade window can extend downtime by hours, since the operator may need to roll back the database and restart the build from scratch.

The second pitfall is ignoring the attachment storage decision. Teams that default to file-based storage because it is the default often run into capacity issues six to twelve months later. Object-based storage is almost always the better choice for production environments, and planning for it early saves a migration later. The migration tool exists, but it is an additional operational task that could have been avoided with a better initial configuration.

The third pitfall is conflating suite-level and Manage-level administration. New MAS administrators often try to manage users through Security Groups (Manage-level) when user management is actually in the MAS Core admin interface (suite-level). Understanding this split early prevents a lot of frustration and misconfiguration. A related pitfall is assuming that the Operational Dashboard configuration is in the traditional Maximo admin tools. It is not. It is in the MAS Core admin interface, and finding it for the first time requires navigating away from the familiar Maximo applications.

The fourth pitfall is neglecting the Operational Dashboard configuration. The dashboards are powerful, but they require explicit configuration. Data sources must be defined, widgets must be assigned to dashboard templates, and templates must be assigned to security groups. Teams that skip this configuration step end up with empty dashboards that no one uses, and the business value of the operational dashboard is never realized.

The fifth pitfall is not testing BIRT reports after upgrade. The BIRT 4.16 upgrade is handled automatically, but custom reports can have visual or behavioral differences. A simple smoke test of the top 10 most-used reports after upgrade catches issues before end users find them. The testing should include verifying that charts render correctly, that PDF output is properly formatted, and that scheduled report distribution still works.

The sixth pitfall is overlooking the CSV export configuration. The asynchronous export pipeline is a valuable capability, but it requires a destination configuration. Teams that enable the export without configuring an S3 destination find that exports fail silently or fill up the application server's file system. Configure the S3 destination as part of the initial ManageWorkspace setup, not after users discover the export button.

Practical Implications

The ManageWorkspace custom resource is the single most important configuration object in Maximo Manage 9.2. Understanding its structure, its sections, and its operational impact is essential for any administrator. The attachment storage decision is effectively permanent for the life of the deployment: changing it after go-live requires a migration that touches every attachment record. The build resource allocation determines whether your upgrades succeed or fail, and underestimating it is the most common cause of failed upgrade windows. The BIRT 4.16 upgrade is automatic but requires report testing to catch visual regressions. The CSV export pipeline is a valuable tool but requires destination configuration to work properly. And the split between suite-level and Manage-level administration is a learning curve that every new MAS administrator must climb, preferably before they are asked to make changes in a production environment. The teams that invest in understanding these configuration surfaces before they need to make changes are the teams that operate smoothly. The teams that learn under pressure are the ones that open support tickets at 2 AM.

Bottom Line

Maximo Manage 9.2 is a mature, well-structured application platform, but its configuration model is fundamentally different from the 7.6.x era. The ManageWorkspace custom resource is the control plane. The attachment storage type, the build-config pod templates, the BIRT 4.16 reporting integration, the CSV export pipeline, the Operational Dashboard configuration, and the split between suite-level and Manage-level administration are the areas where administrators spend the most time and make the most mistakes. Invest in understanding these areas before you need to make changes. Test your builds in non-production. Choose object-based storage from the start. Allocate generous resources to the build pod. And learn the admin boundary between MAS Core and Manage. The configuration model is well-designed once you understand it, but it does not forgive teams that skip the learning curve.