Skip to main content

Multi-tenancy (optional)

By default a Orchestrate install serves one organization. If you run Orchestrate as a service for several organizations, the install can host them all, each isolated from the others.

tenancy.modeWhat it is
single (default)One organization per install. Nothing on this page applies.
saasMany organizations on one install, isolated by PostgreSQL row-level security.

Switching back to single turns the row-level security off again.

Before you switch

SaaS mode is new and optional. Contact us before you switch an install that holds real data, and try it on a separate install first.

How isolation works​

Every row that belongs to an organization carries its organization, and every such table has a row-level security policy. In SaaS mode, the API switches those policies on and forces them at start-up, and every service sets the caller's organization at the start of each database transaction. A row is visible only to its own organization, or to the platform itself.

Who a request acts for comes from its credential:

CallerOrganization
A console user who belongs to one organizationThat organization
A console user who belongs to severalThe one chosen in the console's organization switcher. With none chosen, the request sees nothing.
A user whose token names an organizationThat organization
A platform operatorThe whole platform, or one organization when they choose it
A personal, project or agent keyThe key's organization
Hosted chats, channel webhooks and other public routesThe organization of the chat, channel or object the address names

A request starts bound to nothing, and sees nothing, until its credential binds it. A database connection that never sets an organization sees no rows at all. Shared catalog rows, such as the model catalog, clusters and install-wide policies, are visible to every organization, and only the platform can change them.

Roles​

  • Platform operator, the realm role platform-operator (tenancy.operatorRole). Sees every organization, onboards and offboards them, and manages the shared model catalog and install-wide policies. In SaaS mode the platform admin role on its own no longer reaches every organization: an admin without the operator role is an ordinary user, bounded by their organization.
  • Organization admin, an admin membership on the organization, as on any install. Manages its members, folders, projects, settings, its own custom policies and budgets, and reads its own audit events.

Organization lifecycle​

Platform operators manage organizations on Platform in the console.

ActionWhat happens
OnboardCreates the organization, its first admin and a first project. With tenancy.keycloakOrganizations, also a Keycloak organization.
Suspend and ResumeRefuse, or stop refusing, every member, key and agent of the organization.
OffboardFor good: the organization is marked as offboarding and every personal, project and agent key of it is revoked. You must type its id to confirm.
PurgeDeletes an offboarding organization's data outside the database, then its rows from every table, then the organization.
Coming

Before any row is deleted, a purge removes the organization's data outside the database: its knowledge bases' vectors and files, its secrets in Vault (connector credentials and users' tokens, channel and webhook secrets, code agent credentials, SIP trunk passwords, its own external models' keys), code agent source archives, build logs and SBOMs, call recordings, and its agent and model images in the registry.

  • It is refused while anything of the organization still runs on a cluster, such as a code agent or a model deployment. Undeploy those first.
  • It is all or nothing. If a store can't be cleaned, nothing in the database is deleted, and the answer lists the problems. Fix the cause and purge again: every step can be repeated.
  • Removing images needs a registry account that can list and delete repositories (modelRegistry.purgeCredentialsSecret). Without it, the purge leaves the images and names each one it left.
  • Not removed: model weights an operator imported for the whole install, workflow history (it expires with the orchestration engine's retention), and sign-in accounts, since a person may belong to other organizations.

What each organization owns​

  • Catalog. Models and clusters can be shared with every organization, or registered for one.
  • Custom policies. An organization admin's rules apply only to that organization's projects. Install-wide rules stay with the operators.
  • Audit log. Events are filed under the organization, and an organization admin reads only their own.
  • Budgets. An organization's budget is set by a platform operator. See Usage controls.
  • Settings. Time zone, default guardrail profile, model policy, branding and MFA, set by the organization admin.

Set it up​

orchestrate-values.yaml
tenancy:
mode: saas
# keycloakOrganizations: true # needs Keycloak 26 with organizations on the realm

Orchestrate refuses to start in SaaS mode if its database role can bypass row-level security, because isolation would then be a promise and not a control.

Database backups of a SaaS install need the platform scope or a superuser, because a plain connection sees no organization's rows.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →