Concepts
Read this page once before the guides. It explains how Etorm is put together, so the rest of the docs make sense. The short version: the control plane is a Kubernetes-compatible API, every service (networking, compute, storage and the rest) is a set of resources in that API, and a controller works to make each resource match what you asked for.
Platform and projects
The platform API at api.etorm.com holds billing accounts, projects and identities. Everything you build lives in a project. A project is an isolated logical cluster with its own hostname, <project>-api.etorm.com.
Each project is billed to one billing account. When you create a billing account, you become its owner.
Resources: intent and status
Each object has a spec and a status. You write the spec to say what you want. A controller writes the status to say what it found, including a phase and a list of conditions.
Controllers are level-triggered. They compare the spec with what exists and fix the difference, so applying the same spec twice changes nothing.
A few rules you will run into early:
- Names are DNS labels.
- Updates are optimistic. If you send an old
resourceVersion, the update fails with409. - Some fields cannot change after creation. A change to one of them is refused with
422. - Unknown fields are rejected, not ignored, so a typo shows up at once.
The network model
- A VPC is a private Ethernet segment. It always has an IPv6 /64, and you can add an IPv4 network if you need one.
- An Account is one member's attachment to a VPC. It gets an IPv6 address. With IPv4 it also gets an IPv4 address and a MAC.
- Members join through a WireGuard tunnel to a Gateway, with a VXLAN or Geneve device inside the tunnel. You make the key pair yourself, and Etorm only ever sees the public key.
- DNSService and DHCPService run inside the VPC on its service address. You configure them with resources, so there are no servers for you to run.
- VPCs are kept apart by tunnel id, so two projects can use the same addresses.
IPv6 is the primary address family, and nothing requires IPv4. See IPv6.
Compute
- A Program is a small WebAssembly module. We check it when you register it, and it never changes after that.
- A Process runs a program with Ethernet interfaces on your VPCs. It runs only when something wakes it, such as a frame arriving on one of its interfaces. Its state survives between wake-ups. Allowances cap its memory and processor time.
- A resident process also keeps its memory between wake-ups. Use it for programs that hold connections open.
- Each interface of a process is a device of its VPC, with its own MAC and IPv6 addresses. See Write your first program.
Storage
- A Bucket holds objects of up to 32 MiB. You read and write them over HTTPS with an API token, and access follows the project's roles on the bucket's objects.
- Etorm encrypts every object with its bucket's keys before storing it. When you delete a bucket, its objects become unreadable at once. See Store objects in a bucket.
Load balancing
A LoadBalancer spreads traffic over backends with health checks. Backends can be processes, VPC members or addresses, and it works at L3 (IP packets), L4 (TCP and UDP) or L7 (HTTP).
An Ingress is where outside traffic comes in. It forwards by listener or, at L7, by host, path and header rules, and it terminates TLS with a Certificate.
Both run as Compute processes on your VPC and work over IPv6 alone. Neither holds a private key in the API. See Balance traffic and accept it at the edge.
Access: By invitation. Request access. Until the engine is enabled for your project, a new load balancer or ingress stays Pending with reason EngineNotAvailable and carries no traffic.
Database
A Database (database.etorm.com) is a PostgreSQL-compatible database, version 16, on one of your VPCs. It has one primary, which Compute runs, and every byte of it lives in a Storage bucket in your project. You connect with psql 16 from a VPC member. The password is shown once, when you create the database.
Access: By invitation. Request access.
Queues
A MessageBroker (queues.etorm.com) is a message broker for MQTT 5.0 and 3.1.1 clients at QoS 0 and 1. It offers shared topics and durable queues. Every session and queued message is kept in Storage, and one node serves the broker. The password is shown once.
Access: By invitation. Request access.
Identity and access
Everything is denied unless a role allows it. People sign in through the sign-in service and act as a principal. Automation uses service accounts.
Roles list permissions and bindings grant them. A role can never grant more than its author holds.
Tokens are shown once and expire. We store only their hashes. Every change and every refusal goes into an audit log.
Diagrams
A Diagram describes resources as blocks with typed ports. A controller creates what the diagram describes, and removes what you delete from it. You can draw a diagram on the canvas or write it as YAML.
Billing and usage
An object is metered while it is Ready, per project and month, at an hourly price set by a SKU. Amounts are integer micro-units of the account currency. Usage is recorded, and nothing is invoiced.
Clients
Any client that follows the Kubernetes API conventions works: kubectl, plain HTTP, the OpenTofu provider and the console. See the HTTP API, the command-line tool and every resource.