Skip to content

Chapter 4: Infrastructure and Deployment

Phase 3 produced your retain/adopt/merge decisions for every customized object. Before those decisions become reality, the infrastructure must be prepared. This chapter provides runbook-style procedures to prepare the database, connect it to MREF, migrate system properties, configure the OpenShift deployment, and verify the result. Each procedure follows a consistent format: pre-check conditions, numbered steps with exact commands, verification queries, and rollback instructions.

Infrastructure Task Sequence

Complete these tasks in order. Each references a detailed procedure section below.

  • [ ] 1. Full database backup (Section 1.1)
  • [ ] 2. Purge AGENT_REGISTRY and AGENT_STARTUP tables (Section 1.2)
  • [ ] 3. Clean ENVIRONMENT_PROPERTIES rows (Section 1.3)
  • [ ] 4. Verify system user account (Section 1.4)
  • [ ] 5. Extract AES encryption secrets (Section 1.5) -- hard gate: must complete before MREF activation
  • [ ] 6. Connect database to MREF (Section 2.1 BYOD or Section 2.2 conversion)
  • [ ] 7. Map system properties to MREF equivalents (Section 3)
  • [ ] 8. Deploy MREF operator on OpenShift (Section 4)
  • [ ] 9. Configure pod sizing and storage (Sections 4.4-4.5)
  • [ ] 10. Run post-deployment verification (Section 5)

Warning

Step 5 is a hard gate. If AES encryption secrets are not migrated to OpenShift before MREF activation, all AES-encrypted integration passwords become permanently unreadable. There is no recovery.

1. Database Preparation

Database preparation is the first hands-on work in the migration. Every step in this section must be completed before you connect the database to MREF. The procedures are sequential -- do not skip ahead.

1.1 Pre-Migration Backup

Pre-check

  • [ ] TRIRIGA application fully shut down
  • [ ] No active user sessions (verify via Admin Console > Users before shutdown)

Steps:

  1. Execute a full database backup using your platform's native tooling:
  2. Oracle: RMAN full backup or expdp data pump export
  3. SQL Server: BACKUP DATABASE [dbname] TO DISK = 'path'
  4. Db2: BACKUP DB [dbname] TO 'path'
  5. Record the backup location, timestamp, and file size

Verify

  • [ ] Backup completes without errors
  • [ ] Backup file size is consistent with the database size (a significantly smaller backup indicates a partial or failed backup)

Rollback

N/A -- this IS the rollback anchor for all subsequent procedures.

1.2 Agent Table Purge

These tables hold legacy agent-to-server mappings and startup configuration. MREF replaces this with automated pod scaling managed by the operator. If these tables are not emptied, MREF initialization will attempt to honor stale agent registrations, causing pod scheduling conflicts. Verified1

Pre-check

  • [ ] TRIRIGA application fully shut down
  • [ ] Database backup from Step 1.1 is complete and verified

Pre-purge verification -- confirm the tables exist and contain data:

SELECT COUNT(*) FROM AGENT_REGISTRY;
SELECT COUNT(*) FROM AGENT_STARTUP;

Steps:

DELETE FROM AGENT_REGISTRY;
DELETE FROM AGENT_STARTUP;
COMMIT;

Verify

SELECT COUNT(*) FROM AGENT_REGISTRY;  -- Must return 0
SELECT COUNT(*) FROM AGENT_STARTUP;   -- Must return 0

Rollback

Restore from backup (Step 1.1). Agent tables will be repopulated with original data.

1.3 Environment Properties Cleanup

Pre-check

  • [ ] Agent table purge (Step 1.2) complete

Steps:

DELETE FROM ENVIRONMENT_PROPERTIES
WHERE PROPERTY IN ('platform.class.upgrade', 'AgentManagementUpgrade');
COMMIT;

Verify

SELECT COUNT(*) FROM ENVIRONMENT_PROPERTIES
WHERE PROPERTY IN ('platform.class.upgrade', 'AgentManagementUpgrade');  -- Must return 0

Rollback

Restore from backup (Step 1.1). These rows control legacy upgrade logic -- leaving them causes MREF initialization conflicts.

Gotcha

This step is frequently missed. Documentation focuses on the two agent tables, but these ENVIRONMENT_PROPERTIES rows trigger legacy upgrade logic that conflicts with MREF initialization. Verified1 Include all three cleanup operations in your execution checklist.

