Skip to main content
Version: Next

Oracle Transaction Manager for Microservices

Oracle Transaction Manager for Microservices, also known as "MicroTx", simplifies application development and operations by enabling distributed transactions to ensure consistency across microservices deployed in Kubernetes.

Oracle Backend for Microservices and AI includes the free version of MicroTx, which has all of the functionality of the commercial version, but limits the number of transactions and only persists data in memory. It is recommended for evaluations and application development purposes.

MicroTx supports the following consistency models:

  • Extended Architecture (XA)
  • Long Running Actions (LRA)
  • Try-Confirm/Cancel (TCC)

Use Oracle Transaction Manager for Microservices with Spring Boot​

To use MicroTx in your Spring Boot applications, include the following dependency in your pom.xml or equivalent:

<dependency>
<groupId>com.oracle.microtx.lra</groupId>
<artifactId>microtx-lra-spring-boot-starter-3x</artifactId>
</dependency>

Add the following configuration to your Spring application configuration. The variables in this configuration are automatically injected into your deployment and pods when you deploy applications to Oracle Backend for Microservices and AI using the OBaaS deployment Helm chart.

spring:
microtx:
lra:
coordinator-url: ${MP_LRA_COORDINATOR_URL}
propagation-active: true
headers-propagation-prefix: "{x-b3-, oracle-tmm-, authorization, refresh-}"

lra:
coordinator:
url: ${MP_LRA_COORDINATOR_URL}

Components and enablement​

The MicroTx installation is made up of three components, each of which can be enabled or disabled independently in the Helm values:

  • otmm.coordinator — the transaction coordinator (XA/LRA/TCC).
  • otmm.workflowServer — the workflow server (see below).
  • otmm.console — the web console used to monitor transactions and workflows.

All three are enabled by default. To disable a component, set its enabled flag to false:

otmm:
coordinator:
enabled: true
workflowServer:
enabled: true
console:
enabled: false

The console exists only to front the coordinator and workflow server, so it is deployed only when at least one of those two components is enabled. If both otmm.coordinator.enabled and otmm.workflowServer.enabled are false, the console is not deployed even if otmm.console.enabled is true. When deployed, the console is connected only to the backends that are enabled, so a coordinator-only or workflow-only install does not leave the console pointing at a service that was not deployed.

Identity provider and JWT security​

Configure MicroTx security under otmm.commonConfiguration.security. The identity-provider fields follow the MicroTx 26.1 identity-provider properties. Use serverType: idcs for Oracle IDCS and other for other supported providers. Copy issuer and jwksUri from the provider's discovery document. Leave scopes empty for non-IDCS providers; IDCS defaults to openid groups.

For example, a Keycloak configuration with console access is:

otmm:
commonConfiguration:
externalURL:
protocol: https
host: microtx.example.com
security:
enabled: true
clientSecretName: microtx-client
identityProvider:
serverType: other
issuer: https://idp.example.com/realms/obaas
jwksUri: https://idp.example.com/realms/obaas/protocol/openid-connect/certs
identityProviderUrl: https://idp.example.com/realms/obaas
audience: microtx
scopes: ""
roleMappings:
coordinator:
adminUserRoles: microtx-admin
adminUserRolesPath: "realm_access, roles"
workflow:
claimsRolePaths: realm_access.roles
roles:
admin: microtx-workflow-admin
coordinator:
authentication:
requestsWithNoJWT: DENY
console:
cookieEncryptionPasswordSecretName: microtx-console-cookie

Prepare namespace-local Secrets: microtx-client with clientId and clientPassword, and microtx-console-cookie with secret. Register the console redirect URI https://microtx.example.com/console/oidc/redirect with the IdP, and configure the audience and roles in the tokens. The IdP must be reachable by MicroTx pods and by users' browsers. Set up the corresponding HTTPS route; externalURL alone does not provision it.

Console cookie encryption is configured separately through otmm.console.cookieEncryption.enabled. It defaults to false to preserve existing console behavior. Set it to true to enable the console's cookie encryption setting and verify browser login with your encryption-password Secret. When common security and the console are enabled, the chart still requires cookieEncryptionPasswordSecretName, regardless of this setting.

Common security enables coordinator RBAC, workflow JWT validation, and console OIDC. An empty coordinator.authentication.requestsWithNoJWT derives DENY when security is enabled and ALLOW otherwise. ALLOW with coordinator RBAC enabled is rejected. For JWT authentication without common RBAC, explicitly set DENY and provide issuer/JWKS details and the expected access-token audience. The chart exports identityProvider.audience as the coordinator's JWT_AUDIENCES setting. API-only installations can disable the console and omit its client Secret, URL, and administrator role settings; coordinator JWT authentication still requires the audience. The evaluation defaults leave security disabled; enable security and require JWTs in production, as described in MicroTx authentication properties.

Use identityProvider.roleMappings.coordinator for administrator roles and identityProvider.roleMappings.workflow for workflow roles. Coordinator role paths use commas; workflow paths use dots. Older OBaaS overrides under identityProvider.adminUserRoles, identityProvider.adminUserRolesPath, identityProvider.policy, and workflowServer.security.identityProvider.policy remain supported and take precedence. Remove those overrides when migrating to the documented roleMappings paths.

