Documentation Reference REST API reference API: servers Reference For: developers
API: servers
Operations of the servers tag of the native REST API.
Tenant-scoped self-service servers (section 3): create from a plan and a catalogue image, power, reinstall, resize, rescue, password reset, snapshots, console, delete; every operation is a task
GET /v1/tenants/{tenant}/serversThe tenant's servers.
CLI kyvernon servers <tenant> listParameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) includeDeletedquery boolean or nullInclude deleted servers (kept for usage).
Responses
Status Description Schema 200 OK array of ServerView 404 Not found (or not visible to the caller) ErrorBody
POST /v1/tenants/{tenant}/serversCreates a server from a plan and a catalogue image (quota-checked; a task). A generated password is in the answer, once.
CLI kyvernon servers <tenant> create <hostname> --plan <plan> --image <image>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N)
Request body
application/json: CreateServerRequest
Name Type Required Description hostnamestringyes Host name (RFC 1123 label), also the VM's name. imagestringyes Catalogue image (vm-N of the template). locationstring or nullDatacenter (datacenter-N; default: the tenant's first). passwordbooleanGenerate a password (always when no SSH keys are given); it is returned once. planstringyes Plan (vmplan-N). sshKeysarray of string SSH public keys for the default user and root. userDatastring or nullcloud-init user data (guestinfo.userdata, at most 64 KiB).
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView400 Invalid argument; the error body names the field ErrorBody404 Not found (or not visible to the caller) ErrorBody409 Conflict: the object exists, or expectedVersion is stale ErrorBody412 error.quota.exceeded (args resource, limit, current, requested), error.tenant.suspendedErrorBody
GET /v1/tenants/{tenant}/servers/{server}One server.
CLI kyvernon servers <tenant> get <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Responses
DELETE /v1/tenants/{tenant}/servers/{server}Deletes a server and its disks; its addresses go back to the pool.
CLI kyvernon servers <tenant> delete <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView404 Not found (or not visible to the caller) ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/consoleA console ticket for the server (refused while the tenant is suspended). Callers that are not users of the tenant also need Kyvernon.Tenant.Impersonate.
CLI kyvernon servers <tenant> console <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Responses
Status Description Schema 200 OK ConsoleTicketView403 Permission denied; args.privilege names the missing privilege ErrorBody412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/powerA power action: on, off, shutdown, reboot or reset.
CLI kyvernon servers <tenant> power <server> <action>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Request body
application/json: ServerPowerRequest
Name Type Required Description actionstringyes on, off (hard), shutdown (through the guest, then hard), reboot or reset.
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/reinstallReinstalls the server from an image; its addresses stay.
CLI kyvernon servers <tenant> reinstall <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Request body
application/json: ReinstallServerRequest
Name Type Required Description imagestring or nullImage (default: the current one). passwordbooleanGenerate a password (always when no SSH keys are given). sshKeysarray of string SSH public keys. userDatastring or nullcloud-init user data.
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/rescueBoots a rescue image with the server's disk attached (the server is shut down).
CLI kyvernon servers <tenant> rescue <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Request body
application/json: RescueServerRequest
Name Type Required Description imagestring or nullRescue image (default: the first catalogue entry marked rescue).
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/reset-passwordSets a new generated password (through the guest agent now, else cloud-init at the next boot); returned once.
CLI kyvernon servers <tenant> reset-password <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/resizeMoves the server to a larger plan: the disk grows (never shrinks) and the server reboots (rebootRequired: true).
CLI kyvernon servers <tenant> resize <server> <plan>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Request body
application/json: ResizeServerRequest
Name Type Required Description planstringyes The larger plan.
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView400 error.server.plan_not_largerErrorBody412 Failed precondition; the error body says which ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/snapshotsTakes a snapshot (within the snapshots quota).
CLI kyvernon servers <tenant> snapshot <server> <name>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Request body
application/json: ServerSnapshotRequest
Name Type Required Description namestringyes Snapshot name (1..=80 characters).
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView412 Failed precondition; the error body says which ErrorBody
DELETE /v1/tenants/{tenant}/servers/{server}/snapshots/{key}Removes a snapshot.
CLI kyvernon servers <tenant> remove-snapshot <server> <key>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant keypath integer (int32)yes Key of the snapshot in the snapshot tree
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView404 Not found (or not visible to the caller) ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/snapshots/{key}/revertReverts the server to a snapshot.
CLI kyvernon servers <tenant> revert-snapshot <server> <key>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant keypath integer (int32)yes Key of the snapshot in the snapshot tree
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView404 Not found (or not visible to the caller) ErrorBody
POST /v1/tenants/{tenant}/servers/{server}/unrescueEnds rescue mode and starts the server again.
CLI kyvernon servers <tenant> unrescue <server>Parameters
Name In Type Required Description tenantpath stringyes Id of the tenant (tenant-N) serverpath stringyes Id of the server of the tenant
Responses
Status Description Schema 202 Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) ServerTaskView412 Failed precondition; the error body says which ErrorBody
Guides
Previous API: scheduled-tasks Next API: system Version 0.1.