Runtime manager setup

The Application Manager and Runtime Manager share the same container image and Helm chart. Refer to the Deployment Guidelines in the release notes to ensure compatibility and verify the correct version.

Infrastructure prerequisites

The Runtime Manager service requires the following components to be set up before it can be started:

PostgreSQL
MongoDB
Redis
Kafka
OAuth2 Authentication

Dependencies

Database configuration
Kafka configuration
Authentication & access roles
Logging

Change the application name

Environment Variable	Description	Example Value
`SPRING_APPLICATION_NAME`	Service identifier used for service discovery and logging	`runtime-manager`

Default Value: application-manager -> must be changed to runtime-manager

Core service configuration

Environment Variable	Description	Example Value
`FLOWX_ENVIRONMENT_NAME`	Environment identifier (dev, staging, prod, etc.). Deprecated in 5.7.0: kept for backward compatibility; the value is no longer surfaced in the Designer’s Configure Environment Info page (removed) and is replaced by the environment name set during organization provisioning.	`pr`
`LOGGING_CONFIG`	Path to logging configuration file	`logback-spring.xml`
`MULTIPART_MAX_FILE_SIZE`	Maximum file size for uploads	`25MB`
`MULTIPART_MAX_REQUEST_SIZE`	Maximum total request size	`25MB`

Database configuration

The Runtime Manager uses the same PostgreSQL (to store application data) and MongoDB (to manage runtime data) as application-manager. Configure these database connections with the following environment variables:

PostgreSQL (Application data)

Environment Variable	Description	Example Value
`SPRING_DATASOURCE_URL`	JDBC URL for PostgreSQL connection	`jdbc:postgresql://postgresql:5432/app_manager`
`SPRING_DATASOURCE_USERNAME`	PostgreSQL username	`flowx`
`SPRING_DATASOURCE_PASSWORD`	PostgreSQL password	sensitive

MongoDB (Runtime data)

Environment Variable	Description	Example Value
`SPRING_DATA_MONGODB_URI`	URI for MongoDB connection	`mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-headless:27017/${DB_NAME}?retryWrites=false`
`DB_NAME`	MongoDB database name	`app-runtime`
`DB_USERNAME`	MongoDB username	`app-runtime`
`DB_PASSWORD`	MongoDB password	sensitive

Redis configuration

Runtime Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables. Quick reference:

Environment Variable	Description	Example Value	Status
`SPRING_DATA_REDIS_HOST`	Redis server hostname	`localhost`	Recommended
`SPRING_DATA_REDIS_PORT`	Redis server port	`6379`	Recommended
`SPRING_DATA_REDIS_PASSWORD`	Redis authentication password	-	Recommended
`REDIS_TTL`	Cache TTL in milliseconds	`5000000`	Optional

Both SPRING_DATA_REDIS_* and SPRING_REDIS_* variable prefixes are supported. The SPRING_DATA_REDIS_* prefix is the modern Spring Boot standard and is recommended for new deployments.

For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

Kafka configuration

Kafka connection

Environment Variable	Description	Example Value
`SPRING_KAFKA_BOOTSTRAPSERVERS`	Kafka broker addresses	`kafka-flowx-kafka-bootstrap:9092`
`KAFKA_TOPIC_NAMING_ENVIRONMENT`	Environment prefix for Kafka topics

Kafka OAuth authentication

Environment Variable	Description	Default Value
`KAFKA_OAUTH_CLIENT_ID`	OAuth client ID	`kafka`
`KAFKA_OAUTH_CLIENT_SECRET`	OAuth client secret	`kafka-secret`
`KAFKA_OAUTH_TOKEN_ENDPOINT_URI`	OAuth token endpoint	`kafka.auth.localhost`

When using the kafka-auth profile, the security protocol will automatically be set to SASL_PLAINTEXT and the SASL mechanism will be set to OAUTHBEARER.

Kafka topics

