Reference

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

HostWhat
api.etorm.comthe platform: billing accounts, projects, identity
<project>-api.etorm.comone project; no /clusters/… in the path
auth.etorm.comsign-in service (OpenID Connect)
storage.etorm.comobjects 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.

PathMeaning
/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/customresourcedefinitionsthe schema of every kind (read-only)
/openapi/v3schemas for kubectl explain and server-side validation
/clusters/<project>/etorm/v1/auditaudit log of that project (needs the audit permission)
POST /etorm/v1/cypherread-only graph queries (openCypher) for principals allowed the query verb

What each HTTP method does

HTTPDoes
GETget, list; ?watch=true streams changes
POSTcreate
PUTreplace; /status writes the status (controllers only)
PATCHapplication/merge-patch+json; apply-patch bodies are treated as a merge patch
DELETEdelete; objects with finalizers get a deletionTimestamp first

Filter a list and get it as a table

How objects are written

These rules differ from Kubernetes in a few places, so check them if a client that works elsewhere fails here.

Errors

A failed request returns a Status object with reason, code and message.

CodeReasonUsually
400BadRequestmalformed request
401Unauthorizedmissing, expired or revoked token
403Forbiddennot allowed, or a quota is reached
404NotFoundno such object, or no such project
405MethodNotAllowednot a verb of that path
409AlreadyExists, Conflictexists, stale resourceVersion, or still referenced
422Invalidthe 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.