JWT validation and RBAC do not enable token propagation to participant callbacks. The chart keeps token propagation disabled; enabling it requires additional encryption-key and callback configuration. After deployment, verify that missing, expired, incorrectly signed, and wrong-issuer tokens are rejected, and that administrator APIs enforce the configured roles. Helm render checks do not establish runtime IdP compatibility.

Coordinator database storage​

The coordinator defaults to otmm.coordinator.storage.type: memory. To persist transaction state across coordinator restarts, use db with a MicroTx Enterprise Edition image. The Free coordinator image does not support database storage. Database storage does not require a coordinator PVC and does not migrate transactions previously held in memory.

Before installing, prepare a reachable Oracle Database and grant the storage user MicroTx's required privileges and tablespace quota. Follow the database setup prerequisites, including separate schemas for the coordinator and workflow server when both use Oracle Database. Accept the applicable Enterprise Edition image terms and provide an image pull secret if required by Oracle Container Registry.

Reuse the OBaaS database credentials​

For a coordinator-only installation, layer these overrides after your normal OBaaS values:

otmm:
coordinator:
image:
repository: container-registry.oracle.com/database/microtx-ee-coordinator
tag: "26.1.2"
storage:
type: db
db:
credentialSecretName: ""
workflowServer:
enabled: false

With credentialSecretName empty, the coordinator uses the same application credential secret as the database metrics exporter. This includes custom secret names and keys configured through database.authN. The application secret's service key supplies the connection string; optionally override it with otmm.coordinator.storage.db.connectionString.

The chart also reuses the exporter's database wallet and mounts it at /etc/config/dbwallet. It overlays sqlnet.ora to point to that directory without changing the shared Secret. No separate JSON credential Secret is needed: the chart serializes the application username and password at startup. Custom coordinator images using this path must provide Python 3 and /app/tcs.

Use a separate coordinator schema​

When the workflow server is enabled, keep its OBaaS application schema separate from the coordinator's transaction-store schema. Create a Secret in the OBaaS application namespace for the coordinator user. Its secret key must contain JSON in this format:

{"username":"<coordinator-user>","password":"<coordinator-password>"}

Create it from a protected local file rather than placing credentials in a committed values file:

kubectl -n <application-namespace> create secret generic microtx-coordinator-db \
--from-file=secret=<credential-json-file>

Keep the Enterprise Edition image override above and configure:

otmm:
coordinator:
storage:
type: db
db:
credentialSecretName: microtx-coordinator-db
credentialSecretKey: secret
connectionString: "<coordinator-connect-string>"
# Set one of these when the connection requires a wallet:
# walletSecretName: "<coordinator-wallet-secret>"
# walletConfigMapName: "<coordinator-wallet-configmap>"

A separate credential Secret requires an explicit connection string. It does not implicitly select the shared OBaaS wallet: supply walletSecretName or walletConfigMapName when needed, in the application namespace. The wallet is mounted at /etc/config/dbwallet; its sqlnet.ora must use that wallet directory. The chart does not rewrite custom wallet configuration.

Schema initialization and verification​

For database storage, otmm.coordinator.storage.db.initializeSchema defaults to true. The initialize-coordinator-schema init container runs the selected image in MicroTx initialization mode with the same credentials and wallet as the service. The coordinator starts only after initialization succeeds. This step can create or upgrade database objects; review MicroTx's migration requirements and back up an existing transaction store before upgrading its image.

If a DBA provisions and upgrades the schema separately, set otmm.coordinator.storage.db.initializeSchema: false.

After the Helm installation or upgrade, check both containers:

kubectl -n <application-namespace> logs <app-release>-otmm-tcs-0 \
-c initialize-coordinator-schema
kubectl -n <application-namespace> logs <app-release>-otmm-tcs-0 -c otmm-tcs

Initialization should complete successfully and the coordinator should report serving.... If startup reports ORA-00942 for OMTM_STATS, check schema initialization and the storage user's privileges. For ORA-28759, check that the wallet files are readable and sqlnet.ora points to their mounted directory.

MicroTx Workflow Server​

The MicroTx Workflow Server extends transaction coordinator with advanced workflow capabilities.

For MicroTx sizing and deployment guidance, see the official Oracle Transaction Manager for Microservices 26.1 documentation. To enable the workflow server in OBaaS, set the otmm.workflowServer.enabled property to true in the Helm values:

otmm:
workflowServer:
enabled: true

When the workflow server is enabled, it uses the OBaaS application database secret, typically <release>-db-authn, and runs Flyway against that schema during startup. The database init job grants OBAAS_USER the schema privileges required for this initialization. If a pre-existing application user is supplied through database.authN.secretName, that user must have equivalent schema DDL privileges and quota on its default tablespace.

Upgrading to the commercial version​

If you have licensed Oracle Transaction Manager for Microservices Enterprise Edition (EE), upgrade the MicroTx components as follows: