HTTP API
Use this page when you call the API without kubectl, or need to know exactly how a request is handled. We followed the Kubernetes REST conventions, so existing clients work. Every project is a logical cluster with its own hostname.
Endpoints
| Host | What |
|---|---|
api.etorm.com | the platform: billing accounts, projects, identity |
<project>-api.etorm.com | one project; no /clusters/… in the path |
auth.etorm.com | sign-in service (OpenID Connect) |
storage.etorm.com | objects of your buckets: /v1/<project>/<bucket>/<key> (see Store objects in a bucket) |
All endpoints are dual-stack. Browsers may call the API only from the console's origin. The platform host also accepts /clusters/<project>/… paths.
Authentication
Send Authorization: Bearer etorm.<cluster>.<name>.<secret> with every request. The only paths you can call without a token are /healthz, /readyz, /livez and /version. To get a token, see Sign in and get kubectl access.
Find a resource by its path
Most requests go to a resource path. The others let you discover what the API serves, read schemas, read the audit log and query the graph.
| Path | Meaning |
|---|---|
/apis, /apis/<group>, /apis/<group>/<version> | discovery |
/apis/<group>/<version>/<plural>[/<name>[/status]] | resources (all Etorm kinds are cluster-scoped within their cluster) |
/apis/apiextensions.k8s.io/v1/customresourcedefinitions | the schema of every kind (read-only) |
/openapi/v3 | schemas for kubectl explain and server-side validation |
/clusters/<project>/etorm/v1/audit | audit log of that project (needs the audit permission) |
POST /etorm/v1/cypher | read-only graph queries (openCypher) for principals allowed the query verb |
What each HTTP method does
| HTTP | Does |
|---|---|
GET | get, list; ?watch=true streams changes |
POST | create |
PUT | replace; /status writes the status (controllers only) |
PATCH | application/merge-patch+json; apply-patch bodies are treated as a merge patch |
DELETE | delete; objects with finalizers get a deletionTimestamp first |
Filter a list and get it as a table
labelSelector:k=v,k==v,k!=v,k, comma-separated.fieldSelector=metadata.name=<name>.Accept: application/json;as=Tablereturns the columns the CRD declares (kubectl getuses it).
How objects are written
These rules differ from Kubernetes in a few places, so check them if a client that works elsewhere fails here.
metadata.nameis required and must be a DNS label. There is nogenerateName.- The server manages
uid,resourceVersion,generation(+1 when the spec changes),creationTimestampanddeletionTimestamp. - A write with a stale
resourceVersionis409 Conflict. Someone changed the object after you read it, so read it again and retry. - Writes to the main resource ignore
status. Writes to/statusignore everything else. - Unknown fields are rejected, not pruned as Kubernetes does. We reject them so that a misspelt field fails your request instead of disappearing.
Errors
A failed request returns a Status object with reason, code and message.
| Code | Reason | Usually |
|---|---|---|
| 400 | BadRequest | malformed request |
| 401 | Unauthorized | missing, expired or revoked token |
| 403 | Forbidden | not allowed, or a quota is reached |
| 404 | NotFound | no such object, or no such project |
| 405 | MethodNotAllowed | not a verb of that path |
| 409 | AlreadyExists, Conflict | exists, stale resourceVersion, or still referenced |
| 422 | Invalid | the message names the field |
Try it with curl
List the VPCs of a project, then watch them change:
export API=https://acme-prod-api.etorm.com A="Authorization: Bearer $ETORM_TOKEN" curl -sS -H "$A" "$API/apis/network.etorm.com/v1alpha1/vpcs" curl -sS -H "$A" "$API/apis/network.etorm.com/v1alpha1/vpcs?watch=true" -N
More in Call the API directly.