Reference
This page is the short version of the facts you look up while working: where to send requests, who may do what, and the limits and errors you will run into. Each section links to the page with the full detail.
Endpoints
The platform and each project have their own host. Use the platform host for billing accounts and projects, and a project's host for everything inside that project.
api.etorm.com | root cluster: billing accounts, projects, IAM |
<project>-api.etorm.com | one project's cluster; no /clusters/… in the path |
auth.etorm.com | OpenID Connect provider for the console |
console.etorm.com | web console |
All endpoints are dual-stack. CORS is limited to the console origin. Errors are Kubernetes Status objects.
Where to find the details
Every kind, with all of its fields, defaults and limits, has its own page generated from the CRDs: Resources. Objects have spec (your intent) and status (written by controllers), conditions, finalizers, resourceVersion and watch.
The other reference pages each cover one interface. The HTTP details are in HTTP API. Reading and writing objects in a bucket is in Storage HTTP API. What a program can call is in Compute program interface, and the commands are in Command-line tool. For how access, tokens and encryption fit together, read Security model. How you get each service, and its limits, is on Service access.
Identity and access
These are the kinds that decide who can sign in and what they may do.
| Kind | Purpose |
|---|---|
User | a person known to the platform (people who sign in also work without one) |
ServiceAccount | a non-human identity in the platform or a project |
Group | a set of principals that roles can be granted to |
Role | rules: apiGroups, resources, verbs, optional resourceNames |
RoleBinding | grants a role to subjects; in the platform cluster it can be limited to one billing account |
APIToken | a bearer secret for a principal; shown once; expires |
Invitation | a one-time link that grants a role when redeemed |
Everything is denied unless a binding allows it. A role can never grant more than its author holds, so nobody can hand out access they do not have. The last owner of a billing account cannot be removed. Add another owner first.
Built-in roles
These roles come with the platform. Check whether one fits before you write your own.
| Role | Grants |
|---|---|
viewer | read everything |
editor | read everything; manage services (networks, compute, storage, databases, queues, load balancing and diagrams) |
owner | everything, and grant roles |
network-admin | all verbs in the network group |
network-user | read VPCs; manage accounts |
iam-admin | manage access objects; grant only a limited set of roles |
billing-admin, billing-viewer | billing accounts, projects and usage |
Billing and usage
Four kinds carry money. A BillingAccount holds the currency (currency defaults to USD and cannot change). Each Project points at one with billingAccountRef. A SKU is a price per hour for a resource kind, and the platform manages them. The platform writes one Usage per project, SKU and month.
An object is metered while it is Ready. Amounts are integer micro-units of the currency. Nothing is invoiced. To read your numbers, see Read your usage and costs.
Names, limits and quotas
A request that would go past a quota fails with 403.
- Object names are DNS labels: lowercase letters, digits and dashes, at most 63.
- Per person: 5 billing accounts, 20 projects per account, 20 personal tokens, 100 access bindings per account. Per project: 100 service accounts, 100 roles, 500 role bindings, 500 tokens.
- Tokens expire: 90 days by default, 365 at most. Invitations: 7 days by default, 30 at most, 1 to 50 uses.
Errors and concurrency
Errors are Kubernetes Status objects. The codes you will see:
400bad request401no or bad token403not allowed or quota reached404not found409exists, staleresourceVersionor still referenced422invalid
Unknown fields are rejected, so a misspelt field fails the request instead of being dropped. A write with an old resourceVersion fails because someone changed the object after you read it. Read it again and retry. If an object is accepted but never becomes ready, see Find out why something stays Pending.
Machine-readable schemas
If you generate clients or validate manifests before you send them, read the schemas from the API. Every kind's schema, with field descriptions and limits, is served as a CRD at /apis/apiextensions.k8s.io/v1/customresourcedefinitions, and kubectl explain reads the same data. See Call the API directly.