Low Level Design: Tenant Provisioning Service

In a SaaS product, onboarding a new customer involves far more than creating a database row. The tenant provisioning service orchestrates every resource allocation step — database schema creation, object storage bucket setup, compute namespace assignment, DNS configuration, and default config seeding — in a reliable, repeatable workflow that handles partial failures gracefully.

Tenant Schema

CREATE TABLE tenants (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug        VARCHAR(63) NOT NULL UNIQUE,  -- used as subdomain: {slug}.app.example.com
  plan        ENUM('starter','growth','enterprise') NOT NULL DEFAULT 'starter',
  status      ENUM('pending','provisioning','active','suspended','deprovisioned') NOT NULL DEFAULT 'pending',
  region      VARCHAR(32) NOT NULL DEFAULT 'us-east-1',
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  suspended_at TIMESTAMPTZ,
  deprovisioned_at TIMESTAMPTZ
);

Provisioning State Machine

Tenant lifecycle follows a strict state machine to make status unambiguous and to give the provisioning workflow a clear re-entry point on failure:

• pending — record created, provisioning not yet started (e.g. waiting for payment confirmation).
• provisioning — active provisioning workflow is running. If the service crashes mid-flight, the workflow resumes from the last completed step on restart.
• active — all resources provisioned, tenant can log in and use the product.
• suspended — soft block: data retained, all API requests return HTTP 402 or 403, tenant cannot log in. Triggered by payment failure or policy violation.
• deprovisioned — permanent end state after offboarding workflow completes.

Provisioning Workflow Steps

The provisioning workflow executes these steps in order. Each step is idempotent — re-running a completed step is a no-op — so the workflow engine can safely retry from the last failed step:

1. Create database schema or namespace. In a shared-schema model: add the tenant_id to the tenants table and rely on row-level filters. In a schema-per-tenant model: CREATE SCHEMA tenant_{slug} and run migrations against it. In a DB-per-tenant model: provision a new database instance (typically reserved for enterprise plans).
2. Provision S3 bucket. Create a bucket named tenant-{id}-{region}, apply a bucket policy scoped to the tenant IAM role, enable server-side encryption, and configure lifecycle rules per the plan quota.
3. Allocate Kubernetes namespace. Create namespace tenant-{slug}, apply resource quotas (CPU, memory limits from the plan), create a service account, and bind the appropriate RBAC roles.
4. Configure DNS subdomain. Create a CNAME record {slug}.app.example.com pointing to the shared ingress. Verify propagation before marking the step complete.
5. Seed default configuration. Write plan-appropriate feature flags, rate limits, and default settings to the config service under the namespace tenant.{id}.
6. Transition to active. Update status = 'active', record activated_at, send welcome email, emit a tenant.provisioned event to the event bus for downstream consumers (analytics, CRM sync).

Quota Management

Each plan defines hard quotas stored in a plan_quotas table: storage bytes, API calls per month, and seat count. A quota service tracks consumption in real time using Redis counters (incremented on every API call, reset on the billing cycle boundary). When consumption crosses 80% of a quota, a warning notification is sent. At 100%, the relevant API surface returns HTTP 429 or rejects new uploads until the tenant upgrades or the cycle resets.

Tenant Suspension

Suspension is a soft block: all tenant data is retained and all infrastructure remains allocated. The suspension record sets suspended_at and the authentication middleware checks the tenant status on every login and API request. Suspension is reversible instantly — a billing event or admin action sets status = 'active' again with no reprovisioning required.

Offboarding Workflow

Offboarding follows a three-phase process to balance data safety with resource reclamation:

1. Data export. Generate a full export of the tenant data (database dump, S3 contents) and make a signed download URL available to the account owner for 30 days. Set status = 'suspended' immediately so no new data can be written.
2. 30-day hold. All resources remain allocated but inaccessible. This window allows the tenant to reconsider or retrieve their export. A scheduled job checks daily for holds that have expired.
3. Permanent deletion. After the hold period: drop the database schema or terminate the database instance, delete the S3 bucket, delete the Kubernetes namespace, remove the DNS record, purge config entries. Set status = 'deprovisioned' and deprovisioned_at = now(). The tenant row itself is retained permanently for billing and audit records.

Multi-Tenant Isolation Strategies

The right isolation model depends on the number of tenants and their security requirements:

• Shared schema with tenant_id filter. All tenants share the same tables. Every query must include WHERE tenant_id = ?. Cheapest to operate, highest risk of a missing filter leaking cross-tenant data. Mitigated by row-level security (RLS) enforced in the database, not the application layer.
• Schema-per-tenant. Each tenant gets a dedicated PostgreSQL schema. Migrations must be applied across all schemas. Provides strong isolation with moderate operational overhead. Good up to ~1,000 tenants per database instance.
• DB-per-tenant. Each tenant gets a dedicated database instance. Maximum isolation, suitable for enterprise customers with compliance requirements. High cost — typically reserved for high-ARPU tenants on enterprise plans.

Interview Talking Points

• How do you handle a provisioning step failing halfway? Use a saga pattern with compensating transactions — if step 3 (Kubernetes namespace) fails, the compensating transaction deletes the S3 bucket created in step 2 and the DB schema from step 1, then sets status back to pending for retry.
• How do you enforce tenant isolation at the query layer? PostgreSQL row-level security policies tied to the application role set with SET app.current_tenant_id = ? at connection time. The database enforces the filter even if the application forgets to include it.
• How do you scale to 100,000 tenants? Shared schema with RLS for the long tail; offer schema-per-tenant or DB-per-tenant as paid upgrades for compliance-sensitive customers.

{ “@context”: “https://schema.org”, “@type”: “FAQPage”, “mainEntity”: [ { “@type”: “Question”, “name”: “What is a tenant provisioning service in system design?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “A tenant provisioning service automates end-to-end onboarding of new SaaS customers: creating database schemas, IAM resources, billing subscriptions, feature flag defaults, and integrations. It also handles offboarding with data export and permanent deletion, using idempotent steps in a durable workflow engine.” } }, { “@type”: “Question”, “name”: “What are the steps in a tenant onboarding workflow?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “Validate input, allocate tenant ID, provision data store and run migrations, create IAM roles and admin user, configure billing, apply feature flags, provision integrations, send welcome email, then mark tenant ACTIVE. Each step is idempotent with persisted completion state so a crash resumes from the last checkpoint.” } }, { “@type”: “Question”, “name”: “What are the tradeoffs between shared schema, schema-per-tenant, and DB-per-tenant multi-tenancy?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “Shared schema: lowest cost, highest blast-radius risk and cross-tenant data leak potential. Schema-per-tenant: strong logical isolation, connection pool pressure at scale. DB-per-tenant: strongest isolation and compliance, highest cost and operational complexity. Most SaaS platforms use shared schema for SMB and DB/schema-per-tenant for enterprise tiers.” } }, { “@type”: “Question”, “name”: “How do you design tenant offboarding and data deletion?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “Soft-delete the tenant immediately (SUSPENDED, block API calls), offer a data export window, cancel billing, then hard-delete all data (schema, buckets, search indices) via a tenant.deleted event after the grace period. Retain a minimal tombstone record for compliance. Use a workflow engine to ensure all deletion steps complete.” } } ] }

See also: Netflix Interview Guide 2026: Streaming Architecture, Recommendation Systems, and Engineering Excellence

See also: Atlassian Interview Guide

See also: Shopify Interview Guide