1.4 System User Verification

Pre-check

  • [ ] Database accessible

Steps:

  1. Verify the system user exists and is assigned to the admin group
  2. Document the system user credentials separately -- post-migration, this user becomes an internal service account only. Human administrators will use MAS admin credentials.

Verify

  • [ ] system user can authenticate (pre-migration check against the running TRIRIGA instance, or verify directly in the database)

Post-migration, the system user is no longer a human login. MAS Core manages user authentication, SSO, and user lifecycle. See the Concept Glossary for the full terminology change. Verified2

1.5 AES Encryption Secret Extraction

Warning

This is a hard gate. Complete this BEFORE MREF activation. Failure means all AES-encrypted integration passwords are permanently lost.

Pre-check

  • [ ] Phase 2 integration inventory identifies Integration Objects with AES encryption (the "AES Encrypted?" column from the Phase 2 template)
  • [ ] If no AES-encrypted integrations exist, skip this step

Steps:

  1. Locate the AES keystore credentials in the current TRIRIGA environment
  2. Extract the keystore password from the existing configuration
  3. Create an OpenShift Secret (vault_secret in the Tririga CRD) containing the keystore credentials:
  4. Secret must contain the key password with the extracted keystore password value
  5. Verify the secret is accessible from the target namespace (mas-<instanceId>-facilities)

Verify

  • [ ] OpenShift Secret exists in the target namespace
  • [ ] Secret contains the expected password key

Rollback

Re-extract from the source environment (source must still be accessible). If the source environment has already been decommissioned, the AES-encrypted data is unrecoverable.

Cross-reference: Phase 2 integration template (AES Encrypted? column) and Phase 5 (integration auth migration procedures).

1.6 Version-Specific Database Considerations

If your environment is upgrading across TRIRIGA versions as part of the migration, review these version-specific gotchas before proceeding:

Version Path Action Required Risk if Missed
11.2/11.3 to 11.5 (Lease Accounting) DBA must create index on T_TRIPAYMENTBREAKDOWNITEMS table after OM package import, then execute 11.4LeasePostProcess patch helper Permanently wipes lease payment amounts Verified3
Platform 5.0 / App 11.6 (Db2 on Liberty) Add jdbcCollection="NULLIDR1" to properties.db2.jcc in server.xml Database connection failures Verified11
Oracle cross-subnet Set SQLNET.EXPIRE_TIME=1 in sqlnet.ora Intermittent connection drops Needs Validation4
Platform 5.0 (IBS_SPEC_TREE removal) Rewrite custom BIRT reports or queries referencing IBS_SPEC_TREE to target module-level association tables Report failures post-migration Verified4
Pre-10.3.0 (legacy upgrades) Execute SetVarcharColsToNumeric_ORCL.sql or SetVarcharColsToNumeric_MSSS.sql before application upgrade Data type mismatches Needs Validation5

Tip

Cross-reference this table against Phase 1, Section 4 for the full version eligibility matrix and Lease Accounting hard gate details.

2. Database Platform Handling

MREF supports three database platforms for customer-managed deployments. Most environments stay on their existing platform -- that is the recommended path. Verified6

2.1 BYOD: Connecting Your Existing Database

Bring your own database is the default approach. MREF connects to your existing TRIRIGA database -- Db2, Oracle, or SQL Server -- without requiring platform conversion. This section covers the connection details for each platform and the procedure for configuring the MREF operator.

Connection Reference Table

Platform JDBC URL Pattern Default Port Bundled Driver TLS Requirement MREF-Specific Gotchas
IBM Db2 jdbc:db2://<host>:<port>/<dbname> 50000 db2jcc4.jar (v11.1.3 FP3) TLS 1.2+ mandatory Schema name and DB username must be identical to source. If change needed, engage IBM Support. jdbcCollection="NULLIDR1" required for Platform 5.0+.
Oracle jdbc:oracle:thin:@//<host>:<port>/<sid> 1521 ojdbc7.jar (v12.0.1.2) TLS 1.2+ mandatory Set SQLNET.EXPIRE_TIME=1 for cross-subnet. spec.db.sid = Oracle SID.
SQL Server jdbc:sqlserver://<host>:<port>;databaseName=<dbname> 1433 jtds-1.2.5.jar TLS 1.2+ mandatory spec.db.sid not required.

