Skip to main content
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

​
Change the application name

Environment VariableDescriptionExample Value
SPRING_APPLICATION_NAMEService identifier used for service discovery and loggingruntime-manager
Default Value: application-manager -> must be changed to runtime-manager

​
Core service configuration

Environment VariableDescriptionExample Value
FLOWX_ENVIRONMENT_NAMEEnvironment identifier (dev, staging, prod, etc.)pr
LOGGING_CONFIG_FILEPath to logging configuration filelogback-spring.xml
MULTIPART_MAX_FILE_SIZEMaximum file size for uploads25MB
MULTIPART_MAX_REQUEST_SIZEMaximum total request size25MB

​
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 VariableDescriptionExample Value
SPRING_DATASOURCE_URLJDBC URL for PostgreSQL connectionjdbc:postgresql://postgresql:5432/app_manager
SPRING_DATASOURCE_USERNAMEPostgreSQL usernameflowx
SPRING_DATASOURCE_PASSWORDPostgreSQL passwordsensitive

​
MongoDB (Runtime data)

Environment VariableDescriptionExample Value
SPRING_DATA_MONGODB_URIURI for MongoDB connectionmongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-headless:27017/${DB_NAME}?retryWrites=false
DB_NAMEMongoDB database nameapp-runtime
DB_USERNAMEMongoDB usernameapp-runtime
DB_PASSWORDMongoDB passwordsensitive

​
Redis configuration

Runtime Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables. Quick reference:
Environment VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
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 VariableDescriptionExample Value
SPRING_KAFKA_BOOTSTRAPSERVERSKafka broker addresseskafka-flowx-kafka-bootstrap:9092
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment prefix for Kafka topics

​
Kafka OAuth authentication

Environment VariableDescriptionDefault Value
KAFKA_OAUTH_CLIENT_IDOAuth client IDkafka
KAFKA_OAUTH_CLIENT_SECRETOAuth client secretkafka-secret
KAFKA_OAUTH_TOKEN_ENDPOINT_URIOAuth token endpointkafka.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 VariableDescriptionDefault Pattern
KAFKA_TOPIC_BUILD_RUNTIMEDATABuild runtime data topic (consumed only by Runtime Manager)ai.flowx.build.runtime-data.v1
KAFKA_TOPIC_BUILD_UPDATEBuild update topicai.flowx.build.update.v1
KAFKA_TOPIC_BUILD_CREATEBuild create topicai.flowx.build.create.v1
KAFKA_TOPIC_BUILD_RESOURCE_EXPORTBuild export topicai.flowx.build.export.v1
KAFKA_TOPIC_BUILD_RESOURCE_IMPORTBuild import topicai.flowx.build.import.v1
KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATESTimer events updates topicai.flowx.build.start-timer-events.updates.in.v1

​
Consumer configuration

Environment VariableDescriptionDefault Value
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATABuild runtime data consumer groupbuild-runtime-data-group
KAFKA_CONSUMER_GROUPID_BUILD_CREATEBuild create consumer groupbuild-create-group
KAFKA_CONSUMER_GROUPID_BUILD_UPDATEBuild update consumer groupbuild-update-group
KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORTBuild export consumer groupbuild-resource-export-group
KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORTBuild import consumer groupbuild-resource-import-group
KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATESBuild timer events updates consumer groupbuild-start-timer-events-updates-group
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATABuild runtime data consumer threads2
KAFKA_CONSUMER_THREADS_BUILD_UPDATEBuild update consumer threads4
KAFKA_AUTH_EXCEPTION_RETRY_INTERVALAuth exception retry interval (seconds)10

​
Process topics

Environment VariableDescriptionDefault Pattern
KAFKA_TOPIC_PROCESS_STARTFOREVENT_INProcess start for event topicai.flowx.core.trigger.start-for-event.process.v1
KAFKA_TOPIC_PROCESS_STARTBYNAME_INProcess start by name topicai.flowx.core.trigger.start-by-name.process.v1
KAFKA_TOPIC_PROCESS_STARTBYNAME_OUTProcess start by name out topicai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1
KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SETSet timer schedule topicai.flowx.core.trigger.set.timer-event-schedule.v1
KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOPStop timer schedule topicai.flowx.core.trigger.stop.timer-event-schedule.v1

​
Other topics

Environment VariableDescriptionDefault Pattern
KAFKA_TOPIC_AUDIT_OUTAudit topicai.flowx.core.trigger.save.audit.v1
KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGEEvents gateway messages topicai.flowx.eventsgateway.receive.copyresource.v1
For the full list of application resource topics (export, import, sync, resource usages, etc.), see the Application Manager Kafka configuration.

​
Authentication configuration

​
Security type

Environment VariableDescriptionDefault Value
SECURITY_TYPESecurity typeoauth2

​
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 VariableDescriptionDefault Value
SECURITY_OAUTH2_BASE_SERVER_URLOAuth2 server base URL
SECURITY_OAUTH2_REALMOAuth2 realm name
SECURITY_OAUTH2_CLIENT_CLIENT_IDClient ID for token introspection
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETClient 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 VariableDescriptionDefault Value
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account client IDflowx-runtime-manager-sa
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secretsensitive
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URIProvider token URI${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token

​
File storage configuration

Environment VariableDescriptionExample Value
APPLICATION_FILE_STORAGE_S3_SERVER_URLS3-compatible storage server URLhttp://minio:9000
APPLICATION_FILE_STORAGE_S3_ACCESS_KEYS3 access keysensitive
APPLICATION_FILE_STORAGE_S3_SECRET_KEYS3 secret keysensitive
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.

​
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

Symptoms: Service fails to start with database connection errors.Solutions:
  1. Verify the PostgreSQL database exists and is accessible
  2. Check that the database user has appropriate permissions
  3. Ensure network connectivity between the pod and PostgreSQL service
  4. Verify the JDBC URL format is correct
  5. For MongoDB, confirm the replica set is healthy and retryWrites=false is set in the connection URI
Symptoms: Messages not reaching consumers, runtime data not syncing between Admin and Runtime Manager.Solutions:
  1. Verify that KAFKA_TOPIC_BUILD_RUNTIMEDATA resolves to the same value in both Admin and Runtime Manager
  2. Check that KAFKA_TOPIC_NAMING_ENVIRONMENT is consistent across services
  3. Ensure Kafka broker addresses are correct and reachable
  4. Review consumer group IDs for conflicts with other deployments
  5. Check Kafka logs for authorization or connectivity errors
Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:
  1. Verify the Keycloak service account (flowx-runtime-manager-sa) is properly configured
  2. Check that client secrets match between configuration and Keycloak
  3. Ensure the service account has required roles assigned
  4. Confirm SECURITY_TYPE is set to oauth2 (default for 5.1.x)
  5. Verify the OAuth2 base server URL, realm, and token introspection URI are accessible

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
Last modified on March 20, 2026