Since the Runtime Manager shares the same container image as the Application Manager, it uses the same Kafka topic definitions. However, the Runtime Manager conditionally activates a listener for the build.runtime-data topic (based on spring.application.name=runtime-manager), which is how it receives runtime data from the Admin service.

The KAFKA_TOPIC_BUILD_RUNTIMEDATA topic must resolve to the same value in both Admin and Runtime Manager. If the KAFKA_TOPIC_NAMING_ENVIRONMENT prefix differs between services (common after export/import to a new environment), Admin will produce to one topic and Runtime Manager will consume from another, causing data not to be passed back to the calling process after subprocess execution.

Build topics

Environment Variable	Description	Default Pattern
`KAFKA_TOPIC_BUILD_RUNTIMEDATA`	Build runtime data topic (consumed only by Runtime Manager)	`ai.flowx.build.runtime-data.v1`
`KAFKA_TOPIC_BUILD_UPDATE`	Build update topic	`ai.flowx.build.update.v1`
`KAFKA_TOPIC_BUILD_CREATE`	Build create topic	`ai.flowx.build.create.v1`
`KAFKA_TOPIC_BUILD_RESOURCE_EXPORT`	Build export topic	`ai.flowx.build.export.v1`
`KAFKA_TOPIC_BUILD_RESOURCE_IMPORT`	Build import topic	`ai.flowx.build.import.v1`
`KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATES`	Timer events updates topic	`ai.flowx.build.start-timer-events.updates.in.v1`

Consumer configuration

Environment Variable	Description	Default Value
`KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA`	Build runtime data consumer group	`build-runtime-data-group`
`KAFKA_CONSUMER_GROUPID_BUILD_CREATE`	Build create consumer group	`build-create-group`
`KAFKA_CONSUMER_GROUPID_BUILD_UPDATE`	Build update consumer group	`build-update-group`
`KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORT`	Build export consumer group	`build-resource-export-group`
`KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORT`	Build import consumer group	`build-resource-import-group`
`KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATES`	Build timer events updates consumer group	`build-start-timer-events-updates-group`
`KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA`	Build runtime data consumer threads	`2`
`KAFKA_CONSUMER_THREADS_BUILD_UPDATE`	Build update consumer threads	`4`
`KAFKA_AUTH_EXCEPTION_RETRY_INTERVAL`	Auth exception retry interval (seconds)	`10`

Process topics

Environment Variable	Description	Default Pattern
`KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`	Process start for event topic	`ai.flowx.core.trigger.start-for-event.process.v1`
`KAFKA_TOPIC_PROCESS_STARTBYNAME_IN`	Process start by name topic	`ai.flowx.core.trigger.start-by-name.process.v1`
`KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT`	Process start by name out topic	`ai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1`
`KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET`	Set timer schedule topic	`ai.flowx.core.trigger.set.timer-event-schedule.v1`
`KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP`	Stop timer schedule topic	`ai.flowx.core.trigger.stop.timer-event-schedule.v1`

Environment Variable	Description	Default Pattern
`KAFKA_TOPIC_AUDIT_OUT`	Audit topic	`ai.flowx.core.trigger.save.audit.v1`
`KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE`	Events gateway messages topic	`ai.flowx.eventsgateway.receive.copyresource.v1`

Scheduler configuration

The Runtime Manager scheduler times out stalled build import/export sessions:

Environment Variable	Description	Default Value
`FLOWX_SCHEDULER_BUILDTIMEOUT`	Build import/export timeout, in seconds	`14400`
`FLOWX_SCHEDULER_BUILDIMPEXTIMEOUTCRON`	Build import/export timeout check cron	`0 /10 * * *`

A build import or export that stays in progress longer than FLOWX_SCHEDULER_BUILDTIMEOUT is moved to IMPORT_TIMEOUT or EXPORT_TIMEOUT. The default of 14400 seconds is 4 hours. FLOWX_SCHEDULER_BUILDIMPEXTIMEOUTCRON controls how often the check runs, every 10 minutes by default.

