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"
- Names are DNS labels.
- Writes to the main resource ignore
status. Controllers writestatusthrough/status. - An update with a stale
metadata.resourceVersionfails with409, because someone else changed the object since you read it. Read it again and retry. - A change to an immutable field, such as a VPC's
cidr, is refused with422.
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.