Skip to content

Global Control Plane Spec - Tenant Registry, Routing, and Licensing (v0)

Date: 2026-02-08 Status: Draft

Summary

Define a shared global control plane that manages tenant metadata, deployment targets, feature licensing, and routing metadata for tenant-isolated data planes.

Goals

  • Maintain a canonical tenant registry for all customers.
  • Track tenant deployment targets in a single AWS account using per-tenant ECS service sets.
  • Manage tenant feature entitlements (licensing/service flags).
  • Publish routing metadata snapshots for edge/router resolution.
  • Provide operational visibility across tenant fleets without exposing tenant business data.

Non-Goals (v0)

  • Billing/invoicing system of record.
  • Cross-tenant product data queries.
  • Shared multi-tenant data plane for customer workloads.

Core Responsibilities

  • Tenant lifecycle: create, suspend, reactivate, decommission.
  • Deployment registry: map tenant_id to environment, service set identifiers, and routing targets.
  • Licensing and entitlements: enable/disable capabilities per tenant plan.
  • Routing metadata publication: produce a versioned lookup artifact for edge/router layers.
  • Fleet health inventory: capture rollout state and service health summaries per tenant.

Data Model (Conceptual)

Tenant

  • tenant_id
  • status (active|suspended|decommissioning)
  • plan (starter|business|enterprise...)
  • primary_domain (optional)
  • created_at, updated_at

TenantDeploymentTarget

  • tenant_id
  • environment (dev|prod)
  • cluster_name
  • service_namespace
  • routing_target (origin ID / ALB target descriptor)
  • deployment_state
  • updated_at

TenantEntitlement

  • tenant_id
  • capability_key (e.g., connectors.aws_discovery)
  • enabled (bool)
  • source (plan|override)
  • updated_by
  • updated_at

RoutingSnapshot

  • snapshot_version
  • generated_at
  • entries (tenant/domain -> routing target)
  • checksum

API Surface (v0)

  • POST /v1/control-plane/tenants
  • GET /v1/control-plane/tenants/:tenantId
  • PATCH /v1/control-plane/tenants/:tenantId
  • POST /v1/control-plane/tenants/:tenantId/entitlements
  • GET /v1/control-plane/tenants/:tenantId/entitlements
  • POST /v1/control-plane/routing/snapshots/publish
  • GET /v1/control-plane/routing/snapshots/latest
  • GET /v1/control-plane/health/tenants

Routing Metadata Propagation

  • Control plane is the source of truth for tenant-to-target mappings.
  • Routing metadata is published as a versioned snapshot for consumption by edge/router components.
  • Router layers should use cached snapshot data and avoid per-request control-plane lookups.
  • Snapshot publication must be auditable and support rollback to previous versions.

Licensing / Service Flags

  • Entitlements are evaluated by service APIs and/or gateway middleware.
  • Integrations catalog may list available connectors globally, while instantiation actions are permission + entitlement gated.
  • Entitlement changes are auditable and have deterministic propagation behavior.

Tenancy & Isolation Requirements

  • Control plane stores tenant metadata only; customer business data remains in tenant-isolated data planes.
  • Cross-tenant data-plane access is out of scope for v0 product flows.
  • Control-plane operators can manage fleet metadata but cannot query tenant business entities through control-plane APIs.

Operational Requirements

  • Idempotent tenant provisioning operations.
  • Safe retries for deployment/entitlement updates.
  • Drift detection between registry state and deployed infrastructure.
  • Rollout waves for version updates across tenant fleets.

Audit Requirements

Audit events must be emitted for: - tenant created/suspended/reactivated/decommissioned - entitlement changed - routing snapshot published/rolled back - deployment target changed

Open Questions

  • Preferred backing store for routing snapshots (e.g., S3 object vs DynamoDB table) for router consumption.
  • Required propagation latency for entitlement changes.
  • Whether tenant domain routing is mandatory in v0 or can be phased after initial launch.