Driver JARs are bundled in the MREF container image. You do not need to supply them. Verify compatibility if your database server version is at the extremes of the support range. Needs Validation (Driver versions cited from professional expertise; not independently verified against current MREF container image.)

Warning

Hard technical limitation: the target MREF Db2 database must retain the exact same schema name and database username as the source TRIRIGA database. If a schema change is attempted during database restore, migration will fail silently or with cryptic errors. If a schema change is mandatory, engage IBM Support directly. Verified7

BYOD Procedure

Pre-check

  • [ ] Database preparation (Section 1) complete -- all five steps
  • [ ] Database server accessible from OpenShift cluster (network connectivity verified)
  • [ ] TLS 1.2+ enabled on database server
  • [ ] Database credentials available for Kubernetes Secret creation

Steps:

  1. Create Kubernetes Secret for database credentials:
  2. Secret name: tas-db-secret (or as specified in operator CR)
  3. Keys: DB_USERNAME, DB_PASSWORD
  4. Configure operator CR spec.db.* fields:
  5. spec.db.dbtype: db2, oracle, or mssql
  6. spec.db.dbdnsname: database hostname or DNS name
  7. spec.db.dbport: port number (see connection reference table above)
  8. spec.db.dbname: database name
  9. spec.db.sid: schema/SID (Oracle = SID, Db2 = schema name, SQL Server = not required)
  10. spec.db.db_secret: name of the Kubernetes Secret created above
  11. spec.db.maxconnpoolsize: connection pool maximum (default: 100, adjust based on user count)
  12. Apply the CR and verify operator reconciliation completes

Verify

  • [ ] Operator logs show successful database connection
  • [ ] TRIRIGA login page accessible (confirms end-to-end connectivity from browser through route to database)

Rollback

Update spec.db.* fields with corrected values and re-apply. The operator will reconcile automatically on the next cycle.

2.2 Database Conversion to Db2

Database conversion is optional for customer-managed deployments. It is required only for SaaS (IBM-hosted) migrations. Verified8

Decision Framework

Scenario Conversion Required? Rationale
SaaS migration (IBM-hosted) Yes IBM SaaS runs Db2 exclusively
Customer-managed, want Db2 licensing savings Optional Db2 is bundled with MAS licensing (no additional DB license cost)
Customer-managed, existing Oracle or SQL Server No Stay on current platform -- BYOD supported

Key Risks and Gotchas

  1. SQL dialect differences: IBM Data Movement Tool (DMT) converts tables and data but CANNOT convert SQL queries saved in the TRIRIGA database -- saved queries, relationship where-clauses, report SQL, and integration queries. These require manual dialect conversion from Oracle/SQL Server SQL to Db2 SQL.
  2. Saved query inventory: Before conversion, run the Phase 2 assessment to identify all saved queries and report SQL. Each must be manually reviewed for dialect compatibility.
  3. Rollback complexity: Database conversion is a one-way operation in practice. Maintain the original database backup (Section 1.1) as a rollback path.

Warning

Do not underestimate SQL dialect conversion. DMT handles the structural migration, but every saved query, report SQL statement, relationship where-clause, and integration query must be individually checked for Db2 compatibility. Budget significant DBA time for this work.

IBM Tooling Pointers

This guide does not provide a full DBA migration runbook -- database conversion is specialized work. The key tooling references:

  • IBM Data Movement Tool (DMT): Primary tool for table and data migration between database platforms
  • Third-party tools: Available but subject to the same SQL dialect limitation
  • IBM Support: Engage for complex conversions, especially with large custom query inventories

See Phase 5 for integration endpoint URL changes that may result from database platform decisions.

Key Takeaway

BYOD is the recommended path. Most environments connect their existing database directly. Only convert to Db2 if migrating to SaaS or seeking licensing consolidation -- and budget for manual SQL dialect conversion if you do.

3. System Property Migration

Phase 2 identified your system properties and classified each as Retained, Moved, or Removed. This section tells you exactly where each property goes in MREF. The expanded mapping table below covers approximately 45 properties across 10 categories -- enough for 90% of environments. For the remainder, the decision heuristic at the end of this section provides a systematic approach to classifying any property you encounter.

