Tenant Plane deployment models & onboarding

This page summarizes how the Tenant Plane (TP) is deployed for customers, how it relates to the Control Plane (CP), and what to expect for databases, connectivity, and first-run onboarding.

Models at a glance

Model	Who runs TP	Typical database	Control Plane	Best for
Shared SaaS	Atlas (multi-tenant TP)	Shared Postgres / SQLite with `tenant_id` on rows	Atlas Cloud	Fastest start, no infra
Dedicated TP	Atlas (one TP + DB per customer)	Dedicated DB instance per tenant	Atlas Cloud	Isolation + managed upgrades
On-prem / customer VPC	Customer	Customer-managed Postgres or local SQLite	Reachable over HTTPS	Strict data residency
Hybrid	Customer (TP) + Atlas (CP)	Same as on-prem for operational data	Cloud AI / routing	Local data + cloud intelligence

For step-by-step guides, see Shared SaaS, On-Prem Installation, Hybrid Deployment, and Dedicated Tenant Plane.

Provisioning flow (Control Plane)

A tenant record is created in the Control Plane (admin UI, signup, or POST /api/tenants/provision).
Shared: no separate TP instance; the customer uses the shared TP URL with x-tenant-id / subdomain routing. Data is isolated logically.
Dedicated: provisioning jobs may allocate a dedicated TP endpoint and db_url on the tenant row (see internal runbooks for Terraform / ECS).
On-prem / hybrid: customer installs TP using a provisioning token from CP, then configures CONTROL_PLANE_BASE_URL, INTERNAL_SERVICE_SECRET, and TENANT_PLANE_DATABASE_URL (or SQLite file path).

Database & persistence

Deployment	Where incident/CMDB/automation data lives	Backup responsibility
Shared SaaS	Atlas-managed tenant DB (row-level tenancy)	Atlas (customer exports via product if offered)
Dedicated	Dedicated cluster / instance for that customer	Atlas + customer DR per contract
On-prem / hybrid	Customer network (`TENANT_PLANE_DATABASE_URL` or default SQLite under `data/`)	Customer — snapshot DB + TLS certs + agent keys

Operational environment variables (TP)

Set on the Tenant Plane host (see repo .env.example):

ATLAS_TP_DEPLOYMENT (or TP_DEPLOYMENT_MODE) — shared | dedicated | on_prem | hybrid. Drives in-app onboarding hints (API: /api/onboarding, /api/tenant-default).
TENANT_PLANE_DATABASE_URL — Postgres (recommended for production); omit for dev SQLite.
CONTROL_PLANE_BASE_URL — CP URL for AI routing and integration checks.
INTERNAL_SERVICE_SECRET — Shared secret for TP→CP service calls (must match CP configuration).

In-product onboarding

After login, the Tenant Plane onboarding checklist (Connect data → monitoring → SLOs → runbook → AI) is the same across models; the API augments responses with deployment (profile + hints) so operators see residency- and connectivity-specific reminders.

docs/NEW_TENANT_SPIN_UP.md — Shared vs dedicated provisioning steps in code.
docs/TP_PROVISIONING_AND_PLANNED_URLS.md — URL shapes and tenant router behavior.
docs/TP_DEPLOYMENT_RUNBOOK.md — Operations runbook for TP.