Getting started with kstack
What kstack is, what a node is, and the order things happen in.
kstack is a hosting control plane. It holds the desired state of everything you sell — websites, DNS zones, mailboxes, databases, machines and AI endpoints — and agents on your nodes make the machines match it.
The two halves
The control plane is a Rust service over PostgreSQL. It is the single source of truth. It writes what should exist and returns; it never opens an SSH session to a node and never runs a command on one.
The agent runs on every node. Each cycle it fetches the manifest version it should be running, observes what is actually on the box, plans the difference, validates it, applies it and reports back.
That split is why drift correction, crash recovery and "rebuild this node from bare metal" are not features — they are the same code path as an ordinary change.
What a node is
A node is a Debian stable machine with cgroup v2 that has been given one or more roles. The role decides what the agent converges on it.
| Role | What it runs |
|---|---|
web |
Tenant site containers, the web server, per-site quotas |
database |
Shared MariaDB / PostgreSQL instances with per-customer grants |
mail |
Postfix, Dovecot, rspamd, and webmail at mail.<domain> |
dns |
PowerDNS on a Postgres backend, transferring to secondaries |
backup |
restic targets, per-tenant keys |
analytics |
ClickHouse — the tenant-facing metric and log sink |
Mail always runs on its own nodes, never beside web: different IP reputation, different scaling curve, different attack surface.
The order things happen in
- Install the control plane and its Postgres.
- Enrol a node and give it a role. The agent connects outbound — you do not open a port to it.
- Create a plan, or add one of the ready-made plans, one per kind.
- Point your billing at the provisioning API. If that is Zephyr, there is no integration work.
- An order arrives, and the resources its plan grants are created.
What to read next
- The resource model — the thirteen types and the one lifecycle they share.
- Plans, locations and what is sellable — how a plan becomes something a billing system can offer.
- Billing with Zephyr — what the provisioning contract expects from each side.