Architecture
statedb is one application and one PostgreSQL database. The application serves the Pulumi HTTP API and the web console from the same container. It holds no state of its own, so every replica is interchangeable and a database backup is a complete backup.
statedb stores state. It never runs your Pulumi program or calls a cloud provider; the CLI does that on your machine or in CI.
Request paths
Section titled “Request paths”Pulumi CLI → /pulumi/api/* → API token or lease ─┐Browser → /api/* → console session ────┴→ PostgreSQLBrowser → /console/* → static console application| Path | Port | Purpose |
|---|---|---|
/pulumi/api/* |
8080 |
The Pulumi backend protocol |
/api/* |
8080 |
The console’s own API, behind a browser session |
/console/* |
8080 |
The console application |
/q/health/*, /q/metrics |
9000 |
Health and metrics for your platform |
The Pulumi API sits under /pulumi so that the console can own the rest of the
origin. That is why the login URL ends in /pulumi.
What happens during an update
Section titled “What happens during an update”- The CLI creates an update record, then starts it. Starting takes the stack’s
lease: one row per stack in PostgreSQL, so a second
pulumi upon the same stack is refused whichever replica it reaches. - As resources change, the CLI sends journal entries. statedb appends each batch in one transaction, in the order the CLI assigned, so a crash cannot leave half a batch behind.
- The CLI also sends engine events. These feed the console’s run history and are never used to rebuild state.
- The CLI renews the lease while it works. A lease lasts five minutes from its last renewal, so a run that dies releases its stack without anyone stepping in.
- Completing the update records its result, releases the lease, and advances the stack’s version, all in one transaction.
When the CLI next asks for the stack, statedb rebuilds the checkpoint from the latest snapshot plus the journal entries written after it.
Storage
Section titled “Storage”| Data | Role |
|---|---|
| Journal entries | The source of truth for every state change, kept in order |
| Snapshots | Full checkpoints that shorten replay; older ones are pruned |
| Engine events | Run history for the console; finished runs are compressed |
| Identity and access | Users, organizations, roles, grants, and token hashes |
| Service keyset | The encryption keys for the service-managed secrets provider |
Compaction runs in the background. It folds journal entries into a new snapshot so that reads stay fast as history grows. Compaction and updates exclude each other on the same stack through a database row lock, so a snapshot is never taken halfway through an update.
There is no queue, cache, or object store. Background work is coordinated through PostgreSQL, which is also why any number of replicas can run side by side.
Access control
Section titled “Access control”Three kinds of credential stay separate:
- A console session is an encrypted cookie issued after OpenID Connect
sign-in. It is scoped to
/api/, so the Pulumi API never sees it. - An API token identifies a person or a service account to the Pulumi API. Only its hash is stored.
- An update lease token authorizes writes to one running update on one stack.
Sessions and API tokens identify who is asking. Cedar
policies then decide what that identity may do, from its role in the
organization and any per-stack grants. A stack you cannot read answers 404,
the same as a stack that does not exist.
Authentication and access describes the roles.
Secrets
Section titled “Secrets”Stacks that use a passphrase or a cloud KMS encrypt on the client, and statedb only ever stores ciphertext. Stacks that use the service-managed provider are encrypted with a keyset held in PostgreSQL, and ciphertext is bound to its stack so it cannot be decrypted through another one.
That keyset protects a leaked checkpoint or a partial dump. It does not protect against someone who has the whole database, so use an external provider for stacks where that matters.
Design reference
Section titled “Design reference”The repository holds the detailed design, written against the code:
| Topic | Document |
|---|---|
| Modules and request flow | Architecture |
| Updates, journals, and compaction | Pulumi state lifecycle |
| Tables and invariants | Database model |
| Sessions, tokens, and Cedar | Authentication and authorization |
| Private stacks and grants | Stack visibility and grants |
| The service secrets provider | Service secrets |
| Startup migrations and upgrades | Migrations |
| Capacity, leases, and recovery | Load and recovery |
| Database credentials and RDS IAM | Database connections |
| The console | Console |
| GitHub pull request reports | GitHub PR reports |
| The native image | Native image |
| How releases are built and gated | Releases |
The design index lists them all, and Pulumi CLI compatibility explains how the protocol is tested.