Skip to content
podmaker docs

Architecture

podmaker is a control plane plus a set of focused services that turn a declarative plan into running infrastructure and keep it reconciled.

The big picture

            podmakerctl (CLI)            Browser (panel)
                  │                              │
                  ▼                              ▼
        ┌───────────────────────── Control plane ─────────────────────────┐
        │  workspaces · IAM · plans · releases · audit · vault connections │
        └───────┬───────────────────────┬───────────────────────┬─────────┘
                │                        │                       │
                ▼                        ▼                       ▼
        topology-planner          vault-broker            event-bridge (NATS↔SSE)
                │                        │                       │
                ▼                        ▼                       ▼
          cloud-broker            vault-bridge-agent       metrics-consumer
          (any cloud)           (your secret manager)        (ClickHouse)
                │
     ┌──────────┼───────────┬───────────┬───────────┐
     ▼          ▼           ▼           ▼           ▼
  server     lb-ctrl     db-ctrl    cache-ctrl   mesh-ctrl
 (agent)    (nginx)     (pg/mysql)   (redis)    (WireGuard)

The control plane

The control plane is the system of record: workspaces, identity, plans, releases, audit log and vault-connection references. It exposes the panel UI and the Bearer-authed API that podmakerctl talks to, and it triggers the workflows that do the real work.

Planning and provisioning

  • topology-planner turns a parsed plan into a deterministic action list and dispatches each action to the right controller.
  • cloud-broker is a stateless translator from control-plane requests to provider adapters (Hetzner, DigitalOcean, AWS, Azure, GCP — plus BYO-SSH for existing servers). It handles discovery and provisioning.
  • Controllers each reconcile one node type:
    • db-controller — databases (primary/replica replication)
    • lb-controller — nginx load balancers rendered from topology edges
    • cache-controller — Redis (with Sentinel for replicas)
    • mesh-controller — WireGuard private mesh between nodes

The agent fabric

Every server runs an agent that enrolls with an internal CA (step-ca) on first boot and dials a regional agent-gateway over mTLS. The agent reports health and metrics via heartbeats and executes commands sent back down the same channel. This is how installs, deploys and config changes reach each box.

Secrets

  • vault-broker mints scoped, just-in-time leases against the meta-cluster vault and wraps them in a cubbyhole.
  • vault-bridge-agent runs inside your network and proxies to your own secret manager, isolated per workspace.

See Vault & Secrets for the full flow.

Events and metrics

  • event-bridge bridges NATS to SSE so the panel shows live release and log streams.
  • metrics-consumer durably reads the metrics stream and batches samples into ClickHouse.

Heritage

podmaker began as a single-binary panel (cmd/podmaker) that ran the whole site-hosting experience — sites, databases, deploys, pipelines, backups — from one Go binary backed by one Postgres database. The multi-service control plane above is the multi-tenant, multi-cloud evolution of that core.