3.1 Three-Status Classification Recap

Every TRIRIGAWEB.properties setting falls into one of three statuses. The key behavior difference is what happens after a pod restart:

  • Retained: Property still lives in TRIRIGAWEB.properties, placed in the persistent config directory on the PVC. Set it there, and it persists across pod restarts.
  • Moved: Property is now managed by the MREF operator via CR spec fields, Kubernetes Secrets, ConfigMaps, or the MAS Admin UI. Setting it in TRIRIGAWEB.properties will be overridden on pod restart or operator reconciliation.
  • Removed: Property no longer exists or applies in MREF. Do not set it.

Warning

Properties with "Moved" status are managed by the MREF operator. If you set them in TRIRIGAWEB.properties, they will work temporarily -- then revert on the next pod restart or operator reconciliation loop. This is the single most common configuration mistake in MREF deployments. Always check the Method column in the mapping table below before editing TRIRIGAWEB.properties.

3.2 Expanded Property Mapping Table

This table expands Phase 2's curated reference from approximately 20 properties to comprehensive coverage. The Method column tells you exactly how to set each property in MREF.

Database Connection (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
DATA_DBUSER / DATA_DBPASSWORD Database K8s Secret tas-db-secret: DB_USERNAME, DB_PASSWORD Secret Credentials never in properties files
data_dbname / DB Host / Port / SID Database spec.db.dbtype, spec.db.dbdnsname, spec.db.dbport, spec.db.dbname, spec.db.sid Operator CR See Section 2.1 connection reference
Connection pool max Database spec.db.maxconnpoolsize Operator CR Default: 100
CACHE_LOAD_SIZE_FOR_ORACLE Database Admin Console Removed from properties Set via Admin Console if needed Verified4
Db2 jdbcCollection Database properties.db2.jcc in server.xml Liberty config Required for Platform 5.0+ Verified9

SMTP and Mail (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
mail.smtp.host SMTP MAS Admin UI MAS Admin Centralized SMTP config
mail.smtp.port SMTP MAS Admin UI MAS Admin Centralized SMTP config
mail.smtp.user SMTP MAS Admin UI MAS Admin Centralized SMTP config
mail.smtp.password SMTP MAS Admin UI MAS Admin Centralized SMTP config
mail.imaps.ssl.port SMTP MAS Admin UI MAS Admin Centralized SMTP config
EXCHANGE_DOMAIN, TRIRIGA_RESERVE_SUB_DOMAIN SMTP Admin Console > Reserve SMTP Agent tab Admin Console App-level config retained

SSO and Authentication (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
SSO / SSO_REQUEST_ATTRIBUTE_NAME SSO MAS Core MAS Core Centralized auth
SSO_SINGLE_SIGN_OUT_REDIRECT_URL SSO Retained Properties URL must be updated for MREF endpoint
SSO_DISABLE_UNAUTHORIZED_STATUS SSO MAS Core MAS Core Centralized auth
USERNAME_CASE_SENSITIVE SSO OIDC secret (tas-oidc-secret.yaml) Secret Managed via MAS Core identity config

Application Routing (Mixed)

TRIRIGA Property Category MREF Equivalent Method Notes
CONTEXT_PATH Routing Removed N/A No longer used in MREF
FRONT_END_SERVER / EXTERNAL_FRONT_END_SERVER Routing Retained Properties Must update URLs for MREF endpoint
Front-end routing Routing spec.rt.domain, spec.rt.routes_crt Operator CR Route and TLS configuration

Licensing (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
SLS_SERVER_HOST / SLS_SERVER_PORT / SLS_LICENSING_ENABLED Licensing spec.sls.sls_host, spec.sls.sls_secret Operator CR MAS manages licensing centrally
UDS/DRO API keys Licensing spec.uds.uds_host, spec.uds.uds_secret Operator CR Data Reporter Operator config
SLS_EXPIRY_NUM_DAYS_WARNING Licensing Retained Properties No change

File System (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
FileSystemRoot / FileSystemBrowseRoot File System spec.storage.*.class, spec.storage.*.size, spec.storage.*.mode Operator CR PVC-based storage replaces file paths
BatchInputLoc, BatchProcessLoc, BatchOutputLoc, BatchErrorLoc, BatchLogLoc File System Operator CR storage config Operator CR Legacy dirs outside userfiles/config/log will NOT persist

JVM and Heap (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
Initial / Maximum Heap Size JVM spec.jvm.javamin, spec.jvm.javamax Operator CR MREF 9.1+ auto-calculates: 75% of pod memory request (min), 75% of pod memory limit (max). Prefer auto-sizing.

Security Headers (Retained)

TRIRIGA Property Category MREF Equivalent Method Notes
httpheader.X-Frame-Options Security Retained Properties No change
httpheader.Strict-Transport-Security Security Retained Properties No change
httpheader.Content-Security-Policy Security Retained Properties No change
httpheader.X-Content-Type-Options Security Retained Properties No change
httpheader.X-XSS-Protection Security Retained Properties No change
httpheader.Cache-Control Security Retained Properties No change

Performance Tuning (Retained)

TRIRIGA Property Category MREF Equivalent Method Notes
WFAgentMaxThreads Performance Retained Config dir Place in persistent config directory
SchedulerAgentMaxThreads Performance Retained Config dir Place in persistent config directory
ReportQueueAgentMaxThreads Performance Retained Config dir Place in persistent config directory
REPORT_MEMORY_USAGE_LIMIT Performance Retained Properties No change
CLEAN_HOUR / CLEAN_TIMEOUT Performance Retained Properties No change
CONCURRENT_AVAILABILITY_POOL_SIZE Performance Retained Properties No change
EXPORT_EXCEL_BATCH_PROCESS_SIZE Performance Retained Properties No change
WF_INSTANCE_SAVE Performance Retained Properties No change
AGENT_STALE_TIME_IN_SECONDS Performance Retained Properties No change
CLEANUP_AGENT_DELETE_DM_CONTENT Performance Retained Properties No change
REBUILD_HIERARCHIES_ON_CLEANUP Performance Retained Properties No change

Certificates and AES (Moved)

TRIRIGA Property Category MREF Equivalent Method Notes
AES encryption keystore password Certificates OpenShift Secret (vault_secret in Tririga CRD) Secret Hard gate -- extract before activation (Section 1.5)
External certificates / truststore Certificates MAS Admin UI or tas-truststore.yaml Secret Secret / MAS Admin Centralized certificate lifecycle

Additional Properties from Release Notes

TRIRIGA Property Category MREF Equivalent Method Notes
COOKIE_SAME_SITE=None Application Retained Properties Required for Outlook Room Search add-in
ENHANCED_RECORD_RENDER_MODE Application Retained Properties Default TRUE in Platform 5.0 Verified4
GANTT_TIMEOUT_MAX Application Retained Properties No change
BIRT_USE_SSL / BIRT_SSL_KEYSTORE / BIRT_SSL_KEYSTORE_PASS Reporting Retained Properties No change
DEFAULT_SYSTEM_USER_EMAIL_FOR_FORGOT_PASSWORD Application Retained Properties No change

3.3 Decision Heuristic for Unknown Properties

For properties not in the mapping table above, use this flowchart to determine where they belong in MREF:

  1. Is it agent-related? --> Likely Moved. The operator manages agent scaling via CR spec.env.size and spec.wfagents. Do not set agent registration properties in TRIRIGAWEB.properties.
  2. Is it database or connection-related? --> Definitely Moved. The operator CR spec.db.* fields manage all database connectivity. Setting connection properties in TRIRIGAWEB.properties will be overridden.
  3. Is it auth or SSO-related? --> Definitely Moved. MAS Core manages authentication centrally. Check MAS Admin UI for the equivalent setting.
  4. Is it SMTP or mail-related? --> Definitely Moved. MAS Admin UI provides centralized SMTP configuration for all MAS applications.
  5. Is it UI tuning or internal application behavior? --> Likely Retained. Place it in the persistent config directory on the PVC. These are application-level settings the operator does not manage.
  6. Is it file path-related? --> Check whether the path maps to userfiles, config, or log. If it references a directory outside these three mount points, the functionality may not persist in containers. Remap to a path within the PVC.
  7. Still unsure? --> Set it in config/TRIRIGAWEB.properties, restart the pod, and test. If the operator overrides it on the next reconciliation cycle, the property is Moved. If it persists, it is Retained.

Tip

Step 7 is your empirical fallback. The operator reconciliation loop is predictable -- if it overrides your setting, the property is operator-managed. Document the result and add it to your project-specific property mapping. Over time, your team builds a supplemental reference that extends this table.

Key Takeaway

The property mapping table and decision heuristic cover 90%+ of environments. For the remaining edge cases, the empirical test (set, restart, observe) gives you a definitive answer. The critical rule: never set a Moved property in TRIRIGAWEB.properties and expect it to persist.

4. OpenShift Deployment

With the database prepared (Section 1), connected (Section 2), and properties mapped (Section 3), you are ready to deploy the MREF operator on OpenShift. This section covers the concepts you need, the deployment model options, and the detailed operator configuration for customer-managed deployments.

4.1 OpenShift Primer for TRIRIGA Consultants

If this is your first MREF engagement, you may be encountering OpenShift for the first time. This primer covers the concepts you need to understand the deployment procedures that follow.

Concept What It Is TRIRIGA Equivalent
Pod Smallest deployable unit. Runs one or more containers. Stateless by default -- anything not on a PVC is lost on restart. A TRIRIGA server/JVM instance
Operator Software that automates deployment and lifecycle management. Watches Custom Resources and reconciles desired state continuously. No direct equivalent -- like an automated admin that constantly checks and corrects configuration
Custom Resource (CR) YAML definition of your desired deployment state. The operator reads this and creates/manages pods, services, and routes. Like a comprehensive properties file that controls the entire deployment
Route Exposes a service externally with a URL and TLS termination. Load balancer or reverse proxy configuration
Persistent Volume Claim (PVC) Request for persistent storage that survives pod restarts. File system directories (but explicitly requested, not assumed)
ConfigMap / Secret Configuration and credential storage as Kubernetes objects. Secrets are base64-encoded and access-controlled. Properties files and keystores
Namespace Logical isolation boundary within the cluster. MREF runs in mas-<instanceId>-facilities. Separate server instances on different boxes
StatefulSet Deployment pattern for pods needing stable network identity and ordered startup. Used for the appserver. Named server instances with predictable hostnames

Tip

You do not need to become an OpenShift expert. You need to understand these eight concepts, read YAML, and know where to look when something goes wrong. Your infrastructure team handles the cluster; you handle the MREF-specific configuration within it.

4.2 Deployment Model Comparison

MREF can be deployed in three models. The comparison below helps you scope your engagement correctly.

Dimension SaaS (IBM-Hosted) Customer-Managed Partner-Hosted
Infrastructure AWS, IBM SRE managed Customer's OCP cluster (on-prem or cloud) Partner manages OCP cluster
OCP Expertise Required None Full in-house OCP team None (partner provides)
Upgrade Control IBM cadence (cannot delay indefinitely) Full customer control Per partner SLA
Database Requirement Db2 ONLY Db2, Oracle, or SQL Server Per partner capability
Flexibility Lowest Highest Medium
Operational Burden Lowest Highest Low-Medium

The remainder of this section covers customer-managed deployment in detail. SaaS and partner-hosted deployments are managed by IBM or the partner respectively -- your role in those models shifts to configuration validation rather than deployment execution. Cross-reference Phase 1's Three-Way Scope Distinction for how deployment model affects engagement planning.

4.3 MREF Operator Configuration

Two operators manage MREF deployment:

  1. ibm-mas-facilities operator -- watches the FacilitiesApp Custom Resource (instance name = MAS <instanceId>). Manages application-level deployment and lifecycle.
  2. <instanceId>-entitymgr-ws operator -- watches the FacilitiesWorkspace Custom Resource (instance name = <instanceId>-<workspaceId>). Manages workspace-specific configuration including database, JVM, and storage.

The FacilitiesWorkspace CR is where you configure most migration-relevant settings. The table below lists key spec fields -- most map directly to your Phase 2 assessment and Section 3 property mapping.

Key CR Spec Fields

Spec Path Purpose Values / Default
spec.env.size Workload distribution tier small, medium, large
spec.env.use Environment purpose development, production
spec.db.dbtype Database platform db2, oracle, mssql
spec.db.dbdnsname Database hostname or DNS name --
spec.db.dbport Database port 50000 / 1521 / 1433
spec.db.dbname Database name --
spec.db.sid Schema/SID Oracle = SID, Db2 = schema, SQL Server = not required
spec.db.db_secret K8s secret for DB credentials e.g., tas-db-secret
spec.db.maxconnpoolsize Max connection pool Default: 100
spec.jvm.javamin Min heap (MB) e.g., 4096
spec.jvm.javamax Max heap (MB) e.g., 8192
spec.rt.domain External routing domain --
spec.rt.routes_crt Route TLS certificate --
spec.rt.contextpath URL context path e.g., tririga
spec.sls.sls_host Suite License Service host --
spec.sls.sls_secret SLS secret name --
spec.uds.uds_host Data Reporter Operator host --
spec.uds.uds_secret DRO secret name --
spec.storage.*.class Storage class Must support root group RW
spec.storage.*.size Volume size (GB) e.g., 30
spec.storage.*.mode Access mode ReadWriteOnce or ReadWriteMany

Tip

Most of these fields map directly to your Phase 2 assessment and Section 3 property mapping. The CR is essentially a structured version of what TRIRIGAWEB.properties and your deployment documentation used to cover separately.

4.4 Pod Sizing and T-Shirt Framework

The spec.env.size field controls how background agents are distributed across pods. This is the primary scaling lever in MREF -- it determines whether agents share a pod or run in isolation. Verified10

Three-Tier Sizing

Tier spec.env.size Agent Distribution Use When
Small small All background agents in a single multiagents pod Dev/test environments, small user counts
Medium medium reportqueueagent and wfagent in dedicated pods; remaining agents in multiagents Mid-size environments, moderate workflow and report volume
Large large Every agent in a dedicated pod (scheduleragent, dataconnectagent, incomingmailagent, etc.) Large production environments, high concurrency

Resource Defaults

Pod Type Memory Request Memory Limit Notes
datainit (job) 64 MB 1 Gi One-time initialization; runs during first deployment only
appserver, dwfagent, multiagents 2 Gi 6 Gi Core application pods
Individual agent pods (medium/large) 1.3 Gi 2 Gi Isolated agent pods when using medium or large tier

MREF dynamically calculates Java heap: minimum = 75% of pod memory request, maximum = 75% of pod memory limit. This replaces manual WebSphere JVM tuning. Manual spec.jvm.* overrides are available but auto-sizing is the recommended approach for most environments. Verified10

Gotcha

Do not set explicit spec.jvm.* values that conflict with auto-sizing. If you set javamax higher than 75% of the pod memory limit, the JVM will be OOMKilled by Kubernetes. When in doubt, use the auto-sizing defaults and adjust pod memory limits instead.

4.5 Persistent Storage Configuration

Container storage is ephemeral by default. Any data not on a Persistent Volume is lost on pod restart. MREF uses PVCs for three directory types:

Directory Purpose PVC Notes
userfiles User-uploaded files, documents Primary PVC
config TRIRIGAWEB.properties, custom configuration Merged into userfiles PVC via subPath Likely10
log Application logs Separate or merged depending on storage class

Storage Requirements:

  • StorageClass must grant read-write to Linux root group (GID 0)
  • Access mode: ReadWriteMany preferred for multi-pod deployments (medium/large tiers); ReadWriteOnce acceptable for single-pod (small tier)
  • Example storage classes: ibmc-file-gold-gid (IBM Cloud), ocs-storagecluster-cephfs (OpenShift Data Foundation)
  • Minimum size: plan for growth -- user-uploaded documents accumulate over the lifecycle of the deployment

Warning

Legacy batch directories (BatchInputLoc, BatchProcessLoc, BatchOutputLoc, BatchErrorLoc, BatchLogLoc) outside the userfiles/config/log PVC mounts will NOT persist in containers. Remap batch processes to use directories within the persistent mount points before migration. See Section 3.2 (File System properties) for the specific properties affected.

4.6 Networking, Routes, and TLS

MREF generates OpenShift Routes automatically during deployment. You configure the domain and certificates; the operator handles route creation.

  • FQDN pattern: <workspaceId>.facilities.<instanceId>.<domain>
  • TLS termination: reencrypt type on OpenShift routes -- traffic is encrypted between the route and the pod
  • Default certificates: Self-signed cluster certificate. For custom domains, provide a TLS secret (tls.key, tls.crt) referenced via spec.rt.routes_crt
  • Load balancing: Round-robin with cookie affinity for session persistence
  • Per-pod routes: MREF generates individual direct routes per appserver pod for troubleshooting -- useful when you need to isolate an issue to a specific pod
  • Appserver deployment: Uses StatefulSet for stable network identity. Pod names are predictable (appserver-0, appserver-1, etc.), which simplifies log correlation and debugging

5. Post-Deployment Verification

Before proceeding to Phase 5 (custom code and integration adaptation), confirm the base MREF deployment is functional. This checklist is a smoke test -- comprehensive testing strategy is covered in Phase 6.

  1. FacilitiesWorkspace CR status: OpenShift Console > Custom Resource Definitions > FacilitiesWorkspace > Instances. Verify Ready condition = True. If not Ready, check the operator logs for the <instanceId>-entitymgr-ws pod in the same namespace.

  2. Pod health: Workloads > Pods in the mas-<instanceId>-facilities namespace. Confirm appserver pods are running, agent pods (multiagents or dedicated per your sizing tier) are running, and no pods show CrashLoopBackOff errors. A CrashLoopBackOff typically indicates a missing Secret, database connection failure, or storage permission denial.

  3. Route accessibility: Networking > Routes. Click the appserver route URL. You should see the TRIRIGA login page or an SSO redirect (depending on your authentication configuration). If you get a 503 or timeout, the appserver pod is not ready.

  4. Database connection: A successful login through the TRIRIGA UI confirms end-to-end database connectivity. For additional verification, check appserver pod logs for connection pool initialization messages (look for WFLYJCA0001 or JDBC pool ready messages).

  5. Agent activity: After login, navigate to Admin Console > Agents. Verify background agents show an active status (not stale). If agents appear stale, check that the agent pods are running and that the AGENT_REGISTRY and AGENT_STARTUP tables were properly purged (Section 1.2).

  6. Workflow execution: Trigger a simple test workflow -- for example, create a work task and verify it routes correctly through the approval workflow. This confirms the workflow engine, agent processing, and database writes are all functional.

  7. Persistent storage: Upload a test document via the TRIRIGA UI, then restart the appserver pod (oc delete pod appserver-0 -n mas-<instanceId>-facilities -- the StatefulSet will recreate it). After the pod restarts, verify the document is still accessible. This confirms PVC mounting and persistence.

Tip

If any check fails, start with the appserver pod logs: oc logs appserver-0 -n mas-<instanceId>-facilities. Most deployment issues surface as database connection errors, missing secrets, or storage permission denials. The operator logs (oc logs on the entitymgr-ws pod) provide additional context for CR reconciliation failures.

Key Takeaway

Infrastructure preparation follows a strict sequence: backup, purge, extract secrets, connect database, map properties, deploy operator, verify. The two most common failure modes are (1) setting Moved properties in TRIRIGAWEB.properties (they revert on restart) and (2) forgetting to extract AES encryption secrets before activation (data loss is permanent). When in doubt, check the sequencing checklist at the top of this chapter. With the base deployment verified, proceed to Phase 5 for custom code repackaging and integration auth migration, and Phase 6 for the comprehensive testing strategy.

Sources

  1. eCIFM: Early TRIRIGA-to-MREF Lessons ↩↩

  2. IBM Docs: Migrating the application database; IBM MREF vs TAS architecture comparison (PDF) ↩

  3. IBM TRIRIGA Release Notes for 11.5 and 4.5 ↩

  4. IBM TRIRIGA Release Notes for 11.6 and 5.0 ↩↩↩↩

  5. IBM TRIRIGA Release Notes for 11.0 and 4.0 ↩

  6. IBM Docs: Installing TAS components; IBM MREF technical content (PDF) ↩

  7. IBM Docs: Migrating the application database; eCIFM: Early TRIRIGA-to-MREF Lessons ↩

  8. IBM Docs: MREF compatibility matrix; AWS Marketplace: IBM Expert Labs DB Migration Offering for MAS SaaS ↩

  9. IBM TRIRIGA Release Notes for 11.1 and 4.1 ↩

  10. IBM MREF vs TAS architecture comparison (PDF) ↩↩↩

  11. IBM TRIRIGA Release Notes for 11.X and 4/5.X ↩