Control Plane

The control plane is a small, single-instance HTTP service that owns Org lifecycle, data-plane registration, and the routing table the gateway and operator depend on. It speaks only to Postgres and to data planes via mTLS — no end-user traffic flows through it.

Responsibilities

Org provisioning — create, list, suspend, and re-region tenants.
Data-plane registry — data planes register on boot and heartbeat over mTLS.
Routing source-of-truth — the gateway pulls assignments from here and caches them with a configurable TTL.
Region pinning — an Org's region code is enforced end-to-end.

Tenant onboarding flow

REST surface

Method & path	Purpose	Auth
POST /control/orgs	Create a new Org. Body: slug, region_code, plan_tier.	Bearer (admin)
GET /control/orgs	List Orgs. Filter by region or status.	Bearer (admin)
PATCH /control/orgs/{id}/region	Move an Org to a new region. Triggers reschedule.	Bearer (admin)
POST /control/orgs/{id}/suspend	Suspend an Org (status = suspended). Gateway returns 423.	Bearer (admin)
POST /control/data-planes/register	Data plane announces itself. Body: region_code, base_url, mtls_cert_fingerprint.	mTLS
GET /control/data-planes	List registered planes (operator dashboards).	Bearer (admin)
POST /control/data-planes/{id}/heartbeat	Liveness ping. Updates last_heartbeat_at.	mTLS
GET /control/assignments	Resolve `?slug=acme` → data-plane base URL.	Bearer (gateway)

Schema

Three Postgres tables back the control plane:

SQL

CREATE TABLE control_orgs (
    id            UUID PRIMARY KEY,
    slug          TEXT NOT NULL UNIQUE,
    region_code   TEXT NOT NULL,
    plan_tier     TEXT NOT NULL DEFAULT 'free'
                   CHECK (plan_tier IN ('free','team','enterprise','government')),
    status        TEXT NOT NULL DEFAULT 'active'
                   CHECK (status IN ('active','suspended','deleted')),
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at    TIMESTAMPTZ
);

CREATE TABLE control_data_planes (
    id                       UUID PRIMARY KEY,
    region_code              TEXT NOT NULL,
    base_url                 TEXT NOT NULL,
    mtls_cert_fingerprint    TEXT NOT NULL,
    last_heartbeat_at        TIMESTAMPTZ
);

CREATE TABLE control_org_assignments (
    org_id          UUID PRIMARY KEY REFERENCES orgs(id) ON DELETE CASCADE,
    data_plane_id   UUID NOT NULL REFERENCES control_data_planes(id),
    assigned_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

Running it

Bash

tetrapus-control \
    --bind 0.0.0.0:9100 \
    --postgres-url postgres://control:secret@db:5432/tetrapus_control \
    --control-token "$(cat /etc/tetrapus/control.token)" \
    --default-region us-east-1

Gateway — reads assignments from this service.
Operator — mirrors Org CRDs into control_orgs.
tetrapus-admin tenant-plane — CLI for register/list.

Questions?

Reach out for help with integration, deployment, or custom domain codecs.

Get Started Request a Demo