Raise FLOWX_SCHEDULER_BUILDTIMEOUT if large builds are legitimately being marked as timed out before they finish. The equivalent timeouts for application version import/export are configured on the Application Manager. See Application Manager scheduler configuration.

Authentication configuration

Security type

Environment Variable	Description	Default Value
`SECURITY_TYPE`	Security type	`oauth2`

Resource server (opaque-token introspection)

In 5.1.x, the Runtime Manager validates access tokens using opaque-token introspection against the identity provider’s introspect endpoint.

Environment Variable	Description	Default Value
`SECURITY_OAUTH2_BASE_SERVER_URL`	OAuth2 server base URL
`SECURITY_OAUTH2_REALM`	OAuth2 realm name
`SECURITY_OAUTH2_CLIENT_CLIENT_ID`	Client ID for token introspection
`SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`	Client secret for token introspection

The introspection URI is derived automatically: ${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token/introspect

Service account configuration

Environment Variable	Description	Default Value
`SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`	Service account client ID	`flowx-runtime-manager-sa`
`SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`	Service account client secret	sensitive
`SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI`	Provider token URI	`${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token`

File storage configuration

Environment Variable	Description	Example Value
`APPLICATION_FILE_STORAGE_S3_SERVER_URL`	S3-compatible storage server URL	`http://minio:9000`
`APPLICATION_FILE_STORAGE_S3_ACCESS_KEY`	S3 access key	sensitive
`APPLICATION_FILE_STORAGE_S3_SECRET_KEY`	S3 secret key	sensitive

S3-compatible storage is used for storing application files, exports, and imports. The Runtime Manager supports MinIO, AWS S3, and other S3-compatible storage solutions.

Temporary storage for build exports and imports

Runtime Manager uses the container’s /tmp directory as working space for build exports and imports. It writes each exported resource and assembles the export archive in /tmp before uploading it to S3-compatible storage, and it unpacks imported builds there. Size /tmp to hold your largest build both unpacked and as a zip archive, for every export or import that runs at the same time. Builds exported with binary files included are larger. When the container runs with a read-only root filesystem, mount a writable volume at /tmp. Prefer a disk-backed emptyDir: a memory-backed one (medium: Memory) counts against the container’s memory limit. To increase the volume, override the Runtime Manager volumes in your Helm values:

services:
  runtime-manager:
    extraVolumes:
      - name: tmpdir
        emptyDir:
          sizeLimit: 2Gi
    extraVolumeMounts:
      - name: tmpdir
        mountPath: /tmp
        readOnly: false

If your Runtime Manager values aren’t nested under services, set extraVolumes and extraVolumeMounts at the top level of those values instead.

extraVolumes and extraVolumeMounts are lists, so your values replace the whole list. Include any other volumes the Runtime Manager already mounts.

Ingress configuration

The Runtime Manager uses the standard FlowX.AI ingress pattern with three separate ingress configurations. For complete setup instructions including the full ingress template, CORS configuration, and troubleshooting, see the Ingress Configuration Guide.

Public ingress

Service-specific values for Runtime Manager Public:

Ingress name: runtime-manager-public
Service path: /rtm/api/runtime(/|$)(.*)
Service name: runtime-manager
Rewrite target: /api/runtime/$2
Fx-Workspace-Id: Required

Admin ingress

Service-specific values for Runtime Manager Admin:

Ingress name: runtime-manager-admin
Service path: /rtm/api/build-mgmt(/|$)(.*)
Service name: runtime-manager
Rewrite target: /api/build-mgmt/$2
Fx-Workspace-Id: Required

Admin instances ingress

Service-specific values for Runtime Manager Admin Instances:

Ingress name: runtime-manager-admin-instances
Service path: /rtm/api/(runtime|runtime-internal)/(.*)
Service name: runtime-manager
Rewrite target: /api/$1/$2
Fx-Workspace-Id: Required

Complete Ingress Configuration

View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.

Note: Replace placeholders in environment variables with the appropriate values for your environment before starting the service.

Troubleshooting

Common issues

Database connection failures

Symptoms: Service fails to start with database connection errors.Solutions:

Verify the PostgreSQL database exists and is accessible
Check that the database user has appropriate permissions
Ensure network connectivity between the pod and PostgreSQL service
Verify the JDBC URL format is correct
For MongoDB, confirm the replica set is healthy and retryWrites=false is set in the connection URI

Kafka publishing failures

Symptoms: Messages not reaching consumers, runtime data not syncing between Admin and Runtime Manager.Solutions:

Verify that KAFKA_TOPIC_BUILD_RUNTIMEDATA resolves to the same value in both Admin and Runtime Manager
Check that KAFKA_TOPIC_NAMING_ENVIRONMENT is consistent across services
Ensure Kafka broker addresses are correct and reachable
Review consumer group IDs for conflicts with other deployments
Check Kafka logs for authorization or connectivity errors

Service account authentication errors

Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:

Verify the Keycloak service account (flowx-runtime-manager-sa) is properly configured
Check that client secrets match between configuration and Keycloak
Ensure the service account has required roles assigned
Confirm SECURITY_TYPE is set to oauth2 (default for 5.1.x)
Verify the OAuth2 base server URL, realm, and token introspection URI are accessible

Build exports fail with No space left on device

Symptoms: Some build exports or imports fail with No space left on device while others succeed, and the failures look random.Solutions:

Check the size of the volume mounted at /tmp in the Runtime Manager pod
Increase its sizeLimit as described in Temporary storage for build exports and imports
Switch a memory-backed emptyDir (medium: Memory) to a disk-backed one
To free the space right away, replace the Runtime Manager pods, for example with kubectl rollout restart. An emptyDir volume is emptied only when its pod is removed, not when the container restarts.

Application Manager

Companion service sharing the same container image and Helm chart

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup

Microservices

Plugins

Observability

Access management

Runtime manager setup

Infrastructure prerequisites

Dependencies

Change the application name

Core service configuration

Database configuration

PostgreSQL (Application data)

MongoDB (Runtime data)

Redis configuration

Kafka configuration

Kafka connection

Kafka OAuth authentication

Kafka topics

Build topics

Consumer configuration

Process topics

Other topics

Scheduler configuration

Authentication configuration

Security type

Resource server (opaque-token introspection)

Service account configuration

File storage configuration

Temporary storage for build exports and imports

Ingress configuration

Public ingress

Admin ingress

Admin instances ingress

Complete Ingress Configuration

Troubleshooting

Common issues

Application Manager

Redis Configuration

Kafka Authentication

IAM Configuration

​Infrastructure prerequisites

​Dependencies

​Change the application name

​Core service configuration

​Database configuration

​PostgreSQL (Application data)

​MongoDB (Runtime data)

​Redis configuration

​Kafka configuration

​Kafka connection

​Kafka OAuth authentication

​Kafka topics

​Build topics

​Consumer configuration

​Process topics

​Other topics

​Scheduler configuration

​Authentication configuration

​Security type

​Resource server (opaque-token introspection)

​Service account configuration

​File storage configuration

​Temporary storage for build exports and imports

​Ingress configuration

​Public ingress

​Admin ingress

​Admin instances ingress

Complete Ingress Configuration

​Troubleshooting

​Common issues

​Related resources

Application Manager

Redis Configuration

Kafka Authentication

IAM Configuration

Infrastructure prerequisites

Dependencies

Change the application name

Core service configuration

Database configuration

PostgreSQL (Application data)

MongoDB (Runtime data)

Redis configuration

Kafka configuration

Kafka connection

Kafka OAuth authentication

Kafka topics

Build topics

Consumer configuration

Process topics

Other topics

Scheduler configuration

Authentication configuration

Security type

Resource server (opaque-token introspection)

Service account configuration

File storage configuration

Temporary storage for build exports and imports

Ingress configuration

Public ingress

Admin ingress

Admin instances ingress

Troubleshooting

Common issues

Related resources