Multiple environments and clusters
Software teams typically run multiple instances of their own application. At minimum a production environment and one or more non-production environments such as development, staging, or UAT. When that application integrates with the Timefold Platform, each environment needs its own isolated Timefold context so that test data, API keys, and configuration don’t bleed into production.
You may also run geographically distributed deployments: separate application clusters per region, per your own customer, or per business unit. This page describes how to architect for these situations.
Tenants provide isolation
The Timefold Platform uses tenants as the primary isolation boundary. Within a single platform installation:
-
Each tenant has its own models, datasets, members, API keys, webhooks, and configuration profiles.
-
Members only see the data of tenants they belong to.
-
Data from one tenant is never visible to another tenant, enforced at both the database and application level.
A member can belong to multiple tenants and switch between them in the UI.
This means you don’t need separate platform installations to isolate environments: you need separate tenants.
Recommended approach: multiple tenants on Timefold Cloud
Use Timefold Cloud and create one tenant per environment.
For example:
| Environment | Timefold tenant | API key used by |
|---|---|---|
Production |
|
Production application cluster |
Staging |
|
Staging application cluster |
Development |
|
Development environment |
Each environment of your application is configured with the API key for its corresponding tenant. Developers and QA engineers work in non-production tenants; production traffic never touches the same tenant as test datasets.
Why this is the right approach
- Zero infrastructure overhead
-
No additional clusters or infrastructure to manage. Creating a new tenant takes minutes.
- Full isolation per environment
-
Datasets, API keys, configuration profiles, and audit logs are all scoped to the tenant.
- Independent configuration
-
Each tenant can have its own configuration profiles and model settings, which lets staging mirror production configuration while development uses faster, looser solver settings.
- UI access for all environments
-
Developers can use the full Timefold UI to debug their integration in the development or staging tenant, using the same visualization and troubleshooting tools available for production.
- Member access control
-
Production access can be restricted to administrators, while developers have full access to non-production tenants.
Multiple geographic regions
If your application runs in both the EU and the US, point each regional cluster at the appropriate Timefold Cloud endpoint while still using separate tenants per environment:
| Application cluster | Timefold endpoint | Tenant |
|---|---|---|
EU production |
|
|
EU staging |
|
|
US production |
|
|
US staging |
|
|
app.timefold.ai and app-us1.timefold.ai are separate platform installations with separate tenant namespaces.
A tenant named acme-prod on the EU endpoint is independent of any identically named tenant on the US endpoint.
|
Self-hosted: single-tenant limitation
If you’re self-hosting, be aware that the self-hosted platform is single-tenant only. Each installation supports exactly one tenant. This means:
-
If you want separate production and staging environments, you must operate two separate self-hosted installations.
-
Each installation requires its own Kubernetes cluster, OpenID Connect configuration, data store, DNS name, and TLS certificate.
-
Maintenance effort roughly doubles for each additional installation.
This is one of the key operational cost differences between self-hosting and Timefold Cloud. If you’re self-hosting and need multiple environments, consider migrating to Timefold Cloud, where this is handled natively.
Summary
| Need | Recommended approach |
|---|---|
Separate dev / staging / prod environments |
One tenant per environment on Timefold Cloud |
EU and US regional isolation |
|
Other regional isolation |
Contact Timefold: a Managed service may be available for specific regions |
Fully isolated per-customer deployments (ISV model) |
One tenant per customer on Timefold Cloud, contact us if dedicated infrastructure is needed |
Self-hosted with multiple environments |
Separate platform installation per environment (high operational cost) |