Guides / Operate

Call the API directly

You can call the API from a shell script or from a language that has no Kubernetes client. It follows the Kubernetes REST conventions, so any HTTP client works. These examples use curl.

Pick an endpoint and authenticate

Each project has its own endpoint. The platform cluster, with billing accounts and projects, is at https://api.etorm.com. Send your token as a bearer token on every request.

export API=https://acme-prod-api.etorm.com      # a project; the platform is https://api.etorm.com
curl -sS -H "Authorization: Bearer $ETORM_TOKEN" "$API/apis"

The probes /healthz, /readyz, /livez and /version need no token. Everything else does, and there is no anonymous access. Browsers may call the API only from the console's origin.

Create, read, update and delete an object

This sequence creates a VPC, reads it, lists VPCs by label, changes its MTU with a merge patch and deletes it.

A="Authorization: Bearer $ETORM_TOKEN"
R=apis/network.etorm.com/v1alpha1/vpcs

curl -sS -H "$A" -H "Content-Type: application/json" -X POST "$API/$R"   -d '{"apiVersion":"network.etorm.com/v1alpha1","kind":"VPC","metadata":{"name":"lan"},"spec":{}}'
curl -sS -H "$A" "$API/$R/lan"
curl -sS -H "$A" "$API/$R?labelSelector=env=prod"
curl -sS -H "$A" -H "Content-Type: application/merge-patch+json" -X PATCH "$API/$R/lan" -d '{"spec":{"mtu":1300}}'
curl -sS -H "$A" -X DELETE "$API/$R/lan"

Watch for changes

A watch keeps the connection open, and changes arrive as they happen.

curl -sSN -H "Authorization: Bearer $ETORM_TOKEN" "$API/$R?watch=true"

Watching needs read access to the whole resource type in that project. Lists in the platform cluster are filtered to what you may read.

Get table output and the schema

curl -sS -H "Authorization: Bearer $ETORM_TOKEN" -H "Accept: application/json;as=Table" "$API/$R"
curl -sS -H "Authorization: Bearer $ETORM_TOKEN" "$API/apis/apiextensions.k8s.io/v1/customresourcedefinitions/vpcs.network.etorm.com"

The second call returns the CRD, the normative schema of the resource: field types, limits, defaults and descriptions. The console builds its create and edit wizards from it, and kubectl explain reads the same schemas.

Read an error

A failure comes back as a Status object with reason, code and message. Check reason in code and show message to people.

{"kind":"Status","status":"Failure","reason":"Invalid","code":422,"message":"…"}

Next

HTTP API lists every path, verb and error, and Resources lists every kind.