Skip to content
Documentation
Core concepts

Core concepts

A short vocabulary. Everything else in these docs builds on these ideas.

Tenant & token

You are a tenant. Sign up on the website at kubrain.dev or from the CLI (kubrain auth signup) — either way you get a Bearer token that authorizes only your operations, within your quota and budget. The server re-verifies your identity, funds, and quota on every call — it never trusts the client. You only ever see your own resources.

  • Agents connect over remote MCP (streamable HTTP) with the token in an Authorization: Bearer header.
  • The kubrain CLI hits the same HTTP API with the same token (kubrain auth login stores it in ~/.kubrain/config; or set $KUBRAIN_TOKEN).

A few tools — pricing, estimate, versions, regions, list_addons — are public (no token): the pre-signup quote surface.

One endpoint

Agents talk to one endpoint, api.kubrain.dev (override with --api / $KUBRAIN_API). There is no per-region URL to juggle — the region is a property of your VPC, not something you route to by hand.

Region & zone

  • A region is a latency domain. Clusters and VPCs live in a region.
  • A zone is a named failure domain within a region. An ha cluster spreads its 3 control-plane nodes across ≥3 zones so it survives losing one.
  • A VPC is a regional, tenant-isolated network. Clusters in the same VPC talk to each other across the region; different VPCs are isolated. A cluster inherits its region from its VPC.

Use regions to see regions and zones that actually exist, with coarse free capacity, before you place a cluster.

Idempotency

Every create/set operation is idempotent: running it twice with the same arguments is a no-op that returns the existing resource, never a duplicate. This is what lets an agent safely “ensure” a resource exists without checking first — and what makes blueprints (declarative apply) work.

Async

Provisioning, scaling, resizing, and upgrading a cluster return when the change is requested, not when it is done. The response hands you a resource in a transitional state; you poll the matching get_* view until it reaches the state you need. A resource fetched too early may look empty — re-check.

Cost is a first-class output

Anything that spends money has a dry path, so the € is visible before you commit:

  • pricing — the rate card.
  • estimate — an exact quote for a specific shape; creates nothing.
  • dry_run on create_cluster/install_addon — the plan plus the monthly delta.
  • plan_blueprint — the full diff for a whole tenant.
  • get_quota — your limits, current usage, and €/month burn.

Billing is on RAM, with two add-on dimensions (volumes, LB IPs) — see Pricing.

Names are addresses

Cluster, deployment, bucket, and zone names are lowercase letters, digits, and hyphens. A deployment name is also its namespace (kbn-<name>). Choose them deliberately — they are how everything is addressed.

Quickstart