{ "openapi": "3.1.0", "info": { "title": "Kyvernon native API", "description": "The first-class interface of the Kyvernon control plane. Field names are camelCase; object ids are MoRef-compatible strings (vm-42, host-7); timestamps are RFC 3339 UTC. Errors use one flat envelope with `code`, `message`, `messageId` and `args` so clients can localise (the `messageId` catalogue is on `ErrorBody`). Long-running operations return 202 with a task id. Inventory objects are `ObjectView`: a union discriminated on `kind` whose `data` follows the schema of `kyvernon_inventory::model` for that kind (snake_case fields, as stored). Version 1.1.0: typed `ObjectView` bodies, `health` on `ObjectView`, `scope` on `/v1/usage`. Version 1.1.1: `TaskView.result` is `TaskResultView` (oneOf of known operation payloads); backup request and response stand-ins are typed (`DiskSelectionView`, `BackupSessionView`, `DiskChangeInfoView`, `ApiInfoView`, `NbdExportView`, quiesce/end/invalidation enums; all additive; 1.0 clients keep working).", "contact": { "name": "GoTrust BV and Kyvernon contributors" }, "license": { "name": "Apache-2.0" }, "version": "1.1.1-m10" }, "servers": [ { "url": "/", "description": "Same origin" } ], "paths": { "/folder/{path}": { "get": { "tags": [ "datastores" ], "summary": "`GET /folder/?dcPath=&dsName=`: downloads a file (vSphere datastore HTTP\naccess; bearer, session cookie, or `vmware_cgi_ticket`; `Range` gives 206).", "operationId": "folder_get", "parameters": [ { "name": "path", "in": "path", "description": "File path below the datastore root, each segment percent-encoded", "required": true, "schema": { "type": "string" } }, { "name": "dcPath", "in": "query", "description": "Datacenter name or inventory path (`DC1`, `folder/DC1`); may be omitted when the\ndatastore name is unique.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "dsName", "in": "query", "description": "Datastore name.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream": {} } }, "206": { "description": "Partial content (the requested range)" }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "datastores" ], "summary": "`PUT /folder/?dcPath=&dsName=`: uploads a file, streamed (replacing one that is\nnot a VM disk, as vSphere does): 201 for a new file, 200 for a replaced one.", "operationId": "folder_put", "parameters": [ { "name": "path", "in": "path", "description": "Datastore path of the file (`[datastore] folder/file`, URL-encoded)", "required": true, "schema": { "type": "string" } }, { "name": "dcPath", "in": "query", "description": "Datacenter name or inventory path (`DC1`, `folder/DC1`); may be omitted when the\ndatastore name is unique.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "dsName", "in": "query", "description": "Datastore name.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "413": { "description": "Payload too large (`error.datastore_upload_too_large`, `args.limit`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "datastores" ], "summary": "`DELETE /folder/?dcPath=&dsName=`: deletes a file or folder.", "operationId": "folder_delete", "parameters": [ { "name": "path", "in": "path", "description": "Datastore path of the file (`[datastore] folder/file`, URL-encoded)", "required": true, "schema": { "type": "string" } }, { "name": "dcPath", "in": "query", "description": "Datacenter name or inventory path (`DC1`, `folder/DC1`); may be omitted when the\ndatastore name is unique.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "dsName", "in": "query", "description": "Datastore name.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/healthz": { "get": { "tags": [ "system" ], "summary": "Liveness: the process serves requests.", "operationId": "healthz", "responses": { "200": { "description": "Alive", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/metrics": { "get": { "tags": [ "system" ], "summary": "Prometheus metrics (OpenMetrics text). Requires a bearer token unless\n`metrics_anonymous` is set.", "operationId": "metrics", "responses": { "200": { "description": "Metrics", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/metrics/perf": { "get": { "tags": [ "metrics" ], "summary": "Prometheus text exposition of the newest performance samples of every host, VM and\ndatastore the caller can see (all of them for an anonymous scrape when\n`metrics_anonymous` is set).", "operationId": "prometheus", "responses": { "200": { "description": "Prometheus text format 0.0.4", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/readyz": { "get": { "tags": [ "system" ], "summary": "Readiness: the store has a leader and this node has applied its state.", "operationId": "readyz", "responses": { "200": { "description": "Ready", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Not ready", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/about": { "get": { "tags": [ "system" ], "summary": "Service information.", "operationId": "about", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/About" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/alarms": { "get": { "tags": [ "alarms" ], "summary": "Lists alarm definitions with their states.", "operationId": "list_alarms", "parameters": [ { "name": "target", "in": "query", "description": "Only alarms applicable to this target.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "alarms" ], "summary": "Defines an alarm.", "operationId": "create_alarm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlarmRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlarmView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/alarms/clear-triggered": { "post": { "tags": [ "alarms" ], "summary": "Resets triggered (non-green) alarm states to green (`ClearTriggeredAlarms`).", "operationId": "clear_triggered_alarms", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearTriggeredAlarmsRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/alarms/{id}": { "get": { "tags": [ "alarms" ], "summary": "One alarm definition with its states.", "operationId": "get_alarm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the alarm definition", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlarmView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "alarms" ], "summary": "Changes an alarm definition (`Alarm.Edit` on the alarm's scope). Absent fields keep\ntheir value; a new trigger resets the states of the alarm to gray (the next event or\nsample sets them again).", "operationId": "update_alarm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the alarm definition", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlarmRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlarmView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "alarms" ], "summary": "Deletes an alarm.", "operationId": "delete_alarm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the alarm definition", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/alarms/{id}/acknowledge": { "post": { "tags": [ "alarms" ], "summary": "Acknowledges an alarm on a target.", "operationId": "acknowledge_alarm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the alarm definition", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/audit": { "get": { "tags": [ "identity" ], "summary": "Audit log, oldest first (requires `Global.Diagnostics`). With a filter the server\nreads the log and pages over the matching records; `format=csv` exports them.", "operationId": "audit_log", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum items (default 100, maximum 1000; with `format=csv` up to 100000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Resume after this id (from `next`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "actor", "in": "query", "description": "Only this actor (user name, exact).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "action", "in": "query", "description": "Only actions that start with this text (`identity.`, `identity.user.create`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "target", "in": "query", "description": "Only records about this object id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "outcome", "in": "query", "description": "`success`, `denied` or `error`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "since", "in": "query", "description": "Only records at or after this time (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "until", "in": "query", "description": "Only records at or before this time (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Text that the actor, action, target, correlation id, client address or a detail\ncontains (case-insensitive).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "format", "in": "query", "description": "`json` (default) or `csv` (the matching records as a CSV file, no paging).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "A page of records, or `text/csv` with `format=csv`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_AuditView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/api-tokens": { "get": { "tags": [ "auth" ], "summary": "The caller's API tokens.", "operationId": "list_api_tokens", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "auth" ], "summary": "Creates an API token for the caller (shown once).", "operationId": "create_api_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/api-tokens/{id}": { "delete": { "tags": [ "auth" ], "summary": "Revokes one of the caller's API tokens.", "operationId": "delete_api_token", "parameters": [ { "name": "id", "in": "path", "description": "Id of the API token", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/config": { "get": { "tags": [ "auth" ], "summary": "What the sign-in page needs before anyone is signed in (no authentication).", "operationId": "config", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfigView" } } } } } } }, "/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "Browser password login.", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Session (possibly restricted) or MFA challenge; token responses set the kyv_refresh and kyvernon_csrf cookies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "error.auth.invalid_credentials (same answer for every reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "error.auth.origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "error.auth.rate_limited, with Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Ends the browser session (the whole token family) and clears the cookies.", "operationId": "logout", "parameters": [ { "name": "X-Kyvernon-CSRF", "in": "header", "description": "Value of the kyvernon_csrf cookie", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Logged out; cookies cleared" }, "403": { "description": "error.auth.csrf or error.auth.origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/auth/mfa": { "post": { "tags": [ "auth" ], "summary": "Second factor for a pending browser login.", "operationId": "mfa", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMfaRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "neither or both of code and recoveryCode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "error.auth.invalid_code or error.auth.mfa_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "Rate limited; `Retry-After` says when to retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/auth/password": { "post": { "tags": [ "auth" ], "summary": "Changes the caller's password: every session of the account ends and the caller gets\na new one (next stage: TOTP enrolment when still required).", "operationId": "change_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "New session; new cookies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "error.password.* (too_short, too_long, common, repetitive, sequential, contains_username, unchanged, current_incorrect)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/refresh": { "post": { "tags": [ "auth" ], "summary": "Rotates the refresh token and issues a new access token.", "operationId": "refresh", "parameters": [ { "name": "X-Kyvernon-CSRF", "in": "header", "description": "Value of the kyvernon_csrf cookie", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "New tokens; new kyv_refresh cookie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "error.auth.session_expired or error.auth.refresh_reuse (cookies cleared)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "error.auth.csrf or error.auth.origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "error.auth.refresh_race: another tab refreshed; retry once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/auth/session": { "get": { "tags": [ "auth" ], "summary": "The caller's session and stage (works for restricted sessions).", "operationId": "session", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionView" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/totp/confirm": { "post": { "tags": [ "auth" ], "summary": "Confirms TOTP enrolment with a current code; the session is re-keyed (new tokens and\ncookies) and the recovery codes are returned once.", "operationId": "totp_confirm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Authenticated; recoveryCodes present", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "error.auth.invalid_code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/totp/enrol": { "post": { "tags": [ "auth" ], "summary": "Starts TOTP enrolment (after the password change, when TOTP is not enrolled yet).", "operationId": "totp_enrol", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpEnrolResponse" } } } }, "412": { "description": "error.password_rotation_required or error.mfa.already_enrolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/auth/totp/recovery-codes": { "post": { "tags": [ "auth" ], "summary": "Replaces the caller's recovery codes (needs a current TOTP code).", "operationId": "recovery_codes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodesResponse" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/controller": { "get": { "tags": [ "backup" ], "summary": "The archives of the controller's own state (`System.Read` on the root folder): where\nthey go, when they are taken, the last run and the archives kept. Status of the\ncontroller that answers.", "operationId": "controller_backup", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerBackupStatusView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "backup" ], "summary": "Changes the schedule, target folder and retention of the archives of the controller\nstate (`Global.Settings`; audited). Kept in the replicated store over the `[backup]`\nkeys `controller_schedule`, `controller_target`, `controller_retention` and applied by\nevery controller; the folder must be absolute and creatable.", "operationId": "set_controller_backup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerBackupRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerBackupStatusView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/controller/run": { "post": { "tags": [ "backup" ], "summary": "Archives the controller's state now (`Global.Settings`; task\n`ServiceInstance.backupControllerState`, run by the leader for its own state): a\nconsistent copy of the store and the metrics, the other files of the state directory\nand the configuration, read back and checked before it counts.", "operationId": "run_controller_backup", "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/disks/{diskId}/invalidate": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/disks/{diskId}/invalidate`", "operationId": "invalidate", "parameters": [ { "name": "diskId", "in": "path", "description": "Stable disk id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidateRequestView" } } }, "required": true }, "responses": { "204": { "description": "Tracking restarted" } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/info": { "get": { "tags": [ "backup" ], "summary": "`GET /v1/backup/info`", "operationId": "info", "responses": { "200": { "description": "Backup service capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiInfoView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/points": { "get": { "tags": [ "backup" ], "summary": "The backup points in the repository, newest first (`System.Read` on the virtual\nmachine; without `vmId`, the points of every virtual machine the caller can see, and\nof deleted ones for callers who can read the root folder).", "operationId": "list_points", "parameters": [ { "name": "vmId", "in": "query", "description": "Only the backup points of this virtual machine: its instance uuid or its id (`vm-N`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BackupPointView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "backup" ], "summary": "Backs a virtual machine up to the repository now (task\n`VirtualMachine.backupToRepository`; `VirtualMachine.Provisioning.DiskRandomRead` and\n`VirtualMachine.State.CreateSnapshot` on the VM). The controller takes the backup\npoint, reads every disk over its export into the repository and writes the manifest\nwhen the session committed. Incremental when the newest point of the VM has change\nids for its disks, unless `full`. Change tracking is turned on when it is off.", "operationId": "start_backup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartBackupRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/points/{id}": { "delete": { "tags": [ "backup" ], "summary": "Deletes a backup point from the repository: its manifest and disk images\n(`Global.Settings` on the root folder; logged).", "operationId": "delete_point", "parameters": [ { "name": "id", "in": "path", "description": "Id of the backup point", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/points/{id}/restore": { "post": { "tags": [ "backup" ], "summary": "Restores a backup point. `new`: to a new virtual machine\n(`VirtualMachine.Inventory.Create` on the folder,\n`VirtualMachine.Provisioning.DiskRandomAccess` on the source; task\n`VirtualMachine.restoreBackup`). `in-place`: into the powered-off source, whose disks\nare replaced (`VirtualMachine.Config.AddNewDisk` and `VirtualMachine.Config.RemoveDisk`;\ntask `VirtualMachine.restoreBackupInPlace`; the old disks come back when it fails).\nWith `verify`, the point is then verified in quarantine.", "operationId": "restore_point", "parameters": [ { "name": "id", "in": "path", "description": "Id of the backup point", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestorePointRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/repository": { "get": { "tags": [ "backup" ], "summary": "The backup repository: configured or not, number of points (`System.Read` on the root\nfolder).", "operationId": "repository", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRepositoryView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/restores": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/restores`", "operationId": "begin_restore", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginRestoreRequest" } } }, "required": true }, "responses": { "201": { "description": "Writable NBD export for the restore target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NbdExportView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/restores/{vmId}": { "get": { "tags": [ "backup" ], "summary": "`GET /v1/backup/restores/{vmId}`: the verification state of a restored VM.", "operationId": "get_restore", "parameters": [ { "name": "vmId", "in": "path", "description": "Restored VM instance UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSession" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/restores/{vmId}/disks/{deviceKey}/finish": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/restores/{vmId}/disks/{deviceKey}/finish`", "operationId": "finish_restore", "parameters": [ { "name": "vmId", "in": "path", "description": "VM instance UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deviceKey", "in": "path", "description": "Device key", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishRestoreRequest" } } }, "required": true }, "responses": { "204": { "description": "Restore finished" } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/restores/{vmId}/verify": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/restores/{vmId}/verify`: verifies a restored VM now.", "operationId": "verify_restore", "parameters": [ { "name": "vmId", "in": "path", "description": "Restored VM instance UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifySpec" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSession" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/schedules": { "get": { "tags": [ "backup" ], "summary": "The backup schedules (`System.Read` on the root folder).", "operationId": "list_schedules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BackupScheduleView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "backup" ], "summary": "Creates a backup schedule (`Global.Settings`; audited). It backs up every virtual\nmachine of its scope at the time, UTC, keeping `retention` points per VM.", "operationId": "create_schedule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupScheduleView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/schedules/{id}": { "get": { "tags": [ "backup" ], "summary": "One backup schedule.", "operationId": "get_schedule", "parameters": [ { "name": "id", "in": "path", "description": "Schedule id (bkschedule-N).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupScheduleView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "backup" ], "summary": "Changes a backup schedule (`Global.Settings`; audited). Its next run counts from now.", "operationId": "update_schedule", "parameters": [ { "name": "id", "in": "path", "description": "Schedule id (bkschedule-N).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupScheduleView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "backup" ], "summary": "Deletes a backup schedule (`Global.Settings`; audited). Its backup points stay.", "operationId": "delete_schedule", "parameters": [ { "name": "id", "in": "path", "description": "Schedule id (bkschedule-N).", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/schedules/{id}/run": { "post": { "tags": [ "backup" ], "summary": "Runs a backup schedule now (`Global.Settings`): one backup task per virtual machine\nof its scope, as at its time. Answers the schedule with `lastRunAt` set.", "operationId": "run_schedule", "parameters": [ { "name": "id", "in": "path", "description": "Schedule id (bkschedule-N).", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupScheduleView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/sessions": { "get": { "tags": [ "backup" ], "summary": "`GET /v1/backup/sessions`", "operationId": "list_sessions", "parameters": [ { "name": "vmId", "in": "query", "description": "Filter to one VM instance UUID.", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Sessions, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BackupSessionView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/sessions`", "operationId": "begin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginBackupRequestView" } } }, "required": true }, "responses": { "201": { "description": "Session in EXPORTING", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSessionView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/sessions/{id}": { "get": { "tags": [ "backup" ], "summary": "`GET /v1/backup/sessions/{id}`", "operationId": "get_session", "parameters": [ { "name": "id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Backup session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSessionView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/sessions/{id}/disks/{deviceKey}/changed-areas": { "get": { "tags": [ "backup" ], "summary": "`GET /v1/backup/sessions/{id}/disks/{deviceKey}/changed-areas`", "operationId": "changed_areas", "parameters": [ { "name": "id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deviceKey", "in": "path", "description": "Disk device key", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "startOffset", "in": "query", "description": "Byte offset (granularity-aligned).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "maxAreas", "in": "query", "description": "Page size.", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "Changed areas page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiskChangeInfoView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/sessions/{id}/end": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/sessions/{id}/end`", "operationId": "end_session", "parameters": [ { "name": "id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndBackupRequestView" } } }, "required": true }, "responses": { "200": { "description": "Terminal session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSessionView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/sessions/{id}/keepalive": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/sessions/{id}/keepalive`", "operationId": "keepalive", "parameters": [ { "name": "id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session with extended deadline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSessionView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/settings": { "get": { "tags": [ "backup" ], "summary": "The backup settings (`System.Read` on the root folder).", "operationId": "get_settings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSettingsView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "backup" ], "summary": "Changes the backup settings (`Global.Settings`; audited). The repository must be an\nabsolute directory this controller can create, the network a quarantine network and\nthe pool a datastore. `remoteExports` is set in the configuration and ignored here.", "operationId": "put_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSettingsView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/verification": { "get": { "tags": [ "backup" ], "summary": "`GET /v1/backup/verification`: last verification run per VM.", "operationId": "verification_report", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationReport" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/backup/verification/run": { "post": { "tags": [ "backup" ], "summary": "`POST /v1/backup/verification/run`: runs the nightly job now, in the background.", "operationId": "run_verification", "responses": { "202": { "description": "Started; poll GET /v1/backup/verification" } }, "security": [ { "bearer": [] } ] } }, "/v1/catalogue/images": { "get": { "tags": [ "plans" ], "summary": "The self-service image catalogue: every entry for operators, the offered ones for\ntenant users.", "operationId": "list_catalogue", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogueImageView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/catalogue/images/{id}": { "put": { "tags": [ "plans" ], "summary": "Sets the catalogue flag and metadata of a template (`Kyvernon.Catalogue.Manage`).", "operationId": "put_catalogue", "parameters": [ { "name": "id", "in": "path", "description": "The template VM (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogueImageView" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogueImageView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "plans" ], "summary": "Removes a template from the catalogue.", "operationId": "delete_catalogue", "parameters": [ { "name": "id", "in": "path", "description": "Id of the catalogue image (a template virtual machine)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/clusters/{id}/hosts": { "post": { "tags": [ "hosts" ], "summary": "Adds a pending (disconnected) host to a cluster. The agent on that machine\nregisters with the join token and the same name to connect it.", "operationId": "add_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the cluster (`domain-cN`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddHostRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/clusters/{id}/move-hosts": { "post": { "tags": [ "hosts" ], "summary": "Moves hosts into a cluster (`Host.Inventory.EditCluster` on the cluster,\n`Host.Inventory.MoveHost` on each host). Each host must be in maintenance mode\n(`error.host.not_in_maintenance`) and have no virtual machines (`error.host_has_vms`).\nRuns as a task (`ClusterComputeResource.moveInto`).", "operationId": "move_hosts", "parameters": [ { "name": "id", "in": "path", "description": "Id of the cluster (`domain-cN`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveHostsRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/clusters/{id}/reconfigure": { "post": { "tags": [ "hosts" ], "summary": "Reconfigures cluster HA / scheduler / migration policy (`ReconfigureComputeResource_Task`).", "operationId": "reconfigure_cluster", "parameters": [ { "name": "id", "in": "path", "description": "Id of the cluster (`domain-cN`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconfigureClusterRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/content/libraries": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/libraries`", "operationId": "list_libraries", "responses": { "200": { "description": "Local content libraries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryView" } } } } } } }, "post": { "tags": [ "content" ], "summary": "`POST /v1/content/libraries`", "operationId": "create_library", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLibraryRequest" } } }, "required": true }, "responses": { "201": { "description": "Created library", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryView" } } } } } } }, "/v1/content/libraries/{id}": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/libraries/{id}`", "operationId": "get_library", "parameters": [ { "name": "id", "in": "path", "description": "Library id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryView" } } } } } }, "delete": { "tags": [ "content" ], "summary": "`DELETE /v1/content/libraries/{id}`", "operationId": "delete_library", "parameters": [ { "name": "id", "in": "path", "description": "Library id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/content/library-items": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/library-items`", "operationId": "list_items", "parameters": [ { "name": "libraryId", "in": "query", "description": "Restrict to one library.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryItemView" } } } } } } }, "post": { "tags": [ "content" ], "summary": "`POST /v1/content/library-items`", "operationId": "create_item", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLibraryItemRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryItemView" } } } } } } }, "/v1/content/library-items/{id}": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/library-items/{id}`", "operationId": "get_item", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryItemView" } } } } } }, "delete": { "tags": [ "content" ], "summary": "`DELETE /v1/content/library-items/{id}`", "operationId": "delete_item", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/content/update-sessions": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/update-sessions`", "operationId": "list_sessions", "parameters": [ { "name": "libraryItemId", "in": "query", "description": "Restrict to one library item.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateSessionView" } } } } } } }, "post": { "tags": [ "content" ], "summary": "`POST /v1/content/update-sessions`", "operationId": "create_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUpdateSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionView" } } } } } } }, "/v1/content/update-sessions/{id}": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/update-sessions/{id}`", "operationId": "get_session", "parameters": [ { "name": "id", "in": "path", "description": "Update session id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionView" } } } } } }, "delete": { "tags": [ "content" ], "summary": "`DELETE /v1/content/update-sessions/{id}`: cancel.", "operationId": "cancel_session", "parameters": [ { "name": "id", "in": "path", "description": "Update session id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } } } }, "/v1/content/update-sessions/{id}/complete": { "post": { "tags": [ "content" ], "summary": "`POST /v1/content/update-sessions/{id}/complete`", "operationId": "complete_session", "parameters": [ { "name": "id", "in": "path", "description": "Update session id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryItemView" } } } } } } }, "/v1/content/update-sessions/{id}/files": { "get": { "tags": [ "content" ], "summary": "`GET /v1/content/update-sessions/{id}/files`", "operationId": "list_session_files", "parameters": [ { "name": "id", "in": "path", "description": "Update session id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateSessionFileView" } } } } } } }, "post": { "tags": [ "content" ], "summary": "`POST /v1/content/update-sessions/{id}/files`", "operationId": "add_session_file", "parameters": [ { "name": "id", "in": "path", "description": "Update session id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUpdateSessionFileRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionFileView" } } } } } } }, "/v1/content/update-sessions/{id}/files/{name}/content": { "put": { "tags": [ "content" ], "summary": "`PUT /v1/content/update-sessions/{id}/files/{name}/content`", "operationId": "upload_session_file", "parameters": [ { "name": "id", "in": "path", "description": "Update session id", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "File name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionFileView" } } } } } } }, "/v1/customization/specs": { "get": { "tags": [ "customization" ], "summary": "`GET /v1/customization/specs`", "operationId": "list_specs", "responses": { "200": { "description": "Customization specifications", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomizationSpecView" } } } } } } }, "post": { "tags": [ "customization" ], "summary": "`POST /v1/customization/specs`", "operationId": "create_spec", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomizationSpecRequest" } } }, "required": true }, "responses": { "201": { "description": "Created specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomizationSpecView" } } } } } } }, "/v1/customization/specs/{name}": { "get": { "tags": [ "customization" ], "summary": "`GET /v1/customization/specs/{name}`", "operationId": "get_spec", "parameters": [ { "name": "name", "in": "path", "description": "Specification name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomizationSpecView" } } } } } }, "put": { "tags": [ "customization" ], "summary": "`PUT /v1/customization/specs/{name}`", "operationId": "overwrite_spec", "parameters": [ { "name": "name", "in": "path", "description": "Specification name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomizationSpecRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated specification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomizationSpecView" } } } } } }, "delete": { "tags": [ "customization" ], "summary": "`DELETE /v1/customization/specs/{name}`", "operationId": "delete_spec", "parameters": [ { "name": "name", "in": "path", "description": "Specification name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/datacenters": { "post": { "tags": [ "inventory" ], "summary": "Creates a datacenter with its folders for virtual machines, hosts, networks and\ndatastores (`Datacenter.Create` on the parent folder).", "operationId": "create_datacenter", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatacenterRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datacenters/{id}": { "delete": { "tags": [ "inventory" ], "summary": "Deletes an empty datacenter and its folders (`Datacenter.Delete` on the datacenter).\nA datacenter that still holds clusters, hosts, virtual machines, networks or\ndatastores is refused (`error.datacenter.not_empty`).", "operationId": "delete_datacenter", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datacenter", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}": { "delete": { "tags": [ "datastores" ], "summary": "Removes a datastore from every host that mounts it and from the inventory\n(`Datastore.Delete` on the datastore and `Host.Config.Storage` on each host). The files\nstay on the storage. Refused while a virtual machine has a disk on it\n(`error.datastore_file_in_use`).", "operationId": "delete_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/files": { "get": { "tags": [ "datastores" ], "summary": "Lists a folder of a datastore.", "operationId": "list_files", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path below the datastore root (`iso/ubuntu.iso`); empty for the root.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreListing" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "datastores" ], "summary": "Deletes a file or a folder with its content. Disks of virtual machines, and folders\nholding them, are refused (`FAILED_PRECONDITION`, `error.datastore_file_in_use`).", "operationId": "delete_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path below the datastore root (`iso/ubuntu.iso`); empty for the root.", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/files/content": { "get": { "tags": [ "datastores" ], "summary": "Downloads a file (streamed; `Range: bytes=a-b` gives `206`).", "operationId": "download_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path below the datastore root (`iso/ubuntu.iso`); empty for the root.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream": {} } }, "206": { "description": "Partial content (the requested range)" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "datastores" ], "summary": "Uploads a file (streamed request body; written to a temporary file and renamed into\nplace when complete).", "operationId": "upload_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path of the new file below the datastore root.", "required": true, "schema": { "type": "string" } }, { "name": "overwrite", "in": "query", "description": "Replace an existing file (never a disk of a virtual machine).", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "413": { "description": "Payload too large (`error.datastore_upload_too_large`, `args.limit`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/files/copy": { "post": { "tags": [ "datastores" ], "summary": "Copies a file on a datastore (`POST /v1/datastores/{id}/files/copy`, SOAP\n`CopyDatastoreFile_Task`). Synchronous; same-host only. Privilege\n`Datastore.FileManagement` on source and destination.", "operationId": "copy_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyMoveFileRequest" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/files/move": { "post": { "tags": [ "datastores" ], "summary": "Moves or renames a file on a datastore (`POST /v1/datastores/{id}/files/move`, SOAP\n`MoveDatastoreFile_Task`). Synchronous; same-host only. Privilege\n`Datastore.FileManagement` on source and destination.", "operationId": "move_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyMoveFileRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/folders": { "post": { "tags": [ "datastores" ], "summary": "Creates a folder on a datastore (`ALREADY_EXISTS` when the path exists).", "operationId": "make_folder", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MakeFolderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/orphan-disks": { "get": { "tags": [ "datastores" ], "summary": "Reports the disk images on a datastore that nothing references: no virtual machine,\ntemplate or snapshot names them, and they are neither an overlay nor the backing\nimage of a disk that is referenced, nor a content-library file. Report only: nothing\nis deleted. Images uploaded to make disks from are listed too; check before removing.", "operationId": "orphan_disks", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } }, { "name": "minAgeSeconds", "in": "query", "description": "Leave out files changed within this many seconds (default 300): a task may be\nmaking them right now.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrphanDiskReport" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/datastores/{id}/refresh": { "post": { "tags": [ "datastores" ], "summary": "Measures the datastore on a connected host that mounts it and stores its size and free\nspace (`System.Read` on the datastore). The leader also does this every five minutes.\nNeeds a host whose agent has the `datastore-capacity` capability\n(`error.datastore_no_host` otherwise).", "operationId": "refresh_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Datastore id (datastore-N).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreCapacityView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/distributed-portgroups": { "post": { "tags": [ "networks" ], "summary": "Creates a distributed port group on a switch.", "operationId": "create_portgroup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDistributedPortgroupRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/distributed-portgroups/{id}": { "put": { "tags": [ "networks" ], "summary": "Changes a distributed port group (compare-and-set on `expectedVersion`). Addresses\nalready allocated stay while they are in the subnet.", "operationId": "update_portgroup", "parameters": [ { "name": "id", "in": "path", "description": "Distributed port group id (`dvportgroup-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDistributedPortgroupRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "networks" ], "summary": "Deletes a distributed port group no NIC uses.", "operationId": "delete_portgroup", "parameters": [ { "name": "id", "in": "path", "description": "Distributed port group id (`dvportgroup-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/distributed-switches": { "post": { "tags": [ "networks" ], "summary": "Creates a distributed switch in a datacenter's network folder.", "operationId": "create_switch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDistributedSwitchRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/distributed-switches/{id}": { "put": { "tags": [ "networks" ], "summary": "Changes a distributed switch (compare-and-set on `expectedVersion`).", "operationId": "update_switch", "parameters": [ { "name": "id", "in": "path", "description": "Distributed switch id (`dvs-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDistributedSwitchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "networks" ], "summary": "Deletes a distributed switch without port groups.", "operationId": "delete_switch", "parameters": [ { "name": "id", "in": "path", "description": "Distributed switch id (`dvs-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/events": { "get": { "tags": [ "events" ], "summary": "Lists events, oldest first or with `order=desc` newest first; `after` takes the\n`next` cursor of the previous page. Events of deleted entities stay listed (with the\nentity name they were logged with) for callers with `System.View` on the root.", "operationId": "list_events", "parameters": [ { "name": "target", "in": "query", "description": "Only events on this target.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "recursive", "in": "query", "description": "Include descendants of `target`.", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "eventType", "in": "query", "description": "Comma-separated event types.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "user", "in": "query", "description": "Only this user.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "chainId", "in": "query", "description": "Only this chain id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "begin", "in": "query", "description": "Events at or after (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end", "in": "query", "description": "Events at or before (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "minSeverity", "in": "query", "description": "Minimum severity (`info`, `warning`, `error`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "afterId", "in": "query", "description": "Collector cursor: only events with id number greater than this.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "order", "in": "query", "description": "`asc` (default, oldest first) or `desc` (newest first).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum items.", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Cursor: the `next` of the previous page (in the same order).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_EventView" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "events" ], "summary": "Injects a typed event into the native event log (`PostEvent`).", "operationId": "post_event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostEventRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/events/user": { "post": { "tags": [ "events" ], "summary": "Appends a user event on an inventory entity (`LogUserEvent`).", "operationId": "log_user_event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogUserEventRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/bypass": { "get": { "tags": [ "firewall" ], "summary": "The emergency bypasses in force.", "operationId": "list_bypasses", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BypassView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "firewall" ], "summary": "Opens every vNIC of a host for a limited time with an audited Emergency rule (a task;\n`Kyvernon.Firewall.Bypass`). Enabling it again extends it.", "operationId": "enable_bypass", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BypassBody" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/bypass/{id}": { "delete": { "tags": [ "firewall" ], "summary": "Ends a bypass before its time.", "operationId": "remove_bypass", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall bypass", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/groups": { "get": { "tags": [ "firewall" ], "summary": "Firewall groups of a scope (a tenant user: its own and the shared provider groups,\nname only).", "operationId": "list_groups", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id (`tenant-N`); absent: the provider (a tenant user: its tenant).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "firewall" ], "summary": "Creates a group (`Kyvernon.Firewall.ManageGroups`; a shared provider group needs\n`Kyvernon.Firewall.ManageProvider`).", "operationId": "create_group", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/groups/{id}": { "get": { "tags": [ "firewall" ], "summary": "One group.", "operationId": "get_group", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall group", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Replaces a group.", "operationId": "update_group", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall group", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "firewall" ], "summary": "Deletes a group (refused while it is referenced).", "operationId": "delete_group", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall group", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/groups/{id}/members": { "get": { "tags": [ "firewall" ], "summary": "Resolved members of a group: vNICs and addresses.", "operationId": "group_members", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall group", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembersView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/logs": { "get": { "tags": [ "firewall" ], "summary": "Firewall log records of every host, newest first (kept in memory, bounded).", "operationId": "logs", "parameters": [ { "name": "limit", "in": "query", "description": "Most records (default 500, at most 5,000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "host", "in": "query", "description": "Host id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "rule", "in": "query", "description": "Rule number.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogRecordView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/policies": { "get": { "tags": [ "firewall" ], "summary": "Policies with their rules, in evaluation order.", "operationId": "list_policies", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id (`tenant-N`); absent: the provider (a tenant user: its tenant).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "firewall" ], "summary": "Creates a policy (Environment and Application: `Kyvernon.Firewall.ManagePolicies`;\nEmergency and Infrastructure: `Kyvernon.Firewall.ManageProvider`).", "operationId": "create_policy", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/policies/{id}": { "get": { "tags": [ "firewall" ], "summary": "One policy with its rules.", "operationId": "get_policy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Replaces a policy (with `rules`: its rules too; a rule with the `id` of an existing\none keeps its number and counters).", "operationId": "update_policy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyView" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "firewall" ], "summary": "Deletes a policy and its rules.", "operationId": "delete_policy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/policies/{id}/rules": { "get": { "tags": [ "firewall" ], "summary": "The rules of a policy.", "operationId": "list_rules", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "firewall" ], "summary": "Adds a rule (`?position=`: default last); the control plane gives it its number.", "operationId": "add_rule", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/policies/{id}/rules/{rid}": { "get": { "tags": [ "firewall" ], "summary": "One rule (by id or number).", "operationId": "get_rule", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "rid", "in": "path", "description": "Id of the rule in the policy", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Replaces a rule (keeps its number and position). `If-Match` is the policy's version.", "operationId": "update_rule", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "rid", "in": "path", "description": "Id of the rule in the policy", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleView" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "firewall" ], "summary": "Deletes a rule.", "operationId": "delete_rule", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "rid", "in": "path", "description": "Id of the rule in the policy", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/policies/{id}/rules/{rid}/move": { "post": { "tags": [ "firewall" ], "summary": "Moves a rule inside its policy.", "operationId": "move_rule", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } }, { "name": "rid", "in": "path", "description": "Id of the rule in the policy", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveRuleBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/policies/{id}/stats": { "get": { "tags": [ "firewall" ], "summary": "Hit counters of a policy's rules: packets, bytes, per host and total, last hit.", "operationId": "policy_stats", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall policy", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyStatsView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/profiles": { "get": { "tags": [ "firewall" ], "summary": "Default profiles (a tenant user: the selectable ones).", "operationId": "list_profiles", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "firewall" ], "summary": "Creates a provider profile.", "operationId": "create_profile", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/profiles/{id}": { "get": { "tags": [ "firewall" ], "summary": "One profile.", "operationId": "get_profile", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall profile", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Replaces a profile (a built-in name stores a replacement of the built-in).", "operationId": "put_profile", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall profile", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileView" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "firewall" ], "summary": "Deletes a provider profile (a replaced built-in comes back).", "operationId": "delete_profile", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall profile", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/realization": { "get": { "tags": [ "firewall" ], "summary": "Realization per host: wanted and applied plan version, error, flows, preconditions.", "operationId": "realization", "parameters": [ { "name": "host", "in": "query", "description": "Host id.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HostRealizationView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/rules/{number}/stats": { "get": { "tags": [ "firewall" ], "summary": "Hit counters of one rule by number.", "operationId": "rule_stats", "parameters": [ { "name": "number", "in": "path", "description": "Rule number, as the effective rules and the logs show it", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleStatsView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/services": { "get": { "tags": [ "firewall" ], "summary": "Named services (a tenant user: its own and the provider's).", "operationId": "list_services", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id (`tenant-N`); absent: the provider (a tenant user: its tenant).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "firewall" ], "summary": "Creates a named service.", "operationId": "create_service", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/services/{id}": { "get": { "tags": [ "firewall" ], "summary": "One named service.", "operationId": "get_service", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall service", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Replaces a named service.", "operationId": "update_service", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall service", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceView" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "firewall" ], "summary": "Deletes a named service (refused while a rule uses it).", "operationId": "delete_service", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall service", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/settings": { "get": { "tags": [ "firewall" ], "summary": "The firewall settings.", "operationId": "get_settings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Changes the firewall settings.", "operationId": "put_settings", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsView" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/simulate": { "post": { "tags": [ "firewall" ], "summary": "Verdict and deciding rule for a described packet at a vNIC (reference evaluator).", "operationId": "simulate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/tag-categories": { "get": { "tags": [ "firewall" ], "summary": "Tag categories and whether they are provider-managed.", "operationId": "list_tag_categories", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TagCategoryView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/tag-categories/{id}": { "put": { "tags": [ "firewall" ], "summary": "Marks a tag category provider-managed: only the provider attaches its tags, and only\nsuch categories count in provider groups' tag criteria.", "operationId": "set_tag_category", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag category", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCategoryBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCategoryView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/templates": { "get": { "tags": [ "firewall" ], "summary": "The rule templates.", "operationId": "list_templates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/templates/{id}": { "get": { "tags": [ "firewall" ], "summary": "One template.", "operationId": "get_template", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall template", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Creates or replaces a provider template (built-in ids are refused with\n`error.firewall.builtin`).", "operationId": "put_template", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall template", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "firewall" ], "summary": "Deletes a provider template.", "operationId": "delete_template", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall template", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/firewall/templates/{id}/apply": { "post": { "tags": [ "firewall" ], "summary": "Applies a template to a VM: its rules go into the VM's own policy (a task).", "operationId": "apply_template", "parameters": [ { "name": "id", "in": "path", "description": "Id of the firewall template", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyTemplateBody" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/guest-agent/offer": { "post": { "tags": [ "vms" ], "summary": "Whether to offer installing the guest agent for a VM created from `template`.", "description": "The Ubuntu and Debian cloud images do not ship `qemu-guest-agent`; a VM created from\nthem has no tools status, no guest addresses from the agent and no quiesced snapshots\nuntil the package is installed. This says when to offer the installation and what it\nadds; nothing changes until the create request sets `guestAgent: true` (or the caller\nputs the returned `vendorData` into its own `guestinfo.vendordata`).", "operationId": "guest_agent_offer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAgentOfferRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAgentOffer" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/join-token": { "get": { "tags": [ "hosts" ], "summary": "The join token and the controller endpoint a new host needs (`Host.Inventory.AddHostToCluster`\non the root folder). 404 when the controller has no join token file.", "operationId": "join_token", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinTokenView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}": { "delete": { "tags": [ "hosts" ], "summary": "Removes a host with no VMs placed on it (`HostSystem.Destroy_Task`).", "operationId": "destroy_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/datastores": { "post": { "tags": [ "hosts" ], "summary": "Creates a local, NFS, or VMFS datastore on the host (SOAP HostDatastoreSystem).", "operationId": "create_host_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostDatastoreRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/datastores/{dsId}": { "delete": { "tags": [ "hosts" ], "summary": "Removes a datastore mounted on the host (SOAP `RemoveDatastore`).", "operationId": "remove_host_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } }, { "name": "dsId", "in": "path", "description": "datastore-N", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/datastores/{dsId}/mount": { "post": { "tags": [ "datastores" ], "summary": "Mounts an existing NFS or iSCSI datastore on one more host, or again after an\nunmount (`Host.Config.Storage` on the host). A local datastore belongs to its host and\ncannot be mounted elsewhere (`error.datastore.not_shareable`).", "operationId": "mount_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } }, { "name": "dsId", "in": "path", "description": "Id of the datastore on the host (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/datastores/{dsId}/unmount": { "post": { "tags": [ "datastores" ], "summary": "Unmounts a datastore on one host (`Host.Config.Storage` on the host). The datastore\nand its files stay; the host no longer offers it. Refused while a virtual machine\nplaced on that host has a disk on it (`error.datastore_file_in_use`).", "operationId": "unmount_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } }, { "name": "dsId", "in": "path", "description": "Id of the datastore on the host (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/disconnect": { "post": { "tags": [ "hosts" ], "summary": "Disconnects a host (`HostSystem.DisconnectHost_Task`). Heartbeats stay\ndisconnected until reconnect.", "operationId": "disconnect_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/enter-maintenance": { "post": { "tags": [ "hosts" ], "summary": "Puts a host into maintenance mode.", "operationId": "enter_maintenance", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/exit-maintenance": { "post": { "tags": [ "hosts" ], "summary": "Takes a host out of maintenance mode.", "operationId": "exit_maintenance", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi": { "get": { "tags": [ "hosts" ], "summary": "The software iSCSI configuration of a host: adapter, CHAP (without secrets), send and\nstatic targets, what the last rescan found (`Host.Config.Storage` on the host).", "operationId": "get_iscsi", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiConfigView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi/authentication": { "put": { "tags": [ "hosts" ], "summary": "Updates adapter-level or per-target CHAP (`UpdateInternetScsiAuthenticationProperties`).", "operationId": "set_iscsi_authentication", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiAuthenticationRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi/rescan": { "post": { "tags": [ "hosts" ], "summary": "Rescans one HBA (`RescanHba`); software iSCSI `vmhba64` only.", "operationId": "rescan_iscsi_hba", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiRescanRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi/rescan-all": { "post": { "tags": [ "hosts" ], "summary": "Rescans every projected HBA (`RescanAllHba`).", "operationId": "rescan_all_iscsi_hba", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi/send-targets": { "post": { "tags": [ "hosts" ], "summary": "Adds iSCSI send targets (`AddInternetScsiSendTargets`).", "operationId": "add_iscsi_send_targets", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiSendTargetsRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "hosts" ], "summary": "Removes iSCSI send targets (`RemoveInternetScsiSendTargets`).", "operationId": "remove_iscsi_send_targets", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiSendTargetsRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi/software": { "put": { "tags": [ "hosts" ], "summary": "Enables or disables software iSCSI (`UpdateSoftwareInternetScsiEnabled`).", "operationId": "set_software_iscsi", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSoftwareIscsiRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/iscsi/static-targets": { "post": { "tags": [ "hosts" ], "summary": "Adds iSCSI static targets (`AddInternetScsiStaticTargets`).", "operationId": "add_iscsi_static_targets", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiStaticTargetsRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "hosts" ], "summary": "Removes iSCSI static targets (`RemoveInternetScsiStaticTargets`).", "operationId": "remove_iscsi_static_targets", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IscsiStaticTargetsRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/network-health": { "get": { "tags": [ "hosts" ], "summary": "Host-bridge VLAN/MTU realisation health (ESX-N-17 / M1-NET-01).", "operationId": "get_network_health", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkHealthView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/network-hints": { "get": { "tags": [ "hosts" ], "summary": "Lists LLDP/CDP neighbours for a host (`HostNetworkSystem.QueryNetworkHint`).", "operationId": "list_network_hints", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } }, { "name": "device", "in": "query", "description": "Optional physical NIC device names (SOAP `device`; repeat `device=` or omit).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkHintsView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/reboot": { "post": { "tags": [ "hosts" ], "summary": "Reboots a host. Needs `Host.Config.Maintenance` on the host and, without `force`,\nthe host in maintenance mode (`error.host.not_in_maintenance`). The host's agent must\ndeclare the `host-power` capability (`error.host_capability_missing`).", "operationId": "reboot_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; `{}` when absent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostPowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "501": { "description": "The host agent cannot restart its machine (`error.host_capability_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/reconnect": { "post": { "tags": [ "hosts" ], "summary": "Clears an admin disconnect (`HostSystem.ReconnectHost_Task`).", "operationId": "reconnect_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/shutdown": { "post": { "tags": [ "hosts" ], "summary": "Shuts a host down (powers the machine off). Same rules as reboot; the host stays off\nuntil someone powers it on (out-of-band management).", "operationId": "shutdown_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; `{}` when absent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostPowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "501": { "description": "The host agent cannot power its machine off (`error.host_capability_missing`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/vmfs-create-options": { "get": { "tags": [ "hosts" ], "summary": "Lists VMFS create options for a disk (`QueryVmfsDatastoreCreateOptions`).", "operationId": "list_vmfs_create_options", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } }, { "name": "devicePath", "in": "query", "description": "Device path, WWID, or `naa.…` (SOAP `devicePath`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VmfsCreateOptionView" } } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/hosts/{id}/vmfs-disks": { "get": { "tags": [ "hosts" ], "summary": "Lists iSCSI LUNs available for VMFS create (`QueryAvailableDisksForVmfs`).", "operationId": "list_vmfs_disks", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VmfsDiskView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/check": { "get": { "tags": [ "identity" ], "summary": "Whether the caller holds a privilege on an entity.", "operationId": "check_privilege", "parameters": [ { "name": "entityId", "in": "query", "description": "Entity id.", "required": true, "schema": { "type": "string" } }, { "name": "privilege", "in": "query", "description": "Privilege id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/groups": { "get": { "tags": [ "identity" ], "summary": "Lists the local groups (`Kyvernon.Identity.ManageUsers`).", "operationId": "list_groups", "parameters": [ { "name": "search", "in": "query", "description": "Only groups whose name contains this text (case-insensitive).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of groups (default and maximum 1000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupView" } } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "identity" ], "summary": "Creates a local group (`Kyvernon.Identity.ManageUsers`; audited).", "operationId": "create_group", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/groups/{name}": { "get": { "tags": [ "identity" ], "summary": "Reads one local group with its members (`Kyvernon.Identity.ManageUsers`).", "operationId": "get_group", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "identity" ], "summary": "Renames a group or changes its description (`Kyvernon.Identity.ManageUsers`;\naudited). A rename carries the memberships and the permissions of the group.", "operationId": "update_group", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "identity" ], "summary": "Deletes a group (`Kyvernon.Identity.ManageUsers`; audited). Users leave it, it leaves\nthe groups it was nested in, and the permissions granted to it are removed.", "operationId": "delete_group", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/groups/{name}/members": { "put": { "tags": [ "identity" ], "summary": "Replaces the members of a group: exactly these users and nested groups afterwards\n(`Kyvernon.Identity.ManageUsers`; audited).", "operationId": "set_members", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembersRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "identity" ], "summary": "Adds users and nested groups to a group (`Kyvernon.Identity.ManageUsers`; audited).\nMembers that are already in the group are left as they are.", "operationId": "add_members", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembersRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/groups/{name}/members/groups/{member}": { "delete": { "tags": [ "identity" ], "summary": "Removes a nested group from a group (`Kyvernon.Identity.ManageUsers`; audited).", "operationId": "remove_group_member", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } }, { "name": "member", "in": "path", "description": "Name of the nested group", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/groups/{name}/members/users/{username}": { "delete": { "tags": [ "identity" ], "summary": "Removes a user from a group (`Kyvernon.Identity.ManageUsers`; audited).", "operationId": "remove_user_member", "parameters": [ { "name": "name", "in": "path", "description": "Name of the local group", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/lockout-policy": { "get": { "tags": [ "identity" ], "summary": "Reads the lockout policy (`Kyvernon.Identity.ManagePolicy`).", "operationId": "get_lockout_policy", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockoutPolicyView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "identity" ], "summary": "Changes the lockout policy (`Kyvernon.Identity.ManagePolicy`; audited).", "operationId": "put_lockout_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockoutPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockoutPolicyView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/login": { "post": { "tags": [ "identity" ], "summary": "Password login.", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/identity/logout": { "post": { "tags": [ "identity" ], "summary": "Revokes the caller's session.", "operationId": "logout", "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/mfa/complete": { "post": { "tags": [ "identity" ], "summary": "Completes an MFA login.", "operationId": "complete_mfa", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteMfaRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/identity/oidc/callback": { "get": { "tags": [ "identity" ], "summary": "Completes an OIDC login: starts a browser session family, sets the `kyv_refresh` and\n`kyvernon_csrf` cookies and redirects (303) to the UI at `/`, which then calls\n`POST /v1/auth/refresh` for its access token. No token travels in the body or a URL.", "operationId": "oidc_callback", "parameters": [ { "name": "state", "in": "query", "description": "State from the start response.", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "Authorization code.", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Session cookies set; Location: /" }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/identity/oidc/config": { "get": { "tags": [ "identity" ], "summary": "Reads the identity provider (`Global.Settings`). The secret is never returned.", "operationId": "get_oidc_config", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcAdminView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "identity" ], "summary": "Sets up the identity provider (`Global.Settings`; audited). The controller runs\nprovider discovery first; a provider that does not answer is refused\n(`error.identity.oidc_unreachable`) and the stored one stays.", "operationId": "put_oidc_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcAdminInput" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcAdminView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "identity" ], "summary": "Removes the identity provider (`Global.Settings`; audited). Local sign-in stays. This\nalso switches off a provider of the `[oidc]` configuration section.", "operationId": "delete_oidc_config", "responses": { "204": { "description": "Removed" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/oidc/start": { "get": { "tags": [ "identity" ], "summary": "Starts an OIDC login; redirect the browser to `url`. Sets the `kyv_oidc` cookie\n(`HttpOnly; Secure; SameSite=Lax; Path=/v1/identity/oidc`) that binds the login to\nthis browser: the callback refuses a `state` that arrives without it.", "operationId": "oidc_start", "responses": { "200": { "description": "Provider URL; sets the kyv_oidc browser-binding cookie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcStartResponse" } } } }, "501": { "description": "Not configured on this controller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } } } }, "/v1/identity/password-policy": { "get": { "tags": [ "identity" ], "summary": "Reads the password policy (`Kyvernon.Identity.ManagePolicy`).", "operationId": "get_password_policy", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordPolicyView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "identity" ], "summary": "Changes the password policy (`Kyvernon.Identity.ManagePolicy`; audited).", "operationId": "put_password_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordPolicyView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/permissions": { "get": { "tags": [ "identity" ], "summary": "Permissions defined on an entity.", "operationId": "list_permissions", "parameters": [ { "name": "entityId", "in": "query", "description": "Entity id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionView" } } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "identity" ], "summary": "Sets (creates or replaces) a permission.", "operationId": "set_permission", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPermissionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/permissions/{id}": { "delete": { "tags": [ "identity" ], "summary": "Removes a permission.", "operationId": "remove_permission", "parameters": [ { "name": "id", "in": "path", "description": "Id of the permission", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/privileges": { "get": { "tags": [ "identity" ], "summary": "The privilege catalogue.", "operationId": "list_privileges", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PrivilegeView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/roles": { "get": { "tags": [ "identity" ], "summary": "Lists roles.", "operationId": "list_roles", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "identity" ], "summary": "Creates a role.", "operationId": "create_role", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/roles/{id}": { "put": { "tags": [ "identity" ], "summary": "Updates a role.", "operationId": "update_role", "parameters": [ { "name": "id", "in": "path", "description": "Id of the role", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "identity" ], "summary": "Deletes a role.", "operationId": "delete_role", "parameters": [ { "name": "id", "in": "path", "description": "Id of the role", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/self": { "get": { "tags": [ "identity" ], "summary": "The caller's identity.", "operationId": "whoami", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/self/mfa/confirm": { "post": { "tags": [ "identity" ], "summary": "Confirms TOTP enrolment; returns the ten single-use recovery codes once.", "operationId": "confirm_mfa", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodesResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/self/mfa/enrol": { "post": { "tags": [ "identity" ], "summary": "Starts TOTP enrolment for the caller.", "operationId": "enrol_mfa", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaEnrolResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/self/password": { "post": { "tags": [ "identity" ], "summary": "Changes the caller's own password. Every other session of the account is revoked; the\ncalling session stays. Browsers use `POST /v1/auth/password` instead.", "operationId": "change_own_password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/sessions": { "get": { "tags": [ "identity" ], "summary": "Active sessions (administrator).", "operationId": "list_sessions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionInfoView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/sessions/{id}": { "delete": { "tags": [ "identity" ], "summary": "Revokes one session (`Sessions.TerminateSession`; audited). The id is the `id` of\n`GET /v1/identity/sessions`.", "operationId": "revoke_session", "parameters": [ { "name": "id", "in": "path", "description": "Id of the session", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users": { "get": { "tags": [ "identity" ], "summary": "Lists users.", "operationId": "list_users", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "identity" ], "summary": "Creates a local user.", "operationId": "create_user", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}": { "get": { "tags": [ "identity" ], "summary": "One user, with the lockout state (`locked`, `lockedUntil`).", "operationId": "get_user", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "identity" ], "summary": "Changes a user's display name, e-mail address and local groups\n(`Kyvernon.Identity.ManageUsers`; audited as `identity.user.update` and\n`identity.user.groups`).", "operationId": "update_user", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "identity" ], "summary": "Deletes a user.", "operationId": "delete_user", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/api-tokens": { "get": { "tags": [ "identity" ], "summary": "API tokens of a user (administrator, or the user).", "operationId": "list_user_api_tokens", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "identity" ], "summary": "Creates an API token for a user, e.g. a service account (administrator).", "operationId": "create_user_api_token", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/api-tokens/{id}": { "delete": { "tags": [ "identity" ], "summary": "Revokes an API token of a user (administrator, or the user).", "operationId": "delete_user_api_token", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Id of the API token", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/enabled": { "put": { "tags": [ "identity" ], "summary": "Enables or disables a user.", "operationId": "set_user_enabled", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnabledRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/mfa": { "delete": { "tags": [ "identity" ], "summary": "Resets a user's MFA enrolment.", "operationId": "reset_user_mfa", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/password": { "post": { "tags": [ "identity" ], "summary": "Sets another user's password (administrator).", "operationId": "set_user_password", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/service-account": { "put": { "tags": [ "identity" ], "summary": "Flags or unflags a service account (administrator).", "operationId": "set_service_account", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/sessions": { "delete": { "tags": [ "identity" ], "summary": "Revokes all sessions of a user.", "operationId": "revoke_user_sessions", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/identity/users/{username}/unlock": { "post": { "tags": [ "identity" ], "summary": "Lifts a lockout (administrator).", "operationId": "unlock_user", "parameters": [ { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/changes": { "get": { "tags": [ "inventory" ], "summary": "Long-poll change feed. Returns immediately with retained history after\n`since`, otherwise waits up to `timeout` for new changes. `resync: true`\nmeans the client must re-list and resume from `version`.", "operationId": "changes", "parameters": [ { "name": "since", "in": "query", "description": "Version to resume after (from a listing's `version` or the last response).", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "timeout", "in": "query", "description": "Long-poll timeout in seconds (default 30, bounded by the server).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "kinds", "in": "query", "description": "Comma-separated kinds to include (default all).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum change sets per response (default 100).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesResponse" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/clusters/{id}": { "get": { "tags": [ "inventory" ], "summary": "A cluster.", "operationId": "get_cluster", "parameters": [ { "name": "id", "in": "path", "description": "Id of the cluster (`domain-cN`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/datacenters/{id}": { "get": { "tags": [ "inventory" ], "summary": "A datacenter.", "operationId": "get_datacenter", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datacenter", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/datastores": { "get": { "tags": [ "inventory" ], "summary": "Datastores, optionally scoped.", "operationId": "list_datastores", "parameters": [ { "name": "scope", "in": "query", "description": "Container object id: datacenter, folder, cluster, host, resource\npool, datastore or network. Items are returned when they live under\nthe container or reference it (VMs on a host, datastore or network).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum items (default 100, maximum 1000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Resume after this id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "consistency", "in": "query", "description": "`linearizable` (default) or `local`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_ObjectView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/datastores/{id}": { "get": { "tags": [ "inventory" ], "summary": "A datastore.", "operationId": "get_datastore", "parameters": [ { "name": "id", "in": "path", "description": "Id of the datastore (`datastore-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/folders/{id}/move-into": { "post": { "tags": [ "inventory" ], "summary": "Re-parents inventory entities under a folder (`POST /v1/inventory/folders/{id}/move-into`,\nSOAP `Folder.MoveIntoFolder_Task`). Returns a task; privilege `Folder.Move` on the\ndestination folder.", "operationId": "move_into_folder", "parameters": [ { "name": "id", "in": "path", "description": "Id of the folder (`group-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveIntoFolderRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/hosts": { "get": { "tags": [ "inventory" ], "summary": "Hosts, optionally scoped.", "operationId": "list_hosts", "parameters": [ { "name": "scope", "in": "query", "description": "Container object id: datacenter, folder, cluster, host, resource\npool, datastore or network. Items are returned when they live under\nthe container or reference it (VMs on a host, datastore or network).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum items (default 100, maximum 1000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Resume after this id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "consistency", "in": "query", "description": "`linearizable` (default) or `local`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_ObjectView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/hosts/{id}": { "get": { "tags": [ "inventory" ], "summary": "A host.", "operationId": "get_host", "parameters": [ { "name": "id", "in": "path", "description": "Id of the host (`host-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/kinds/{kind}": { "get": { "tags": [ "inventory" ], "summary": "Records of one kind (`virtual_machine`, `host`, `vm_folder`, ...). Same privileges as\n`GET /v1/inventory/objects/{id}`: invisible records are left out, a kind the caller may\nnot read is refused (`403`), and `session` is refused for everyone (`400`).", "operationId": "list_kind", "parameters": [ { "name": "kind", "in": "path", "description": "Object kind of the inventory (for example `VirtualMachine`)", "required": true, "schema": { "type": "string" } }, { "name": "parent", "in": "query", "description": "Only direct children of this parent.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "namePrefix", "in": "query", "description": "Name prefix.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "changedAfter", "in": "query", "description": "Only records changed after this version.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Maximum items.", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Resume after id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "consistency", "in": "query", "description": "`linearizable` or `local`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "inventory" ], "summary": "Creates a record of `kind` under `parentId`.", "operationId": "create_object", "parameters": [ { "name": "kind", "in": "path", "description": "Object kind of the inventory (for example `VirtualMachine`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/networks": { "get": { "tags": [ "inventory" ], "summary": "Networks and distributed port groups, optionally scoped.", "operationId": "list_networks", "parameters": [ { "name": "scope", "in": "query", "description": "Container object id: datacenter, folder, cluster, host, resource\npool, datastore or network. Items are returned when they live under\nthe container or reference it (VMs on a host, datastore or network).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum items (default 100, maximum 1000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Resume after this id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "consistency", "in": "query", "description": "`linearizable` (default) or `local`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_ObjectView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/networks/{id}": { "get": { "tags": [ "inventory" ], "summary": "A network or distributed port group.", "operationId": "get_network", "parameters": [ { "name": "id", "in": "path", "description": "Id of the network", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/nodes/{id}/children": { "get": { "tags": [ "inventory" ], "summary": "Direct children of a node (lazy tree loading).", "operationId": "children", "parameters": [ { "name": "id", "in": "path", "description": "Object id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryNode" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/nodes/{id}/path": { "get": { "tags": [ "inventory" ], "summary": "Ancestors of a node, root first, including the node (breadcrumb).", "operationId": "path", "parameters": [ { "name": "id", "in": "path", "description": "Object id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryNode" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/objects/{id}": { "get": { "tags": [ "inventory" ], "summary": "Any record by id. Inventory entities need `System.View`; other kinds need the\nprivilege of their dedicated endpoint (users `Kyvernon.Identity.ManageUsers`, webhooks\n`Kyvernon.Webhook.Manage`, audit records `Global.Diagnostics`, the rest `System.Read`\nplus visibility of the entity they belong to). Session records are not served here.\nSecrets (password hashes, TOTP seeds, token hashes, signing and CHAP secrets) are never\nreturned.", "operationId": "get_object", "parameters": [ { "name": "id", "in": "path", "description": "Id of the inventory object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "inventory" ], "summary": "Replaces a record's body (compare-and-set).", "operationId": "update_object", "parameters": [ { "name": "id", "in": "path", "description": "Id of the inventory object", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateObjectRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "inventory" ], "summary": "Deletes a record.", "operationId": "delete_object", "parameters": [ { "name": "id", "in": "path", "description": "Id of the inventory object", "required": true, "schema": { "type": "string" } }, { "name": "expectedVersion", "in": "query", "description": "Compare-and-set version.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "cascade", "in": "query", "description": "Delete descendants too.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "204": { "description": "Done; no body" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/objects/{id}/rename": { "post": { "tags": [ "inventory" ], "summary": "Renames an inventory object: a datacenter (`Datacenter.Rename`), folder\n(`Folder.Rename`), cluster (`Host.Inventory.EditCluster`), host\n(`Host.Config.Settings`), resource group (`Resource.EditPool`), virtual machine\n(`VirtualMachine.Config.Rename`), datastore (`Datastore.Rename`) or network\n(`Network.Config`). Runs as a task (`.rename`).", "operationId": "rename_object", "parameters": [ { "name": "id", "in": "path", "description": "Id of the inventory object", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/objects/{id}/tags": { "get": { "tags": [ "inventory" ], "summary": "The tags attached to an object (`System.View` on the object).", "operationId": "list_object_tags", "parameters": [ { "name": "id", "in": "path", "description": "Id of the inventory object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TagView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/roots": { "get": { "tags": [ "inventory" ], "summary": "Top-level tree nodes (datacenters) visible to the caller.", "operationId": "roots", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryNode" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/search": { "get": { "tags": [ "inventory" ], "summary": "Name search over tree nodes.", "operationId": "search", "parameters": [ { "name": "q", "in": "query", "description": "Case-insensitive substring of the name.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum results (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryNode" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/vms": { "get": { "tags": [ "inventory" ], "summary": "Virtual machines, optionally scoped to a container.", "operationId": "list_vms", "parameters": [ { "name": "scope", "in": "query", "description": "Container object id: datacenter, folder, cluster, host, resource\npool, datastore or network. Items are returned when they live under\nthe container or reference it (VMs on a host, datastore or network).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum items (default 100, maximum 1000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Resume after this id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "consistency", "in": "query", "description": "`linearizable` (default) or `local`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_ObjectView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/inventory/vms/{id}": { "get": { "tags": [ "inventory" ], "summary": "A virtual machine.", "operationId": "get_vm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools": { "get": { "tags": [ "ip-pools" ], "summary": "Lists IP pools (those whose network the caller may configure).", "operationId": "list_pools", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IpPoolView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "ip-pools" ], "summary": "Creates an IP pool on a host-bridge network.", "operationId": "create_pool", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPoolRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPoolView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}": { "get": { "tags": [ "ip-pools" ], "summary": "Reads an IP pool.", "operationId": "get_pool", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPoolView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "ip-pools" ], "summary": "Changes an IP pool (compare-and-set on `expectedVersion`); allocations are kept.", "operationId": "update_pool", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPoolRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPoolView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "ip-pools" ], "summary": "Deletes an IP pool without allocations.", "operationId": "delete_pool", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}/allocations": { "get": { "tags": [ "ip-pools" ], "summary": "Lists the allocated and quarantined addresses of a pool.", "operationId": "list_allocations", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AllocationView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "ip-pools" ], "summary": "Allocates an address (or a /64) and binds it to a VM NIC. A named address that another\ncaller took first fails with `error.ip_pool.address_in_use` (409), one in quarantine with\n`error.ip_pool.address_quarantined` (412).", "operationId": "allocate", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocateBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}/allocations/{address}": { "delete": { "tags": [ "ip-pools" ], "summary": "Returns an address (or `prefix/64`, URL-encoded) to the pool: into quarantine, PTR\nrecord deleted.", "operationId": "free", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "Allocated address of the pool (an IPv6 block by its address)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}/allocations/{address}/ptr": { "put": { "tags": [ "ip-pools" ], "summary": "Sets or removes the PTR name of an allocated address (operator path).", "operationId": "set_pool_ptr", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "Allocated address of the pool (an IPv6 block by its address)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtrBody" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}/allocations/{address}/ptr/applied": { "post": { "tags": [ "ip-pools" ], "summary": "The operator applied a manual PTR request (the name is in DNS, or a removal is done).", "operationId": "ptr_applied", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "Allocated address of the pool (an IPv6 block by its address)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}/allocations/{address}/ptr/rejected": { "post": { "tags": [ "ip-pools" ], "summary": "The operator could not apply a manual PTR request.", "operationId": "ptr_rejected", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "Allocated address of the pool (an IPv6 block by its address)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtrRejectBody" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ip-pools/{id}/available": { "get": { "tags": [ "ip-pools" ], "summary": "Lists the IPv4 addresses of a pool that can be allocated now (the allocator's own list,\nascending), with the number of free IPv4 addresses and IPv6 blocks. Needs `Network.Config`\nor `Network.Assign` on the pool's network.", "operationId": "list_available", "parameters": [ { "name": "id", "in": "path", "description": "Id of the IP pool (`ippool-N`)", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Most addresses returned (default 256, at most 4096; 0 returns only the counts).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPoolAvailableView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/licence": { "get": { "tags": [ "licence" ], "summary": "Effective entitlements and live counters.", "operationId": "status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenceStatus" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/licence/install": { "post": { "tags": [ "licence" ], "summary": "Install a signed licence file.", "operationId": "install", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallLicenceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstalledLicenceView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/licence/{id}": { "delete": { "tags": [ "licence" ], "summary": "Remove an installed licence. Running virtual machines are not stopped.", "operationId": "remove", "parameters": [ { "name": "id", "in": "path", "description": "Licence id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "401": { "description": "Not authenticated, or the session is restricted (`error.mfa_required`, `error.password_rotation_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/metrics/counters": { "get": { "tags": [ "metrics" ], "summary": "Lists the counter catalogue.", "operationId": "counters", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CounterView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/metrics/entities/{id}/available": { "get": { "tags": [ "metrics" ], "summary": "Counters (and instances) with data for an entity at an interval.", "operationId": "available", "parameters": [ { "name": "id", "in": "path", "description": "Host, VM or datastore id", "required": true, "schema": { "type": "string" } }, { "name": "interval", "in": "query", "description": "Sampling period: 20 (default for hosts and VMs), 300, 1800, 7200 or 86400.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/metrics/intervals": { "get": { "tags": [ "metrics" ], "summary": "Lists the sampling intervals and their collection levels.", "operationId": "intervals", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntervalView" } } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/metrics/query": { "get": { "tags": [ "metrics" ], "summary": "Queries samples (URL parameters).", "operationId": "query_get", "parameters": [ { "name": "entity", "in": "query", "description": "Comma-separated entity ids.", "required": true, "schema": { "type": "string" } }, { "name": "counter", "in": "query", "description": "Comma-separated counter names or ids.", "required": true, "schema": { "type": "string" } }, { "name": "interval", "in": "query", "description": "Sampling period.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "start", "in": "query", "description": "Exclusive start (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "end", "in": "query", "description": "Inclusive end (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "instance", "in": "query", "description": "Instance selector (`\"\"`, `\"*\"` or a name).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "maxSamples", "in": "query", "description": "Newest N samples per series.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsQueryResponse" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "metrics" ], "summary": "Queries samples.", "operationId": "query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsQueryResponse" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/network/realization": { "get": { "tags": [ "networks" ], "summary": "Realization of the OVN logical networks (`docs/network/DESIGN.md` §6.3): the model\ngeneration, the Northbound connection and realization, the counters' state and every\nhost's report. `enabled: false` when the controller has no `[ovn]`.", "operationId": "realization", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OvnStatusView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/networks": { "post": { "tags": [ "networks" ], "summary": "Creates a host-bridge network under a datacenter.", "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNetworkRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/networks/{id}": { "put": { "tags": [ "networks" ], "summary": "Updates a host-bridge network (compare-and-set).", "operationId": "update", "parameters": [ { "name": "id", "in": "path", "description": "Id of the network", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNetworkRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "networks" ], "summary": "Deletes a network. Refuses when any VM still has a NIC on it.", "operationId": "delete", "parameters": [ { "name": "id", "in": "path", "description": "Id of the network", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/nfc-leases/{id}": { "get": { "tags": [ "nfc" ], "summary": "`GET /v1/nfc-leases/{id}`: lease state (SOAP PropertyCollector on HttpNfcLease).", "operationId": "get_lease", "parameters": [ { "name": "id", "in": "path", "description": "Id of the transfer lease", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/nfc-leases/{id}/abort": { "post": { "tags": [ "nfc" ], "summary": "`POST /v1/nfc-leases/{id}/abort`: SOAP `HttpNfcLeaseAbort`.", "operationId": "abort", "parameters": [ { "name": "id", "in": "path", "description": "Id of the transfer lease", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/nfc-leases/{id}/complete": { "post": { "tags": [ "nfc" ], "summary": "`POST /v1/nfc-leases/{id}/complete`: SOAP `HttpNfcLeaseComplete`.", "operationId": "complete", "parameters": [ { "name": "id", "in": "path", "description": "Id of the transfer lease", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/nfc-leases/{id}/files/{name}": { "get": { "tags": [ "nfc" ], "summary": "`GET /v1/nfc-leases/{id}/files/{name}`: export download (SOAP `/nfc` GET).", "operationId": "download_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the transfer lease", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "File name inside the library item", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "octet-stream" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "nfc" ], "summary": "`PUT /v1/nfc-leases/{id}/files/{name}`: import upload (SOAP `/nfc` PUT).", "operationId": "upload_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the transfer lease", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "File name inside the library item", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/nfc-leases/{id}/progress": { "post": { "tags": [ "nfc" ], "summary": "`POST /v1/nfc-leases/{id}/progress`: SOAP `HttpNfcLeaseProgress`.", "operationId": "progress", "parameters": [ { "name": "id", "in": "path", "description": "Id of the transfer lease", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseProgressRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ovf/create-descriptor": { "post": { "tags": [ "ovf" ], "summary": "`POST /v1/ovf/create-descriptor`: SOAP `OvfManager.CreateDescriptor`.", "operationId": "create_descriptor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOvfDescriptorRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OvfCreateDescriptorView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ovf/import-spec": { "post": { "tags": [ "ovf" ], "summary": "`POST /v1/ovf/import-spec`: SOAP `OvfManager.CreateImportSpec`.", "operationId": "create_import_spec", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOvfImportSpecRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OvfImportSpecView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/ovf/parse": { "post": { "tags": [ "ovf" ], "summary": "`POST /v1/ovf/parse`: SOAP `OvfManager.ParseDescriptor`.", "operationId": "parse_descriptor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OvfParseDescriptorRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OvfParseDescriptorView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/plans": { "get": { "tags": [ "plans" ], "summary": "VM plans: all for operators, the orderable ones for tenant users.", "operationId": "list_plans", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlanView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "plans" ], "summary": "Creates a plan (`Kyvernon.Plan.Manage`).", "operationId": "create_plan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanView" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/plans/{id}": { "get": { "tags": [ "plans" ], "summary": "One plan.", "operationId": "get_plan", "parameters": [ { "name": "id", "in": "path", "description": "Id of the plan (`vmplan-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "plans" ], "summary": "Replaces a plan (`Kyvernon.Plan.Manage`); servers keep their size until resized.", "operationId": "update_plan", "parameters": [ { "name": "id", "in": "path", "description": "Id of the plan (`vmplan-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanView" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "plans" ], "summary": "Deletes a plan that no server uses (`error.plan.in_use`).", "operationId": "delete_plan", "parameters": [ { "name": "id", "in": "path", "description": "Id of the plan (`vmplan-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/resource-pools/{id}/import-vapp": { "post": { "tags": [ "nfc" ], "summary": "`POST /v1/resource-pools/{id}/import-vapp`: SOAP `ResourcePool.ImportVApp`.", "description": "From a browser: an OVA is a tar archive whose first entry is the `.ovf` descriptor.\nThe console reads that entry from the selected file, sends it here, and uploads each\ndisk entry of the archive (a slice of the file at the entry's offset and size) with\n`PUT` to the `url` of the matching lease file; `bytesReceived` on the lease shows the\nprogress, `POST .../progress` keeps the lease alive (it expires after 15 minutes\nwithout use), and `POST .../complete` converts the disks and finishes the import.\nAn OVF with separate disk files works the same with one file per disk.", "operationId": "import_vapp", "parameters": [ { "name": "id", "in": "path", "description": "Resource pool id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportVAppRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/resource-pools/{id}/move-into": { "post": { "tags": [ "inventory" ], "summary": "Moves VMs and/or child pools under a resource pool\n(`POST /v1/resource-pools/{id}/move-into`, SOAP `MoveIntoResourcePool`).\nReturns a task; privilege `Resource.AssignVMToPool` for VMs and\n`Resource.MovePool` for child pools on the destination.", "operationId": "move_into_resource_pool", "parameters": [ { "name": "id", "in": "path", "description": "Id of the resource group (`resgroup-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveIntoResourcePoolRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/scheduled-tasks": { "get": { "tags": [ "scheduled-tasks" ], "summary": "Lists scheduled tasks visible to the caller.", "operationId": "list_scheduled_tasks", "parameters": [ { "name": "entity", "in": "query", "description": "Only tasks for this VM entity.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledTaskView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "scheduled-tasks" ], "summary": "Creates a scheduled power task on a VM.", "operationId": "create_scheduled_task", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledTaskRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/scheduled-tasks/{id}": { "get": { "tags": [ "scheduled-tasks" ], "summary": "One scheduled task.", "operationId": "get_scheduled_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the scheduled task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "scheduled-tasks" ], "summary": "Reconfigures a scheduled task (entity stays fixed).", "operationId": "reconfigure_scheduled_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the scheduled task", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconfigureScheduledTaskRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskView" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "scheduled-tasks" ], "summary": "Deletes a scheduled task.", "operationId": "delete_scheduled_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the scheduled task", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/scheduled-tasks/{id}/run": { "post": { "tags": [ "scheduled-tasks" ], "summary": "Runs a scheduled task immediately (same privilege as SOAP `RunScheduledTask`).", "operationId": "run_scheduled_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the scheduled task", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/tag-categories": { "get": { "tags": [ "inventory" ], "summary": "Lists tag categories (any authenticated user).", "operationId": "list_categories", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TagCategoryView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "inventory" ], "summary": "Creates a tag category (`InventoryService.Tagging.CreateCategory` on the root folder).", "operationId": "create_category", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagCategoryRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCategoryView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tag-categories/{id}": { "get": { "tags": [ "inventory" ], "summary": "Reads a tag category.", "operationId": "get_category", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag category", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCategoryView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "inventory" ], "summary": "Changes a tag category (`InventoryService.Tagging.EditCategory` on the root folder).", "operationId": "update_category", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag category", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagCategoryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCategoryView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "inventory" ], "summary": "Deletes a tag category with its tags (`InventoryService.Tagging.DeleteCategory` on the\nroot folder). The tags are detached from every object.", "operationId": "delete_category", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag category", "required": true, "schema": { "type": "string" } }, { "name": "expectedVersion", "in": "query", "description": "Version the client read; `CONFLICT` when the record changed since.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tags": { "get": { "tags": [ "inventory" ], "summary": "Lists tags, optionally of one category (any authenticated user).", "operationId": "list_tags", "parameters": [ { "name": "categoryId", "in": "query", "description": "Only tags of this category.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TagView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "inventory" ], "summary": "Creates a tag (`InventoryService.Tagging.CreateTag` on the root folder).", "operationId": "create_tag", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tags/{id}": { "get": { "tags": [ "inventory" ], "summary": "Reads a tag.", "operationId": "get_tag", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag (`tag-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "inventory" ], "summary": "Changes a tag (`InventoryService.Tagging.EditTag` on the root folder).", "operationId": "update_tag", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag (`tag-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "inventory" ], "summary": "Deletes a tag (`InventoryService.Tagging.DeleteTag` on the root folder). It is\ndetached from every object.", "operationId": "delete_tag", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag (`tag-N`)", "required": true, "schema": { "type": "string" } }, { "name": "expectedVersion", "in": "query", "description": "Version the client read; `CONFLICT` when the record changed since.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tags/{id}/attach": { "post": { "tags": [ "inventory" ], "summary": "Attaches a tag to objects (`InventoryService.Tagging.AttachTag` on each object).\nObjects that already carry the tag are left as they are.", "operationId": "attach_tag", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag (`tag-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagObjectsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tags/{id}/detach": { "post": { "tags": [ "inventory" ], "summary": "Detaches a tag from objects (`InventoryService.Tagging.AttachTag` on each object).\nObjects that do not carry the tag are left as they are.", "operationId": "detach_tag", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag (`tag-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagObjectsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tags/{id}/objects": { "get": { "tags": [ "inventory" ], "summary": "The objects a tag is attached to that the caller can see.", "operationId": "list_tag_objects", "parameters": [ { "name": "id", "in": "path", "description": "Id of the tag (`tag-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaggedObjectView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tasks": { "get": { "tags": [ "tasks" ], "summary": "Lists tasks, oldest first or with `order=desc` newest first; `after` takes the\n`next` cursor of the previous page.", "operationId": "list_tasks", "parameters": [ { "name": "target", "in": "query", "description": "Only tasks on this target.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "recursive", "in": "query", "description": "With `target`: also tasks on the objects below it (a datacenter, cluster, folder).", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "state", "in": "query", "description": "Comma-separated states (`queued,running,success,error,cancelled`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "operation", "in": "query", "description": "Comma-separated operations (`descriptionId`, e.g. `VirtualMachine.powerOn`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "user", "in": "query", "description": "Only this user.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "chainId", "in": "query", "description": "Only this chain id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "since", "in": "query", "description": "Only tasks queued at or after this time (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "until", "in": "query", "description": "Only tasks queued at or before this time (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "order", "in": "query", "description": "`asc` (default, oldest first) or `desc` (newest first).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum items.", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "after", "in": "query", "description": "Cursor: the `next` of the previous page (in the same order).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paged_TaskView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tasks/{id}": { "get": { "tags": [ "tasks" ], "summary": "One task.", "operationId": "get_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tasks/{id}/cancel": { "post": { "tags": [ "tasks" ], "summary": "Cancels a task (own tasks, or `Global.CancelTask`).", "operationId": "cancel_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tasks/{id}/wait": { "get": { "tags": [ "tasks" ], "summary": "Waits until a task is terminal or the timeout passes (long polling). Answers `200`\nwith the task either way: a task still `queued` or `running` at the timeout is\nreturned as it is, and the client asks again.", "operationId": "wait_task", "parameters": [ { "name": "id", "in": "path", "description": "Id of the task", "required": true, "schema": { "type": "string" } }, { "name": "timeout", "in": "query", "description": "Seconds to wait (default 30, maximum 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "The task: terminal, or still queued or running when the timeout passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants": { "get": { "tags": [ "tenants" ], "summary": "Every tenant (`Kyvernon.Tenant.Read`).", "operationId": "list_tenants", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantView" } } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "tenants" ], "summary": "Creates a tenant: a folder `Tenants/` per datacenter and a resource pool per\ncluster (`Kyvernon.Tenant.Create`).", "operationId": "create_tenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}": { "get": { "tags": [ "tenants" ], "summary": "One tenant with its quota and current use (operators, and the tenant's own users).", "operationId": "get_tenant", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/close": { "post": { "tags": [ "tenants" ], "summary": "Closes a tenant: VMs are powered off now and destroyed with their disks after the grace\nperiod; users cannot log in any more (`Kyvernon.Tenant.Close`).", "operationId": "close_tenant", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseTenantRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/network-usage": { "get": { "tags": [ "traffic" ], "summary": "Network usage of a tenant in a period: traffic per server, public addresses per server\n(merged into `GET /v1/tenants/{t}/usage` by the tenancy module).", "operationId": "tenant_network_usage", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "description": "Period that starts in this month (`YYYY-MM`); absent: the current one.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantNetworkUsage" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/quota": { "put": { "tags": [ "tenants" ], "summary": "Replaces the quota (`Kyvernon.Tenant.SetQuota`); `null` is unlimited.", "operationId": "set_quota", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaView" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/resume": { "post": { "tags": [ "tenants" ], "summary": "Resumes a suspended tenant and starts the VMs that ran at suspend\n(`Kyvernon.Tenant.Resume`).", "operationId": "resume_tenant", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers": { "get": { "tags": [ "servers" ], "summary": "The tenant's servers.", "operationId": "list_servers", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "includeDeleted", "in": "query", "description": "Include deleted servers (kept for usage).", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServerView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "servers" ], "summary": "Creates a server from a plan and a catalogue image (quota-checked; a task). A\ngenerated password is in the answer, once.", "operationId": "create_server", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "`error.quota.exceeded` (args resource, limit, current, requested), `error.tenant.suspended`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}": { "get": { "tags": [ "servers" ], "summary": "One server.", "operationId": "get_server", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "servers" ], "summary": "Deletes a server and its disks; its addresses go back to the pool.", "operationId": "delete_server", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/console": { "post": { "tags": [ "servers" ], "summary": "A console ticket for the server (refused while the tenant is suspended). Callers that\nare not users of the tenant also need `Kyvernon.Tenant.Impersonate`.", "operationId": "server_console", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsoleTicketView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/power": { "post": { "tags": [ "servers" ], "summary": "A power action: `on`, `off`, `shutdown`, `reboot` or `reset`.", "operationId": "server_power", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/reinstall": { "post": { "tags": [ "servers" ], "summary": "Reinstalls the server from an image; its addresses stay.", "operationId": "server_reinstall", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallServerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/rescue": { "post": { "tags": [ "servers" ], "summary": "Boots a rescue image with the server's disk attached (the server is shut down).", "operationId": "server_rescue", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescueServerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/reset-password": { "post": { "tags": [ "servers" ], "summary": "Sets a new generated password (through the guest agent now, else cloud-init at the\nnext boot); returned once.", "operationId": "server_reset_password", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/resize": { "post": { "tags": [ "servers" ], "summary": "Moves the server to a larger plan: the disk grows (never shrinks) and the server\nreboots (`rebootRequired: true`).", "operationId": "server_resize", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResizeServerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "400": { "description": "`error.server.plan_not_larger`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/snapshots": { "post": { "tags": [ "servers" ], "summary": "Takes a snapshot (within the `snapshots` quota).", "operationId": "server_create_snapshot", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerSnapshotRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/snapshots/{key}": { "delete": { "tags": [ "servers" ], "summary": "Removes a snapshot.", "operationId": "server_remove_snapshot", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Key of the snapshot in the snapshot tree", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/snapshots/{key}/revert": { "post": { "tags": [ "servers" ], "summary": "Reverts the server to a snapshot.", "operationId": "server_revert_snapshot", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Key of the snapshot in the snapshot tree", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/servers/{server}/unrescue": { "post": { "tags": [ "servers" ], "summary": "Ends rescue mode and starts the server again.", "operationId": "server_unrescue", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "server", "in": "path", "description": "Id of the server of the tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerTaskView" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/suspend": { "post": { "tags": [ "tenants" ], "summary": "Suspends a tenant: running VMs are shut down (through the guest, then hard) and their\npower state recorded; users become read-only; power-on and console are refused\n(`Kyvernon.Tenant.Suspend`).", "operationId": "suspend_tenant", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/usage": { "get": { "tags": [ "tenants" ], "summary": "Usage of a month per server: hours per plan (proration over a resize), snapshot\nGiB-hours, and the network side's traffic and extra-IP figures (`Kyvernon.Usage.Read`\non the tenant).", "operationId": "tenant_usage", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "description": "`YYYY-MM` (UTC; default: the current month, up to now).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUsageView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/users": { "get": { "tags": [ "tenants" ], "summary": "The tenant's accounts (`Kyvernon.Tenant.ManageUsers` on the tenant).", "operationId": "tenant_list_users", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "tenants" ], "summary": "Creates an account of the tenant; its role (`admin`, `user`, `read-only`) is granted\non the tenant's folders and pools only.", "operationId": "tenant_create_user", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantUserRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/users/{username}": { "delete": { "tags": [ "tenants" ], "summary": "Deletes an account of the tenant.", "operationId": "tenant_delete_user", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/users/{username}/api-tokens": { "get": { "tags": [ "tenants" ], "summary": "API tokens of a tenant account.", "operationId": "tenant_list_tokens", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "tenants" ], "summary": "Creates an API token for a tenant account (the token is shown once).", "operationId": "tenant_create_token", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenResponse" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/tenants/{tenant}/users/{username}/api-tokens/{id}": { "delete": { "tags": [ "tenants" ], "summary": "Revokes an API token of a tenant account.", "operationId": "tenant_delete_token", "parameters": [ { "name": "tenant", "in": "path", "description": "Id of the tenant (`tenant-N`)", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "User name of the account", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Id of the API token", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/traffic": { "get": { "tags": [ "traffic" ], "summary": "Monthly traffic per VM and per tenant.", "operationId": "traffic", "parameters": [ { "name": "tenant", "in": "query", "description": "Only this tenant (its anchor day applies).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "vm", "in": "query", "description": "Only this VM.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "month", "in": "query", "description": "Period that starts in this month (`YYYY-MM`); absent: the current one.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficReport" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/usage": { "get": { "tags": [ "usage" ], "summary": "The usage ledger over a date range, grouped by VM, tenant, resource pool, folder or\nhost, per day, month or for the whole range; `scope` restricts it to the VMs of one\ncontainer. `format=csv` answers `text/csv`.", "operationId": "usage", "parameters": [ { "name": "from", "in": "query", "description": "First day, `YYYY-MM-DD` (UTC).", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Last day, inclusive.", "required": true, "schema": { "type": "string" } }, { "name": "groupBy", "in": "query", "description": "`vm` (default), `tenant`, `resourcePool`, `folder` or `host`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "period", "in": "query", "description": "`day` (default), `month` or `total`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "format", "in": "query", "description": "`json` (default) or `csv`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "scope", "in": "query", "description": "Container id (datacenter, folder, cluster, host, resource pool, datastore or\nnetwork): only the VMs in it count, with the same rule as\n`GET /v1/inventory/vms?scope=`. Tenant, pool, folder and host lines are then\ncomputed over those VMs only. Requires `System.View` on the container.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "JSON, or text/csv with format=csv", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReportView" } } } }, "400": { "description": "Bad date, range, group, period, format or scope (`error.usage_*`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "The scope container does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/usage/days/{day}": { "get": { "tags": [ "usage" ], "summary": "The usage summary of one day (the document pushed to webhooks).", "operationId": "usage_day", "parameters": [ { "name": "day", "in": "path", "description": "YYYY-MM-DD (UTC)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailySummaryView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms": { "post": { "tags": [ "vms" ], "summary": "Creates a VM in a folder.", "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/register": { "post": { "tags": [ "vms" ], "summary": "Registers an existing VM from a datastore path (`POST /v1/vms/register`,\nSOAP `Folder.RegisterVM_Task`). Restores inventory from `.kyvernon-vm.json`\nwithout recreating disks.", "operationId": "register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterVmRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}": { "delete": { "tags": [ "vms" ], "summary": "Deletes a powered-off VM.", "operationId": "destroy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/addresses": { "get": { "tags": [ "ip-pools" ], "summary": "The public addresses of a VM.", "operationId": "vm_addresses", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VmAddress" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "ip-pools" ], "summary": "Gives a server its public addresses (the server-create hook as a native call):\na primary IPv4 address and, when the pool has IPv6, a /64.", "operationId": "allocate_server", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerAddressBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerAddresses" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "ip-pools" ], "summary": "Returns every address of a server to its pool (the server-delete hook).", "operationId": "release_server", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReleasedAddress" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/addresses/{address}/ptr": { "put": { "tags": [ "ip-pools" ], "summary": "Sets or removes the PTR name of one of the VM's addresses (the tenant path).", "operationId": "set_vm_ptr", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "Public address of the virtual machine", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtrBody" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/clone": { "post": { "tags": [ "vms" ], "summary": "Clones a virtual machine (full or linked).", "operationId": "clone_vm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneVmRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/console/screenshot": { "get": { "tags": [ "vms" ], "summary": "The current frame of the VM's graphical console as a PNG (the summary thumbnail).", "operationId": "screenshot", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "maxWidth", "in": "query", "description": "Widest image wanted in pixels (1..=1920); the host scales down by an integer\nfactor. Absent: the guest's resolution.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "image/png": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "`error.console.powered_off`, `error.console.not_available` (the VM has no graphical console), `error.vm_not_placed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/console/ticket": { "post": { "tags": [ "vms" ], "summary": "Issues a single-use console ticket (30 s) for the VM. The caller then opens the\nWebSocket at `websocketPath` on the same origin; the stream carries RFB (VNC) bytes\nin binary frames, which noVNC speaks directly.", "operationId": "ticket", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsoleTicketView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "`error.console.powered_off`, `error.vm_not_placed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "`error.console.rate_limited`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "`error.console.host_disconnected`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/customize": { "post": { "tags": [ "vms" ], "summary": "Applies a named customization specification to a powered-off VM\n(`POST /v1/vms/{id}/customize`, SOAP `CustomizeVM_Task`).", "description": "Linux / cloud-init specs merge `guestinfo.*` via a reconfigure task; Windows\nspecs submit offline `virt-customize` with the rendered unattend answer file.", "operationId": "customize", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomizeVmRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/export": { "post": { "tags": [ "nfc" ], "summary": "`POST /v1/vms/{id}/export`: SOAP `VirtualMachine.ExportVm`.", "operationId": "export_vm", "parameters": [ { "name": "id", "in": "path", "description": "Virtual machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfcLeaseView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/firewall": { "get": { "tags": [ "firewall" ], "summary": "The firewall of every vNIC of a VM: mode, profile, protection, effective rules with\ncounters, realization.", "operationId": "vm_firewall", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VnicFirewallView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/firewall/logs": { "get": { "tags": [ "firewall" ], "summary": "Firewall log records of a VM, newest first.", "operationId": "vm_logs", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Most records (default 500, at most 5,000).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "host", "in": "query", "description": "Host id.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "rule", "in": "query", "description": "Rule number.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogRecordView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/firewall/mode": { "post": { "tags": [ "firewall" ], "summary": "Switches the firewall mode of a VM's vNICs (a task; `Kyvernon.Firewall.ManageProvider`).\nWith `confirmWithin` the previous mode comes back unless confirmed in time.", "operationId": "set_mode", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModeBody" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/firewall/mode/confirm": { "post": { "tags": [ "firewall" ], "summary": "Confirms the mode switches of a VM that wait for confirmation.", "operationId": "confirm_mode", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VnicFirewallView" } } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/firewall/monitor": { "get": { "tags": [ "firewall" ], "summary": "What the vNICs' rules would have dropped in mode `monitor`, and a proposal.", "operationId": "monitor_report", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorReportView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/firewall/open-port": { "post": { "tags": [ "firewall" ], "summary": "Opens a port of a VM: an inbound allow rule in the VM's own policy `vm-N` (an equal\nrule that exists is returned).", "operationId": "open_port", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "tenant", "in": "query", "description": "Tenant id of a new object (create only).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "wait", "in": "query", "description": "`realized`: answer when the hosts concerned applied the change.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeoutSeconds", "in": "query", "description": "Longest wait in seconds (default 30, at most 300).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "position", "in": "query", "description": "Position of a new rule (default: last).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenPortBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/credentials/acquire": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/credentials/acquire`: SOAP `AcquireCredentialsInGuest`.", "operationId": "acquire_credentials", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAuthRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAuthView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/credentials/release": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/credentials/release`: SOAP `ReleaseCredentialsInGuest`.", "operationId": "release_credentials", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAuthRequest" } } }, "required": true }, "responses": { "204": { "description": "Released" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/credentials/validate": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/credentials/validate`: SOAP `ValidateCredentialsInGuest`.", "operationId": "validate_credentials", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestAuthRequest" } } }, "required": true }, "responses": { "204": { "description": "Guest operations are available" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/environment": { "get": { "tags": [ "guest" ], "summary": "`GET /v1/vms/{id}/guest/environment`: SOAP `ReadEnvironmentVariableInGuest`.", "operationId": "read_environment", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Variable names; empty means the whole environment.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestEnvView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/attrs": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/attrs`: SOAP `ChangeFileAttributesInGuest` (posix).", "operationId": "change_attributes", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestChangeAttributesRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/delete": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/delete`: SOAP `DeleteFileInGuest`.", "operationId": "delete_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestDeleteFileRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/list": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/list`: SOAP `ListFilesInGuest`.", "operationId": "list_files", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestFileListRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestFileListView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/mkdir": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/mkdir`: SOAP `MakeDirectoryInGuest`.", "operationId": "make_directory", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestMkdirRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/move": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/move`: SOAP `MoveFileInGuest`.", "operationId": "move_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestMoveFileRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/move-dir": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/move-dir`: SOAP `MoveDirectoryInGuest`.", "operationId": "move_directory", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestMoveDirectoryRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/read": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/read`: SOAP `InitiateFileTransferFromGuest` (inline bytes).", "operationId": "read_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestFileReadRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestFileReadView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/rmdir": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/rmdir`: SOAP `DeleteDirectoryInGuest`.", "operationId": "delete_directory", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestRmdirRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/temp-dir": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/temp-dir`: SOAP `CreateTemporaryDirectoryInGuest`.", "operationId": "create_temporary_directory", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestCreateTemporaryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestCreateTemporaryView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/temp-file": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/temp-file`: SOAP `CreateTemporaryFileInGuest`.", "operationId": "create_temporary_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestCreateTemporaryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestCreateTemporaryView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/files/write": { "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/files/write`: SOAP `InitiateFileTransferToGuest` (inline bytes).", "operationId": "write_file", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestFileWriteRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestFileWriteView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/processes": { "get": { "tags": [ "guest" ], "summary": "`GET /v1/vms/{id}/guest/processes`: SOAP `ListProcessesInGuest`.", "operationId": "list_processes", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "pid", "in": "query", "description": "Process ids to include (repeat or comma-separated); empty means all remembered.", "required": false, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestProcessListView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "guest" ], "summary": "`POST /v1/vms/{id}/guest/processes`: SOAP `StartProgramInGuest`.", "operationId": "start_program", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestStartProgramRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestStartProgramView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/guest/processes/{pid}": { "delete": { "tags": [ "guest" ], "summary": "`DELETE /v1/vms/{id}/guest/processes/{pid}`: SOAP `TerminateProcessInGuest`.", "operationId": "terminate_process", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "pid", "in": "path", "description": "Process id in the guest", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Terminated" }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/mark-as-template": { "post": { "tags": [ "vms" ], "summary": "Marks a powered-off VM as a template (`POST /v1/vms/{id}/mark-as-template`).", "operationId": "mark_as_template", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/mark-as-vm": { "post": { "tags": [ "vms" ], "summary": "Converts a template back to a VM (`POST /v1/vms/{id}/mark-as-vm`).", "operationId": "mark_as_vm", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsVmRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/nics/{key}/firewall": { "get": { "tags": [ "firewall" ], "summary": "The firewall of one vNIC.", "operationId": "nic_firewall", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Device key of the network adapter (for example `4000`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VnicFirewallView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "firewall" ], "summary": "Sets the profile of a vNIC (`null`: the profile of its kind). A tenant user may\nchoose a selectable profile only.", "operationId": "set_nic_profile", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Device key of the network adapter (for example `4000`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NicProfileBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VnicFirewallView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/power-off": { "post": { "tags": [ "vms" ], "summary": "Powers a VM off hard, at once: the guest is not asked. A VM that is already off stays off and the task succeeds. Use `shutdown` to let the guest shut down first.", "operationId": "power_off", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/power-on": { "post": { "tags": [ "vms" ], "summary": "Powers a VM on.", "operationId": "power_on", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/reconfigure": { "post": { "tags": [ "vms" ], "summary": "Changes the VM configuration. The body carries the whole configuration as read from\n`GET /v1/vms/{id}` with the changes made in it; `config.change_version` names that\nread. Requests made from the same read are merged (each adds its own disk or network\nadapter); a request made from a read that is no longer known answers 409\n`error.vm.concurrent_modification`. Device counts, host capacity, datastore space and\ndisk shrink are checked by the task (`error.vm.too_many_devices`,\n`error.vm.exceeds_host_cpu`, `error.vm.exceeds_host_memory`,\n`error.datastore.insufficient_space`, `error.disk.shrink_not_supported`).", "operationId": "reconfigure", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconfigureVmRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/relocate": { "post": { "tags": [ "vms" ], "summary": "Relocates a VM (`POST /v1/vms/{id}/relocate`, SOAP `RelocateVM_Task`).", "description": "Cold storage relocate via `datastore` and/or per-disk `disks` requires a\npowered-off VM without snapshots; `nics` rebinds Ethernet network backing\n(SOAP `deviceChange` Edit). Host / pool / folder placement uses the same\nmigrate task path.", "operationId": "relocate", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelocateVmRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/reset": { "post": { "tags": [ "vms" ], "summary": "Resets a running VM.", "operationId": "reset", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/resolve-migration": { "post": { "tags": [ "vms" ], "summary": "Resolves a VM fenced after a live migration with an unknown outcome\n(`POST /v1/vms/{id}/resolve-migration`, AgentOps `resolve-migration`).", "description": "The caller must have checked the destination. `source-keeps` resumes the\nsource; `destination-keeps` removes the source instance and moves inventory\nplacement to `host`. Never resume both.", "operationId": "resolve_migration", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveMigrationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveMigrationView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/serial-log": { "get": { "tags": [ "vms" ], "summary": "Reads the tail of the VM's serial console log from the host.", "operationId": "serial_log", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "maxBytes", "in": "query", "description": "Maximum bytes from the end of the log (default 65536, maximum 1048576).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerialLogView" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/shutdown": { "post": { "tags": [ "vms" ], "summary": "Shuts a VM down gracefully: the guest is asked to power off (guest agent, then the ACPI\npower button); when it has not gone down after `timeoutSeconds` (default 90) the VM is\npowered off hard. A guest that takes its time holds up no other virtual machine. A VM\nthat is already off stays off and the task succeeds.", "operationId": "shutdown", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShutdownRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/smtp": { "get": { "tags": [ "ip-pools" ], "summary": "Outgoing SMTP of a VM: whether TCP 25 is blocked per family and whether the VM is\nunblocked.", "operationId": "get_smtp", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmtpView" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "ip-pools" ], "summary": "Unblocks (or blocks again) outgoing SMTP of a VM (operator or portal after its checks;\nrecorded as event `VmSmtpChangedEvent`).", "operationId": "put_smtp", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmtpBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmtpView" } } } }, "403": { "description": "Permission denied; `args.privilege` names the missing privilege", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/snapshots": { "post": { "tags": [ "vms" ], "summary": "Creates a snapshot of a VM.", "operationId": "create_snapshot", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "vms" ], "summary": "Removes every snapshot of a VM.", "operationId": "remove_all_snapshots", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/snapshots/{key}": { "delete": { "tags": [ "vms" ], "summary": "Removes one snapshot (`removeChildren` query removes the subtree).", "operationId": "remove_snapshot", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Key of the snapshot in the snapshot tree", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "removeChildren", "in": "query", "description": "Also remove child snapshots", "required": false, "schema": { "type": "boolean" } } ], "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/snapshots/{key}/rename": { "post": { "tags": [ "vms" ], "summary": "Renames a snapshot (`POST /v1/vms/{id}/snapshots/{key}/rename`, SOAP\n`VirtualMachineSnapshot.RenameSnapshot`). Synchronous; at least one of\n`name` or `description` is required.", "operationId": "rename_snapshot", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Key of the snapshot in the snapshot tree", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSnapshotRequest" } } }, "required": true }, "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/snapshots/{key}/revert": { "post": { "tags": [ "vms" ], "summary": "Reverts a VM to a snapshot.", "operationId": "revert_snapshot", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Key of the snapshot in the snapshot tree", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertSnapshotRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/suspend": { "post": { "tags": [ "vms" ], "summary": "Suspends a running VM.", "operationId": "suspend", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRef" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/traffic": { "get": { "tags": [ "traffic" ], "summary": "A VM's traffic in a period: totals, limit, throttle state and bytes per day.", "operationId": "vm_traffic", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "description": "Period that starts in this month (`YYYY-MM`); absent: the current one.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmTrafficView" } } } }, "503": { "description": "Temporarily unavailable (not the leader, or the service is off)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/traffic-packages": { "post": { "tags": [ "traffic" ], "summary": "Adds an extra traffic package to the VM's current period (raises the limit; lifts a\nthrottle when the new limit is above the use).", "operationId": "add_package", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficPolicy" } } } }, "412": { "description": "Failed precondition; the error body says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/traffic-policy": { "get": { "tags": [ "traffic" ], "summary": "The traffic limit of a VM.", "operationId": "get_policy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficPolicy" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "traffic" ], "summary": "Sets the traffic limit of a VM (from its plan).", "operationId": "put_policy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyInput" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficPolicy" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "traffic" ], "summary": "Removes the traffic limit of a VM (accounting continues; a throttle is lifted).", "operationId": "delete_policy", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/vms/{id}/unregister": { "post": { "tags": [ "vms" ], "summary": "Removes a powered-off VM from inventory without deleting its disk files\n(`POST /v1/vms/{id}/unregister`). Writes `[ds] name/.kyvernon-vm.json` when datastore\nfiles are reachable so SOAP `RegisterVM_Task` / native register can restore it.", "operationId": "unregister", "parameters": [ { "name": "id", "in": "path", "description": "Id of the virtual machine (`vm-N`)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict: the object exists, or `expectedVersion` is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "Lists subscriptions.", "operationId": "list", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionView" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "webhooks" ], "summary": "Creates a subscription.", "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionView" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/webhooks/{id}": { "put": { "tags": [ "webhooks" ], "summary": "Changes a subscription (`Kyvernon.Webhook.Manage`).", "operationId": "update", "parameters": [ { "name": "id", "in": "path", "description": "Id of the webhook subscription", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionView" } } } }, "400": { "description": "Invalid argument; the error body names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "webhooks" ], "summary": "Deletes a subscription.", "operationId": "delete", "parameters": [ { "name": "id", "in": "path", "description": "Id of the webhook subscription", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no body" } }, "security": [ { "bearer": [] } ] } }, "/v1/webhooks/{id}/dead-letters": { "get": { "tags": [ "webhooks" ], "summary": "Dead letters of a subscription.", "operationId": "dead_letters", "parameters": [ { "name": "id", "in": "path", "description": "Id of the webhook subscription", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeadLetterView" } } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "webhooks" ], "summary": "The delivery log of a subscription: its last deliveries (at most 50), newest first,\ntest deliveries included. Kept in the replicated store with the subscription.", "operationId": "deliveries", "parameters": [ { "name": "id", "in": "path", "description": "Id of the webhook subscription", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryView" } } } } }, "404": { "description": "Not found (or not visible to the caller)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "webhooks" ], "summary": "Sends a test event.", "operationId": "test", "parameters": [ { "name": "id", "in": "path", "description": "Id of the webhook subscription", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResultView" } } } } }, "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "About": { "type": "object", "description": "Service information.", "required": [ "name", "version", "apiVersion", "nodeId", "isLeader", "storeVersion", "records", "uptimeSeconds" ], "properties": { "apiVersion": { "type": "string", "description": "API version." }, "isLeader": { "type": "boolean", "description": "Whether this node is the leader." }, "name": { "type": "string", "description": "Product name." }, "nodeId": { "type": "integer", "format": "int64", "description": "Store node id.", "minimum": 0 }, "records": { "type": "integer", "description": "Number of records.", "minimum": 0 }, "storeVersion": { "type": "integer", "format": "int64", "description": "Current store version.", "minimum": 0 }, "uptimeSeconds": { "type": "integer", "format": "int64", "description": "Uptime in seconds.", "minimum": 0 }, "version": { "type": "string", "description": "Build version." } } }, "AcknowledgeRequest": { "type": "object", "description": "Acknowledge request.", "required": [ "targetId" ], "properties": { "targetId": { "type": "string", "description": "Entity whose state is acknowledged." } } }, "ActionView": { "type": "string", "description": "Rule action.", "enum": [ "allow", "drop", "reject", "pass" ] }, "AddHostRequest": { "type": "object", "description": "Body for `POST /v1/clusters/{id}/hosts` (`AddHost_Task`).", "required": [ "name" ], "properties": { "force": { "type": [ "boolean", "null" ], "description": "When true, return an existing same-name host instead of failing; a registered host\nin this cluster is reset (its certificate revoked) so its agent can join again with\nthe join token." }, "managementAddress": { "type": [ "string", "null" ], "description": "Optional management address; defaults to `name`." }, "name": { "type": "string", "description": "Host display name / FQDN (must match the agent's `hostname` at join)." } } }, "AddUpdateSessionFileRequest": { "type": "object", "description": "Add a PUSH file to an update session.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "File name (basename, e.g. `ubuntu.iso`)." }, "size": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional expected size in bytes." }, "sourceType": { "type": "string", "description": "Source type; only `PUSH` is supported." } } }, "AddressSince": { "type": "object", "description": "An address and when it was allocated.", "required": [ "address", "since" ], "properties": { "address": { "type": "string", "description": "The address." }, "since": { "type": "string", "description": "Allocation time." } } }, "AlarmAction": { "oneOf": [ { "type": "object", "description": "Emit an `AlarmStatusChangedEvent` (always done; listed for explicitness).", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "event" ] } } }, { "type": "object", "description": "Deliver to webhook subscriptions tagged with this label.", "required": [ "label", "type" ], "properties": { "label": { "type": "string", "description": "Subscription label." }, "type": { "type": "string", "enum": [ "webhook" ] } } } ], "description": "What an alarm does when it changes status." }, "AlarmStateView": { "type": "object", "description": "Alarm state on one entity.", "required": [ "targetId", "status", "since", "acknowledged" ], "properties": { "acknowledged": { "type": "boolean", "description": "Acknowledged." }, "since": { "type": "string", "description": "Since." }, "status": { "$ref": "#/components/schemas/AlarmStatusView", "description": "Status." }, "targetId": { "type": "string", "description": "Entity id." } } }, "AlarmStatus": { "type": "string", "description": "Alarm status (`ManagedEntityStatus`).", "enum": [ "gray", "green", "yellow", "red" ] }, "AlarmStatusView": { "type": "string", "description": "Alarm status.", "enum": [ "gray", "green", "yellow", "red" ] }, "AlarmTrigger": { "oneOf": [ { "type": "object", "description": "An event of this type on an entity in scope sets `status`.", "required": [ "event_type", "status", "type" ], "properties": { "event_type": { "type": "string", "description": "Event type to match." }, "status": { "$ref": "#/components/schemas/AlarmStatus", "description": "Status to set." }, "type": { "type": "string", "enum": [ "event" ] } } }, { "type": "object", "description": "A metric sample crossing a threshold.", "required": [ "metric", "comparison", "yellow", "red", "type" ], "properties": { "comparison": { "$ref": "#/components/schemas/Comparison", "description": "Comparison." }, "metric": { "type": "string", "description": "Metric id, e.g. `cpu.usage.percent`." }, "red": { "type": "number", "format": "double", "description": "Threshold for red." }, "type": { "type": "string", "enum": [ "metric" ] }, "yellow": { "type": "number", "format": "double", "description": "Threshold for yellow." } } } ], "description": "What raises an alarm." }, "AlarmView": { "type": "object", "description": "An alarm definition with states.", "required": [ "id", "name", "description", "scopeId", "enabled", "trigger", "states" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmAction" }, "description": "Actions." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled." }, "id": { "type": "string", "description": "Alarm id." }, "name": { "type": "string", "description": "Name." }, "scopeId": { "type": "string", "description": "Scope entity id." }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmStateView" }, "description": "Per-entity states." }, "trigger": { "$ref": "#/components/schemas/AlarmTrigger", "description": "Trigger definition." }, "version": { "type": "integer", "format": "int64", "description": "Record version, for `expectedVersion` of `PUT /v1/alarms/{id}`.", "minimum": 0 } } }, "AllocateBody": { "type": "object", "description": "Allocate an address.", "properties": { "address": { "type": [ "string", "null" ], "description": "A specific IPv4 address." }, "family": { "type": [ "string", "null" ], "description": "`ipv4` (default) or `ipv6` (a /64)." }, "mac": { "type": [ "string", "null" ], "description": "NIC MAC (absent: the VM's first NIC on the pool's network)." }, "reference": { "type": [ "string", "null" ], "description": "Caller reference." }, "role": { "type": [ "string", "null" ], "description": "`primary` (default) or `extra`." }, "tenant": { "type": [ "string", "null" ], "description": "Tenant (quota)." }, "vm": { "type": [ "string", "null" ], "description": "VM to bind to (absent: reserved for the tenant)." } }, "additionalProperties": false }, "AllocationView": { "type": "object", "description": "One address of a pool: allocated or in quarantine.", "required": [ "address", "family", "status" ], "properties": { "address": { "type": "string", "description": "IPv4 address, or the /64 (`prefix/64`)." }, "allocatedAt": { "type": [ "string", "null" ], "description": "Allocation time." }, "family": { "type": "string", "description": "`ipv4` or `ipv6`." }, "mac": { "type": [ "string", "null" ], "description": "Bound NIC MAC." }, "ptr": { "type": [ "string", "null" ], "description": "Reverse DNS name." }, "ptrReason": { "type": [ "string", "null" ], "description": "Why the operator rejected the name." }, "ptrStatus": { "type": [ "string", "null" ], "description": "`applied`, `requested`, `rejected`, or `to_remove` (a released address whose PTR an\noperator must remove; status `released`)." }, "quarantinedUntil": { "type": [ "string", "null" ], "description": "End of the quarantine." }, "reference": { "type": [ "string", "null" ], "description": "Caller reference." }, "role": { "type": [ "string", "null" ], "description": "`primary` or `extra` (IPv4)." }, "status": { "type": "string", "description": "`allocated` or `quarantined`." }, "tenant": { "type": [ "string", "null" ], "description": "Tenant." }, "vm": { "type": [ "string", "null" ], "description": "Bound VM." } } }, "ApiInfoView": { "type": "object", "description": "OpenAPI stand-in for `GET /v1/backup/info` (`ApiInfo`).", "required": [ "apiVersion", "granularity", "maxAreasPerPage", "maxTtlSeconds", "remoteExports", "features" ], "properties": { "apiVersion": { "type": "string", "description": "API version string (`1.0`)." }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/BackupFeatureView" }, "description": "Features the service advertises." }, "granularity": { "type": "integer", "format": "int64", "description": "Default tracking granularity in bytes.", "minimum": 0 }, "maxAreasPerPage": { "type": "integer", "format": "int64", "description": "Largest `maxAreas` accepted.", "minimum": 0 }, "maxTtlSeconds": { "type": "integer", "format": "int64", "description": "Longest session TTL in seconds.", "minimum": 0 }, "remoteExports": { "type": "boolean", "description": "Whether exports are reachable off-host (TCP with TLS)." } } }, "ApiTokenView": { "type": "object", "description": "An API token without its secret.", "required": [ "id", "name", "createdAt" ], "properties": { "createdAt": { "type": "string", "description": "Creation time." }, "expiresAt": { "type": [ "string", "null" ], "description": "Expiry." }, "id": { "type": "string", "description": "Public id (16 hex characters, also inside the token)." }, "lastUsed": { "type": [ "string", "null" ], "description": "Last use." }, "name": { "type": "string", "description": "Label." } } }, "ApplyTemplateBody": { "type": "object", "description": "Body of `POST /v1/firewall/templates/{id}/apply`.", "required": [ "vm" ], "properties": { "vm": { "type": "string", "description": "VM id." } }, "additionalProperties": false }, "AuditView": { "type": "object", "description": "An audit record.", "required": [ "id", "at", "actor", "action", "correlationId", "outcome", "clientAddress", "details" ], "properties": { "action": { "type": "string", "description": "Action." }, "actor": { "type": "string", "description": "Actor." }, "afterHash": { "type": [ "string", "null" ], "description": "After hash." }, "at": { "type": "string", "description": "Time." }, "beforeHash": { "type": [ "string", "null" ], "description": "Before hash." }, "clientAddress": { "type": "string", "description": "Client address." }, "correlationId": { "type": "string", "description": "Correlation id." }, "details": { "type": "object", "description": "Details.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Id." }, "outcome": { "type": "string", "description": "`success`, `denied` or `error`." }, "targetId": { "type": [ "string", "null" ], "description": "Target." } } }, "AuthConfigView": { "type": "object", "description": "`GET /v1/auth/config`: what the sign-in page needs before anyone is signed in.", "required": [ "oidc", "idleTimeoutSeconds" ], "properties": { "idleTimeoutSeconds": { "type": "integer", "format": "int64", "description": "Idle timeout of browser sessions in seconds.", "minimum": 0 }, "oidc": { "$ref": "#/components/schemas/OidcConfigView", "description": "OIDC sign-in." } } }, "AuthLoginRequest": { "type": "object", "description": "`POST /v1/auth/login` body.", "required": [ "username", "password" ], "properties": { "password": { "type": "string", "description": "Password." }, "username": { "type": "string", "description": "Account name." } } }, "AuthMfaRequest": { "type": "object", "description": "`POST /v1/auth/mfa` body: the challenge token and exactly one of `code` and\n`recoveryCode`.", "required": [ "pendingToken" ], "properties": { "code": { "type": [ "string", "null" ], "description": "Six-digit TOTP code." }, "pendingToken": { "type": "string", "description": "`pendingToken` from the login response (`mfaToken` is accepted as an alias)." }, "recoveryCode": { "type": [ "string", "null" ], "description": "A recovery code." } } }, "AuthPasswordRequest": { "type": "object", "description": "`POST /v1/auth/password` body.", "required": [ "currentPassword", "newPassword" ], "properties": { "currentPassword": { "type": "string", "description": "Current password." }, "newPassword": { "type": "string", "description": "New password (12..=256 characters, not common, not containing the username)." } } }, "AuthResponse": { "type": "object", "description": "Response of the browser login endpoints (`/v1/auth/login`, `/mfa`, `/refresh`,\n`/password`, `/totp/confirm`). Token responses also set the `kyv_refresh` and\n`kyvernon_csrf` cookies. Shape agreed with the UI (`ui/app/src/auth/contract.ts`).", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "description": "`session` (a session, possibly restricted to the password change, see\n`session.passwordRotationRequired`), `mfa_enrolment_required` (a session restricted\nto TOTP enrolment) or `mfa_required` (no session; answer with `pendingToken`)." }, "pendingToken": { "type": [ "string", "null" ], "description": "For `mfa_required`: the single-use challenge token for `POST /v1/auth/mfa`." }, "pendingTokenExpiresAt": { "type": [ "string", "null" ], "description": "For `mfa_required`: expiry of the challenge (5 minutes)." }, "recoveryCodes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only from `POST /v1/auth/totp/confirm`: ten single-use recovery codes, shown once." }, "session": { "oneOf": [ { "$ref": "#/components/schemas/AuthSessionTokens", "description": "The session, absent for `mfa_required`." }, { "type": "null" } ] }, "stage": { "type": [ "string", "null" ], "description": "What the session may do: `authenticated`, `password_change_required` or\n`mfa_enrolment_required`; absent for `mfa_required`." } } }, "AuthSessionTokens": { "type": "object", "description": "A browser session in an [`AuthResponse`].", "required": [ "token", "tokenType", "sessionId", "expiresAt", "accessExpiresAt", "expiresIn", "idleTimeoutSeconds", "csrfToken", "user", "passwordRotationRequired", "mfaEnrolmentRequired" ], "properties": { "accessExpiresAt": { "type": "string", "description": "Expiry of this access token (RFC 3339; 15 min); refresh before it." }, "csrfToken": { "type": "string", "description": "The CSRF token (same value as the `kyvernon_csrf` cookie)." }, "expiresAt": { "type": "string", "description": "Absolute expiry of the session (RFC 3339; 12 h after login)." }, "expiresIn": { "type": "integer", "format": "int64", "description": "Seconds until the access token expires.", "minimum": 0 }, "idleTimeoutSeconds": { "type": "integer", "format": "int64", "description": "Idle timeout of the session in seconds.", "minimum": 0 }, "mfaEnrolmentRequired": { "type": "boolean", "description": "TOTP enrolment is required (after the password change, if that is pending too)." }, "passwordRotationRequired": { "type": "boolean", "description": "Only the password change is allowed until it is done." }, "sessionId": { "type": "string", "description": "Session (token family) id." }, "token": { "type": "string", "description": "Bearer access token; keep it in memory only." }, "tokenType": { "type": "string", "description": "Always `Bearer`." }, "user": { "$ref": "#/components/schemas/UserView", "description": "The user." } } }, "AuthSessionView": { "type": "object", "description": "`GET /v1/auth/session` response.", "required": [ "stage", "sessionId", "createdAt", "sessionExpiresAt", "idleTimeoutSeconds", "mfaVerified", "user" ], "properties": { "accessTokenExpiresAt": { "type": [ "string", "null" ], "description": "Expiry of the presented access token (browser sessions)." }, "createdAt": { "type": "string", "description": "Creation time." }, "idleTimeoutSeconds": { "type": "integer", "format": "int64", "description": "Idle timeout in seconds.", "minimum": 0 }, "mfaVerified": { "type": "boolean", "description": "Second factor completed in this session." }, "sessionExpiresAt": { "type": "string", "description": "Absolute expiry." }, "sessionId": { "type": "string", "description": "Session id." }, "stage": { "type": "string", "description": "`authenticated`, `password_change_required` or `mfa_enrolment_required`." }, "user": { "$ref": "#/components/schemas/UserView", "description": "The user." } } }, "AvailableMetricView": { "type": "object", "description": "One available (counter, instance) pair.", "required": [ "counterId", "counter", "instance" ], "properties": { "counter": { "type": "string", "description": "Counter name." }, "counterId": { "type": "integer", "format": "int32", "description": "Counter id." }, "instance": { "type": "string", "description": "Instance (`\"\"` = aggregate)." } } }, "AvailableView": { "type": "object", "description": "Counters with data for an entity.", "required": [ "entity", "interval", "metrics" ], "properties": { "entity": { "type": "string", "description": "Entity id." }, "interval": { "type": "integer", "format": "int32", "description": "Sampling period.", "minimum": 0 }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableMetricView" }, "description": "Pairs." } } }, "BackupFeatureView": { "type": "string", "description": "OpenAPI stand-in for backup feature names advertised by `/v1/backup/info`.", "enum": [ "allocation-context", "dirty-bitmap-context", "fleecing", "quiesce" ] }, "BackupPointDiskView": { "type": "object", "description": "One disk of a backup point.", "required": [ "deviceKey", "capacityBytes" ], "properties": { "capacityBytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "changeId": { "type": [ "string", "null" ], "description": "Change id the backup was taken at (for incremental backups), when known." }, "deviceKey": { "type": "integer", "format": "int32", "description": "Device key of the disk in the virtual machine." } } }, "BackupPointView": { "type": "object", "description": "A backup kept in the repository.", "required": [ "id", "vmId", "vmName", "takenAt", "kind", "consistency", "sizeBytes", "disks", "diskDetails" ], "properties": { "consistency": { "type": "string", "description": "`CRASH_CONSISTENT`: what the repository can promise (the manifest does not say\nwhether the guest was quiesced)." }, "diskDetails": { "type": "array", "items": { "$ref": "#/components/schemas/BackupPointDiskView" }, "description": "The disks." }, "disks": { "type": "integer", "description": "Number of disks.", "minimum": 0 }, "id": { "type": "string", "description": "Id of the backup point (the id of the backup session that made it)." }, "kind": { "type": "string", "description": "`full`: the repository keeps whole disk images." }, "sessionId": { "type": [ "string", "null" ], "description": "The backup session that made it." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "Size of the backup in the repository, in bytes.", "minimum": 0 }, "takenAt": { "type": "string", "description": "When the backup completed (RFC 3339)." }, "verified": { "type": [ "boolean", "null" ], "description": "Result of the last restore verification of this point, when one ran." }, "vmId": { "type": "string", "description": "Instance uuid of the virtual machine." }, "vmName": { "type": "string", "description": "Name of the virtual machine, when it still exists." }, "vmRef": { "type": [ "string", "null" ], "description": "Inventory id of the virtual machine (`vm-N`), when it still exists." } } }, "BackupRepositoryView": { "type": "object", "description": "The backup repository.", "required": [ "configured", "points" ], "properties": { "configured": { "type": "boolean", "description": "A repository is configured (`[backup] verify_repository` of the controller)." }, "points": { "type": "integer", "description": "Backup points kept.", "minimum": 0 } } }, "BackupScheduleRequest": { "type": "object", "description": "Body of `POST /v1/backup/schedules` and `PUT /v1/backup/schedules/{id}`.", "required": [ "name", "scope", "frequency", "hour" ], "properties": { "enabled": { "type": "boolean", "description": "Runs when true." }, "frequency": { "type": "string", "description": "`daily` or `weekly`." }, "fullEvery": { "type": "integer", "format": "int32", "description": "A full transfer every n points (default 7).", "minimum": 0 }, "hour": { "type": "integer", "format": "int32", "description": "Hour, UTC.", "minimum": 0 }, "minute": { "type": "integer", "format": "int32", "description": "Minute.", "minimum": 0 }, "name": { "type": "string", "description": "Name." }, "quiesce": { "$ref": "#/components/schemas/QuiesceModeView", "description": "Quiescing." }, "retention": { "type": "integer", "format": "int32", "description": "Points kept per virtual machine (default 14; 0: all).", "minimum": 0 }, "scope": { "type": "string", "description": "Inventory id of the folder, datacenter, cluster, resource pool, host or virtual\nmachine." }, "weekdays": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Weekdays, 0 is Sunday (weekly only)." } } }, "BackupScheduleView": { "type": "object", "description": "A backup schedule.", "required": [ "id", "name", "enabled", "scope", "frequency", "hour", "minute", "weekdays", "quiesce", "fullEvery", "retention" ], "properties": { "enabled": { "type": "boolean", "description": "Runs when true." }, "frequency": { "type": "string", "description": "`daily` or `weekly`." }, "fullEvery": { "type": "integer", "format": "int32", "description": "A full transfer every n points (1: every point is full).", "minimum": 0 }, "hour": { "type": "integer", "format": "int32", "description": "Hour, UTC.", "minimum": 0 }, "id": { "type": "string", "description": "Id (`bkschedule-N`)." }, "lastResult": { "type": [ "string", "null" ], "description": "`success` or `failure` of the last finished run." }, "lastRunAt": { "type": [ "string", "null" ], "description": "Start of the last run." }, "minute": { "type": "integer", "format": "int32", "description": "Minute.", "minimum": 0 }, "name": { "type": "string", "description": "Name." }, "nextRunAt": { "type": [ "string", "null" ], "description": "Next run." }, "quiesce": { "$ref": "#/components/schemas/QuiesceModeView", "description": "Quiescing." }, "retention": { "type": "integer", "format": "int32", "description": "Points kept per virtual machine (0: all).", "minimum": 0 }, "scope": { "type": "string", "description": "Folder, datacenter, cluster, resource pool, host or virtual machine it covers." }, "scopeName": { "type": [ "string", "null" ], "description": "Name of the scope." }, "weekdays": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Weekdays, 0 is Sunday (weekly only)." } } }, "BackupSessionView": { "type": "object", "description": "OpenAPI stand-in for `BackupSession`.", "required": [ "id", "vmId", "state", "disks", "quiesce", "fleecing", "owner", "createdAt", "updatedAt", "deadline", "ttlSeconds" ], "properties": { "cleanupPending": { "type": "boolean", "description": "Host-side cleanup is pending retry." }, "consistency": { "oneOf": [ { "$ref": "#/components/schemas/ConsistencyView", "description": "Achieved consistency, once the backup point exists." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation time (RFC 3339 UTC)." }, "deadline": { "type": "string", "format": "date-time", "description": "Session expires at this time unless kept alive (RFC 3339 UTC)." }, "disks": { "type": "array", "items": { "$ref": "#/components/schemas/DiskBackupView" }, "description": "Disks in the session." }, "fleecing": { "type": "boolean", "description": "Whether fleecing was requested." }, "id": { "type": "string", "format": "uuid", "description": "Session id." }, "owner": { "type": "string", "description": "Principal that started the session." }, "pointId": { "type": [ "string", "null" ], "description": "Agent-side identifier of the backup point." }, "quiesce": { "$ref": "#/components/schemas/QuiesceModeView", "description": "Requested quiescing." }, "reason": { "type": [ "string", "null" ], "description": "Message key for `ABORTED` or `EXPIRED`, if any." }, "state": { "$ref": "#/components/schemas/SessionStateView", "description": "Current state." }, "ttlSeconds": { "type": "integer", "format": "int64", "description": "Lifetime granted by each keepalive, in seconds.", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last state change or keepalive (RFC 3339 UTC)." }, "vmId": { "type": "string", "format": "uuid", "description": "VM instance UUID." } } }, "BackupSettingsRequest": { "type": "object", "description": "Body of `PUT /v1/backup/settings` (`remoteExports` is ignored).", "required": [ "repository", "defaultQuiesce", "verifyTimeoutSeconds", "verifyDestroy" ], "properties": { "defaultQuiesce": { "$ref": "#/components/schemas/QuiesceModeView", "description": "Quiescing of backups that do not say." }, "remoteExports": { "type": [ "boolean", "null" ], "description": "Ignored (configuration only)." }, "repository": { "type": "string", "description": "Repository directory, absolute; empty: none." }, "verifyDestroy": { "type": "boolean", "description": "Destroy verification VMs after the verdict." }, "verifyNetwork": { "type": "string", "description": "Quarantine network (id or name); empty: none." }, "verifyPool": { "type": "string", "description": "Datastore restored disks go to; empty: the first usable one." }, "verifySchedule": { "type": "string", "description": "Nightly verification schedule; empty: off." }, "verifyTimeoutSeconds": { "type": "integer", "format": "int64", "description": "Timeout of one verification, 30 to 3600 seconds.", "minimum": 0 } } }, "BackupSettingsView": { "type": "object", "description": "Settings of the backup service. Changes are kept in the replicated store and apply on\nevery controller; a field the console never changed shows the `[backup]` section.", "required": [ "repository", "defaultQuiesce", "remoteExports", "verifySchedule", "verifyNetwork", "verifyTimeoutSeconds", "verifyDestroy", "verifyPool" ], "properties": { "defaultQuiesce": { "$ref": "#/components/schemas/QuiesceModeView", "description": "Quiescing of backups that do not say." }, "remoteExports": { "type": "boolean", "description": "Off-host exports (TCP with TLS); set in the configuration, read-only here." }, "repository": { "type": "string", "description": "Repository directory (`verify_repository`); empty: none." }, "verifyDestroy": { "type": "boolean", "description": "Destroy verification VMs after the verdict." }, "verifyNetwork": { "type": "string", "description": "Quarantine network of the nightly verification." }, "verifyPool": { "type": "string", "description": "Datastore restored disks go to; empty: the first usable one." }, "verifySchedule": { "type": "string", "description": "Nightly verification: `HH:MM` UTC or an interval such as `6h`; empty: off." }, "verifyTimeoutSeconds": { "type": "integer", "format": "int64", "description": "Timeout of one verification, seconds.", "minimum": 0 } } }, "BeginBackupRequestView": { "type": "object", "description": "OpenAPI stand-in for BeginBackupRequest (model lives in kyvernon-backup).", "required": [ "vmId" ], "properties": { "disks": { "type": "array", "items": { "$ref": "#/components/schemas/DiskSelectionView" }, "description": "Disk selections; empty means every CBT-enabled disk with `*`." }, "fallbackToFull": { "type": "boolean", "description": "Fall back to a full backup when a change id is stale." }, "fleecing": { "type": "boolean", "description": "Fleecing requested." }, "quiesce": { "$ref": "#/components/schemas/QuiesceModeView", "description": "Quiesce mode (`NONE` / `PREFERRED` / `REQUIRED`)." }, "ttlSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Session TTL in seconds.", "minimum": 0 }, "vmId": { "type": "string", "format": "uuid", "description": "VM instance UUID." } } }, "BeginRestoreRequest": { "type": "object", "description": "Body for begin restore.", "required": [ "vmId", "deviceKey", "capacity", "pool" ], "properties": { "capacity": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "deviceKey": { "type": "integer", "format": "int32", "description": "Device key the restored disk will use." }, "pool": { "type": "string", "description": "Target pool / datastore name (recorded; simulate attaches using an existing datastore)." }, "thin": { "type": "boolean", "description": "Thin provisioning." }, "verify": { "oneOf": [ { "$ref": "#/components/schemas/VerifySpec", "description": "Verify the restore when this disk is committed: the VM (all of whose NICs must be on\nthe quarantine network named here) is powered on and judged by its boot, its DHCP\nlease and its console; see `GET /v1/backup/restores/{vmId}`. Put it on the last disk\nof a multi-disk VM." }, { "type": "null" } ] }, "vmId": { "type": "string", "format": "uuid", "description": "Target VM instance UUID (new or powered-off)." } } }, "Billable": { "type": "string", "description": "Which direction is billed.", "enum": [ "out", "in_out", "max" ] }, "BootEvidence": { "type": "object", "description": "What the boot showed.", "required": [ "reachedRunning", "serialBytes", "firmwareMarkers", "osMarkers", "serialTail" ], "properties": { "firmwareMarkers": { "type": "array", "items": { "type": "string" }, "description": "Firmware markers seen." }, "osMarkers": { "type": "array", "items": { "type": "string" }, "description": "Operating-system markers seen." }, "reachedRunning": { "type": "boolean", "description": "The VM's lifecycle state was `running`." }, "serialBytes": { "type": "integer", "format": "int64", "description": "Bytes of serial console output seen.", "minimum": 0 }, "serialTail": { "type": "string", "description": "The end of the serial console output (bounded)." } } }, "BridgeKind": { "type": "string", "description": "OpenAPI schema of [`BridgeKind`], whose crate has no schema support;\n`bridge_kind_schema_matches_the_model` keeps the two equal.", "enum": [ "ovs", "linux" ] }, "BypassBody": { "type": "object", "description": "Body of `POST /v1/firewall/bypass`.", "required": [ "host", "reason" ], "properties": { "durationSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long, seconds (60 to 86,400; default 1,800).", "minimum": 0 }, "host": { "type": "string", "description": "Host id (`host-N`)." }, "reason": { "type": "string", "description": "Why (kept in the policy and the events; 1 to 500 characters)." } }, "additionalProperties": false }, "BypassView": { "type": "object", "description": "A bypass in force.", "required": [ "id", "host", "reason", "expiresAt", "rule" ], "properties": { "expiresAt": { "type": "string", "description": "End (RFC 3339)." }, "host": { "type": "string", "description": "Host id." }, "id": { "type": "string", "description": "Policy id (`fwpolicy-N`), the id for `DELETE`." }, "reason": { "type": "string", "description": "Reason." }, "rule": { "type": "integer", "format": "int32", "description": "Rule number.", "minimum": 0 } } }, "Cardinality": { "type": "string", "description": "Tag cardinality within a category.", "enum": [ "single", "multiple" ] }, "CatalogueImageView": { "type": "object", "description": "Catalogue metadata of an image (a template VM).", "properties": { "catalogue": { "type": "boolean", "description": "Offered to tenants." }, "cloudInit": { "type": "boolean", "description": "Personalised through cloud-init." }, "defaultUser": { "type": "string", "description": "Default user." }, "displayName": { "type": "string", "description": "Name shown to tenants." }, "minDiskGib": { "type": "integer", "format": "int64", "description": "Smallest disk (GiB).", "minimum": 0 }, "noCredentials": { "type": "boolean", "description": "Takes no credentials (no password or SSH keys; e.g. EuroOS)." }, "osFamily": { "type": "string", "description": "`linux`, `windows`, `euroos`, `bsd` or `other`." }, "osVersion": { "type": "string", "description": "OS version." }, "rescue": { "type": "boolean", "description": "A rescue image." }, "templateId": { "type": "string", "description": "The template (`vm-N`; ignored in requests, the path names it)." }, "templateName": { "type": "string", "description": "The template's name." } } }, "CategoryView": { "type": "string", "description": "Category.", "enum": [ "emergency", "infrastructure", "environment", "application" ] }, "CdpHintView": { "type": "object", "description": "CDP neighbour fields (`PhysicalNicCdpInfo`).", "properties": { "deviceId": { "type": [ "string", "null" ], "description": "Device ID (`devId`)." }, "mgmtAddr": { "type": [ "string", "null" ], "description": "Management address." }, "platform": { "type": [ "string", "null" ], "description": "Platform / hardware." }, "portId": { "type": [ "string", "null" ], "description": "Port ID." }, "softwareVersion": { "type": [ "string", "null" ], "description": "Software version." }, "systemName": { "type": [ "string", "null" ], "description": "System name when distinct from device id." }, "ttl": { "type": [ "integer", "null" ], "format": "int32", "description": "TTL." } } }, "ChangePasswordRequest": { "type": "object", "description": "Change-password request.", "required": [ "newPassword" ], "properties": { "currentPassword": { "type": [ "string", "null" ], "description": "Current password (required for self-service)." }, "newPassword": { "type": "string", "description": "New password." } } }, "ChangeSetView": { "type": "object", "description": "Changes of one committed transaction.", "required": [ "version", "at", "changes" ], "properties": { "actor": { "type": [ "string", "null" ], "description": "Actor." }, "at": { "type": "string", "description": "Time." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeView" }, "description": "Changes." }, "version": { "type": "integer", "format": "int64", "description": "Version produced by the transaction.", "minimum": 0 } } }, "ChangeView": { "type": "object", "description": "One change in the feed.", "required": [ "kind", "object" ], "properties": { "kind": { "type": "string", "description": "`created`, `updated` or `deleted`." }, "object": { "$ref": "#/components/schemas/ObjectView", "description": "The object after the change (before, for `deleted`)." } } }, "ChangedAreaView": { "type": "object", "description": "OpenAPI stand-in for one changed or allocated byte range.", "required": [ "start", "length" ], "properties": { "length": { "type": "integer", "format": "int64", "description": "Length in bytes (never zero).", "minimum": 0 }, "start": { "type": "integer", "format": "int64", "description": "Byte offset.", "minimum": 0 } } }, "ChangesResponse": { "type": "object", "description": "Long-poll response of the change feed.", "required": [ "version", "changeSets", "resync" ], "properties": { "changeSets": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeSetView" }, "description": "Change sets since the requested version (may be empty on timeout)." }, "resync": { "type": "boolean", "description": "True when the requested version is too old or the replica jumped: the\nclient must re-read and resume from `version`." }, "version": { "type": "integer", "format": "int64", "description": "Version to resume from.", "minimum": 0 } } }, "CheckResponse": { "type": "object", "description": "Privilege check result.", "required": [ "granted" ], "properties": { "granted": { "type": "boolean", "description": "Granted." } } }, "ClearTriggeredAlarmsRequest": { "type": "object", "description": "Clear triggered (non-green) alarm states (`ClearTriggeredAlarms`).", "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmStatusView" }, "description": "Only clear these statuses; empty clears every non-green state." } } }, "CloneVmRequest": { "type": "object", "description": "Clone a virtual machine (`POST /v1/vms/{id}/clone`).\n\nBuilds disk copies next to the source (or on `datastore`) and submits the same\ntask the SOAP `CloneVM_Task` path uses.", "required": [ "name" ], "properties": { "copyFirewall": { "type": "boolean", "description": "Copy the source's firewall: vNIC mode and profile, static group memberships, the\nrules of its own policy (same tenant only; `Kyvernon.Firewall.ManagePolicies` on\nthe source). Without it the clone's vNICs start like new ones." }, "copyTags": { "type": "boolean", "description": "Attach the source's tags to the clone (same tenant only;\n`InventoryService.Tagging.AttachTag` on the source)." }, "datastore": { "type": [ "string", "null" ], "description": "Target datastore for every disk. Defaults to each disk's current datastore.\nLinked clones require the same datastore as the source disks." }, "folderId": { "type": [ "string", "null" ], "description": "Destination VM folder (`group-vN`). Defaults to the source's folder." }, "host": { "type": [ "string", "null" ], "description": "Host (`host-N`). Defaults to the source's host." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "linked": { "type": "boolean", "description": "Linked clone (qcow2 child of a snapshot). Requires `snapshot`." }, "name": { "type": "string", "description": "Name of the clone." }, "powerOn": { "type": "boolean", "description": "Power the clone on after creation." }, "resourcePool": { "type": [ "string", "null" ], "description": "Resource pool (`resgroup-N`). Defaults to the source's pool." }, "snapshot": { "type": [ "integer", "null" ], "format": "int32", "description": "Snapshot key to clone from (required when `linked` is true).", "minimum": 0 }, "template": { "type": "boolean", "description": "Mark the clone as a template." } } }, "CloseTenantRequest": { "type": "object", "description": "Request to close a tenant.", "properties": { "graceSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds until VMs and disks are destroyed (default: the controller's\n`[tenancy] close_grace`, 7 days).", "minimum": 0 } } }, "Cluster": { "type": "object", "description": "A cluster of hosts.", "required": [ "name" ], "properties": { "ha": { "$ref": "#/components/schemas/ClusterHaConfig", "description": "HA settings." }, "migration": { "$ref": "#/components/schemas/ClusterMigrationConfig", "description": "Live-migration policy (bandwidth, downtime, postcopy opt-in)." }, "name": { "type": "string", "description": "Display name." }, "scheduler": { "$ref": "#/components/schemas/ClusterSchedulerConfig", "description": "Scheduler settings." } }, "additionalProperties": false }, "ClusterHaConfig": { "type": "object", "description": "High-availability settings of a cluster (subset; the scheduler team extends).", "properties": { "enabled": { "type": "boolean", "description": "Whether HA restarts VMs of failed hosts." }, "host_failures_to_tolerate": { "type": "integer", "format": "int32", "description": "Number of host failures to tolerate in admission control.", "minimum": 0 } }, "additionalProperties": false }, "ClusterMigrationConfig": { "type": "object", "description": "Live-migration policy for VMs in this cluster (L-109 / TP-3 / L-91).\n\nPassed by the control plane as `MigrationOptions.policy` on migrate-out.\nUnset members fall back to each host's `[migration]` defaults; nothing set\nmeans uncapped bandwidth and the host downtime default.", "properties": { "allow_postcopy": { "type": "boolean", "description": "Allow postcopy when a migrate request asks for it (opt-in, L-91)." }, "downtime_limit_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Acceptable downtime in ms; `None` takes the host default (typically 300).", "minimum": 0 }, "max_bandwidth_mib_s": { "type": [ "integer", "null" ], "format": "int64", "description": "Bandwidth cap in MiB/s; `None` = uncapped (after host default).", "minimum": 0 } }, "additionalProperties": false }, "ClusterSchedulerConfig": { "type": "object", "description": "Scheduling (DRS-like) settings of a cluster.", "properties": { "automatic": { "type": "boolean", "description": "Whether migrations are applied automatically or only recommended." }, "enabled": { "type": "boolean", "description": "Whether the scheduler balances load automatically." } }, "additionalProperties": false }, "Comparison": { "type": "string", "description": "Comparison for metric triggers.", "enum": [ "above", "below" ] }, "CompleteMfaRequest": { "type": "object", "description": "MFA completion request.", "required": [ "pendingToken", "code" ], "properties": { "code": { "type": "string", "description": "Six-digit code." }, "pendingToken": { "type": "string", "description": "Pending token from the login response." } } }, "ComputeResource": { "type": "object", "description": "A compute resource wrapping a standalone host (vSphere `ComputeResource`).", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name (same as the host)." } }, "additionalProperties": false }, "ConsistencyView": { "type": "string", "description": "OpenAPI stand-in for `Consistency`.", "enum": [ "CRASH_CONSISTENT", "FILESYSTEM_CONSISTENT" ] }, "ConsoleTicketView": { "type": "object", "description": "A single-use console ticket (`POST /v1/vms/{id}/console/ticket`).", "required": [ "ticket", "vmId", "expiresAt", "expiresIn", "websocketPath" ], "properties": { "expiresAt": { "type": "string", "description": "When the ticket stops working (RFC 3339); 30 seconds after issue." }, "expiresIn": { "type": "integer", "format": "int64", "description": "Seconds of validity.", "minimum": 0 }, "ticket": { "type": "string", "description": "The ticket (base64url). Single use, bound to the VM and to this session." }, "vmId": { "type": "string", "description": "The VM it opens." }, "websocketPath": { "type": "string", "description": "Same-origin WebSocket path to open (`/v1/console/{ticket}`); binary frames carry\nRFB (VNC) bytes, so noVNC connects to it directly." } } }, "ControllerArchiveView": { "type": "object", "description": "One archive of the controller state.", "required": [ "name", "sizeBytes" ], "properties": { "name": { "type": "string", "description": "File name in the target folder." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "Size in bytes.", "minimum": 0 } } }, "ControllerBackupRequest": { "type": "object", "description": "Body of `PUT /v1/backup/controller`.", "required": [ "enabled", "target", "retention" ], "properties": { "enabled": { "type": "boolean", "description": "Take archives on the schedule." }, "retention": { "type": "integer", "description": "Archives kept (1 to 365).", "minimum": 0 }, "schedule": { "type": "string", "description": "`HH:MM` UTC or an interval such as `6h`; needed when `enabled`." }, "target": { "type": "string", "description": "Folder on the controller the archives go to (absolute)." } } }, "ControllerBackupStatusView": { "type": "object", "description": "State of the backup of the controller's own state (not implemented yet).", "required": [ "enabled", "target", "schedule", "retention", "stateDirectory", "running", "archives" ], "properties": { "archives": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerArchiveView" }, "description": "The archives in the target folder, newest first." }, "enabled": { "type": "boolean", "description": "Backups of the controller state are taken." }, "lastError": { "type": [ "string", "null" ], "description": "Error of the last run." }, "lastResult": { "type": [ "string", "null" ], "description": "`success` or `failure`." }, "lastRunAt": { "type": [ "string", "null" ], "description": "Last run." }, "lastSizeBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Size of the last archive.", "minimum": 0 }, "nextRunAt": { "type": [ "string", "null" ], "description": "Next run." }, "retention": { "type": "integer", "description": "Archives kept.", "minimum": 0 }, "running": { "type": "boolean", "description": "A run is going on." }, "schedule": { "type": "string", "description": "When they are taken." }, "stateDirectory": { "type": "string", "description": "The state directory that is copied." }, "target": { "type": "string", "description": "Folder on the controller the archives go to." } } }, "CopyMoveFileRequest": { "type": "object", "description": "Copy or move a datastore file (`CopyDatastoreFile_Task` / `MoveDatastoreFile_Task`).", "required": [ "sourcePath", "destinationPath" ], "properties": { "destinationDatastoreId": { "type": [ "string", "null" ], "description": "Destination datastore (`datastore-N`). Defaults to the path datastore." }, "destinationPath": { "type": "string", "description": "Destination path below the destination datastore root." }, "overwrite": { "type": "boolean", "description": "Replace an existing destination file." }, "sourcePath": { "type": "string", "description": "Source path below the path datastore root." } } }, "CounterView": { "type": "object", "description": "A counter of the catalogue.", "required": [ "id", "name", "group", "groupLabel", "nameKey", "label", "summary", "rollup", "unit", "unitLabel", "statsType", "level", "perDeviceLevel", "metric", "entityTypes", "instances", "instancesOnly" ], "properties": { "entityTypes": { "type": "array", "items": { "type": "string" }, "description": "Entity types (`host`, `vm`, `datastore`)." }, "group": { "type": "string", "description": "Group key (`cpu`, `mem`, `disk`, `net`, `datastore`, `virtualDisk`, `sys`, `rescpu`)." }, "groupLabel": { "type": "string", "description": "Group label." }, "id": { "type": "integer", "format": "int32", "description": "Stable id (vCenter's where one exists; 900000 and up otherwise)." }, "instances": { "type": "string", "description": "Instance kind (`none`, `device`, `object`)." }, "instancesOnly": { "type": "boolean", "description": "True when the counter has no aggregate instance." }, "label": { "type": "string", "description": "Label." }, "level": { "type": "integer", "format": "int32", "description": "Collection level of the aggregate.", "minimum": 0 }, "metric": { "type": "string", "description": "The metric the counter reads." }, "name": { "type": "string", "description": "`group.name.rollup`." }, "nameKey": { "type": "string", "description": "Name key." }, "perDeviceLevel": { "type": "integer", "format": "int32", "description": "Collection level of device instances.", "minimum": 0 }, "rollup": { "type": "string", "description": "Rollup type (`average`, `minimum`, `maximum`, `latest`, `summation`, `none`)." }, "statsType": { "type": "string", "description": "Statistics type (`absolute`, `delta`, `rate`)." }, "summary": { "type": "string", "description": "What is measured." }, "unit": { "type": "string", "description": "Unit key (`percent`, `kiloBytesPerSecond`, ...)." }, "unitLabel": { "type": "string", "description": "Unit label (`%`, `KBps`, ...)." } } }, "CreateAlarmRequest": { "type": "object", "description": "Request to define an alarm.", "required": [ "name", "scopeId", "trigger" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmAction" }, "description": "Actions." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled (default true)." }, "name": { "type": "string", "description": "Name." }, "scopeId": { "type": "string", "description": "Scope entity id." }, "trigger": { "$ref": "#/components/schemas/AlarmTrigger", "description": "Trigger." } } }, "CreateApiTokenRequest": { "type": "object", "description": "Request to create an API token.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Label (1..=64 characters)." }, "ttlSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Lifetime in seconds, 1 up to the controller maximum (`[identity.policy] api_token_max_ttl`,\n365 days unless configured otherwise). Absent: the maximum. Every token expires;\na longer lifetime is refused (`error.api_token.ttl`).", "minimum": 0 } } }, "CreateApiTokenResponse": { "type": "object", "description": "A created API token. The token is shown once.", "required": [ "token", "apiToken" ], "properties": { "apiToken": { "$ref": "#/components/schemas/ApiTokenView", "description": "Its public description." }, "token": { "type": "string", "description": "`kyvt__`; give it as the password of programmatic logins." } } }, "CreateCustomizationSpecRequest": { "type": "object", "description": "Create or overwrite a customization specification.", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description." }, "dnsServers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "DNS servers." }, "dnsSuffixes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "DNS search suffixes." }, "domain": { "type": [ "string", "null" ], "description": "DNS domain." }, "domainAdmin": { "type": [ "string", "null" ], "description": "Domain-join account name." }, "domainAdminPassword": { "type": [ "string", "null" ], "description": "Domain-join account password (stored; never returned on GET)." }, "domainOu": { "type": [ "string", "null" ], "description": "Optional target OU DN." }, "fullName": { "type": [ "string", "null" ], "description": "Windows registered owner." }, "hostname": { "type": [ "string", "null" ], "description": "Fixed host name." }, "joinDomain": { "type": [ "string", "null" ], "description": "AD domain to join." }, "joinWorkgroup": { "type": [ "string", "null" ], "description": "Workgroup when not joining a domain." }, "metadata": { "type": [ "string", "null" ], "description": "Raw cloud-init metadata (overrides hostname synthesis when set)." }, "name": { "type": "string", "description": "Spec name (1..=80; ignored on PUT path overwrite in favour of the path)." }, "nics": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CustomizationNicSetting" }, "description": "NIC mappings (static IP / DHCP)." }, "orgName": { "type": [ "string", "null" ], "description": "Windows organisation." }, "password": { "type": [ "string", "null" ], "description": "Plaintext guest password (stored; never returned on GET)." }, "sshUser": { "type": [ "string", "null" ], "description": "Optional SSH username that also receives the password." }, "timezone": { "type": [ "string", "null" ], "description": "Timezone." }, "type": { "type": [ "string", "null" ], "description": "Guest OS family (`Linux` or `Windows`); defaults to Linux." }, "unattend": { "type": [ "string", "null" ], "description": "Raw unattend.xml for Windows (stored; never returned on GET)." }, "userdata": { "type": [ "string", "null" ], "description": "Raw cloud-init user-data (overrides synthesized user-data when set)." } } }, "CreateDatacenterRequest": { "type": "object", "description": "Body of `POST /v1/datacenters`.", "required": [ "name" ], "properties": { "folderId": { "type": [ "string", "null" ], "description": "Datacenter folder to create it in (`group-dN`); default: the root folder." }, "name": { "type": "string", "description": "Name, 1 to 80 characters, unique among the datacenters of the folder." } }, "additionalProperties": false }, "CreateDistributedPortgroupRequest": { "type": "object", "description": "Body of `POST /v1/distributed-portgroups`.", "required": [ "name", "switchId" ], "properties": { "datacenterId": { "type": [ "string", "null" ], "description": "The datacenter of the switch (optional; checked when given)." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "ipv4": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeIpv4Request", "description": "IPv4 subnet, gateway, DNS, range and DHCP." }, { "type": "null" } ] }, "ipv6": { "oneOf": [ { "$ref": "#/components/schemas/PortgroupIpv6Request", "description": "IPv6 prefix and DHCPv6." }, { "type": "null" } ] }, "name": { "type": "string", "description": "Name (1 to 80 characters)." }, "staticAddresses": { "type": [ "object", "null" ], "description": "Fixed IPv4 addresses by MAC.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "switchId": { "type": "string", "description": "The switch." }, "vlanId": { "type": [ "integer", "null" ], "format": "int32", "description": "VLAN id, 0 for untagged; ignored when `vni` is set.", "minimum": 0 }, "vni": { "type": [ "integer", "null" ], "format": "int32", "description": "Overlay segment (Geneve VNI) instead of a VLAN.", "minimum": 0 } }, "additionalProperties": false }, "CreateDistributedSwitchRequest": { "type": "object", "description": "Body of `POST /v1/distributed-switches`.", "required": [ "name", "datacenterId" ], "properties": { "datacenterId": { "type": "string", "description": "The datacenter; the switch goes into its network folder." }, "hostUplinks": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/HostUplinksRequest" }, "description": "The physical NICs of member hosts behind the uplinks." }, "hosts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Member hosts (default none)." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "mtu": { "type": [ "integer", "null" ], "format": "int32", "description": "MTU (576 to 9216; default 1500).", "minimum": 0 }, "name": { "type": "string", "description": "Name (1 to 80 characters)." }, "uplinkNames": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Uplink names (default `uplink1` to `uplink`)." }, "uplinks": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of uplinks (default 1).", "minimum": 0 } }, "additionalProperties": false }, "CreateGroupRequest": { "type": "object", "description": "Body of `POST /v1/identity/groups`.", "required": [ "name" ], "properties": { "description": { "type": "string", "description": "Description." }, "name": { "type": "string", "description": "Name, 1 to 80 characters." } }, "additionalProperties": false }, "CreateHostDatastoreRequest": { "type": "object", "description": "Body for `POST /v1/hosts/{id}/datastores` (`CreateLocalDatastore` /\n`CreateNasDatastore` / `CreateVmfsDatastore`).", "required": [ "type", "name" ], "properties": { "accessMode": { "type": [ "string", "null" ], "description": "`readWrite` or `readOnly` (default `readWrite`)." }, "disk": { "type": [ "string", "null" ], "description": "Disk key for VMFS create: WWID, `naa.…`, or device path." }, "name": { "type": "string", "description": "Datastore display name (`CreateLocalDatastore.name` /\n`HostNasVolumeSpec.localPath` / `HostVmfsSpec.volumeName`)." }, "nfsType": { "type": [ "string", "null" ], "description": "`NFS` or `NFS41` (default `NFS`)." }, "path": { "type": [ "string", "null" ], "description": "Absolute host path for a local datastore." }, "remoteHost": { "type": [ "string", "null" ], "description": "NFS server (`CreateNasDatastore`)." }, "remotePath": { "type": [ "string", "null" ], "description": "NFS export path." }, "securityType": { "type": [ "string", "null" ], "description": "NFS security flavour (default `sys`)." }, "type": { "type": "string", "description": "`local`, `nfs`, or `vmfs` (SOAP CreateLocal / CreateNas / CreateVmfs)." } }, "additionalProperties": false }, "CreateLibraryItemRequest": { "type": "object", "description": "Register a library item that references an existing datastore file, or an empty\nitem that will receive content through an update session.", "required": [ "libraryId", "name", "type" ], "properties": { "clientToken": { "type": [ "string", "null" ], "description": "Optional client token for idempotent create." }, "datastoreId": { "type": [ "string", "null" ], "description": "Override the library's datastore backing." }, "description": { "type": [ "string", "null" ], "description": "Optional description." }, "filePath": { "type": [ "string", "null" ], "description": "Datastore-relative path; omit or empty when uploading via update session." }, "libraryId": { "type": "string", "description": "Owning library id." }, "name": { "type": "string", "description": "Display name." }, "size": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional size hint in bytes." }, "type": { "type": "string", "description": "`iso`, `ovf`, or `vm-template`." } } }, "CreateLibraryRequest": { "type": "object", "description": "Create a local content library.", "required": [ "name", "datastoreId" ], "properties": { "clientToken": { "type": [ "string", "null" ], "description": "Optional client token for idempotent create." }, "datastoreId": { "type": "string", "description": "Datastore that backs item files." }, "description": { "type": [ "string", "null" ], "description": "Optional description." }, "name": { "type": "string", "description": "Display name (1..=80)." } } }, "CreateNetworkRequest": { "type": "object", "description": "Create a host-bridge network / standard port group (`POST /v1/networks`).\n\nLands under the datacenter's network folder. Empty `hosts` means every host\ncurrently under the datacenter; operators can narrow the list later.", "required": [ "name", "datacenterId", "backing" ], "properties": { "backing": { "$ref": "#/components/schemas/HostBridgeBackingRequest", "description": "How NICs reach the hosts (host-bridge only in this slice)." }, "datacenterId": { "type": "string", "description": "Datacenter that owns the network (`datacenter-N`)." }, "hosts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Hosts offering this network (`host-N`). Empty or omitted: all hosts under the datacenter." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "name": { "type": "string", "description": "Display name (1..=80 characters)." }, "vlanId": { "type": [ "integer", "null" ], "format": "int32", "description": "VLAN id, 0 for untagged (default 0).", "minimum": 0 } } }, "CreateObjectRequest": { "type": "object", "description": "Inventory create request.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ObjectBody", "description": "Body in the kind's schema." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key; a repeat returns the same object." }, "parentId": { "type": [ "string", "null" ], "description": "Parent id (required for inventory entities)." } } }, "CreateOvfDescriptorRequest": { "type": "object", "description": "Build an OVF envelope from export file metadata (`OvfManager.CreateDescriptor`).", "required": [ "vmId", "ovfFiles" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Annotation / description override." }, "includeImageFiles": { "type": [ "boolean", "null" ], "description": "Package attached ISO images as References (govc `export.ovf -i`)." }, "name": { "type": [ "string", "null" ], "description": "Override entity name; defaults to the VM display name." }, "ovfFiles": { "type": "array", "items": { "$ref": "#/components/schemas/OvfCreateDescriptorFileRequest" }, "description": "Disk and optional ISO package members (govc `export.ovf` file list)." }, "vmId": { "type": "string", "description": "Source VM whose hardware is reflected in the descriptor." } } }, "CreateOvfImportSpecRequest": { "type": "object", "description": "Build an import plan from an OVF descriptor (`OvfManager.CreateImportSpec`).", "required": [ "ovfDescriptor", "resourcePoolId", "datastoreId" ], "properties": { "datastoreId": { "type": "string", "description": "Target datastore (`datastore-N`)." }, "deploymentOption": { "type": [ "string", "null" ], "description": "Optional deployment configuration id." }, "entityName": { "type": [ "string", "null" ], "description": "Override entity name; defaults to the package VirtualSystem name." }, "networkMapping": { "type": "array", "items": { "$ref": "#/components/schemas/OvfNetworkMappingRequest" }, "description": "OVF network name → inventory network mappings." }, "ovfDescriptor": { "type": "string", "description": "OVF envelope XML." }, "resourcePoolId": { "type": "string", "description": "Target resource pool (`resgroup-N` / `resourcepool-N`)." } } }, "CreateScheduledTaskRequest": { "type": "object", "description": "Request to create a scheduled task.", "required": [ "name", "entityId", "action" ], "properties": { "action": { "$ref": "#/components/schemas/ScheduledAction", "description": "Power action." }, "activeTime": { "type": [ "string", "null" ], "description": "Optional scheduler active time." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled (default true)." }, "entityId": { "type": "string", "description": "Target VM id." }, "expireTime": { "type": [ "string", "null" ], "description": "Optional scheduler expire time." }, "name": { "type": "string", "description": "Display name." }, "notification": { "type": [ "string", "null" ], "description": "Optional notification address (SMTP send when `[smtp] enabled`)." }, "recurrence": { "$ref": "#/components/schemas/ScheduledRecurrence", "description": "Scheduler cadence (default `once`)." }, "runAt": { "type": [ "string", "null" ], "description": "One-shot run time / create-time anchor (RFC 3339). Defaults to now." } } }, "CreateServerRequest": { "type": "object", "description": "Request to create a server.", "required": [ "plan", "image", "hostname" ], "properties": { "hostname": { "type": "string", "description": "Host name (RFC 1123 label), also the VM's name." }, "image": { "type": "string", "description": "Catalogue image (`vm-N` of the template)." }, "location": { "type": [ "string", "null" ], "description": "Datacenter (`datacenter-N`; default: the tenant's first)." }, "password": { "type": "boolean", "description": "Generate a password (always when no SSH keys are given); it is returned once." }, "plan": { "type": "string", "description": "Plan (`vmplan-N`)." }, "sshKeys": { "type": "array", "items": { "type": "string" }, "description": "SSH public keys for the default user and root." }, "userData": { "type": [ "string", "null" ], "description": "cloud-init user data (`guestinfo.userdata`, at most 64 KiB)." } } }, "CreateSnapshotRequest": { "type": "object", "description": "Create a VM snapshot (`POST /v1/vms/{id}/snapshots`).", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Free-text description." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "memory": { "type": "boolean", "description": "Capture memory when the guest is powered on (resume on revert)." }, "name": { "type": "string", "description": "Display name (1..=80 characters)." }, "quiesce": { "type": "boolean", "description": "Quiesce guest file systems when a guest agent is present." } } }, "CreateSubscriptionRequest": { "type": "object", "description": "Create-subscription request.", "required": [ "name", "url", "secret" ], "properties": { "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Event types (empty = all)." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels." }, "maxAttempts": { "type": [ "integer", "null" ], "format": "int32", "description": "Attempts per event (default 5).", "minimum": 0 }, "name": { "type": "string", "description": "Name." }, "secret": { "type": "string", "description": "Shared secret for `X-Kyvernon-Signature` (HMAC-SHA256); at least 16 bytes." }, "tenant": { "type": [ "string", "null" ], "description": "Deliver only the self-service events of this tenant (`tenant-N`; §5)." }, "url": { "type": "string", "description": "Target URL (https recommended)." } } }, "CreateTagCategoryRequest": { "type": "object", "description": "Body of `POST /v1/tag-categories`.", "required": [ "name" ], "properties": { "associableKinds": { "type": "array", "items": { "type": "string" }, "description": "Object kinds the tags may be attached to; empty or absent: every inventory kind." }, "cardinality": { "type": [ "string", "null" ], "description": "`single` (default) or `multiple`." }, "description": { "type": "string", "description": "Description." }, "name": { "type": "string", "description": "Name, 1 to 80 characters, unique." } }, "additionalProperties": false }, "CreateTagRequest": { "type": "object", "description": "Body of `POST /v1/tags`.", "required": [ "categoryId", "name" ], "properties": { "categoryId": { "type": "string", "description": "Category id." }, "description": { "type": "string", "description": "Description." }, "name": { "type": "string", "description": "Name, 1 to 80 characters, unique within the category." } }, "additionalProperties": false }, "CreateTenantRequest": { "type": "object", "description": "Request to create a tenant.", "required": [ "name" ], "properties": { "anchorDay": { "type": [ "integer", "null" ], "format": "int32", "description": "Day of the month (1 to 28) the traffic period starts (default: the 1st).", "minimum": 0 }, "displayName": { "type": "string", "description": "Display name." }, "externalRef": { "type": "string", "description": "The portal's account id." }, "labels": { "type": "object", "description": "Labels.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Short name (`[a-z0-9-]`, 1..=63), also the name of its folders and pools." }, "quota": { "$ref": "#/components/schemas/QuotaView", "description": "Limits (default: unlimited)." } } }, "CreateTenantUserRequest": { "type": "object", "description": "Request to create a tenant user.", "required": [ "username", "password" ], "properties": { "displayName": { "type": "string", "description": "Display name." }, "email": { "type": "string", "description": "E-mail." }, "password": { "type": "string", "description": "Initial password." }, "role": { "type": "string", "description": "`admin` (Tenant administrator), `user` (Tenant user) or `read-only`." }, "rotationRequired": { "type": "boolean", "description": "The password must be changed at first login." }, "serviceAccount": { "type": "boolean", "description": "Automation account (API logins only)." }, "username": { "type": "string", "description": "Login name." } } }, "CreateUpdateSessionRequest": { "type": "object", "description": "Create an update session for a library item.", "required": [ "libraryItemId" ], "properties": { "clientToken": { "type": [ "string", "null" ], "description": "Optional client token for idempotent create." }, "libraryItemId": { "type": "string", "description": "Library item id." } } }, "CreateUserRequest": { "type": "object", "description": "Create-user request.", "required": [ "username", "password" ], "properties": { "displayName": { "type": "string", "description": "Display name." }, "email": { "type": "string", "description": "E-mail." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Groups." }, "password": { "type": "string", "description": "Initial password." }, "rotationRequired": { "type": "boolean", "description": "Require a password change at first login (default true)." }, "username": { "type": "string", "description": "Username." } } }, "CreateVmRequest": { "type": "object", "description": "VM create request.", "required": [ "folderId", "spec" ], "properties": { "createDisks": { "type": "array", "items": { "$ref": "#/components/schemas/DiskFileRequest" }, "description": "Disk files the task creates before the VM record exists: empty qcow2 images, or\ncopies or linked clones of an image (`sourcePath`). Each must be one of the disks\nof `spec.config.disks` (same datastore and path)." }, "folderId": { "type": "string", "description": "VM folder id (`group-vN`)." }, "guestAgent": { "type": "boolean", "description": "Install the guest agent through cloud-init: merges `packages: [qemu-guest-agent]` and\n`runcmd: [systemctl enable --now qemu-guest-agent]` into `guestinfo.vendordata`\n(`kyvernon_vm_model::guestinfo::with_guest_agent`). For images that lack the package\n(the Ubuntu and Debian cloud images); without it such a VM reports\n`toolsNotInstalled`. Never applied unless set: `POST /v1/guest-agent/offer` says when\nto offer it. Vendor data that is not `#cloud-config` is refused, not rewritten." }, "host": { "type": [ "string", "null" ], "description": "Host to place the VM on (`host-N`). Without it the VM goes to the first\nconnected host of the resource pool's cluster." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "spec": { "$ref": "#/components/schemas/VirtualMachine", "description": "Body in the `VirtualMachine` schema, validated as a record (`name`, `instance_uuid`,\n`resource_pool` and `config` are required)." } } }, "CreatedObjectResultView": { "type": "object", "description": "`TaskView.result` when the operation creates or returns an inventory object\n(create VM, clone, AddHost, CreateSnapshot).", "required": [ "vimResult" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Native object id (`vm-42`, `host-7`), when present." }, "snapshot": { "type": [ "integer", "null" ], "format": "int32", "description": "Snapshot key when the created object is a snapshot.", "minimum": 0 }, "vimResult": { "$ref": "#/components/schemas/VimMoRefView", "description": "Facade MoRef (`TaskInfo.result`)." } } }, "CustomField": { "type": "object", "description": "A custom field definition (`CustomFieldsManager`).", "required": [ "name" ], "properties": { "managed_kind": { "type": [ "string", "null" ], "description": "Kind the field applies to, `None` for all." }, "managed_type": { "type": [ "string", "null" ], "description": "The vSphere managed object type the field applies to (`VirtualMachine`,\n`Folder`, `ManagedEntity`, ...), as the facade's `CustomFieldDef.managedObjectType`\nnames it; `None` for all. Kept next to `managed_kind` because several kinds share a\ntype (the folders) and some types have no kind (`ManagedEntity`)." }, "name": { "type": "string", "description": "Field name." }, "values": { "type": "object", "description": "Values per object.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "CustomizationNicSetting": { "type": "object", "description": "One NIC mapping (`CustomizationAdapterMapping` / cloud-init physical).", "properties": { "dnsServers": { "type": "array", "items": { "type": "string" }, "description": "Optional per-NIC DNS servers (falls back to spec `dnsServers`)." }, "gateway": { "type": "array", "items": { "type": "string" }, "description": "Default gateway(s)." }, "ip": { "type": [ "string", "null" ], "description": "Fixed IPv4 address; omit or empty for DHCP." }, "macAddress": { "type": [ "string", "null" ], "description": "Optional MAC for cloud-init matching." }, "subnetMask": { "type": [ "string", "null" ], "description": "IPv4 subnet mask (`255.255.255.0`) or prefix length (`24`); required with `ip`." } } }, "CustomizationSpecView": { "type": "object", "description": "Named customization specification (`GET/POST /v1/customization/specs`).", "required": [ "name", "description", "type", "changeVersion", "lastUpdateTime", "passwordSet" ], "properties": { "changeVersion": { "type": "string", "description": "Change version." }, "description": { "type": "string", "description": "Description." }, "dnsServers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers." }, "dnsSuffixes": { "type": "array", "items": { "type": "string" }, "description": "DNS search suffixes." }, "domain": { "type": "string", "description": "DNS domain." }, "domainAdmin": { "type": [ "string", "null" ], "description": "Domain-join account name." }, "domainAdminPasswordSet": { "type": "boolean", "description": "Whether a domain-join password is stored (value never returned)." }, "domainOu": { "type": [ "string", "null" ], "description": "Optional target OU DN." }, "fullName": { "type": [ "string", "null" ], "description": "Windows registered owner." }, "hostname": { "type": [ "string", "null" ], "description": "Fixed host name." }, "joinDomain": { "type": [ "string", "null" ], "description": "AD domain to join." }, "joinWorkgroup": { "type": [ "string", "null" ], "description": "Workgroup when not joining a domain." }, "lastUpdateTime": { "type": "string", "description": "Last update time (RFC3339 / vim wire)." }, "metadata": { "type": [ "string", "null" ], "description": "Raw cloud-init metadata." }, "name": { "type": "string", "description": "Spec name (unique key)." }, "nics": { "type": "array", "items": { "$ref": "#/components/schemas/CustomizationNicSetting" }, "description": "NIC mappings (static IP / DHCP)." }, "orgName": { "type": [ "string", "null" ], "description": "Windows organisation." }, "passwordSet": { "type": "boolean", "description": "Whether a password is stored (value never returned)." }, "sshUser": { "type": [ "string", "null" ], "description": "Optional SSH username that also receives the password." }, "timezone": { "type": [ "string", "null" ], "description": "Timezone." }, "type": { "type": "string", "description": "Guest OS family (`Linux` or `Windows`)." }, "unattendSet": { "type": "boolean", "description": "Whether a raw unattend.xml is stored (value never returned)." }, "userdata": { "type": [ "string", "null" ], "description": "Raw cloud-init user-data." } } }, "CustomizeResultView": { "type": "object", "description": "`TaskView.result` of guest customization.", "required": [ "customized" ], "properties": { "customized": { "type": "boolean", "description": "Always `true` on success." } } }, "CustomizeVmRequest": { "type": "object", "description": "Apply a named customization specification to a powered-off VM\n(`POST /v1/vms/{id}/customize`, SOAP `CustomizeVM_Task`).", "required": [ "spec" ], "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "spec": { "type": "string", "description": "Name of a catalogue specification (`GET /v1/customization/specs/{name}`)." } } }, "DailySummaryView": { "type": "object", "description": "The usage summary of one day.", "required": [ "day", "totals", "tenants", "vms" ], "properties": { "day": { "type": "string", "description": "The day." }, "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLineView" }, "description": "Per tenant." }, "totals": { "$ref": "#/components/schemas/UsageLineView", "description": "Totals." }, "vms": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLineView" }, "description": "Per VM." } } }, "Datacenter": { "type": "object", "description": "A datacenter: the top-level container. Its four child folders are created\nwith it.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name." } }, "additionalProperties": false }, "Datastore": { "type": "object", "description": "A datastore.", "required": [ "name" ], "properties": { "accessible": { "type": "boolean", "description": "Whether it is reachable." }, "capacity_bytes": { "type": "integer", "format": "int64", "description": "Total capacity.", "minimum": 0 }, "datastore_type": { "$ref": "#/components/schemas/DatastoreType", "description": "Backend type." }, "free_bytes": { "type": "integer", "format": "int64", "description": "Free space.", "minimum": 0 }, "hosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts that have mounted it." }, "name": { "type": "string", "description": "Display name." }, "nas": { "oneOf": [ { "$ref": "#/components/schemas/DatastoreNas", "description": "NFS remote when `datastore_type` is NFS (SOAP `NasDatastoreInfo`)." }, { "type": "null" } ] }, "url": { "type": "string", "description": "Backend-specific URL/path (never contains credentials)." } }, "additionalProperties": false }, "DatastoreCapacityView": { "type": "object", "description": "The size and free space of a datastore as a host measured them.", "required": [ "id", "name", "capacityBytes", "freeBytes", "accessible", "measuredOn", "refreshedAt" ], "properties": { "accessible": { "type": "boolean", "description": "Reachable from the host that measured it." }, "capacityBytes": { "type": "integer", "format": "int64", "description": "Size of the file system in bytes.", "minimum": 0 }, "freeBytes": { "type": "integer", "format": "int64", "description": "Free bytes.", "minimum": 0 }, "id": { "type": "string", "description": "Datastore id." }, "measuredOn": { "type": "string", "description": "The host that measured it." }, "name": { "type": "string", "description": "Name." }, "refreshedAt": { "type": "string", "description": "When (RFC 3339)." } } }, "DatastoreEntry": { "type": "object", "description": "An entry of a folder listing (native API).", "required": [ "name", "type", "kind" ], "properties": { "capacityBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Guest-visible capacity of a disk image.", "minimum": 0 }, "format": { "type": [ "string", "null" ], "description": "Format of a disk image (`qcow2`, `raw`, `vmdk`)." }, "kind": { "type": "string", "description": "Class of the file (`vmDisk`, `iso`, `vmConfig`, `file`, ...; `folder` for folders)." }, "modifiedAt": { "type": [ "string", "null" ], "description": "Last change (RFC 3339)." }, "name": { "type": "string", "description": "Name." }, "sizeBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Size in bytes (allocated bytes for disk images); absent for folders.", "minimum": 0 }, "type": { "type": "string", "description": "`folder` or `file`." } } }, "DatastoreListing": { "type": "object", "description": "A folder listing (native API).", "required": [ "path", "entries", "truncated" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/DatastoreEntry" }, "description": "Folders first, then files, by name." }, "path": { "type": "string", "description": "The folder, relative to the datastore root (empty: the root)." }, "truncated": { "type": "boolean", "description": "The folder has more entries than one listing returns." } } }, "DatastoreNas": { "type": "object", "description": "NFS remote recorded for a datastore created via `HostDatastoreSystem.CreateNasDatastore`.\n\nThe inventory `url` is the host `file://` mount point after AgentOps `pool-attach`\n(`PoolManager` → `mount -t nfs`); this carries the remote host/export projected as\n`NasDatastoreInfo`.", "required": [ "remote_host", "remote_path" ], "properties": { "remote_host": { "type": "string", "description": "NFS server (`HostNasVolumeSpec.remoteHost`)." }, "remote_path": { "type": "string", "description": "Export path (`HostNasVolumeSpec.remotePath`)." }, "security_type": { "type": [ "string", "null" ], "description": "Security flavour (`sys` / `krb5` / …), when known." }, "volume_type": { "type": [ "string", "null" ], "description": "Volume type string (`NFS` / `NFS41`), when known." } }, "additionalProperties": false }, "DatastoreType": { "type": "string", "description": "Datastore backend type. The string form matches what tools expect in\n`summary.type`.", "enum": [ "LOCAL", "NFS", "BLOCK", "RBD", "LINSTOR", "ZFS" ] }, "DeadLetterView": { "type": "object", "description": "A dead letter.", "required": [ "eventId", "attempts", "lastError", "failedAt" ], "properties": { "attempts": { "type": "integer", "format": "int32", "description": "Attempts.", "minimum": 0 }, "eventId": { "type": "string", "description": "Event id." }, "failedAt": { "type": "string", "description": "When it was parked." }, "lastError": { "type": "string", "description": "Last error." } } }, "DefaultActionView": { "type": "string", "description": "Default action of a profile direction.", "enum": [ "allow", "drop", "reject" ] }, "DeliveryResultView": { "type": "object", "description": "Delivery outcome.", "required": [ "delivered", "status", "attempts" ], "properties": { "attempts": { "type": "integer", "format": "int32", "description": "Attempts made.", "minimum": 0 }, "delivered": { "type": "boolean", "description": "Delivered (2xx)." }, "error": { "type": [ "string", "null" ], "description": "Last error." }, "status": { "type": "integer", "format": "int32", "description": "Last HTTP status.", "minimum": 0 } } }, "DhcpEvidence": { "type": "object", "description": "What the DHCP responder on the quarantine bridge saw.", "required": [ "offers", "acks" ], "properties": { "acks": { "type": "integer", "format": "int64", "description": "ACKs sent (the guest took the lease).", "minimum": 0 }, "address": { "type": [ "string", "null" ], "description": "The leased address." }, "mac": { "type": [ "string", "null" ], "description": "The NIC's MAC." }, "nic": { "type": [ "string", "null" ], "description": "The NIC the evidence is about." }, "offers": { "type": "integer", "format": "int64", "description": "OFFERs sent.", "minimum": 0 } } }, "DirectionView": { "type": "string", "description": "Direction relative to the vNICs the rule applies to.", "enum": [ "in", "out", "in-out" ] }, "DiskBackupView": { "type": "object", "description": "OpenAPI stand-in for one disk inside a backup session.", "required": [ "deviceKey", "diskId", "capacity", "granularity", "since", "changeId", "incremental" ], "properties": { "capacity": { "type": "integer", "format": "int64", "description": "Capacity in bytes at the backup point.", "minimum": 0 }, "changeId": { "type": "string", "description": "Change id this backup will commit on success." }, "deviceKey": { "type": "integer", "format": "int32", "description": "Device key of the disk in the VM." }, "diskId": { "type": "string", "format": "uuid", "description": "Stable disk identity." }, "export": { "oneOf": [ { "$ref": "#/components/schemas/NbdExportView", "description": "The NBD export once state is `EXPORTING`." }, { "type": "null" } ] }, "granularity": { "type": "integer", "format": "int64", "description": "Tracking granularity in bytes.", "minimum": 0 }, "incremental": { "type": "boolean", "description": "Whether `since` was honoured (false means full/allocated areas)." }, "since": { "type": "string", "description": "`*` or a change id the client asked relative to." } } }, "DiskChangeInfoView": { "type": "object", "description": "OpenAPI stand-in for one page of changed areas.", "required": [ "startOffset", "length", "changedArea" ], "properties": { "changedArea": { "type": "array", "items": { "$ref": "#/components/schemas/ChangedAreaView" }, "description": "Areas within the covered range." }, "length": { "type": "integer", "format": "int64", "description": "Number of bytes covered by this reply.", "minimum": 0 }, "startOffset": { "type": "integer", "format": "int64", "description": "First byte covered by this reply.", "minimum": 0 } } }, "DiskFileRequest": { "type": "object", "description": "A disk file a create or reconfigure task makes on the datastore.", "required": [ "datastore", "path" ], "properties": { "datastore": { "type": "string", "description": "Datastore id (`datastore-N`)." }, "linked": { "type": "boolean", "description": "With `sourcePath`: true makes a qcow2 overlay whose backing file is the image\n(linked clone; same datastore, the image is only read), false a full copy." }, "path": { "type": "string", "description": "Path below the datastore root (`web-01/web-01.qcow2`)." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes. For a disk from an image: at least the image's virtual size;\na larger value grows the new disk (the image stays as it is).", "minimum": 0 }, "sourceDatastore": { "type": [ "string", "null" ], "description": "Datastore of the image (`datastore-N`)." }, "sourcePath": { "type": [ "string", "null" ], "description": "Image to start from: a path below the root of `sourceDatastore` (default: the\ntarget datastore)." } }, "additionalProperties": false }, "DiskSelectionView": { "type": "object", "description": "OpenAPI stand-in for one disk selection in a begin-backup request.", "required": [ "deviceKey", "since" ], "properties": { "deviceKey": { "type": "integer", "format": "int32", "description": "Device key of the disk in the VM." }, "since": { "type": "string", "description": "`*` for a full backup, or a change id from a previous completed session.", "example": "*" } } }, "DistributedPortgroup": { "type": "object", "description": "A port group on a distributed switch.", "required": [ "name" ], "properties": { "ipv4": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeIpv4", "description": "IPv4 subnet, gateway, DNS, address range and DHCP of the segment (the settings of a\nhost-bridge network); `None`: guests configure their addresses themselves." }, { "type": "null" } ] }, "ipv6": { "oneOf": [ { "$ref": "#/components/schemas/PortgroupIpv6", "description": "IPv6 prefix of the segment; each port gets the address derived from its MAC." }, { "type": "null" } ] }, "leases": { "type": "object", "description": "The IPv4 address of every NIC on the port group by MAC (lower case): the fixed ones\nand those allocated from the range. Maintained by the control plane.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Display name." }, "static_addresses": { "type": "object", "description": "Fixed IPv4 addresses by MAC (lower case), set by the operator; inside the subnet,\ninside or outside the range.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "switch": { "type": [ "string", "null" ], "description": "The switch." }, "vlan_id": { "type": "integer", "format": "int32", "description": "VLAN id, 0 for untagged.", "minimum": 0 }, "vni": { "type": [ "integer", "null" ], "format": "int32", "description": "Overlay segment (Geneve VNI) when not VLAN-backed.", "minimum": 0 } }, "additionalProperties": false }, "DistributedSwitch": { "type": "object", "description": "A distributed virtual switch (maps to an OVN logical switch set).", "required": [ "name" ], "properties": { "host_uplinks": { "type": "array", "items": { "$ref": "#/components/schemas/DvsHostUplinks" }, "description": "The physical NICs of each member host that back the uplinks (vSphere: the host proxy\nswitch, `DistributedVirtualSwitchHostMemberPnicSpec`). VLAN-backed port groups reach\nthe physical network through them (`docs/network/DESIGN.md` §6.4)." }, "hosts": { "type": "array", "items": { "type": "string" }, "description": "Member hosts." }, "mtu": { "type": "integer", "format": "int32", "description": "Maximum transmission unit.", "minimum": 0 }, "name": { "type": "string", "description": "Display name." }, "uplink_names": { "type": "array", "items": { "type": "string" }, "description": "Names of the uplinks (the ports of the switch's uplink port group,\n`uplinkPortPolicy.uplinkPortName` in vSphere); empty: `uplink1` to `uplink`." }, "uplinks": { "type": "integer", "format": "int32", "description": "Number of uplinks per host.", "minimum": 0 } }, "additionalProperties": false }, "DvsHostUplinks": { "type": "object", "description": "The physical NICs of one member host of a distributed switch.", "required": [ "host" ], "properties": { "host": { "type": "string", "description": "The member host." }, "nics": { "type": "object", "description": "Uplink name to the host's physical NIC (`eno2`).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "EffectiveRule": { "type": "object", "description": "One rule in a vNIC's evaluation order.", "required": [ "position", "number", "origin", "direction", "action", "sources", "destinations", "services", "ipVersion", "stateful", "logged", "packets", "bytes" ], "properties": { "action": { "$ref": "#/components/schemas/ActionView", "description": "Action (`pass` included)." }, "bytes": { "type": "integer", "format": "int64", "description": "Bytes counted.", "minimum": 0 }, "category": { "oneOf": [ { "$ref": "#/components/schemas/CategoryView", "description": "Category (`null` for the defaults)." }, { "type": "null" } ] }, "destinations": { "type": "array", "items": { "type": "string" }, "description": "Destinations." }, "destinationsNegated": { "type": "boolean", "description": "Destinations are negated." }, "direction": { "$ref": "#/components/schemas/DirectionView", "description": "Direction." }, "ipVersion": { "$ref": "#/components/schemas/IpVersionView", "description": "IP families." }, "lastHit": { "type": [ "string", "null" ], "description": "Last report with a non-zero count." }, "logged": { "type": "boolean", "description": "Logged." }, "number": { "type": "integer", "format": "int32", "description": "Rule number (0 for the defaults).", "minimum": 0 }, "origin": { "$ref": "#/components/schemas/Origin", "description": "Origin." }, "packets": { "type": "integer", "format": "int64", "description": "Packets counted (all hosts, since the controller started).", "minimum": 0 }, "policy": { "type": [ "string", "null" ], "description": "Policy id (`null` for the defaults and generated system rules)." }, "policyName": { "type": [ "string", "null" ], "description": "Policy name." }, "position": { "type": "integer", "format": "int32", "description": "Position in evaluation order (0 first).", "minimum": 0 }, "rule": { "type": [ "string", "null" ], "description": "Rule id." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEntryView" }, "description": "Services." }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Sources (group ids or prefixes; empty: any)." }, "sourcesNegated": { "type": "boolean", "description": "Sources are negated." }, "stateful": { "type": "boolean", "description": "Stateful." } } }, "EndBackupRequestView": { "type": "object", "description": "OpenAPI stand-in for EndBackupRequest.", "required": [ "outcome" ], "properties": { "outcome": { "$ref": "#/components/schemas/EndOutcomeView", "description": "`SUCCESS` or `FAILURE`." } } }, "EndOutcomeView": { "type": "string", "description": "OpenAPI stand-in for `EndOutcome` (model lives in kyvernon-backup).", "enum": [ "SUCCESS", "FAILURE" ] }, "EntitlementsView": { "type": "object", "description": "UI-facing entitlements (utoipa schema).", "required": [ "edition", "runningVmsLimit", "hostsLimit" ], "properties": { "edition": { "type": "string", "description": "`free` or `licensed`." }, "expiresAt": { "type": [ "string", "null" ], "description": "Earliest expiry among contributing licences, if any (RFC 3339)." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Unlocked feature names." }, "hostsLimit": { "type": "string", "description": "Maximum hosts." }, "licenceIds": { "type": "array", "items": { "type": "string" }, "description": "Contributing licence ids." }, "licensee": { "type": "string", "description": "Licensee name when licensed." }, "runningVmsLimit": { "type": "string", "description": "Maximum running VMs (`unlimited` or a number as string for OpenAPI simplicity)." } } }, "ErrorBody": { "type": "object", "description": "The REST error body.", "required": [ "code", "message", "correlationId" ], "properties": { "args": { "type": "object", "description": "Arguments for the message.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "code": { "type": "string", "description": "Stable code, e.g. `NOT_FOUND`.", "example": "NOT_FOUND" }, "correlationId": { "type": "string", "description": "Request correlation id (echoed from `x-request-id` or generated)." }, "message": { "type": "string", "description": "English developer message." }, "messageId": { "type": [ "string", "null" ], "description": "Message key the UI localises; one of the ids below (clients treat unknown ids as `code`). `args` names the arguments in brackets.\n- `error.not_found`: The object does not exist (or is not visible to the caller).\n- `error.already_exists`: An object with that name or id exists.\n- `error.conflict`: Compare-and-set failed: `expectedVersion` is stale.\n- `error.unauthenticated`: No or invalid bearer token.\n- `error.permission_denied` [privilege]: The caller lacks a privilege on the entity.\n- `error.mfa_required` [reason]: The session is restricted until multi-factor authentication completes.\n- `error.password_rotation_required` [reason]: The session is restricted until the password is changed.\n- `error.auth.invalid_credentials`: Login refused (one answer for every reason).\n- `error.auth.rate_limited` [retryAfterSeconds]: Too many login attempts; also `Retry-After`.\n- `error.auth.invalid_code`: The TOTP or recovery code was not accepted.\n- `error.auth.mfa_expired`: The MFA challenge token expired.\n- `error.auth.mfa_proof`: The MFA challenge token does not match the login.\n- `error.auth.access_expired`: The access token expired; refresh.\n- `error.auth.session_expired`: The refresh token or session expired; log in again.\n- `error.auth.refresh_reuse`: A refresh token was presented twice; the session family is revoked.\n- `error.auth.refresh_race`: Another tab refreshed first; retry once.\n- `error.auth.csrf`: The `X-Kyvernon-CSRF` header does not match the cookie.\n- `error.auth.origin`: The `Origin` header is not an allowed origin.\n- `error.mfa.already_enrolled`: TOTP is already set up.\n- `error.mfa.not_enrolled`: TOTP is not set up.\n- `error.mfa.not_enrolling`: No TOTP enrolment is pending.\n- `error.password.too_short` [min]: The password is shorter than `min`.\n- `error.password.too_long` [max]: The password is longer than `max`.\n- `error.password.common`: The password is on the common-password list.\n- `error.password.repetitive`: The password repeats one character or group.\n- `error.password.sequential`: The password is a keyboard or alphabet sequence.\n- `error.password.contains_username`: The password contains the user name.\n- `error.password.unchanged` [field]: The new password equals the current one.\n- `error.password.current_required` [field]: The current password must be given.\n- `error.password.current_incorrect` [field]: The current password is wrong.\n- `error.api_token.name` [field]: The API token name is empty or too long.\n- `error.api_token.limit` [max]: The user has `max` API tokens already.\n- `error.api_token.ttl` [field, max]: The API token lifetime is zero or longer than the maximum of `max` seconds.\n- `error.webhook.target_restricted` [field, url]: The webhook target is a loopback, private, link-local or other restricted address that is not allow-listed.\n- `error.invalid_power_state` [power_state, required]: The operation needs another power state: `power_state` is the current one, `required` the one it needs (`powered_off`, `powered_on` or `suspended`).\n- `error.vm_not_placed` [reason]: The VM has no host. `reason` is `no_connected_host`, `all_in_maintenance`, `no_hosts`, `no_compute_resource` (placement finds no host today) or `not_assigned` (a host is available but the VM names none).\n- `error.vm_spec_unbuildable`: The VM configuration cannot be built on the host; the `message` names the cause.\n- `error.vm.concurrent_modification`: The VM configuration changed since the request's `change_version` was read and the change cannot be merged; read the VM again and repeat (HTTP 409).\n- `error.vm.exceeds_host_cpu` [field, requested, limit, host]: More vCPUs than the host has logical CPUs (or than `vm_ops.max_vcpus_per_vm`).\n- `error.vm.exceeds_host_memory` [field, requested, limit, host]: More memory (MiB) than the host has after `vm_ops.host_memory_reserve_mib`.\n- `error.vm.too_many_devices` [device, count, limit]: More disks and network adapters together (`device` = `disks_and_nics`), or CD-ROM drives (`cdroms`), than a virtual machine has slots.\n- `error.host.insufficient_memory` [requested, available, host]: Power-on refused: the host has `available` MiB free for virtual machines, the guest needs `requested`.\n- `error.host.not_in_maintenance` [host]: Reboot or shutdown needs the host in maintenance mode (or `force`).\n- `error.host.not_connected` [host]: The host is not connected to the control plane.\n- `error.datastore.not_shareable` [datastore]: The datastore cannot be mounted on or unmounted from a single host: an iSCSI (VMFS-like) datastore belongs to one host, a local datastore to its own.\n- `error.tag.not_associable` [category, kind]: Tags of the category cannot be attached to objects of that kind (the category's associable kinds).\n- `error.tag.cardinality` [category, object]: The object already carries another tag of a category that allows one tag per object.\n- `error.tag.provider_managed` [category]: Tags of a provider-managed category are attached and detached by the provider only.\n- `error.tag.category_change` [field]: A category's cardinality changes from single to multiple only, and associable kinds can only be added.\n- `error.backup.no_repository`: No backup repository is configured on the controller (`[backup] verify_repository` or the backup settings).\n- `error.backup.repository_unusable` [repository]: The repository directory cannot be created or written on this controller.\n- `error.backup.export_unreachable`: The controller cannot reach the NBD export of a disk on the host.\n- `error.backup.change_tracking` [vm]: Change tracking could not be turned on for the virtual machine before its first backup.\n- `error.backup.no_disks` [vm]: The virtual machine has no disk to back up.\n- `error.backup.vm_powered_on` [vm]: A restore in place replaces the disks of the virtual machine; it must be powered off.\n- `error.backup.verify_failed` [point]: The restore finished, but the verification of the backup point in quarantine failed.\n- `error.backup.controller_running`: A backup of the controller state is already running.\n- `error.backup.controller_target` [target]: The folder for the archives of the controller state cannot be created.\n- `error.backup.controller_changed` [file]: A file of the state directory changed while it was archived.\n- `error.backup.controller_unreadable`: The archive that was written does not read back as written.\n- `error.backup.controller_unavailable`: This controller keeps its state in memory; there is nothing to archive.\n- `error.backup.source_gone`: The virtual machine of the backup point no longer exists; its configuration is needed for a restore.\n- `error.datacenter.not_empty` [datacenter]: The datacenter still holds clusters, hosts, virtual machines, networks or datastores.\n- `error.datastore.insufficient_space` [requested, available, datastore]: A new or grown disk asks for more bytes than the datastore has free (thick) or than the thin-disk cap.\n- `error.disk.shrink_not_supported` [field, disk]: A disk cannot be made smaller.\n- `error.guest_operations_unavailable`: Guest operations are not available (powered off, no agent, or agent blocks the command).\n- `error.guest_file_exists`: The file already exists in the guest (use overwrite).\n- `error.guest_path_not_found`: The path does not exist in the guest.\n- `error.guest_path_is_directory`: The path is a directory in the guest.\n- `error.guest_path_not_directory`: The path is not a directory in the guest.\n- `error.guest_directory_not_empty`: The directory is not empty in the guest.\n- `error.console.powered_off`: The VM is powered off; a console needs a running VM.\n- `error.console.not_available`: The VM runs without a graphical console (no `console.vnc`).\n- `error.console.host_disconnected`: The VM's host is not connected.\n- `error.console.rate_limited` [retryAfterSeconds]: Too many console tickets for this session.\n- `error.console.ticket_invalid`: The console ticket is unknown, used or expired.\n- `error.no_current_snapshot`: The VM has no current snapshot to revert to.\n- `error.nic_network_unwired` [network, nic]: A NIC is on a network without a host-bridge backing.\n- `error.host_capability_missing` [capability]: The host did not declare the needed capability.\n- `error.host_has_running_vms`: Maintenance mode needs the host's VMs powered off or moved.\n- `error.host_has_vms`: The host still has VMs placed on it; relocate or destroy them first.\n- `error.host_in_maintenance`: The host is in maintenance mode.\n- `error.template_relocate`: Templates cannot be relocated.\n- `error.image_in_use` [vm]: The image file backs a VM.\n- `error.datastore_bad_path` [field]: The datastore path is empty, absolute, or escapes the root.\n- `error.datastore_file_exists`: The file or folder exists (use `overwrite`).\n- `error.datastore_file_not_found`: No such file on the datastore.\n- `error.datastore_folder_not_found`: No such folder on the datastore.\n- `error.datastore_folder_not_empty`: The folder still has entries.\n- `error.datastore_file_in_use` [vm, vmId]: The file backs a VM disk.\n- `error.disk_owned_by_other_vm` [field]: The disk file belongs to another VM the caller has no disk access to.\n- `error.audit_record_immutable`: Audit records cannot be deleted.\n- `error.datastore_upload_too_large` [limit]: The upload exceeds `limit` bytes (HTTP 413).\n- `error.datastore_upload_incomplete`: The upload ended before `Content-Length` bytes.\n- `error.datastore_read_only`: The datastore refuses writes.\n- `error.datastore_range_invalid`: The `Range` header cannot be satisfied (HTTP 416).\n- `error.datastore_inaccessible` [datastore]: The datastore is not accessible from its hosts.\n- `error.datastore_no_host` [datastore]: No connected host mounts the datastore.\n- `error.datastore_not_on_host` [datastore]: The chosen host does not mount the datastore.\n- `error.datastore_not_shared`: The operation needs a datastore shared by both hosts.\n- `error.metrics_disabled`: Performance metrics are turned off on the controller.\n- `error.metrics_bad_entity` [entity]: No performance data is kept for that object kind.\n- `error.metrics_bad_interval` [interval]: Not a supported sampling period.\n- `error.metrics_unknown_counter` [counter]: No such counter.\n- `error.metrics_query_empty`: The query names no entity or counter.\n- `error.metrics_query_too_large`: The query would return too many samples.\n- `error.metrics_too_many_batches` [max]: A host agent sent more than `max` metric batches in one report; the whole report is rejected.\n- `error.usage_bad_date` [field]: A date is not `YYYY-MM-DD`.\n- `error.usage_bad_range`: `to` is before `from` or the range exceeds ten years.\n- `error.usage_bad_group`: `groupBy` is not vm, tenant, resourcePool, folder or host.\n- `error.usage_bad_period`: `period` is not day, month or total.\n- `error.usage_bad_format`: `format` is not json or csv.\n- `error.usage_bad_scope`: `scope` is not an inventory container id.\n- `error.licence.limit_running_vms` [limit, current, delta]: Power-on would exceed the running-VM licence limit.\n- `error.licence.limit_hosts` [limit, current, delta]: Enrolling a host would exceed the host licence limit.\n- `error.licence.feature_required` [feature]: The operation needs a licence feature that is not enabled.\n- `error.licence.signature_invalid`: The licence file signature is not valid.\n- `error.licence.not_valid`: The licence is outside its validity window.\n- `error.quota.exceeded` [resource, limit, current, requested, tenant]: The operation would take the tenant over its quota of `resource` (vcpus, memoryMib, diskGib, vms, publicIpv4, snapshots).\n- `error.tenant.suspended` [tenant]: The tenant is suspended: no power-on, no console, users are read-only.\n- `error.tenant.closed` [tenant]: The tenant is closed.\n- `error.server.not_ready` [state]: The server is not in a state that allows the operation (creating, deleted, failed or rescue).\n- `error.server.plan_not_larger` [field]: Resize goes to a plan that is at least as large in vCPU, memory and disk.\n- `error.server.plan_not_orderable` [field]: The plan is not orderable.\n- `error.server.image_not_allowed` [field]: The plan does not allow the image.\n- `error.server.disk_too_small` [field]: The plan's disk is smaller than the image needs.\n- `error.server.no_credentials` [field]: The image takes no credentials (no SSH keys, password or user data).\n- `error.server.rescue_active`: The server is already in rescue mode.\n- `error.server.no_rescue_image`: No catalogue image is marked as a rescue image.\n- `error.plan.in_use` [servers]: Servers use the plan; make it not orderable instead.\n- `error.catalogue.not_template`: Only template VMs can be catalogue images.\n- `error.ip_pool.exhausted` [pool]: The IP pool has no free address (or /64) left.\n- `error.ip_pool.address_in_use` [address]: The requested address is allocated already.\n- `error.ip_pool.address_quarantined` [address]: The address was released recently and is in quarantine.\n- `error.ip_pool.primary_exists` [mac]: The NIC already has a primary address in this pool; ask for an extra one.\n- `error.ip_pool.no_ipv6`: The IP pool has no IPv6 prefix.\n- `error.ip_pool.overlap` [field, pool]: The ranges overlap another IP pool.\n- `error.ip_pool.in_use` [pool]: The IP pool still has allocations.\n- `error.ip_pool.not_allocated` [address]: The address is not allocated in the pool (or not the VM's).\n- `error.ip_pool.no_nic` [network, vm]: The VM has no NIC on the IP pool's network.\n- `error.ip_pool.ipv6_block_len` [field]: The IPv6 block length per server must be 64 to 128.\n- `error.ip_pool.ipv6_layout_in_use` [field]: The IPv6 prefix and block length cannot change while blocks are allocated or in quarantine.\n- `error.network.proxy_uplink` [field]: Proxy mode needs an Open vSwitch bridge and the name of the uplink interface.\n- `error.network.promiscuous_unsupported` [field]: Promiscuous mode is not realised by the host bridge; use a mirror session.\n- `error.network.shaping_invalid` [field]: The traffic shaping values are incomplete, negative or out of order (`field` names the value).\n- `error.network.teaming_invalid` [field]: The NIC teaming policy is unknown, or a NIC name is invalid or listed twice.\n- `error.firewall.validation` [object, issue, count]: The firewall change adds validation errors (`issue` is the `net.validation.fw_*` key of the first, `object` its path, `count` how many); the message lists them all.\n- `error.firewall.builtin` [object]: The firewall object is built in and maintained by the control plane (read-only).\n- `error.firewall.reserved_name` [field]: Firewall object names starting with `sys:` are reserved for built-in objects.\n- `error.firewall.quota` [resource, limit, used]: The tenant's firewall quota (`fwGroups`, `fwPolicies`, `fwRules`, `fwGroupMembers`) would be exceeded.\n- `error.firewall.category_scope` [field]: Emergency and Infrastructure policies belong to the provider.\n- `error.firewall.in_use` [object]: The firewall object is still used (a profile set on vNICs).\n- `error.firewall.no_vnic`: The VM has no vNIC on a host-bridge network.\n- `error.firewall.profile_not_selectable` [profile]: A tenant user chose a firewall profile the provider did not mark selectable.\n- `error.firewall.unprotected` [nic, reason]: The vNIC cannot be firewalled; its mode stays `off`. `reason` is `linux_or_quarantine_bridge` or `port_security_off`.\n- `error.firewall.not_pending`: No firewall mode switch of the VM waits for confirmation.\n- `error.identity.group_exists` [group]: A local group with that name exists (names are compared without regard to case).\n- `error.identity.group_not_found` [group]: No local group has that name.\n- `error.identity.group_cycle` [group, member]: Nesting `member` in `group` would make a group contain itself, or nest deeper than eight levels.\n- `error.identity.oidc_unreachable` [issuer]: The identity provider did not answer OpenID Connect discovery at `issuer`; the stored provider is unchanged.\n- `error.identity.policy_invalid` [field]: A password or lockout policy value is out of range (`field` names it).\n- `error.nsx.unsupported`: NSX Policy API facade: the request uses a feature outside the subset this server serves; the message names the field (`DFW-HOSTBRIDGE.md` §6.4).\n- `error.nsx.invalid`: NSX Policy API facade: a field of the request is not valid; the message names it.\n- `error.nsx.not_found`: NSX Policy API facade: the path names no object, or one the caller cannot see.\n- `error.nsx.revision`: NSX Policy API facade: the `_revision` of the write is stale (412); read the object again.\n- `error.nsx.read_only`: NSX Policy API facade: the object is built in, or a tenant user wrote into the provider scope.\n- `error.nsx.xsrf`: NSX Policy API facade: a write with a session cookie lacks the session's `X-XSRF-TOKEN`.\n- `error.identity.provider_privilege_in_tenant` [role, privilege]: The role holds a provider-only privilege (Kyvernon.Firewall.ManageProvider, Kyvernon.Firewall.Bypass), which cannot be granted inside a tenant's folders and pools.\n- `error.rdns.nothing_pending` [address]: No PTR request is waiting for this address.\n- `error.rdns.reason_required` [field]: A rejected PTR request needs a reason.\n- `error.rdns.provider_failed` [http_status]: The DNS provider did not accept the change; retry later. `http_status` is the provider's answer when it gave one; the cause is in the `message`.\n- `error.rdns.no_zone` [name]: No reverse zone on the DNS server holds the address.\n- `error.rdns.not_forward_confirmed` [name, address]: The PTR name does not resolve back to the address.\n- `error.rdns.invalid_name` [field]: The PTR name is not a valid host name.\n- `error.traffic.bad_month` [field]: `month` is not `YYYY-MM`.\n- `error.traffic.no_policy` [vm]: The VM has no traffic limit.\n- `error.task.secrets_lost`: The task's secret parameters lived only in the memory of a controller that restarted or lost leadership; submit the operation again.\n" } } }, "EventView": { "type": "object", "description": "An event.", "required": [ "id", "time", "severity", "eventType", "messageId", "args", "targetName", "related", "user", "chainId", "attributes" ], "properties": { "args": { "type": "object", "description": "Message arguments.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "attributes": { "type": "object", "description": "Attributes.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "chainId": { "type": "string", "description": "Correlation id." }, "eventType": { "type": "string", "description": "Event type in vSphere style (`VmPoweredOnEvent`)." }, "id": { "type": "string", "description": "Event id (`event-N`)." }, "messageId": { "type": "string", "description": "Localisable message key." }, "related": { "type": "array", "items": { "type": "string" }, "description": "Related object ids." }, "severity": { "$ref": "#/components/schemas/SeverityView", "description": "Severity." }, "targetId": { "type": [ "string", "null" ], "description": "Target id." }, "targetName": { "type": "string", "description": "Target name." }, "targetType": { "type": [ "string", "null" ], "description": "Target short type." }, "taskId": { "type": [ "string", "null" ], "description": "Producing task." }, "time": { "type": "string", "description": "Time (RFC 3339)." }, "user": { "type": "string", "description": "User." } } }, "Evidence": { "type": "object", "description": "The evidence of one verification.", "required": [ "boot", "dhcp", "network", "durationMs" ], "properties": { "boot": { "$ref": "#/components/schemas/BootEvidence", "description": "Boot." }, "dhcp": { "$ref": "#/components/schemas/DhcpEvidence", "description": "DHCP lease." }, "durationMs": { "type": "integer", "format": "int64", "description": "Time from power-on to the verdict.", "minimum": 0 }, "network": { "$ref": "#/components/schemas/NetworkEvidence", "description": "Network." }, "tcp": { "oneOf": [ { "$ref": "#/components/schemas/TcpEvidence", "description": "Host-side TCP checks (present when `tcpPorts` was set)." }, { "type": "null" } ] } } }, "FenceResolutionView": { "type": "string", "description": "Who keeps the guest after a fenced migration.", "enum": [ "source-keeps", "destination-keeps" ], "example": "source-keeps" }, "FinishRestoreRequest": { "type": "object", "description": "Body for finish restore.", "required": [ "commit" ], "properties": { "commit": { "type": "boolean", "description": "Commit the written image and attach it; false discards." } } }, "FirmwareKind": { "type": "string", "description": "OpenAPI schema of [`Firmware`] (`kyvernon_vm_model::spec::FirmwareKind`), whose crate\nhas no schema support; `firmware_kind_schema_matches_the_model` keeps the two equal.", "enum": [ "bios", "uefi" ] }, "Folder": { "type": "object", "description": "A folder. The type decides which kinds may be its children.", "required": [ "name", "folder_type" ], "properties": { "folder_type": { "$ref": "#/components/schemas/FolderType", "description": "Which kinds this folder holds." }, "name": { "type": "string", "description": "Display name." } }, "additionalProperties": false }, "FolderType": { "type": "string", "description": "The kind of objects a folder may hold.", "enum": [ "datacenter", "virtual_machine", "host", "network", "datastore" ] }, "GroupBody": { "type": "object", "description": "Create or replace a group.", "required": [ "name" ], "properties": { "criteria": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/TagView" } }, "description": "Tag criteria: a vNIC is a member when its VM carries every tag of one criterion." }, "description": { "type": "string", "description": "Description (tenants see it with the name for shared provider groups)." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Nested groups." }, "macs": { "type": "array", "items": { "type": "string" }, "description": "Every vNIC with one of these MAC addresses (`00:50:56:aa:bb:cc`)." }, "name": { "type": "string", "description": "Name (unique in its scope; `sys:` is reserved)." }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Every vNIC on these host-bridge networks." }, "prefixes": { "type": "array", "items": { "type": "string" }, "description": "Addresses and prefixes (endpoints outside the platform)." }, "shared": { "type": "boolean", "description": "Provider groups only: tenants may use it as source or destination (name only)." }, "vms": { "type": "array", "items": { "type": "string" }, "description": "Every vNIC of these VMs." }, "vnics": { "type": "array", "items": { "$ref": "#/components/schemas/VnicView" }, "description": "These vNICs." } }, "additionalProperties": false }, "GroupMembersRequest": { "type": "object", "description": "Body of `POST /v1/identity/groups/{name}/members`.", "properties": { "groups": { "type": "array", "items": { "type": "string" }, "description": "Groups to add as nested groups. A group that would contain itself, directly or\nthrough other groups, is refused (`error.identity.group_cycle`)." }, "users": { "type": "array", "items": { "type": "string" }, "description": "Users to add (local users)." } }, "additionalProperties": false }, "GroupMembersView": { "type": "object", "description": "Resolved members of a group.", "required": [ "group", "vnics", "addresses" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "Their addresses and the group's prefixes (aggregated)." }, "group": { "type": "string", "description": "Group id." }, "vnics": { "type": "array", "items": { "$ref": "#/components/schemas/VnicView" }, "description": "Member vNICs." } } }, "GroupView": { "allOf": [ { "$ref": "#/components/schemas/GroupBody", "description": "The definition." }, { "type": "object", "required": [ "id", "version", "builtin" ], "properties": { "builtin": { "type": "boolean", "description": "Built in and maintained by the control plane (read-only)." }, "fwVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Store version of this write (writes only).", "minimum": 0 }, "id": { "type": "string", "description": "`fwgroup-N`." }, "pendingHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts that had not applied the change when `?wait=realized` timed out." }, "redacted": { "type": "boolean", "description": "Membership is hidden (a shared provider group read by a tenant)." }, "tenant": { "type": [ "string", "null" ], "description": "Owner: `null` for the provider, else the tenant id." }, "version": { "type": "integer", "format": "int64", "description": "Record version (for `If-Match`).", "minimum": 0 } } } ], "description": "A group." }, "GrownDiskView": { "type": "object", "description": "Outcome of one grown disk in a reconfigure task's `result.grownDisks`.", "required": [ "datastore", "path", "sizeBytes" ], "properties": { "datastore": { "type": "string", "description": "Datastore id." }, "outcome": { "type": [ "string", "null" ], "description": "`online` (the guest saw the new size), `offline` (the file grew while the VM\nwas off) or `at-next-start` (the running VM sees it after its next power cycle)." }, "path": { "type": "string", "description": "Path below the datastore root." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "New capacity in bytes.", "minimum": 0 } } }, "GuestAgentOffer": { "type": "object", "description": "The answer: whether to offer, and what installing it means.", "required": [ "offer", "reason", "vendorData" ], "properties": { "extraConfig": { "type": [ "object", "null" ], "description": "`extraConfig` with the snippet merged into `guestinfo.vendordata`, what\n`guestAgent: true` on the create request produces; absent when it cannot be merged\n(the VM's vendor data is not `#cloud-config`) or not offered.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "mergeError": { "type": [ "string", "null" ], "description": "Set when the snippet cannot be merged into the VM's vendor data." }, "offer": { "type": "boolean", "description": "Offer the installation: the template's cloud image lacks `qemu-guest-agent` and the\nVM's cloud-init data does not install it." }, "reason": { "type": "string", "description": "Why (or why not), for the UI to show next to the choice." }, "vendorData": { "type": "string", "description": "The vendor-data snippet (`#cloud-config` that installs and starts the agent)." } } }, "GuestAgentOfferRequest": { "type": "object", "description": "Asks whether to offer the guest agent installation for a VM about to be created.", "required": [ "template" ], "properties": { "extraConfig": { "type": "object", "description": "The VM's `extraConfig` so far (`guestinfo.userdata` and friends).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "template": { "type": "string", "description": "The template, image or guest OS the VM is created from (`Ubuntu 24.04 LTS`,\n`debian-13`, `ubuntu64Guest`)." } } }, "GuestAuthRequest": { "type": "object", "description": "Guest authentication accepted by guest-ops routes (not checked against the guest).", "properties": { "interactiveSession": { "type": [ "boolean", "null" ], "description": "Interactive session flag (SOAP parity; ignored)." }, "password": { "type": [ "string", "null" ], "description": "Guest password (accepted and discarded)." }, "username": { "type": [ "string", "null" ], "description": "Guest account name (echoed; not verified)." } } }, "GuestAuthView": { "type": "object", "description": "Credentials echo from `AcquireCredentialsInGuest`.", "properties": { "interactiveSession": { "type": "boolean", "description": "Interactive session flag echoed." }, "username": { "type": "string", "description": "Account name handed back." } } }, "GuestChangeAttributesRequest": { "type": "object", "description": "Change posix file attributes in the guest (`ChangeFileAttributesInGuest`).", "required": [ "path" ], "properties": { "accessTimeUnix": { "type": [ "integer", "null" ], "format": "int64", "description": "Access time, Unix seconds; omit to leave unchanged." }, "groupId": { "type": [ "integer", "null" ], "format": "int32", "description": "Group gid; omit to leave unchanged." }, "modificationTimeUnix": { "type": [ "integer", "null" ], "format": "int64", "description": "Modification time, Unix seconds; omit to leave unchanged." }, "ownerId": { "type": [ "integer", "null" ], "format": "int32", "description": "Owner uid; omit to leave unchanged." }, "path": { "type": "string", "description": "Path in the guest." }, "permissions": { "type": [ "integer", "null" ], "format": "int64", "description": "Mode bits as VMware `permissions` (e.g. `420` = `0644`); omit to leave unchanged." } } }, "GuestCreateTemporaryRequest": { "type": "object", "description": "Create a temporary file or directory in the guest (`CreateTemporary*InGuest`).", "properties": { "directoryPath": { "type": [ "string", "null" ], "description": "Parent directory; omit for guest `/tmp`." }, "prefix": { "type": "string", "description": "Name prefix (no path separators); may be empty." }, "suffix": { "type": "string", "description": "Name suffix (no path separators); may be empty." } } }, "GuestCreateTemporaryView": { "type": "object", "description": "Path created by `CreateTemporary*InGuest`.", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Absolute path in the guest." } } }, "GuestDeleteFileRequest": { "type": "object", "description": "Delete a file in the guest (`DeleteFileInGuest`).", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "File path in the guest (not a directory)." } } }, "GuestEnvView": { "type": "object", "description": "Guest environment variables.", "properties": { "variables": { "type": "array", "items": { "type": "string" }, "description": "`NAME=value` lines." } } }, "GuestFileEntryView": { "type": "object", "description": "One guest path as `ListFilesInGuest` / native list reports it.", "properties": { "path": { "type": "string", "description": "Absolute path in the guest." }, "size": { "type": "integer", "format": "int64", "description": "Size in bytes." }, "type": { "type": "string", "description": "`file`, `directory`, or `symlink`." } } }, "GuestFileListRequest": { "type": "object", "description": "List files in the guest (`ListFilesInGuest`).", "required": [ "path" ], "properties": { "index": { "type": [ "integer", "null" ], "format": "int32", "description": "Zero-based start index (default 0)." }, "matchPattern": { "type": [ "string", "null" ], "description": "Basename regex (`grep -E`); empty / `.*` matches all." }, "maxResults": { "type": [ "integer", "null" ], "format": "int32", "description": "Cap on returned entries." }, "path": { "type": "string", "description": "Directory or file path in the guest." } } }, "GuestFileListView": { "type": "object", "description": "Guest directory listing page.", "required": [ "remaining" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/GuestFileEntryView" }, "description": "Matched page." }, "remaining": { "type": "integer", "format": "int32", "description": "How many matches remain after this page." } } }, "GuestFileReadRequest": { "type": "object", "description": "Read a file from the guest.", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Absolute path in the guest." } } }, "GuestFileReadView": { "type": "object", "description": "File contents from the guest (inline; replaces SOAP NFC-style transfer URL).", "required": [ "path", "size", "dataBase64" ], "properties": { "dataBase64": { "type": "string", "description": "File content, standard Base64." }, "path": { "type": "string", "description": "Path that was read." }, "size": { "type": "integer", "format": "int64", "description": "Size in bytes.", "minimum": 0 } } }, "GuestFileWriteRequest": { "type": "object", "description": "Write a file into the guest.", "required": [ "path", "dataBase64" ], "properties": { "dataBase64": { "type": "string", "description": "File content, standard Base64." }, "overwrite": { "type": [ "boolean", "null" ], "description": "Replace an existing file (default true)." }, "path": { "type": "string", "description": "Absolute path in the guest." } } }, "GuestFileWriteView": { "type": "object", "description": "Result of writing a guest file.", "required": [ "path", "size" ], "properties": { "path": { "type": "string", "description": "Path that was written." }, "size": { "type": "integer", "format": "int64", "description": "Bytes written.", "minimum": 0 } } }, "GuestMkdirRequest": { "type": "object", "description": "Create a directory in the guest (`MakeDirectoryInGuest`).", "required": [ "path" ], "properties": { "createParents": { "type": [ "boolean", "null" ], "description": "Create missing parents (default false)." }, "path": { "type": "string", "description": "Directory path in the guest." } } }, "GuestMoveDirectoryRequest": { "type": "object", "description": "Move or rename a directory in the guest (`MoveDirectoryInGuest`).", "required": [ "src", "dst" ], "properties": { "dst": { "type": "string", "description": "Destination directory path in the guest." }, "src": { "type": "string", "description": "Source directory path in the guest." } } }, "GuestMoveFileRequest": { "type": "object", "description": "Move or rename a file in the guest (`MoveFileInGuest`).", "required": [ "src", "dst" ], "properties": { "dst": { "type": "string", "description": "Destination path in the guest." }, "overwrite": { "type": [ "boolean", "null" ], "description": "Replace an existing destination file (default false)." }, "src": { "type": "string", "description": "Source path in the guest." } } }, "GuestNic": { "type": "object", "description": "A network interface of the guest as the guest agent reports it.", "required": [ "name" ], "properties": { "ip_addresses": { "type": "array", "items": { "type": "string" }, "description": "Addresses: IPv4 first, then global IPv6 (link-local ones are left out)." }, "mac": { "type": "string", "description": "Hardware address (lower case), the key that ties it to a virtual NIC." }, "name": { "type": "string", "description": "Interface name in the guest (`eth0`, `enp1s0`)." } }, "additionalProperties": false }, "GuestProcessListView": { "type": "object", "description": "List of guest processes.", "properties": { "processes": { "type": "array", "items": { "$ref": "#/components/schemas/GuestProcessView" }, "description": "Processes remembered for this VM (or filtered by pid)." } } }, "GuestProcessView": { "type": "object", "description": "A program of the guest as `ListProcessesInGuest` / native list reports it.", "required": [ "pid", "startUnix" ], "properties": { "cmdLine": { "type": "string", "description": "Path and arguments." }, "endUnix": { "type": [ "integer", "null" ], "format": "int64", "description": "End, when it has ended.", "minimum": 0 }, "exitCode": { "type": [ "integer", "null" ], "format": "int32", "description": "Exit code, once it has exited." }, "name": { "type": "string", "description": "Program name." }, "owner": { "type": "string", "description": "Owner (the account the start named)." }, "pid": { "type": "integer", "format": "int64", "description": "Process id in the guest." }, "startUnix": { "type": "integer", "format": "int64", "description": "Start, seconds since the Unix epoch.", "minimum": 0 } } }, "GuestRmdirRequest": { "type": "object", "description": "Delete a directory in the guest (`DeleteDirectoryInGuest`).", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Directory path in the guest." }, "recursive": { "type": [ "boolean", "null" ], "description": "Remove contents too (default false)." } } }, "GuestStartProgramRequest": { "type": "object", "description": "Start a program in the guest.", "required": [ "programPath" ], "properties": { "arguments": { "type": [ "string", "null" ], "description": "Arguments as one string (SOAP `GuestProgramSpec.arguments`)." }, "auth": { "$ref": "#/components/schemas/GuestAuthRequest", "description": "Authentication (accepted, not checked)." }, "envVariables": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Environment variables (`NAME=value`)." }, "programPath": { "type": "string", "description": "Absolute path of the program in the guest." }, "workingDirectory": { "type": [ "string", "null" ], "description": "Working directory." } } }, "GuestStartProgramView": { "type": "object", "description": "Result of starting a guest program.", "required": [ "pid" ], "properties": { "pid": { "type": "integer", "format": "int64", "description": "Guest process id." } } }, "Host": { "type": "object", "description": "A hypervisor host.", "required": [ "name" ], "properties": { "agent_credential_hash": { "type": [ "string", "null" ], "description": "SHA-256 of the agent's bearer credential issued at registration. The\nAPI strips this field from every host view." }, "agent_version": { "type": "string", "description": "Host OS / agent version string." }, "bridges": { "type": "array", "items": { "type": "string" }, "description": "Declared standard-switch / host-bridge names (`HostNetworkSystem.AddVirtualSwitch`).\nPort groups on host-bridge networks also imply their bridge here when projected." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capabilities the agent declared at registration (`kvm`, `tcg`, `swtpm`,\n`secure-boot`, `live-migration`, `nbd-export`, `dirty-bitmaps`, `runtime:`).\nPlacement and operations check them (a host without `suspend-to-disk` cannot\nsuspend)." }, "certificate_expires_at": { "type": [ "string", "null" ], "description": "Expiry of the issued host certificate." }, "certificate_sha256": { "type": [ "string", "null" ], "description": "SHA-256 (hex) of the DER host certificate the control plane issued at\nregistration. Agent calls are accepted only over mutual TLS with exactly this\ncertificate; issuing a new one (re-registration) revokes the old one." }, "hardware": { "$ref": "#/components/schemas/HostHardware", "description": "Agent-reported hardware." }, "iscsi_chap": { "oneOf": [ { "$ref": "#/components/schemas/HostIscsiChapAuth", "description": "Adapter-level software iSCSI CHAP (`UpdateInternetScsiAuthenticationProperties`).\nThe secret is stripped from REST host views; never log it." }, { "type": "null" } ] }, "iscsi_discovered_targets": { "type": "array", "items": { "$ref": "#/components/schemas/HostIscsiDiscoveredTarget" }, "description": "Discovered static targets after `RescanHba` (`iscsiadm` discovery)." }, "iscsi_scsi_disks": { "type": "array", "items": { "$ref": "#/components/schemas/HostIscsiScsiDisk" }, "description": "SCSI disks visible after software iSCSI rescan (for `QueryAvailableDisksForVmfs`)." }, "iscsi_send_targets": { "type": "array", "items": { "$ref": "#/components/schemas/HostIscsiSendTarget" }, "description": "Configured iSCSI send targets (`AddInternetScsiSendTargets`)." }, "iscsi_static_targets": { "type": "array", "items": { "$ref": "#/components/schemas/HostIscsiDiscoveredTarget" }, "description": "Manually configured static targets (`AddInternetScsiStaticTargets`).\nSurvives send-target removal; RescanHba logs in without discovery." }, "management_address": { "type": "string", "description": "Management address the control plane dials." }, "name": { "type": "string", "description": "Display name (usually the FQDN)." }, "runtime": { "$ref": "#/components/schemas/HostRuntime", "description": "Agent-reported runtime." }, "software_internet_scsi_enabled": { "type": [ "boolean", "null" ], "description": "Software iSCSI initiator enabled (`HostStorageSystem` / `storageDeviceInfo`).\n`None` means enabled (legacy / default); `Some(false)` disables the projected HBA." } }, "additionalProperties": false }, "HostBridgeBacking": { "type": "object", "description": "A host-bridge backing.", "required": [ "bridge" ], "properties": { "bridge": { "type": "string", "description": "Bridge name on the hosts." }, "bridge_kind": { "$ref": "#/components/schemas/BridgeKind", "description": "Bridge kind." }, "ipv4": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeIpv4", "description": "IPv4 and DHCP; `None` for a network without addressing by Kyvernon." }, { "type": "null" } ] }, "leases": { "type": "object", "description": "Static leases, MAC (lower case, colon form) to address; maintained by the control\nplane ([`HostBridgeBacking::reconcile_leases`]).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "nic_policies": { "type": "object", "description": "Per-NIC policy, MAC (lower case, colon form) to policy: public addresses from IP pools\nand traffic throttles (`docs/network/DESIGN.md` §11.2). Projected by the control plane\nfrom the `ip_pool` allocations and the traffic state; never edited by hand.", "additionalProperties": { "$ref": "#/components/schemas/NicPolicy" }, "propertyNames": { "type": "string" } }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgePortGroupPolicy", "description": "SOAP / Terraform `HostPortGroupSpec.policy` overrides (security, teaming, shaping).\nAbsent means inherit / empty policy projection (stable for VLAN-only clients)." }, { "type": "null" } ] }, "port_security": { "type": "boolean", "description": "Enforce each NIC's MAC and leased address." }, "quarantine": { "type": "boolean", "description": "A quarantine network (M2-NET-02, `docs/network/DESIGN.md` §11.1): the agent creates\nthe bridge itself, dedicated and without uplink, the lease carries no gateway and no\nDNS, and the pipeline lets VMs reach each other and the DHCP responder only. Restore\nverification boots restored backups here (M2-STO-03)." }, "uplink": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeUplink", "description": "How public addresses reach the bridge (`docs/network/DESIGN.md` §11.6); `None`:\nbridged." }, { "type": "null" } ] } }, "additionalProperties": false }, "HostBridgeBackingRequest": { "type": "object", "description": "Host-bridge backing for a standard network / port group.", "required": [ "bridge" ], "properties": { "bridge": { "type": "string", "description": "Bridge name on every host (`br-vm`)." }, "bridgeKind": { "type": [ "string", "null" ], "description": "`ovs` (default) or `linux`." }, "ipv4": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeIpv4Request", "description": "IPv4 and DHCP; omit for a network without addressing by Kyvernon." }, { "type": "null" } ] }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgePortGroupPolicy", "description": "Port-group policy: security, traffic shaping and NIC teaming, in the shape the\nnetwork record shows it (`data.backing.policy`; the SOAP `HostNetworkPolicy`\nwrites the same). Absent: kept on update (none on create); `null` or `{}`: cleared.\nPromiscuous mode is refused (`error.network.promiscuous_unsupported`); shaping that\nis on needs `average_bandwidth` of at least 1000 bit/s and `peak_bandwidth` not below\nit (`error.network.shaping_invalid`); teaming takes `loadbalance_srcid`,\n`loadbalance_srcmac`, `loadbalance_ip` or `failover_explicit` and each NIC once\n(`error.network.teaming_invalid`)." }, { "type": "null" } ] }, "portSecurity": { "type": [ "boolean", "null" ], "description": "Enforce each NIC's MAC and leased address (default true)." }, "quarantine": { "type": [ "boolean", "null" ], "description": "Quarantine network (default false): a dedicated bridge the agents create, without\nuplink, gateway or DNS; VMs reach each other and DHCP only. Needs `ipv4` with a\n`serverId` and no `gateway`; used by restore verification." }, "uplink": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeUplink", "description": "How public addresses reach the bridge: `bridged` (default, the bridge carries the\nuplink) or `proxy` with a named uplink (`{\"mode\": \"proxy\", \"interface\": \"eno1\"}`):\nthe host routes and answers ARP/NDP on the uplink (`docs/network/DESIGN.md` §11.6)." }, { "type": "null" } ] } } }, "HostBridgeIpv4": { "type": "object", "description": "IPv4 settings and DHCP of a host-bridge network.", "required": [ "prefix_len", "range_start", "range_end" ], "properties": { "dhcp": { "type": "boolean", "description": "Answer DHCP (otherwise guests configure the leased address themselves)." }, "dns_servers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers handed out; empty: the host agent's defaults." }, "domain_name": { "type": [ "string", "null" ], "description": "Domain name handed out." }, "gateway": { "type": [ "string", "null" ], "description": "Default gateway handed out (and the DHCP server identifier unless `server_id` is set)." }, "lease_time_s": { "type": "integer", "format": "int32", "description": "Lease time in seconds.", "minimum": 0 }, "mtu": { "type": [ "integer", "null" ], "format": "int32", "description": "Interface MTU handed out.", "minimum": 0 }, "prefix_len": { "type": "integer", "format": "int32", "description": "Prefix length of the subnet.", "minimum": 0 }, "range_end": { "type": "string", "description": "Last address leases are allocated from (inclusive)." }, "range_start": { "type": "string", "description": "First address leases are allocated from." }, "server_id": { "type": [ "string", "null" ], "description": "DHCP server identifier." } }, "additionalProperties": false }, "HostBridgeIpv4Request": { "type": "object", "description": "IPv4 / DHCP settings for a host-bridge network (`POST`/`PUT /v1/networks`).", "required": [ "prefixLen", "rangeStart", "rangeEnd" ], "properties": { "dhcp": { "type": [ "boolean", "null" ], "description": "Answer DHCP (default true)." }, "dnsServers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers handed out." }, "domainName": { "type": [ "string", "null" ], "description": "Domain name handed out." }, "gateway": { "type": [ "string", "null" ], "description": "Default gateway handed out (and DHCP server id unless `serverId` is set)." }, "leaseTimeS": { "type": [ "integer", "null" ], "format": "int32", "description": "Lease time in seconds (default 86400).", "minimum": 0 }, "mtu": { "type": [ "integer", "null" ], "format": "int32", "description": "Interface MTU handed out.", "minimum": 0 }, "prefixLen": { "type": "integer", "format": "int32", "description": "Prefix length of the subnet.", "minimum": 0 }, "rangeEnd": { "type": "string", "description": "Last address leases are allocated from (inclusive)." }, "rangeStart": { "type": "string", "description": "First address leases are allocated from." }, "serverId": { "type": [ "string", "null" ], "description": "DHCP server identifier." } } }, "HostBridgeNicTeamingPolicy": { "type": "object", "description": "NIC teaming overrides (`HostNicTeamingPolicy`) for facade round-trip and OVS bonds.\n\nWith ≥2 members in `active_nic` + `standby_nic`, [`HostBridgeNicTeamingPolicy::bond_spec`]\nmaps the policy to an OVS uplink bond the agent realises on the host-bridge\n(`docs/network/VSPHERE_MAPPING.md`). Fewer than two members stay facade-only (the\noperator plugs a single uplink). Beacon probing is stored but not realised.", "properties": { "active_nic": { "type": "array", "items": { "type": "string" }, "description": "`nicOrder.activeNic`." }, "check_beacon": { "type": [ "boolean", "null" ], "description": "`failureCriteria.checkBeacon`." }, "notify_switches": { "type": [ "boolean", "null" ], "description": "`notifySwitches`." }, "policy": { "type": [ "string", "null" ], "description": "`policy` (`loadbalance_srcid`, `failover_explicit`, …)." }, "reverse_policy": { "type": [ "boolean", "null" ], "description": "`reversePolicy`." }, "rolling_order": { "type": [ "boolean", "null" ], "description": "`rollingOrder` (true means no failback)." }, "standby_nic": { "type": "array", "items": { "type": "string" }, "description": "`nicOrder.standbyNic`." } }, "additionalProperties": false }, "HostBridgePortGroupPolicy": { "type": "object", "description": "Port-group `HostNetworkPolicy` overrides persisted on a host-bridge network.", "properties": { "nic_teaming": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeNicTeamingPolicy", "description": "NIC teaming overrides." }, { "type": "null" } ] }, "security": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeSecurityPolicy", "description": "Security overrides." }, { "type": "null" } ] }, "shaping": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeShapingPolicy", "description": "Traffic shaping overrides." }, { "type": "null" } ] } }, "additionalProperties": false }, "HostBridgeSecurityPolicy": { "type": "object", "description": "Layer-2 security overrides for a host-bridge port group (`HostNetworkSecurityPolicy`).\n\nPersisted for SOAP / Terraform round-trip (M1-NET-01). `macChanges` /\n`forgedTransmits` drive OpenFlow MAC enforcement on host-bridge VM taps via\n[`HostBridgeSecurityPolicy::mac_enforcement`] → [`BridgeAttach::port_security`].\n`allowPromiscuous=true` is refused (use a mirror session); OVS/OVN cannot dump the\nswitch onto a port without mirroring.", "properties": { "allow_promiscuous": { "type": [ "boolean", "null" ], "description": "`allowPromiscuous`." }, "forged_transmits": { "type": [ "boolean", "null" ], "description": "`forgedTransmits`." }, "mac_changes": { "type": [ "boolean", "null" ], "description": "`macChanges`." } }, "additionalProperties": false }, "HostBridgeShapingPolicy": { "type": "object", "description": "Traffic shaping overrides (`HostNetworkTrafficShapingPolicy`) for facade round-trip.\n\nBandwidth figures are bit/s and burst is bytes, matching vim25. When enabled, the host\nagent realises average/burst as OVS `Interface.ingress_policing_*` on VM taps\n([`HostBridgeShapingPolicy::ingress_policing`], from the VM into the switch) and as a\n`Port.qos` `linux-htb` queue ([`HostBridgeShapingPolicy::egress_htb`], to the VM). Peak\nsizes the burst bucket when `burst_size` is unset. Standard-switch\n`HostNetworkTrafficShapingPolicy` is one policy; both directions share those figures.", "properties": { "average_bandwidth": { "type": [ "integer", "null" ], "format": "int64", "description": "`averageBandwidth` (bit/s)." }, "burst_size": { "type": [ "integer", "null" ], "format": "int64", "description": "`burstSize` (bytes)." }, "enabled": { "type": [ "boolean", "null" ], "description": "`enabled`." }, "peak_bandwidth": { "type": [ "integer", "null" ], "format": "int64", "description": "`peakBandwidth` (bit/s)." } }, "additionalProperties": false }, "HostBridgeUplink": { "type": "object", "description": "Uplink of a host-bridge network.", "properties": { "interface": { "type": [ "string", "null" ], "description": "The host interface facing the provider's router (`eno1`); required in proxy mode." }, "mode": { "$ref": "#/components/schemas/UplinkMode", "description": "`bridged` (default) or `proxy`." } }, "additionalProperties": false }, "HostBusAdapter": { "type": "object", "description": "Physical HBA reported by the host agent (not software iSCSI).", "required": [ "device" ], "properties": { "bus": { "type": "integer", "format": "int32", "description": "Host / bus number." }, "device": { "type": "string", "description": "Device name (`vmhba0`)." }, "driver": { "type": [ "string", "null" ], "description": "Kernel driver." }, "kind": { "type": "string", "description": "`parallel-scsi` | `block` | `serial-attached`." }, "model": { "type": "string", "description": "Model / description." }, "pci": { "type": [ "string", "null" ], "description": "Parent PCI address when known." } }, "additionalProperties": false }, "HostConnectionState": { "type": "string", "description": "Host connection state as seen by the control plane.", "enum": [ "connected", "disconnected", "not_responding" ] }, "HostCountView": { "type": "object", "description": "Counters of one rule on one host.", "required": [ "packets", "bytes" ], "properties": { "bytes": { "type": "integer", "format": "int64", "description": "Bytes.", "minimum": 0 }, "lastHit": { "type": [ "string", "null" ], "description": "Last report with a non-zero count." }, "packets": { "type": "integer", "format": "int64", "description": "Packets.", "minimum": 0 } } }, "HostHardware": { "type": "object", "description": "Hardware summary reported by the host agent.", "properties": { "cpu_mhz": { "type": "integer", "format": "int32", "description": "Nominal CPU frequency.", "minimum": 0 }, "cpu_model": { "type": "string", "description": "CPU model string." }, "cpu_sockets": { "type": "integer", "format": "int32", "description": "Physical sockets.", "minimum": 0 }, "cpu_threads": { "type": "integer", "format": "int32", "description": "Logical CPUs (threads).", "minimum": 0 }, "host_bus_adapters": { "type": "array", "items": { "$ref": "#/components/schemas/HostBusAdapter" }, "description": "Physical SCSI / block HBAs (`HostStorageDeviceInfo.hostBusAdapter`).\nSoftware iSCSI (`vmhba64`) is projected separately from\n[`Host::software_internet_scsi_enabled`]." }, "local_disks": { "type": "array", "items": { "$ref": "#/components/schemas/HostLocalDisk" }, "description": "Local disks (`HostStorageDeviceInfo.scsiLun`); software iSCSI disks are not here." }, "memory_bytes": { "type": "integer", "format": "int64", "description": "Installed memory.", "minimum": 0 }, "model": { "type": "string", "description": "Model string." }, "pci_devices": { "type": "array", "items": { "$ref": "#/components/schemas/HostPciDevice" }, "description": "Physical PCI functions (`HostHardwareInfo.pciDevice`)." }, "vendor": { "type": "string", "description": "Vendor string." } }, "additionalProperties": false }, "HostIscsiChapAuth": { "type": "object", "description": "CHAP credentials for software iSCSI (adapter-level or per send target).\n\nUni-directional fields map to `chapName`/`chapSecret`; mutual fields map to\n`mutualChapName`/`mutualChapSecret` (`node.session.auth.username_in` /\n`password_in` via open-iscsi). Secrets are persisted for RescanHba and\nstripped from REST host views.", "properties": { "enabled": { "type": "boolean", "description": "`chapAuthEnabled` on the HBA / target." }, "mutual_enabled": { "type": "boolean", "description": "Mutual CHAP enabled (`mutualChapAuthenticationType` ≠ `chapProhibited`)." }, "mutual_secret": { "type": "string", "description": "Mutual CHAP secret (`mutualChapSecret` / `password_in`)." }, "mutual_username": { "type": "string", "description": "Mutual CHAP user name (`mutualChapName` / `username_in`)." }, "secret": { "type": "string", "description": "CHAP secret (`chapSecret`)." }, "username": { "type": "string", "description": "CHAP user name (`chapName`)." } }, "additionalProperties": false }, "HostIscsiDiscoveredTarget": { "type": "object", "description": "An iSCSI static target IQN (`HostInternetScsiHbaStaticTarget`).\n\nUsed for both manually configured targets (`AddInternetScsiStaticTargets`)\nand discovery results after `RescanHba`.", "required": [ "address", "iqn" ], "properties": { "address": { "type": "string", "description": "Portal address." }, "chap": { "oneOf": [ { "$ref": "#/components/schemas/HostIscsiChapAuth", "description": "Per-static-target CHAP override (`UpdateInternetScsiAuthenticationProperties`\nwith `targetSet.staticTargets`). Secrets are persisted for RescanHba and\nstripped from REST host views." }, { "type": "null" } ] }, "iqn": { "type": "string", "description": "Target IQN." }, "port": { "type": [ "integer", "null" ], "format": "int32", "description": "Portal TCP port." } }, "additionalProperties": false }, "HostIscsiScsiDisk": { "type": "object", "description": "A SCSI disk reached via software iSCSI after rescan.", "required": [ "wwid", "canonical_name", "device_path", "target", "portal" ], "properties": { "canonical_name": { "type": "string", "description": "Canonical name projected to vim (`naa.`)." }, "capacity_bytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "device_path": { "type": "string", "description": "Host device path (`/dev/mapper/…` when multipath has a map, else by-id)." }, "lun": { "type": "integer", "format": "int32", "description": "LUN number.", "minimum": 0 }, "portal": { "type": "string", "description": "Portal used for login (`host` or `host:port`)." }, "target": { "type": "string", "description": "Target IQN the LUN was discovered on." }, "wwid": { "type": "string", "description": "Multipath / by-id WWID (hex without `0x`)." } }, "additionalProperties": false }, "HostIscsiSendTarget": { "type": "object", "description": "An iSCSI discovery / send target on a host (`HostInternetScsiHbaSendTarget`).", "required": [ "address" ], "properties": { "address": { "type": "string", "description": "Portal address (hostname or IP)." }, "chap": { "oneOf": [ { "$ref": "#/components/schemas/HostIscsiChapAuth", "description": "Per-target CHAP override (`UpdateInternetScsiAuthenticationProperties` + `targetSet`)." }, { "type": "null" } ] }, "port": { "type": [ "integer", "null" ], "format": "int32", "description": "Portal TCP port; omit for the iSCSI default (3260)." } }, "additionalProperties": false }, "HostLocalDisk": { "type": "object", "description": "Local block disk reported by the host agent (`/sys/block`).", "required": [ "name" ], "properties": { "capacity_bytes": { "type": "integer", "format": "int64", "description": "Size in bytes.", "minimum": 0 }, "model": { "type": "string", "description": "Model." }, "name": { "type": "string", "description": "Kernel name (`sda`, `nvme0n1`)." }, "scsi_address": { "type": [ "string", "null" ], "description": "SCSI address `H:C:T:L` (adapter `vmhbaH`); none for NVMe / virtio disks." }, "ssd": { "type": "boolean", "description": "Non-rotational." }, "vendor": { "type": "string", "description": "Vendor." }, "wwid": { "type": "string", "description": "World-wide id (`naa.…`), empty when the device has none." } }, "additionalProperties": false }, "HostPciDevice": { "type": "object", "description": "One PCI function reported by the host agent.", "required": [ "id" ], "properties": { "bus": { "type": "integer", "format": "int32", "description": "PCI bus number.", "minimum": 0 }, "class_id": { "type": "integer", "format": "int32", "description": "Base class + subclass.", "minimum": 0 }, "device_class_name": { "type": [ "string", "null" ], "description": "Short class label when known." }, "device_id": { "type": "integer", "format": "int32", "description": "Device id.", "minimum": 0 }, "device_name": { "type": "string", "description": "Device display name." }, "function": { "type": "integer", "format": "int32", "description": "Function number.", "minimum": 0 }, "id": { "type": "string", "description": "Domain:bus:slot.function (`0000:00:1f.2`)." }, "slot": { "type": "integer", "format": "int32", "description": "Device / slot number.", "minimum": 0 }, "sub_device_id": { "type": "integer", "format": "int32", "description": "Subsystem device id.", "minimum": 0 }, "sub_vendor_id": { "type": "integer", "format": "int32", "description": "Subsystem vendor id.", "minimum": 0 }, "vendor_id": { "type": "integer", "format": "int32", "description": "Vendor id.", "minimum": 0 }, "vendor_name": { "type": "string", "description": "Vendor display name." } }, "additionalProperties": false }, "HostPowerRequest": { "type": "object", "description": "Body of `POST /v1/hosts/{id}/reboot` and `POST /v1/hosts/{id}/shutdown`.", "properties": { "force": { "type": "boolean", "description": "Reboot or shut down although the host is not in maintenance mode (default false).\nVirtual machines that still run on the host stop with it." } }, "additionalProperties": false }, "HostRealizationView": { "type": "object", "description": "Realization of the firewall on one host.", "required": [ "host", "realized", "flows", "firewalled", "preconditions" ], "properties": { "agentVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Version the agent holds.", "minimum": 0 }, "appliedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Version every bridge confirmed.", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Why not." }, "firewalled": { "type": "integer", "format": "int32", "description": "Firewalled vNICs.", "minimum": 0 }, "flows": { "type": "integer", "format": "int64", "description": "Firewall flows.", "minimum": 0 }, "host": { "type": "string", "description": "Host id." }, "preconditions": { "type": "array", "items": { "type": "string" }, "description": "Host preconditions that do not hold (owner actions, e.g. `ct-zone-range`)." }, "realized": { "type": "boolean", "description": "The host applied the plan last sent." }, "reportedAt": { "type": [ "string", "null" ], "description": "Time of the last report." }, "wantedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Plan version last sent.", "minimum": 0 } } }, "HostRuntime": { "type": "object", "description": "Runtime state reported by the host agent.", "properties": { "admin_disconnected": { "type": "boolean", "description": "Operator disconnected the host (`DisconnectHost_Task`); heartbeats and\nagent re-registration keep it disconnected until `ReconnectHost_Task`." }, "applied_generation": { "type": "integer", "format": "int64", "description": "Host-level desired-state generation the agent last applied (from its heartbeat or\nstate report); compared with the generation the control plane last sent.", "minimum": 0 }, "boot_time": { "type": [ "string", "null" ], "description": "Time of the host's last boot." }, "connection": { "$ref": "#/components/schemas/HostConnectionState", "description": "Connection state." }, "cpu_usage_mhz": { "type": "integer", "format": "int32", "description": "CPU in use.", "minimum": 0 }, "heartbeat_sequence": { "type": "integer", "format": "int64", "description": "Sequence number of the last accepted heartbeat (increases per agent run).", "minimum": 0 }, "last_heartbeat": { "type": [ "string", "null" ], "description": "Time of the last accepted heartbeat." }, "maintenance_mode": { "type": "boolean", "description": "Whether the host is in maintenance mode." }, "memory_usage_bytes": { "type": "integer", "format": "int64", "description": "Memory in use.", "minimum": 0 } }, "additionalProperties": false }, "HostUplinksRequest": { "type": "object", "description": "The physical NICs of one member host (`hostUplinks[]`).", "required": [ "host" ], "properties": { "host": { "type": "string", "description": "Member host id." }, "nics": { "type": "object", "description": "Uplink name to the host's physical NIC (`{\"uplink1\": \"eno2\"}`).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "ImportVAppRequest": { "type": "object", "description": "Import a VM from an OVF plan (`POST /v1/resource-pools/{id}/import-vapp`).\n\nSame body as [`CreateOvfImportSpecRequest`] plus optional folder / host placement.", "required": [ "ovfDescriptor", "datastoreId" ], "properties": { "datastoreId": { "type": "string", "description": "Target datastore (`datastore-N`)." }, "deploymentOption": { "type": [ "string", "null" ], "description": "Optional deployment configuration id." }, "entityName": { "type": [ "string", "null" ], "description": "Override entity name; defaults to the package VirtualSystem name." }, "folderId": { "type": [ "string", "null" ], "description": "Destination VM folder (`group-vN`); defaults to the datacenter VM folder." }, "hostId": { "type": [ "string", "null" ], "description": "Destination host (`host-N`)." }, "networkMapping": { "type": "array", "items": { "$ref": "#/components/schemas/OvfNetworkMappingRequest" }, "description": "OVF network name → inventory network mappings." }, "ovfDescriptor": { "type": "string", "description": "OVF envelope XML." } } }, "InstallLicenceRequest": { "type": "object", "description": "Body of `POST /v1/licence/install`.", "required": [ "payload", "signature" ], "properties": { "payload": { "type": "string", "description": "Licence payload JSON (the signed document)." }, "signature": { "type": "string", "description": "Detached minisign signature file text." } } }, "InstalledLicenceView": { "type": "object", "description": "Summary of one installed licence (no signature bytes).", "required": [ "licenceId", "licensee", "installedAt", "valid" ], "properties": { "installedAt": { "type": "string", "description": "When it was installed on this controller (RFC 3339)." }, "licenceId": { "type": "string", "description": "Licence id." }, "licensee": { "type": "string", "description": "Licensee." }, "valid": { "type": "boolean", "description": "Whether it is currently inside its validity window." } } }, "IntervalView": { "type": "object", "description": "A sampling interval.", "required": [ "key", "samplingPeriod", "length", "name" ], "properties": { "key": { "type": "integer", "format": "int32", "description": "`PerfInterval.key` (0 = realtime)." }, "length": { "type": "integer", "format": "int32", "description": "Seconds of history kept.", "minimum": 0 }, "level": { "type": [ "integer", "null" ], "format": "int32", "description": "Collection level (historical intervals).", "minimum": 0 }, "name": { "type": "string", "description": "Name." }, "samplingPeriod": { "type": "integer", "format": "int32", "description": "Seconds between samples; the `interval` of a query.", "minimum": 0 } } }, "InvalidateRequestView": { "type": "object", "description": "OpenAPI stand-in for InvalidateRequest.", "required": [ "vmId", "reason" ], "properties": { "reason": { "$ref": "#/components/schemas/InvalidationReasonView", "description": "Why change tracking restarts for the disk." }, "vmId": { "type": "string", "format": "uuid", "description": "VM instance UUID." } } }, "InvalidationReasonView": { "type": "string", "description": "OpenAPI stand-in for `InvalidationReason` (model lives in kyvernon-backup).", "enum": [ "TRACKING_RESET", "DISK_RESIZED", "SNAPSHOT_REVERT", "BITMAP_LOST", "RESTORED" ] }, "InventoryNode": { "type": "object", "description": "A node of the inventory tree (lazy loading).", "required": [ "id", "type", "name", "hasChildren", "status" ], "properties": { "hasChildren": { "type": "boolean", "description": "Whether the node has children." }, "id": { "type": "string", "description": "Object id." }, "name": { "type": "string", "description": "Display name." }, "parentId": { "type": [ "string", "null" ], "description": "Parent id." }, "status": { "type": "string", "description": "Health (`ok`, `warning`, `danger`, `unknown`)." }, "type": { "type": "string", "description": "Short type (`datacenter`, `folder`, `cluster`, `host`, `vm`, `datastore`, `network`, ...)." } } }, "IpPoolAvailableView": { "type": "object", "description": "The addresses of a pool that can be allocated now.", "required": [ "pool", "poolName", "freeIpv4", "freeIpv6Blocks", "addresses", "truncated" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "The first free IPv4 addresses, ascending, at most `limit`. The first one is what an\nallocation without an address takes. Gateway, reserved, network and broadcast\naddresses, allocated ones and those in quarantine are never listed. Another caller can\ntake a listed address first: allocating it then fails with\n`error.ip_pool.address_in_use` (409)." }, "freeIpv4": { "type": "integer", "format": "int64", "description": "Free IPv4 addresses in total (not limited).", "minimum": 0 }, "freeIpv6Blocks": { "type": "integer", "format": "int64", "description": "Free IPv6 blocks in total (0 without IPv6).", "minimum": 0 }, "ipv6BlockLen": { "type": [ "integer", "null" ], "format": "int32", "description": "Length of the pool's IPv6 blocks (absent without IPv6).", "minimum": 0 }, "pool": { "type": "string", "description": "Pool id." }, "poolName": { "type": "string", "description": "Pool name." }, "truncated": { "type": "boolean", "description": "True when more addresses are free than listed." } } }, "IpPoolRequest": { "type": "object", "description": "Create or replace a pool.", "required": [ "name", "network", "prefixLen" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "Single IPv4 addresses (a provider's on-link addresses), besides or instead of\nranges." }, "dnsServers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers; empty: the network's." }, "expectedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Required on update: the version read.", "minimum": 0 }, "gateway": { "type": [ "string", "null" ], "description": "Gateway." }, "ipv6": { "oneOf": [ { "$ref": "#/components/schemas/PoolIpv6View", "description": "IPv6 prefix." }, { "type": "null" } ] }, "name": { "type": "string", "description": "Name, unique." }, "network": { "type": "string", "description": "The host-bridge network id (`network-N`)." }, "prefixLen": { "type": "integer", "format": "int32", "description": "Prefix length of the IPv4 subnet.", "minimum": 0 }, "quarantineS": { "type": [ "integer", "null" ], "format": "int64", "description": "Quarantine of released addresses in seconds (default 14 days).", "minimum": 0 }, "ranges": { "type": "array", "items": { "$ref": "#/components/schemas/RangeView" }, "description": "IPv4 ranges." }, "rdns": { "oneOf": [ { "$ref": "#/components/schemas/RdnsMode", "description": "Reverse DNS: `provider` (default, the configured provider) or `manual` (requests an\noperator applies, e.g. Leaseweb addresses)." }, { "type": "null" } ] }, "reserved": { "type": "array", "items": { "type": "string" }, "description": "Addresses never handed out." }, "smtpIpv4": { "oneOf": [ { "$ref": "#/components/schemas/SmtpPolicy", "description": "Outgoing SMTP over IPv4: `allowed` (default) or `blocked`." }, { "type": "null" } ] }, "smtpIpv6": { "oneOf": [ { "$ref": "#/components/schemas/SmtpPolicy", "description": "Outgoing SMTP over IPv6: `blocked` (default) or `allowed`." }, { "type": "null" } ] } }, "additionalProperties": false }, "IpPoolView": { "type": "object", "description": "A pool.", "required": [ "id", "version", "name", "network", "prefixLen", "ranges", "addresses", "dnsServers", "reserved", "quarantineS", "smtpIpv4", "smtpIpv6", "rdns", "usage" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "Single addresses." }, "dnsServers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers." }, "gateway": { "type": [ "string", "null" ], "description": "Gateway." }, "id": { "type": "string", "description": "Id (`ippool-N`)." }, "ipv6": { "oneOf": [ { "$ref": "#/components/schemas/PoolIpv6View", "description": "IPv6." }, { "type": "null" } ] }, "name": { "type": "string", "description": "Name." }, "network": { "type": "string", "description": "Network id." }, "prefixLen": { "type": "integer", "format": "int32", "description": "Prefix length.", "minimum": 0 }, "quarantineS": { "type": "integer", "format": "int64", "description": "Quarantine in seconds.", "minimum": 0 }, "ranges": { "type": "array", "items": { "$ref": "#/components/schemas/RangeView" }, "description": "Ranges." }, "rdns": { "$ref": "#/components/schemas/RdnsMode", "description": "Reverse DNS mode in effect for the pool: `provider` or `manual`." }, "reserved": { "type": "array", "items": { "type": "string" }, "description": "Reserved addresses." }, "smtpIpv4": { "$ref": "#/components/schemas/SmtpPolicy", "description": "Outgoing SMTP over IPv4." }, "smtpIpv6": { "$ref": "#/components/schemas/SmtpPolicy", "description": "Outgoing SMTP over IPv6." }, "uplink": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeUplink", "description": "Uplink of the pool's network (`bridged` or `proxy` with its interface)." }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/PoolUsage", "description": "Counts." }, "version": { "type": "integer", "format": "int64", "description": "Record version (for `expectedVersion`).", "minimum": 0 } } }, "IpVersionView": { "type": "string", "description": "IP families of a rule.", "enum": [ "any", "v4", "v6" ] }, "IscsiAuthenticationRequest": { "type": "object", "description": "Body for `PUT /v1/hosts/{id}/iscsi/authentication`.", "required": [ "chapAuthEnabled" ], "properties": { "chapAuthEnabled": { "type": "boolean", "description": "`chapAuthEnabled`." }, "chapName": { "type": [ "string", "null" ], "description": "`chapName`." }, "chapSecret": { "type": [ "string", "null" ], "description": "`chapSecret` (omit to reuse existing secret for the same name)." }, "mutualChapAuthenticationType": { "type": [ "string", "null" ], "description": "Mutual CHAP type; omit / empty / `chapProhibited` disables mutual." }, "mutualChapName": { "type": [ "string", "null" ], "description": "`mutualChapName`." }, "mutualChapSecret": { "type": [ "string", "null" ], "description": "`mutualChapSecret`." }, "targetSet": { "oneOf": [ { "$ref": "#/components/schemas/IscsiTargetSetBody", "description": "When set, apply CHAP to these targets instead of the adapter." }, { "type": "null" } ] } }, "additionalProperties": false }, "IscsiConfigView": { "type": "object", "description": "The software iSCSI configuration of a host.", "required": [ "hostId", "enabled", "hbaDevice", "chapEnabled", "mutualChapEnabled", "sendTargets", "staticTargets", "discoveredTargets", "luns" ], "properties": { "chapEnabled": { "type": "boolean", "description": "CHAP on the adapter." }, "chapName": { "type": [ "string", "null" ], "description": "CHAP user name on the adapter (the secret is never returned)." }, "discoveredTargets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiTargetView" }, "description": "Targets found by the last rescan." }, "enabled": { "type": "boolean", "description": "Software iSCSI initiator enabled." }, "hbaDevice": { "type": "string", "description": "Adapter name for the rescan (`vmhba64`)." }, "hostId": { "type": "string", "description": "Host id." }, "luns": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiLunView" }, "description": "LUNs found by the last rescan." }, "mutualChapEnabled": { "type": "boolean", "description": "Mutual CHAP on the adapter." }, "sendTargets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiPortalView" }, "description": "Discovery (send target) portals." }, "staticTargets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiTargetView" }, "description": "Static targets entered by an administrator." } } }, "IscsiLunView": { "type": "object", "description": "A LUN the host sees through software iSCSI.", "required": [ "wwid", "canonicalName", "devicePath", "capacityBytes", "target", "portal", "lun" ], "properties": { "canonicalName": { "type": "string", "description": "Canonical name (`naa.`), what `POST /v1/hosts/{id}/datastores` takes as `disk`." }, "capacityBytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "devicePath": { "type": "string", "description": "Device path on the host." }, "lun": { "type": "integer", "format": "int32", "description": "LUN number.", "minimum": 0 }, "portal": { "type": "string", "description": "Portal." }, "target": { "type": "string", "description": "Target IQN." }, "wwid": { "type": "string", "description": "WWID." } } }, "IscsiPortalView": { "type": "object", "description": "An iSCSI portal.", "required": [ "address", "port" ], "properties": { "address": { "type": "string", "description": "Address (host name or IP address)." }, "chapEnabled": { "type": [ "boolean", "null" ], "description": "A CHAP setting of its own (secrets are never returned)." }, "port": { "type": "integer", "format": "int32", "description": "TCP port (3260 when not set).", "minimum": 0 } } }, "IscsiRescanRequest": { "type": "object", "description": "Body for `POST /v1/hosts/{id}/iscsi/rescan`.", "properties": { "hbaDevice": { "type": [ "string", "null" ], "description": "HBA device (`vmhba64`); defaults to the software iSCSI HBA." } }, "additionalProperties": false }, "IscsiSendTargetBody": { "type": "object", "description": "One send-target portal in a request body.", "required": [ "address" ], "properties": { "address": { "type": "string", "description": "Portal address (hostname or IP)." }, "port": { "type": [ "integer", "null" ], "format": "int32", "description": "Portal TCP port; omit for 3260." } }, "additionalProperties": false }, "IscsiSendTargetsRequest": { "type": "object", "description": "Body for add/remove send-target routes.", "required": [ "targets" ], "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiSendTargetBody" }, "description": "Send targets to add or remove." } }, "additionalProperties": false }, "IscsiStaticTargetBody": { "type": "object", "description": "One static-target portal + IQN in a request body.", "required": [ "address", "iqn" ], "properties": { "address": { "type": "string", "description": "Portal address." }, "iqn": { "type": "string", "description": "Target IQN." }, "port": { "type": [ "integer", "null" ], "format": "int32", "description": "Portal TCP port; omit for 3260." } }, "additionalProperties": false }, "IscsiStaticTargetsRequest": { "type": "object", "description": "Body for add/remove static-target routes.", "required": [ "targets" ], "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiStaticTargetBody" }, "description": "Static targets to add or remove." } }, "additionalProperties": false }, "IscsiTargetSetBody": { "type": "object", "description": "Optional target set for per-target CHAP.", "properties": { "sendTargets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiSendTargetBody" }, "description": "Send targets to update." }, "staticTargets": { "type": "array", "items": { "$ref": "#/components/schemas/IscsiStaticTargetBody" }, "description": "Static targets to update." } }, "additionalProperties": false }, "IscsiTargetView": { "type": "object", "description": "An iSCSI target.", "required": [ "address", "port", "iqn" ], "properties": { "address": { "type": "string", "description": "Portal address." }, "chapEnabled": { "type": [ "boolean", "null" ], "description": "A CHAP setting of its own (secrets are never returned)." }, "iqn": { "type": "string", "description": "Target IQN." }, "port": { "type": "integer", "format": "int32", "description": "TCP port.", "minimum": 0 } } }, "IssueView": { "type": "object", "description": "One validation finding.", "required": [ "severity", "key", "object", "message" ], "properties": { "key": { "type": "string", "description": "Message key (`net.validation.fw_*`, `net.note.*`)." }, "message": { "type": "string", "description": "English detail." }, "object": { "type": "string", "description": "Object path (`policies/fwpolicy-3/rules/12`)." }, "severity": { "type": "string", "description": "`error` or `note`." } } }, "JoinTokenView": { "type": "object", "description": "What a host agent needs to join (`GET /v1/hosts/join-token`).", "required": [ "token", "endpoint", "serverName", "bootstrapCertificatePath" ], "properties": { "bootstrapCertificatePath": { "type": "string", "description": "Where the bootstrap certificate is on the controller." }, "endpoint": { "type": "string", "description": "gRPC endpoint hosts dial (`https://controller:8444`)." }, "serverName": { "type": "string", "description": "Name in the controller certificate the host validates." }, "token": { "type": "string", "description": "The join token every new host presents (the content of the controller's join token\nfile; put it in `/etc/kyvernon/join-token` on the host)." } } }, "LibraryItemView": { "type": "object", "description": "Library item (`GET/POST /v1/content/library-items`).", "required": [ "id", "libraryId", "name", "description", "type", "filePath", "datastoreId", "size", "cached", "creationTime", "lastModifiedTime", "contentVersion", "metadataVersion", "version" ], "properties": { "cached": { "type": "boolean", "description": "Cached locally." }, "contentVersion": { "type": "string", "description": "Content version." }, "creationTime": { "type": "string", "description": "Creation time." }, "datastoreId": { "type": "string", "description": "Datastore id." }, "description": { "type": "string", "description": "Description." }, "filePath": { "type": "string", "description": "Datastore-relative path of the registered file." }, "id": { "type": "string", "description": "Item id (UUID)." }, "lastModifiedTime": { "type": "string", "description": "Last modification time." }, "libraryId": { "type": "string", "description": "Owning library id." }, "metadataVersion": { "type": "string", "description": "Metadata version." }, "name": { "type": "string", "description": "Display name." }, "size": { "type": "integer", "format": "int64", "description": "Size in bytes (0 when unknown)." }, "type": { "type": "string", "description": "`iso`, `ovf`, or `vm-template`." }, "version": { "type": "string", "description": "Item version." } } }, "LibraryView": { "type": "object", "description": "Local content library (`GET/POST /v1/content/libraries`).", "required": [ "id", "name", "description", "datastoreId", "creationTime", "lastModifiedTime", "version", "type" ], "properties": { "creationTime": { "type": "string", "description": "Creation time (RFC3339 / vim wire)." }, "datastoreId": { "type": "string", "description": "Datastore backing (`datastore-N`)." }, "description": { "type": "string", "description": "Description." }, "id": { "type": "string", "description": "Library id (UUID)." }, "lastModifiedTime": { "type": "string", "description": "Last modification time." }, "name": { "type": "string", "description": "Display name." }, "type": { "type": "string", "description": "Always `LOCAL` in this thin slice." }, "version": { "type": "string", "description": "Opaque version." } } }, "LicenceStatus": { "type": "object", "description": "Effective entitlements plus live counters for `/v1/licence`.", "required": [ "entitlements", "runningVms", "hosts" ], "properties": { "entitlements": { "$ref": "#/components/schemas/EntitlementsView", "description": "Effective entitlements." }, "hosts": { "type": "integer", "format": "int32", "description": "Enrolled hosts that count toward the limit.", "minimum": 0 }, "installed": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledLicenceView" }, "description": "Installed licence summaries (ids and licensee only)." }, "runningVms": { "type": "integer", "format": "int32", "description": "Running virtual machines that count toward the limit.", "minimum": 0 } } }, "LifecycleState": { "type": "string", "description": "OpenAPI schema of the agent lifecycle state ([`kyvernon_vm_model::PowerState`]), whose\ncrate has no schema support; `lifecycle_schema_matches_the_model` keeps the two equal.", "enum": [ "stopped", "starting", "running", "paused", "stopping", "migrating", "incoming", "crashed" ] }, "LldpHintView": { "type": "object", "description": "LLDP neighbour fields (`LinkLayerDiscoveryProtocolInfo`).", "required": [ "chassisId", "portId", "timeToLive" ], "properties": { "chassisId": { "type": "string", "description": "Chassis ID." }, "mgmtAddr": { "type": [ "string", "null" ], "description": "Optional management address." }, "portDescription": { "type": [ "string", "null" ], "description": "Optional port description." }, "portId": { "type": "string", "description": "Port ID." }, "systemDescription": { "type": [ "string", "null" ], "description": "Optional system description." }, "systemName": { "type": [ "string", "null" ], "description": "Optional system name." }, "timeToLive": { "type": "integer", "format": "int32", "description": "TTL seconds." } } }, "LockoutPolicyRequest": { "type": "object", "description": "Body of `PUT /v1/identity/lockout-policy`. Applies to the next failed login.", "required": [ "maxFailedAttempts", "failedAttemptIntervalSeconds", "autoUnlockIntervalSeconds" ], "properties": { "autoUnlockIntervalSeconds": { "type": "integer", "format": "int64", "description": "1 to 604800 seconds (seven days); 0 (the lockout lifted by an administrator only) is refused.", "minimum": 0 }, "description": { "type": [ "string", "null" ], "description": "Text for administrators (kept when absent)." }, "failedAttemptIntervalSeconds": { "type": "integer", "format": "int64", "description": "1 to 604800 seconds (seven days).", "minimum": 0 }, "maxFailedAttempts": { "type": "integer", "format": "int32", "description": "1 to 1000.", "minimum": 0 } } }, "LockoutPolicyView": { "type": "object", "description": "The account lockout policy.", "required": [ "description", "maxFailedAttempts", "failedAttemptIntervalSeconds", "autoUnlockIntervalSeconds" ], "properties": { "autoUnlockIntervalSeconds": { "type": "integer", "format": "int64", "description": "How long a locked account stays locked, in seconds (an administrator can lift the\nlockout earlier).", "minimum": 0 }, "description": { "type": "string", "description": "Text for administrators." }, "failedAttemptIntervalSeconds": { "type": "integer", "format": "int64", "description": "The window in which failed logins are counted, in seconds.", "minimum": 0 }, "maxFailedAttempts": { "type": "integer", "format": "int32", "description": "Failed logins within `failedAttemptIntervalSeconds` that lock the account.", "minimum": 0 } } }, "LogRecordView": { "type": "object", "description": "One firewall log record.", "required": [ "host", "at", "vm", "nic", "direction", "rule", "verdict", "monitor", "proto", "src", "dst" ], "properties": { "at": { "type": "string", "description": "Time (RFC 3339)." }, "direction": { "type": "string", "description": "`in` or `out`." }, "dport": { "type": [ "integer", "null" ], "format": "int32", "description": "Destination port.", "minimum": 0 }, "dst": { "type": "string", "description": "Destination." }, "host": { "type": "string", "description": "Host." }, "monitor": { "type": "boolean", "description": "The vNIC was in mode `monitor` (the packet was forwarded)." }, "nic": { "type": "string", "description": "NIC id." }, "proto": { "type": "integer", "format": "int32", "description": "IP protocol.", "minimum": 0 }, "rule": { "type": "integer", "format": "int32", "description": "Rule number (0: default or state).", "minimum": 0 }, "sport": { "type": [ "integer", "null" ], "format": "int32", "description": "Source port.", "minimum": 0 }, "src": { "type": "string", "description": "Source." }, "verdict": { "type": "string", "description": "`allow`, `drop` or `reject`." }, "vm": { "type": "string", "description": "VM id." } } }, "LogUserEventRequest": { "type": "object", "description": "Append a user event on an inventory entity (`LogUserEvent`).", "required": [ "entityId", "message" ], "properties": { "entityId": { "type": "string", "description": "Target inventory object id." }, "message": { "type": "string", "description": "Free-form message text shown to operators." } } }, "LoginRequest": { "type": "object", "description": "Login request.", "required": [ "username", "password" ], "properties": { "kind": { "type": [ "string", "null" ], "description": "`interactive` (default) or `api`." }, "password": { "type": "string", "description": "Password." }, "username": { "type": "string", "description": "Username." } } }, "LoginResponse": { "type": "object", "description": "Login response: either a session or an MFA challenge.", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "description": "`session`, `mfa_required` or `mfa_enrolment_required`." }, "pendingToken": { "type": [ "string", "null" ], "description": "Pending token to pass to `/identity/mfa/complete` (for `mfa_required`)." }, "session": { "oneOf": [ { "$ref": "#/components/schemas/SessionView", "description": "Session (for `session` and `mfa_enrolment_required`)." }, { "type": "null" } ] } } }, "MaintenanceModeResultView": { "type": "object", "description": "`TaskView.result` of enter/exit maintenance mode.", "required": [ "maintenanceMode" ], "properties": { "maintenanceMode": { "type": "boolean", "description": "Whether the host is in maintenance mode after the task." } } }, "MakeFolderRequest": { "type": "object", "description": "Create-folder request.", "required": [ "path" ], "properties": { "createParents": { "type": "boolean", "description": "Create missing parent folders too." }, "path": { "type": "string", "description": "Path of the new folder below the datastore root." } } }, "MarkAsVmRequest": { "type": "object", "description": "Convert a template back to a VM (`POST /v1/vms/{id}/mark-as-vm`).", "properties": { "host": { "type": [ "string", "null" ], "description": "Host (`host-N`). Defaults to the template's current host." }, "resourcePool": { "type": [ "string", "null" ], "description": "Resource pool (`resgroup-N`). Defaults to the template's current pool." } } }, "MetricsQueryRequest": { "type": "object", "description": "A metrics query.", "required": [ "entities", "counters" ], "properties": { "counters": { "type": "array", "items": { "type": "string" }, "description": "Counter names (`cpu.usage.average`) or ids (`\"2\"`)." }, "end": { "type": [ "string", "null" ], "description": "Inclusive end (RFC 3339); default now." }, "entities": { "type": "array", "items": { "type": "string" }, "description": "Entity ids (`vm-42`, `host-1`, `datastore-3`)." }, "instance": { "type": [ "string", "null" ], "description": "`\"\"` the aggregate (default), `\"*\"` every instance and the aggregate, or one instance." }, "interval": { "type": [ "integer", "null" ], "format": "int32", "description": "Sampling period (20, 300, 1800, 7200, 86400); default 20 for hosts and VMs, 300\nfor datastores.", "minimum": 0 }, "maxSamples": { "type": [ "integer", "null" ], "format": "int32", "description": "Newest N samples per series.", "minimum": 0 }, "start": { "type": [ "string", "null" ], "description": "Exclusive start (RFC 3339); default as far back as the interval keeps." } } }, "MetricsQueryResponse": { "type": "object", "description": "Query answer.", "required": [ "series" ], "properties": { "series": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesView" }, "description": "Series with at least one point." } } }, "MfaCodeRequest": { "type": "object", "description": "TOTP code.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Six-digit code." } } }, "MfaEnrolResponse": { "type": "object", "description": "TOTP enrolment response.", "required": [ "secret", "otpauthUrl" ], "properties": { "otpauthUrl": { "type": "string", "description": "`otpauth://` URL for QR codes." }, "secret": { "type": "string", "description": "Base32 seed; shown once." } } }, "MigrateResultView": { "type": "object", "description": "`TaskView.result` of migrate / RelocateVM.", "required": [ "live" ], "properties": { "datastore": { "type": [ "string", "null" ], "description": "Destination datastore id after a cold storage relocate, when any." }, "host": { "type": [ "string", "null" ], "description": "Placement host id after the move, when any." }, "live": { "type": "boolean", "description": "Whether a live migration ran." }, "relocatedDisks": { "type": "array", "items": { "$ref": "#/components/schemas/RelocatedDiskView" }, "description": "Disks copied onto the new datastore." }, "relocatedNics": { "type": "array", "items": { "$ref": "#/components/schemas/RelocatedNicView" }, "description": "NICs whose network backing was rebound." }, "report": { "type": [ "object", "null" ], "description": "Live-migration agent report when present; otherwise null." } } }, "ModeBody": { "type": "object", "description": "Body of `POST /v1/vms/{id}/firewall/mode`.", "required": [ "mode" ], "properties": { "confirmWithin": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds until the previous mode comes back unless confirmed (30 to 86,400;\nabsent: no timer).", "minimum": 0 }, "mode": { "$ref": "#/components/schemas/ModeView", "description": "The new mode." }, "nics": { "type": "array", "items": { "type": "string" }, "description": "NIC keys (default: every host-bridge NIC of the VM)." }, "reason": { "type": [ "string", "null" ], "description": "Why (kept in the event)." } }, "additionalProperties": false }, "ModeView": { "type": "string", "description": "Firewall mode of a vNIC.", "enum": [ "off", "monitor", "enforce" ] }, "MonitorEntryView": { "type": "object", "description": "One port seen in the monitor tables.", "required": [ "nic", "direction", "proto", "port", "count", "firstSeen", "lastSeen", "sources" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "Packets that would have been dropped.", "minimum": 0 }, "direction": { "type": "string", "description": "`in` or `out`." }, "firstSeen": { "type": "string", "description": "First seen." }, "lastSeen": { "type": "string", "description": "Last seen." }, "nic": { "type": "string", "description": "NIC id." }, "port": { "type": "integer", "format": "int32", "description": "Destination port (0: none).", "minimum": 0 }, "proto": { "type": "integer", "format": "int32", "description": "IP protocol number.", "minimum": 0 }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Up to 16 sample sources." } } }, "MonitorReportView": { "type": "object", "description": "The monitor report of a VM.", "required": [ "vm", "since", "nics", "entries", "wouldDrop", "proposal" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorEntryView" }, "description": "Would-drops, most packets first." }, "nics": { "type": "object", "description": "The VM's host-bridge vNICs and their modes.", "additionalProperties": { "$ref": "#/components/schemas/ModeView" }, "propertyNames": { "type": "string" } }, "proposal": { "$ref": "#/components/schemas/ProposalView", "description": "What to allow before switching to `enforce`." }, "since": { "type": "string", "description": "Start of the window (`monitorReportDays` back)." }, "vm": { "type": "string", "description": "VM id." }, "wouldDrop": { "type": "integer", "format": "int64", "description": "Packets that would have been dropped, all entries.", "minimum": 0 } } }, "MonthWeekOffset": { "type": "string", "description": "`WeekOfMonth` wire values for [`ScheduledRecurrence::MonthlyByWeekday`].", "enum": [ "first", "second", "third", "fourth", "last" ] }, "MoveHostsRequest": { "type": "object", "description": "Body of `POST /v1/clusters/{id}/move-hosts`.", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "type": "string" }, "description": "Host ids (`host-N`), each in maintenance mode and without virtual machines." } } }, "MoveIntoFolderRequest": { "type": "object", "description": "Re-parent inventory entities under a folder (`POST /v1/inventory/folders/{id}/move-into`,\nSOAP `Folder.MoveIntoFolder_Task`).", "required": [ "list" ], "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "list": { "type": "array", "items": { "type": "string" }, "description": "Entities to move (`vm-N`, `group-vN`, …). Must be non-empty." } } }, "MoveIntoResourcePoolRequest": { "type": "object", "description": "Move VMs and/or child pools under a resource pool\n(`POST /v1/resource-pools/{id}/move-into`, SOAP `MoveIntoResourcePool`).", "required": [ "list" ], "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "list": { "type": "array", "items": { "type": "string" }, "description": "Entities to move (`vm-N`, `resgroup-N`, …). Must be non-empty." } } }, "MoveRuleBody": { "type": "object", "description": "Moves a rule inside its policy.", "required": [ "position" ], "properties": { "position": { "type": "integer", "format": "int32", "description": "New position (0 first; beyond the end: last).", "minimum": 0 } }, "additionalProperties": false }, "NbdExportView": { "type": "object", "description": "OpenAPI stand-in for `NbdExport`.", "required": [ "transport", "exportName", "metaContexts", "readOnly", "fleecing", "size" ], "properties": { "exportName": { "type": "string", "description": "NBD export name." }, "fleecing": { "type": "boolean", "description": "Whether a fleecing image protects the running VM." }, "metaContexts": { "type": "array", "items": { "type": "string" }, "description": "Meta contexts the server offers." }, "readOnly": { "type": "boolean", "description": "Exports are read-only for backup (writable for restore)." }, "size": { "type": "integer", "format": "int64", "description": "Size of the export in bytes.", "minimum": 0 }, "transport": { "$ref": "#/components/schemas/NbdTransportView", "description": "Where to connect." } } }, "NbdTransportView": { "oneOf": [ { "type": "object", "description": "Unix domain socket on the host.", "required": [ "path", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "unix" ] }, "path": { "type": "string", "description": "Socket path." } } }, { "type": "object", "description": "TCP; TLS for off-host exports.", "required": [ "host", "port", "tls", "kind" ], "properties": { "certSha256": { "type": [ "string", "null" ], "description": "SHA-256 fingerprint of the server certificate (hex), when known." }, "host": { "type": "string", "description": "Host name or address." }, "kind": { "type": "string", "enum": [ "tcp" ] }, "port": { "type": "integer", "format": "int32", "description": "Port.", "minimum": 0 }, "tls": { "type": "boolean", "description": "Whether the server requires `NBD_OPT_STARTTLS`." } } } ], "description": "OpenAPI stand-in for `NbdTransport` (tagged on `kind`)." }, "Network": { "type": "object", "description": "A standard (host-scoped) network.", "required": [ "name" ], "properties": { "backing": { "oneOf": [ { "$ref": "#/components/schemas/NetworkBacking", "description": "How NICs on it reach the hosts; `None`: not wired by Kyvernon (NICs have no link)." }, { "type": "null" } ] }, "hosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts offering this network." }, "name": { "type": "string", "description": "Display name." }, "vlan_id": { "type": "integer", "format": "int32", "description": "VLAN id, 0 for untagged.", "minimum": 0 } }, "additionalProperties": false }, "NetworkBacking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/HostBridgeBacking", "description": "An existing bridge on each host." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "host-bridge" ] } } } ], "description": "An existing bridge on each host." } ], "description": "How VMs on a network reach the host." }, "NetworkEvidence": { "type": "object", "description": "The network the guest was verified on.", "required": [ "id", "name", "bridge", "quarantine" ], "properties": { "bridge": { "type": "string", "description": "Bridge on the hosts." }, "id": { "type": "string", "description": "Network record id." }, "name": { "type": "string", "description": "Network name." }, "quarantine": { "type": "boolean", "description": "Always true for a verified restore." } } }, "NetworkHealthCheckView": { "type": "object", "description": "One host-bridge network's VLAN/MTU check.", "required": [ "bridge", "vlanStatus", "vlanExpected", "mtuStatus", "healthy" ], "properties": { "bridge": { "type": "string", "description": "Bridge name." }, "healthy": { "type": "boolean", "description": "True when this check is healthy." }, "mtuExpected": { "type": [ "integer", "null" ], "format": "int32", "description": "Expected MTU when declared.", "minimum": 0 }, "mtuObserved": { "type": [ "integer", "null" ], "format": "int32", "description": "Observed MTU when known.", "minimum": 0 }, "mtuStatus": { "type": "string", "description": "MTU status (`ok`, `mismatch`, `skipped`, `bridgeMissing`, `unknown`, `unchecked`)." }, "name": { "type": [ "string", "null" ], "description": "Display name." }, "networkId": { "type": [ "string", "null" ], "description": "Inventory network id." }, "vlanExpected": { "type": "integer", "format": "int32", "description": "Expected VLAN id.", "minimum": 0 }, "vlanObserved": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkHealthPortVlanView" }, "description": "Observed mismatched ports (VLAN mismatch only)." }, "vlanStatus": { "type": "string", "description": "VLAN status (`ok`, `mismatch`, `noPorts`, `bridgeMissing`, `unchecked`)." } } }, "NetworkHealthPortVlanView": { "type": "object", "description": "Observed VLAN on a mismatched port.", "required": [ "port" ], "properties": { "port": { "type": "string", "description": "Port / tap name." }, "tag": { "type": [ "integer", "null" ], "format": "int32", "description": "OVS tag when present.", "minimum": 0 } } }, "NetworkHealthView": { "type": "object", "description": "Native VLAN/MTU health response.", "required": [ "healthy", "source", "checks" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkHealthCheckView" }, "description": "Per host-bridge network results." }, "healthy": { "type": "boolean", "description": "True when every check is healthy (or there is nothing to check)." }, "source": { "type": "string", "description": "`agent` when the host agent answered; `none` when detached." } } }, "NetworkHintView": { "type": "object", "description": "One physical NIC's discovered neighbour summary (`PhysicalNicHintInfo`).", "required": [ "device" ], "properties": { "cdp": { "oneOf": [ { "$ref": "#/components/schemas/CdpHintView", "description": "CDP neighbour when present." }, { "type": "null" } ] }, "device": { "type": "string", "description": "Host interface name (`eno1`, OVS port name, …)." }, "lldp": { "oneOf": [ { "$ref": "#/components/schemas/LldpHintView", "description": "LLDP neighbour when present." }, { "type": "null" } ] } } }, "NetworkHintsView": { "type": "object", "description": "Native QueryNetworkHint response (agent scrape + optional device filter).", "required": [ "source", "hints" ], "properties": { "hints": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkHintView" }, "description": "Per-device hints (only devices with at least one neighbour protocol)." }, "source": { "type": "string", "description": "Collector that produced the scrape (`ovs`, `lldpd`, or `none`)." } } }, "NfcLeaseFileView": { "type": "object", "description": "One file on a native NFC lease.", "required": [ "name", "key", "capacityBytes", "disk", "requireUpload", "size", "url" ], "properties": { "bytesReceived": { "type": "integer", "format": "int64", "description": "Import: bytes the controller has received of this file so far, also while the\nupload runs (another browser tab or a reload can show the progress).", "minimum": 0 }, "capacityBytes": { "type": "integer", "format": "int64", "description": "Virtual capacity in bytes.", "minimum": 0 }, "disk": { "type": "boolean", "description": "Disk (converted) vs ISO/image." }, "key": { "type": "string", "description": "Device / import key." }, "name": { "type": "string", "description": "Basename (`disk-0.vmdk`)." }, "requireUpload": { "type": "boolean", "description": "Import: must be uploaded before Complete." }, "size": { "type": "integer", "format": "int64", "description": "Known size (prepared download or received upload).", "minimum": 0 }, "url": { "type": "string", "description": "Relative transfer URL (`/v1/nfc-leases/{id}/files/{name}`). A browser uploads with\n`PUT` and `Authorization: Bearer `, the body is the file as it is\n(`application/octet-stream`); no CSRF header is needed. The controller converts\nVMDK (sparse or streamOptimized), qcow2 and raw disks at `complete`." } } }, "NfcLeaseProgressRequest": { "type": "object", "description": "Progress update (`POST /v1/nfc-leases/{id}/progress`).", "required": [ "percent" ], "properties": { "percent": { "type": "integer", "format": "int32", "description": "Percent complete (0 to 100)." } } }, "NfcLeaseView": { "type": "object", "description": "Native HttpNfcLease view (`GET /v1/nfc-leases/{id}`, ExportVm / ImportVApp).", "required": [ "id", "kind", "state", "initializeProgress", "transferProgress", "totalDiskCapacityKb" ], "properties": { "entityId": { "type": [ "string", "null" ], "description": "Imported VM id (import) or exported VM id (export)." }, "error": { "type": [ "string", "null" ], "description": "Error message when `state` is `error`." }, "expiresAt": { "type": "string", "description": "When the lease is aborted unless it is used before (RFC 3339): every upload chunk,\nprogress report and read of the lease moves it 15 minutes ahead. An abandoned import\nis aborted and its virtual machine removed." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/NfcLeaseFileView" }, "description": "Transferrable files." }, "id": { "type": "string", "description": "Lease id (`nfc-lease-` plus 32 random hex digits)." }, "initializeProgress": { "type": "integer", "format": "int32", "description": "Initialize progress (0 to 100)." }, "kind": { "type": "string", "description": "`import` or `export`." }, "sourceVmId": { "type": [ "string", "null" ], "description": "Source VM id on export." }, "state": { "type": "string", "description": "`initializing` / `ready` / `done` / `error`." }, "totalDiskCapacityKb": { "type": "integer", "format": "int64", "description": "Sum of disk capacities in KiB." }, "transferProgress": { "type": "integer", "format": "int32", "description": "Transfer progress (0 to 100)." } } }, "NicIpv6": { "type": "object", "description": "An IPv6 prefix of a NIC (a /64 per server).", "required": [ "prefix", "prefix_len" ], "properties": { "prefix": { "type": "string", "description": "The prefix, host bits zero." }, "prefix_len": { "type": "integer", "format": "int32", "description": "Its length.", "minimum": 0 } }, "additionalProperties": false }, "NicPolicy": { "type": "object", "description": "Policy of one NIC on a host-bridge network (§11.2). A NIC with a policy always has\nport security: anti-spoofing is mandatory for tenant NICs.", "properties": { "extra_ipv4": { "type": "array", "items": { "type": "string" }, "description": "Extra addresses from IP pools (port security allows them; the guest configures them)." }, "ipv4": { "oneOf": [ { "$ref": "#/components/schemas/PoolLease", "description": "Primary address from an IP pool (DHCP answers it)." }, { "type": "null" } ] }, "ipv6": { "type": "array", "items": { "$ref": "#/components/schemas/NicIpv6" }, "description": "IPv6 prefixes from IP pools." }, "rate_limit_kbps": { "type": [ "integer", "null" ], "format": "int64", "description": "Traffic throttle in kbit/s, both directions (ingress policing and `linux-htb`).", "minimum": 0 }, "smtp_block_v4": { "type": "boolean", "description": "Outgoing SMTP (TCP 25) over IPv4 is dropped (pool `smtp_ipv4`, per-VM unblock)." }, "smtp_block_v6": { "type": "boolean", "description": "Outgoing SMTP (TCP 25) over IPv6 is dropped (pool `smtp_ipv6`, default blocked)." } }, "additionalProperties": false }, "NicProfileBody": { "type": "object", "description": "Body of `PUT /v1/vms/{id}/nics/{key}/firewall`.", "properties": { "profile": { "type": [ "string", "null" ], "description": "Profile id; `null`: the profile of the NIC kind." } }, "additionalProperties": false }, "ObjectBody": { "oneOf": [ { "$ref": "#/components/schemas/Datacenter" }, { "$ref": "#/components/schemas/Folder" }, { "$ref": "#/components/schemas/Cluster" }, { "$ref": "#/components/schemas/ComputeResource" }, { "$ref": "#/components/schemas/Host" }, { "$ref": "#/components/schemas/ResourcePool" }, { "$ref": "#/components/schemas/VirtualMachine" }, { "$ref": "#/components/schemas/Datastore" }, { "$ref": "#/components/schemas/Network" }, { "$ref": "#/components/schemas/DistributedSwitch" }, { "$ref": "#/components/schemas/DistributedPortgroup" }, { "$ref": "#/components/schemas/Tag" }, { "$ref": "#/components/schemas/TagCategory" }, { "$ref": "#/components/schemas/CustomField" } ], "description": "A record body in the schema of its kind (`kyvernon_inventory::model`)." }, "ObjectView": { "oneOf": [ { "$ref": "#/components/schemas/ObjectViewDatacenter" }, { "$ref": "#/components/schemas/ObjectViewDatacenterFolder" }, { "$ref": "#/components/schemas/ObjectViewVmFolder" }, { "$ref": "#/components/schemas/ObjectViewHostFolder" }, { "$ref": "#/components/schemas/ObjectViewNetworkFolder" }, { "$ref": "#/components/schemas/ObjectViewDatastoreFolder" }, { "$ref": "#/components/schemas/ObjectViewCluster" }, { "$ref": "#/components/schemas/ObjectViewComputeResource" }, { "$ref": "#/components/schemas/ObjectViewHost" }, { "$ref": "#/components/schemas/ObjectViewResourcePool" }, { "$ref": "#/components/schemas/ObjectViewVirtualMachine" }, { "$ref": "#/components/schemas/ObjectViewDatastore" }, { "$ref": "#/components/schemas/ObjectViewNetwork" }, { "$ref": "#/components/schemas/ObjectViewDistributedSwitch" }, { "$ref": "#/components/schemas/ObjectViewDistributedPortgroup" }, { "$ref": "#/components/schemas/ObjectViewTag" }, { "$ref": "#/components/schemas/ObjectViewTagCategory" }, { "$ref": "#/components/schemas/ObjectViewCustomField" } ], "description": "A stored inventory object: record metadata, `kind`, `health` and the body `data` in the schema of the kind (`kyvernon_inventory::model`). Select the body schema on `kind`.", "discriminator": { "propertyName": "kind", "mapping": { "cluster": "#/components/schemas/ObjectViewCluster", "compute_resource": "#/components/schemas/ObjectViewComputeResource", "custom_field": "#/components/schemas/ObjectViewCustomField", "datacenter": "#/components/schemas/ObjectViewDatacenter", "datacenter_folder": "#/components/schemas/ObjectViewDatacenterFolder", "datastore": "#/components/schemas/ObjectViewDatastore", "datastore_folder": "#/components/schemas/ObjectViewDatastoreFolder", "distributed_portgroup": "#/components/schemas/ObjectViewDistributedPortgroup", "distributed_switch": "#/components/schemas/ObjectViewDistributedSwitch", "host": "#/components/schemas/ObjectViewHost", "host_folder": "#/components/schemas/ObjectViewHostFolder", "network": "#/components/schemas/ObjectViewNetwork", "network_folder": "#/components/schemas/ObjectViewNetworkFolder", "resource_pool": "#/components/schemas/ObjectViewResourcePool", "tag": "#/components/schemas/ObjectViewTag", "tag_category": "#/components/schemas/ObjectViewTagCategory", "virtual_machine": "#/components/schemas/ObjectViewVirtualMachine", "vm_folder": "#/components/schemas/ObjectViewVmFolder" } } }, "ObjectViewCluster": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Cluster" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "cluster" ] } } } ], "description": "An inventory object of kind `cluster` with a `Cluster` body." }, "ObjectViewCommon": { "type": "object", "description": "Fields every inventory object carries besides its metadata and body.", "properties": { "health": { "type": "string", "description": "Health: the worst unacknowledged alarm on the object, `danger` for a disconnected host. Present on inventory reads; absent on writes and on records of kinds that carry no alarms.", "enum": [ "ok", "warning", "danger" ] } } }, "ObjectViewComputeResource": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/ComputeResource" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "compute_resource" ] } } } ], "description": "An inventory object of kind `compute_resource` with a `ComputeResource` body." }, "ObjectViewCustomField": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomField" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "custom_field" ] } } } ], "description": "An inventory object of kind `custom_field` with a `CustomField` body." }, "ObjectViewDatacenter": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Datacenter" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "datacenter" ] } } } ], "description": "An inventory object of kind `datacenter` with a `Datacenter` body." }, "ObjectViewDatacenterFolder": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Folder" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "datacenter_folder" ] } } } ], "description": "An inventory object of kind `datacenter_folder` with a `Folder` body." }, "ObjectViewDatastore": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Datastore" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "datastore" ] } } } ], "description": "An inventory object of kind `datastore` with a `Datastore` body." }, "ObjectViewDatastoreFolder": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Folder" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "datastore_folder" ] } } } ], "description": "An inventory object of kind `datastore_folder` with a `Folder` body." }, "ObjectViewDistributedPortgroup": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/DistributedPortgroup" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "distributed_portgroup" ] } } } ], "description": "An inventory object of kind `distributed_portgroup` with a `DistributedPortgroup` body." }, "ObjectViewDistributedSwitch": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/DistributedSwitch" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "distributed_switch" ] } } } ], "description": "An inventory object of kind `distributed_switch` with a `DistributedSwitch` body." }, "ObjectViewHost": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Host" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "host" ] } } } ], "description": "An inventory object of kind `host` with a `Host` body." }, "ObjectViewHostFolder": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Folder" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "host_folder" ] } } } ], "description": "An inventory object of kind `host_folder` with a `Folder` body." }, "ObjectViewNetwork": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "network" ] } } } ], "description": "An inventory object of kind `network` with a `Network` body." }, "ObjectViewNetworkFolder": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Folder" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "network_folder" ] } } } ], "description": "An inventory object of kind `network_folder` with a `Folder` body." }, "ObjectViewResourcePool": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/ResourcePool" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "resource_pool" ] } } } ], "description": "An inventory object of kind `resource_pool` with a `ResourcePool` body." }, "ObjectViewTag": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "tag" ] } } } ], "description": "An inventory object of kind `tag` with a `Tag` body." }, "ObjectViewTagCategory": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/TagCategory" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "tag_category" ] } } } ], "description": "An inventory object of kind `tag_category` with a `TagCategory` body." }, "ObjectViewVirtualMachine": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/VirtualMachine" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "virtual_machine" ] } } } ], "description": "An inventory object of kind `virtual_machine` with a `VirtualMachine` body." }, "ObjectViewVmFolder": { "allOf": [ { "$ref": "#/components/schemas/RecordMetaView" }, { "$ref": "#/components/schemas/ObjectViewCommon" }, { "type": "object", "required": [ "kind", "data" ], "properties": { "data": { "$ref": "#/components/schemas/Folder" }, "kind": { "type": "string", "description": "Kind name; selects the schema of `data`.", "enum": [ "vm_folder" ] } } } ], "description": "An inventory object of kind `vm_folder` with a `Folder` body." }, "OidcAdminInput": { "type": "object", "description": "The identity provider to store. The controller runs provider discovery first and\nrefuses settings the provider does not answer to.", "required": [ "issuer", "clientId", "redirectUri", "loginTtlSeconds" ], "properties": { "clientId": { "type": "string", "description": "Client id." }, "clientSecret": { "type": [ "string", "null" ], "description": "Client secret (write-only). Blank or absent keeps the stored one." }, "groupsClaim": { "type": "string", "description": "Claim with the group names (default `groups`)." }, "issuer": { "type": "string", "description": "Issuer URL." }, "loginTtlSeconds": { "type": "integer", "format": "int64", "description": "How long a started sign-in stays valid, 60 to 3600 seconds.", "minimum": 0 }, "redirectUri": { "type": "string", "description": "Redirect URI, normally `https:///v1/identity/oidc/callback`." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes beyond `openid`." } } }, "OidcAdminView": { "type": "object", "description": "The OpenID Connect identity provider as an administrator sees it. The client secret is\nnever returned.", "required": [ "configured", "issuer", "clientId", "clientSecretSet", "redirectUri", "scopes", "groupsClaim", "loginTtlSeconds", "source" ], "properties": { "clientId": { "type": "string", "description": "Client id registered at the provider." }, "clientSecretSet": { "type": "boolean", "description": "Whether a client secret is stored." }, "configured": { "type": "boolean", "description": "Whether a provider is set up (sign-in with it is offered)." }, "groupsClaim": { "type": "string", "description": "Claim of the ID token with the group names." }, "issuer": { "type": "string", "description": "Issuer URL." }, "loginTtlSeconds": { "type": "integer", "format": "int64", "description": "How long a started sign-in stays valid, seconds.", "minimum": 0 }, "redirectUri": { "type": "string", "description": "Redirect URI registered at the provider." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes requested beyond `openid`." }, "source": { "type": "string", "description": "Where the provider comes from: `console` (set up here), `configuration` (the\n`[oidc]` section of the controller configuration) or `none`." } } }, "OidcConfigView": { "type": "object", "description": "OIDC part of [`AuthConfigView`].", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "An identity provider is configured." }, "label": { "type": [ "string", "null" ], "description": "Button label (the issuer host), when enabled." } } }, "OidcStartResponse": { "type": "object", "description": "OIDC login start.", "required": [ "url", "state" ], "properties": { "state": { "type": "string", "description": "State to expect on the callback." }, "url": { "type": "string", "description": "Provider URL to redirect the browser to." } } }, "OpenPortBody": { "type": "object", "description": "Body of `POST /v1/vms/{id}/firewall/open-port`.", "required": [ "protocol", "ports" ], "properties": { "from": { "type": "array", "items": { "type": "string" }, "description": "Sources allowed (addresses or prefixes; empty: any)." }, "ipVersion": { "$ref": "#/components/schemas/IpVersionView", "description": "IP families (default `any`)." }, "name": { "type": [ "string", "null" ], "description": "Rule name (default `open `)." }, "ports": { "type": "string", "description": "Port or range (`443`, `8000-8100`)." }, "protocol": { "type": "string", "description": "`tcp` or `udp`." } }, "additionalProperties": false }, "Origin": { "type": "string", "description": "Where an effective rule comes from.", "enum": [ "provider", "tenant", "baseline", "system", "default" ] }, "OrphanDisk": { "type": "object", "description": "A disk image nothing references.", "required": [ "path" ], "properties": { "backing": { "type": [ "string", "null" ], "description": "Backing image as stored in the header (an orphan overlay names its base)." }, "capacityBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Guest-visible capacity, when the header tells.", "minimum": 0 }, "format": { "type": [ "string", "null" ], "description": "Image format (`qcow2`, `raw`, `vmdk`)." }, "modifiedUnix": { "type": [ "integer", "null" ], "format": "int64", "description": "Last change (seconds since the Unix epoch)." }, "path": { "type": "string", "description": "Path below the datastore root." }, "sizeBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes the file takes on the datastore.", "minimum": 0 } } }, "OrphanDiskReport": { "type": "object", "description": "The orphan-disk report of one datastore.", "required": [ "datastore", "datastoreName", "scannedDisks", "referencedDisks", "minAgeSeconds", "truncated", "totalSizeBytes", "orphans" ], "properties": { "datastore": { "type": "string", "description": "The datastore (`datastore-N`)." }, "datastoreName": { "type": "string", "description": "Its name." }, "minAgeSeconds": { "type": "integer", "format": "int64", "description": "Files changed more recently than this were left out.", "minimum": 0 }, "orphanSidecars": { "type": "array", "items": { "$ref": "#/components/schemas/OrphanSidecar" }, "description": "Change-tracking sidecars (`.kcbt`, `.kcbt..`) whose image\nno longer exists, by path (TP-50). The sidecars of a listed image are not repeated\nhere: they go with it." }, "orphans": { "type": "array", "items": { "$ref": "#/components/schemas/OrphanDisk" }, "description": "The disk images nothing references, by path." }, "referencedDisks": { "type": "integer", "description": "Disk images the inventory references (directly, as overlay or as backing image).", "minimum": 0 }, "scannedDisks": { "type": "integer", "description": "Disk images found on the datastore.", "minimum": 0 }, "totalSizeBytes": { "type": "integer", "format": "int64", "description": "Bytes the listed files take together.", "minimum": 0 }, "truncated": { "type": "boolean", "description": "The datastore has more files than one scan returns; the list is incomplete." } } }, "OrphanSidecar": { "type": "object", "description": "A change-tracking sidecar whose image is gone.", "required": [ "path", "image" ], "properties": { "image": { "type": "string", "description": "Path of the image it belonged to." }, "modifiedUnix": { "type": [ "integer", "null" ], "format": "int64", "description": "Last change (seconds since the Unix epoch)." }, "path": { "type": "string", "description": "Path below the datastore root." }, "sizeBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes the file takes on the datastore.", "minimum": 0 } } }, "OvfCreateDescriptorFileRequest": { "type": "object", "description": "One package member for `CreateDescriptor` (`OvfFile`).", "required": [ "path" ], "properties": { "capacity": { "type": [ "integer", "null" ], "format": "int64", "description": "Virtual disk capacity in bytes when known (preferred over `size` for disks)." }, "deviceId": { "type": "string", "description": "NFC / export device id (`/{entity}/disk:N` or cdrom key)." }, "path": { "type": "string", "description": "Package member path (href), e.g. `web-disk1.vmdk` or `media.iso`." }, "populatedSize": { "type": [ "integer", "null" ], "format": "int64", "description": "Populated size when `size` is zero." }, "size": { "type": "integer", "format": "int64", "description": "Transfer / compressed size in bytes." } } }, "OvfCreateDescriptorView": { "type": "object", "description": "Result of `POST /v1/ovf/create-descriptor`.", "properties": { "entityName": { "type": "string", "description": "Entity name written into the envelope." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/OvfMessageView" }, "description": "Hard failures (HTTP still 200, matching SOAP)." }, "includeImageFiles": { "type": "boolean", "description": "Whether ISO image files were packaged." }, "ovfDescriptor": { "type": "string", "description": "OVF envelope XML." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/OvfMessageView" }, "description": "Soft warnings." } } }, "OvfDeploymentOptionView": { "type": "object", "description": "One deployment option from the package.", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "description": "Option key / id." }, "label": { "type": "string", "description": "Display label." } } }, "OvfFileItemView": { "type": "object", "description": "File the NFC lease would upload (`OvfFileItem`).", "required": [ "deviceId", "path", "cimType", "create" ], "properties": { "cimType": { "type": "integer", "format": "int32", "description": "CIM type (17 = disk, 15 = CD-ROM)." }, "create": { "type": "boolean", "description": "Create empty backing instead of uploading." }, "deviceId": { "type": "string", "description": "Device import key." }, "path": { "type": "string", "description": "Package member path (href) or empty-disk basename." }, "size": { "type": [ "integer", "null" ], "format": "int64", "description": "Declared size when known." } } }, "OvfImportCdromView": { "type": "object", "description": "CD-ROM planned by CreateImportSpec.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Package CD-ROM id." }, "importKey": { "type": [ "string", "null" ], "description": "NFC import key when an ISO upload is required." }, "isoPath": { "type": [ "string", "null" ], "description": "ISO datastore path when the package includes media." } } }, "OvfImportDiskView": { "type": "object", "description": "Disk planned by CreateImportSpec.", "required": [ "id", "capacityBytes", "datastorePath", "create", "importKey" ], "properties": { "capacityBytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "create": { "type": "boolean", "description": "Whether an empty disk is created (no NFC upload)." }, "datastorePath": { "type": "string", "description": "Destination datastore path (`[ds] name/disk-N.qcow2`)." }, "id": { "type": "string", "description": "Package disk id." }, "importKey": { "type": "string", "description": "NFC import key (`/{entity}/disk:N`)." } } }, "OvfImportNicView": { "type": "object", "description": "NIC planned by CreateImportSpec.", "required": [ "id", "model", "connected" ], "properties": { "connected": { "type": "boolean", "description": "Connect at power-on." }, "id": { "type": "string", "description": "Package NIC id." }, "mac": { "type": [ "string", "null" ], "description": "MAC when the package states one." }, "model": { "type": "string", "description": "Model string (`vmxnet3`, `e1000`, …)." }, "networkId": { "type": [ "string", "null" ], "description": "Resolved inventory network id when mapped." }, "networkName": { "type": [ "string", "null" ], "description": "Resolved inventory network name." }, "ovfNetwork": { "type": [ "string", "null" ], "description": "Network name from the OVF." } } }, "OvfImportSpecView": { "type": "object", "description": "Result of `POST /v1/ovf/import-spec`.", "properties": { "annotation": { "type": [ "string", "null" ], "description": "Annotation." }, "cdroms": { "type": "array", "items": { "$ref": "#/components/schemas/OvfImportCdromView" }, "description": "Planned CD-ROMs." }, "coresPerSocket": { "type": [ "integer", "null" ], "format": "int32", "description": "Cores per socket when valid.", "minimum": 0 }, "datastoreId": { "type": "string", "description": "Datastore id." }, "disks": { "type": "array", "items": { "$ref": "#/components/schemas/OvfImportDiskView" }, "description": "Planned disks." }, "entityName": { "type": "string", "description": "Planned VM name." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/OvfMessageView" }, "description": "Hard failures (HTTP still 200, matching SOAP)." }, "extraConfig": { "type": "object", "description": "`vmw:ExtraConfig` / guestinfo pairs.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "fileItems": { "type": "array", "items": { "$ref": "#/components/schemas/OvfFileItemView" }, "description": "NFC file items." }, "firmware": { "type": "string", "description": "Firmware: `bios` or `efi` as the package states it, `efi` when it states none." }, "guestId": { "type": [ "string", "null" ], "description": "Guest OS id from the package." }, "hardwareVersion": { "type": [ "string", "null" ], "description": "Hardware version string when stated." }, "memoryMib": { "type": "integer", "format": "int64", "description": "Memory in MiB.", "minimum": 0 }, "nics": { "type": "array", "items": { "$ref": "#/components/schemas/OvfImportNicView" }, "description": "Planned NICs (unmapped NICs are omitted with a warning)." }, "numCpus": { "type": "integer", "format": "int32", "description": "vCPU count.", "minimum": 0 }, "resourcePoolId": { "type": "string", "description": "Resource pool id." }, "secureBoot": { "type": "boolean", "description": "Secure Boot as the package states it (kept with `efi` only)." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/OvfMessageView" }, "description": "Soft warnings." } } }, "OvfMessageView": { "type": "object", "description": "Warning or error from OVF parse / import-spec.", "required": [ "key", "detail" ], "properties": { "detail": { "type": "string", "description": "Non-secret detail." }, "key": { "type": "string", "description": "Stable message key (`import.ovf.*`)." } } }, "OvfNetworkInfoView": { "type": "object", "description": "One OVF network advertised by the package.", "required": [ "name" ], "properties": { "description": { "type": "string", "description": "Description from the package." }, "name": { "type": "string", "description": "Network name in the package." } } }, "OvfNetworkMappingRequest": { "type": "object", "description": "Map an OVF network name to an inventory network.", "required": [ "name", "networkId" ], "properties": { "name": { "type": "string", "description": "Network name as stated in the OVF." }, "networkId": { "type": "string", "description": "Inventory network or distributed port group id." } } }, "OvfParseDescriptorRequest": { "type": "object", "description": "Parse an OVF descriptor (`OvfManager.ParseDescriptor`).", "required": [ "ovfDescriptor" ], "properties": { "deploymentOption": { "type": [ "string", "null" ], "description": "Optional deployment configuration id from the package." }, "ovfDescriptor": { "type": "string", "description": "OVF envelope XML." } } }, "OvfParseDescriptorView": { "type": "object", "description": "Result of `POST /v1/ovf/parse`.", "properties": { "annotation": { "type": "string", "description": "Annotation / description." }, "approximateDownloadSize": { "type": [ "integer", "null" ], "format": "int64", "description": "Approximate download size in bytes." }, "approximateFlatDeploymentSize": { "type": [ "integer", "null" ], "format": "int64", "description": "Approximate flat deployment size in bytes." }, "approximateSparseDeploymentSize": { "type": [ "integer", "null" ], "format": "int64", "description": "Approximate sparse deployment size in bytes." }, "defaultDeploymentOption": { "type": "string", "description": "Default deployment option key." }, "defaultEntityName": { "type": "string", "description": "Default VM name from the first VirtualSystem." }, "deploymentOptions": { "type": "array", "items": { "$ref": "#/components/schemas/OvfDeploymentOptionView" }, "description": "Deployment options." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/OvfMessageView" }, "description": "Hard failures (parse still returns 200 with these populated, matching SOAP)." }, "networks": { "type": "array", "items": { "$ref": "#/components/schemas/OvfNetworkInfoView" }, "description": "Networks declared by the package." }, "virtualApp": { "type": "boolean", "description": "Whether the package is a vApp (always false in this thin slice)." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/OvfMessageView" }, "description": "Soft warnings." } } }, "OvnHostView": { "type": "object", "description": "One host's realization as the status shows it.", "required": [ "host", "generation", "applied", "ports", "portsInstalled", "reportedAt" ], "properties": { "applied": { "type": "boolean", "description": "The slice is realised on the host's Open vSwitch." }, "error": { "type": [ "string", "null" ], "description": "Why not." }, "generation": { "type": "integer", "format": "int64", "description": "Generation of the slice the host holds.", "minimum": 0 }, "host": { "type": "string", "description": "Host id." }, "ports": { "type": "integer", "description": "Logical ports bound to the host.", "minimum": 0 }, "portsInstalled": { "type": "integer", "description": "Of those, ports whose flows `ovn-controller` installed.", "minimum": 0 }, "preconditions": { "type": "array", "items": { "type": "string" }, "description": "Host preconditions that do not hold." }, "reportedAt": { "type": "string", "description": "When the host last reported." } } }, "OvnStatusView": { "type": "object", "description": "Realization status of the OVN logical networks (`GET /v1/network/realization`).", "required": [ "enabled", "northbound", "connected", "modelGeneration", "realizedGeneration", "lastOperations", "lastDrift", "segments", "ports", "portsUp", "counters" ], "properties": { "connected": { "type": "boolean", "description": "The Northbound connection is up." }, "counters": { "type": "string", "description": "Rule counters on segments: `available`, `not configured` (no `[ovn] southbound`)\nor the reason they are not." }, "enabled": { "type": "boolean", "description": "`[ovn] enabled`." }, "error": { "type": [ "string", "null" ], "description": "The model or realization error, if the newest model is not realised." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/OvnHostView" }, "description": "The hosts' reports." }, "lastDrift": { "type": "integer", "description": "Rows another writer changed that the last realization corrected.", "minimum": 0 }, "lastOperations": { "type": "integer", "description": "Database operations of the last realization (0: already in line).", "minimum": 0 }, "modelGeneration": { "type": "integer", "format": "int64", "description": "Generation of the newest model (the store version it was read at).", "minimum": 0 }, "northbound": { "type": "string", "description": "The Northbound remote." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Notes of the compiler and inventory objects left out." }, "ports": { "type": "integer", "description": "Logical ports in the model.", "minimum": 0 }, "portsUp": { "type": "integer", "description": "Logical ports OVN reports up (bound on a chassis).", "minimum": 0 }, "realizedAt": { "type": [ "string", "null" ], "description": "When it was realised." }, "realizedGeneration": { "type": "integer", "format": "int64", "description": "Generation last realised in the Northbound database.", "minimum": 0 }, "segments": { "type": "integer", "description": "Segments in the model.", "minimum": 0 } } }, "PackageBody": { "type": "object", "description": "Add a traffic package.", "required": [ "bytes" ], "properties": { "bytes": { "type": "integer", "format": "int64", "description": "Bytes added to the current period's limit.", "minimum": 0 }, "reference": { "type": [ "string", "null" ], "description": "Order reference; the same reference adds a package once per period." } }, "additionalProperties": false }, "Paged_AuditView": { "type": "object", "description": "A page of items with the store version it was read at.", "required": [ "items", "version" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "An audit record.", "required": [ "id", "at", "actor", "action", "correlationId", "outcome", "clientAddress", "details" ], "properties": { "action": { "type": "string", "description": "Action." }, "actor": { "type": "string", "description": "Actor." }, "afterHash": { "type": [ "string", "null" ], "description": "After hash." }, "at": { "type": "string", "description": "Time." }, "beforeHash": { "type": [ "string", "null" ], "description": "Before hash." }, "clientAddress": { "type": "string", "description": "Client address." }, "correlationId": { "type": "string", "description": "Correlation id." }, "details": { "type": "object", "description": "Details.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Id." }, "outcome": { "type": "string", "description": "`success`, `denied` or `error`." }, "targetId": { "type": [ "string", "null" ], "description": "Target." } } }, "description": "Items in id order." }, "next": { "type": [ "string", "null" ], "description": "Cursor for the next page (`after` query parameter), absent on the last page." }, "version": { "type": "integer", "format": "int64", "description": "Store version at read time; use as `since` for the change feed.", "minimum": 0 } } }, "Paged_EventView": { "type": "object", "description": "A page of items with the store version it was read at.", "required": [ "items", "version" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "An event.", "required": [ "id", "time", "severity", "eventType", "messageId", "args", "targetName", "related", "user", "chainId", "attributes" ], "properties": { "args": { "type": "object", "description": "Message arguments.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "attributes": { "type": "object", "description": "Attributes.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "chainId": { "type": "string", "description": "Correlation id." }, "eventType": { "type": "string", "description": "Event type in vSphere style (`VmPoweredOnEvent`)." }, "id": { "type": "string", "description": "Event id (`event-N`)." }, "messageId": { "type": "string", "description": "Localisable message key." }, "related": { "type": "array", "items": { "type": "string" }, "description": "Related object ids." }, "severity": { "$ref": "#/components/schemas/SeverityView", "description": "Severity." }, "targetId": { "type": [ "string", "null" ], "description": "Target id." }, "targetName": { "type": "string", "description": "Target name." }, "targetType": { "type": [ "string", "null" ], "description": "Target short type." }, "taskId": { "type": [ "string", "null" ], "description": "Producing task." }, "time": { "type": "string", "description": "Time (RFC 3339)." }, "user": { "type": "string", "description": "User." } } }, "description": "Items in id order." }, "next": { "type": [ "string", "null" ], "description": "Cursor for the next page (`after` query parameter), absent on the last page." }, "version": { "type": "integer", "format": "int64", "description": "Store version at read time; use as `since` for the change feed.", "minimum": 0 } } }, "Paged_ObjectView": { "type": "object", "description": "A page of items with the store version it was read at.", "required": [ "items", "version" ], "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ObjectViewDatacenter" }, { "$ref": "#/components/schemas/ObjectViewDatacenterFolder" }, { "$ref": "#/components/schemas/ObjectViewVmFolder" }, { "$ref": "#/components/schemas/ObjectViewHostFolder" }, { "$ref": "#/components/schemas/ObjectViewNetworkFolder" }, { "$ref": "#/components/schemas/ObjectViewDatastoreFolder" }, { "$ref": "#/components/schemas/ObjectViewCluster" }, { "$ref": "#/components/schemas/ObjectViewComputeResource" }, { "$ref": "#/components/schemas/ObjectViewHost" }, { "$ref": "#/components/schemas/ObjectViewResourcePool" }, { "$ref": "#/components/schemas/ObjectViewVirtualMachine" }, { "$ref": "#/components/schemas/ObjectViewDatastore" }, { "$ref": "#/components/schemas/ObjectViewNetwork" }, { "$ref": "#/components/schemas/ObjectViewDistributedSwitch" }, { "$ref": "#/components/schemas/ObjectViewDistributedPortgroup" }, { "$ref": "#/components/schemas/ObjectViewTag" }, { "$ref": "#/components/schemas/ObjectViewTagCategory" }, { "$ref": "#/components/schemas/ObjectViewCustomField" } ], "description": "A stored inventory object: record metadata, `kind`, `health` and the body `data` in the schema of the kind (`kyvernon_inventory::model`). Select the body schema on `kind`.", "discriminator": { "propertyName": "kind", "mapping": { "cluster": "#/components/schemas/ObjectViewCluster", "compute_resource": "#/components/schemas/ObjectViewComputeResource", "custom_field": "#/components/schemas/ObjectViewCustomField", "datacenter": "#/components/schemas/ObjectViewDatacenter", "datacenter_folder": "#/components/schemas/ObjectViewDatacenterFolder", "datastore": "#/components/schemas/ObjectViewDatastore", "datastore_folder": "#/components/schemas/ObjectViewDatastoreFolder", "distributed_portgroup": "#/components/schemas/ObjectViewDistributedPortgroup", "distributed_switch": "#/components/schemas/ObjectViewDistributedSwitch", "host": "#/components/schemas/ObjectViewHost", "host_folder": "#/components/schemas/ObjectViewHostFolder", "network": "#/components/schemas/ObjectViewNetwork", "network_folder": "#/components/schemas/ObjectViewNetworkFolder", "resource_pool": "#/components/schemas/ObjectViewResourcePool", "tag": "#/components/schemas/ObjectViewTag", "tag_category": "#/components/schemas/ObjectViewTagCategory", "virtual_machine": "#/components/schemas/ObjectViewVirtualMachine", "vm_folder": "#/components/schemas/ObjectViewVmFolder" } } }, "description": "Items in id order." }, "next": { "type": [ "string", "null" ], "description": "Cursor for the next page (`after` query parameter), absent on the last page." }, "version": { "type": "integer", "format": "int64", "description": "Store version at read time; use as `since` for the change feed.", "minimum": 0 } } }, "Paged_TaskView": { "type": "object", "description": "A page of items with the store version it was read at.", "required": [ "items", "version" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "A task.", "required": [ "id", "descriptionId", "messageId", "args", "state", "progress", "targetName", "initiator", "chainId", "queuedAt", "retryable", "attempt", "cancelRequested" ], "properties": { "args": { "type": "object", "description": "Message arguments.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "attempt": { "type": "integer", "format": "int32", "description": "Attempts so far.", "minimum": 0 }, "cancelRequested": { "type": "boolean", "description": "Cancellation requested." }, "chainId": { "type": "string", "description": "Correlation id grouping tasks and events of one action." }, "completedAt": { "type": [ "string", "null" ], "description": "Completed at." }, "descriptionId": { "type": "string", "description": "Operation id in vSphere style (`VirtualMachine.powerOn`)." }, "error": { "oneOf": [ { "$ref": "#/components/schemas/ErrorBody", "description": "Error when failed." }, { "type": "null" } ] }, "id": { "type": "string", "description": "Task id (`task-N`)." }, "initiator": { "type": "string", "description": "Submitting user." }, "messageId": { "type": "string", "description": "Localisable message key (`task.virtual_machine.power_on`)." }, "progress": { "type": "integer", "format": "int32", "description": "Progress 0..=100.", "minimum": 0 }, "queuedAt": { "type": "string", "description": "Queued at." }, "result": { "oneOf": [ { "$ref": "#/components/schemas/TaskResultView", "description": "Result on success (`TaskResultView`: oneOf of the known operation payloads).\nDestroy and similar leave it null." }, { "type": "null" } ] }, "retryable": { "type": "boolean", "description": "Whether the failure is retryable." }, "startedAt": { "type": [ "string", "null" ], "description": "Started at." }, "state": { "$ref": "#/components/schemas/TaskStateView", "description": "State." }, "targetId": { "type": [ "string", "null" ], "description": "Target object id." }, "targetName": { "type": "string", "description": "Target name at submission." }, "targetType": { "type": [ "string", "null" ], "description": "Target short type." } } }, "description": "Items in id order." }, "next": { "type": [ "string", "null" ], "description": "Cursor for the next page (`after` query parameter), absent on the last page." }, "version": { "type": "integer", "format": "int64", "description": "Store version at read time; use as `since` for the change feed.", "minimum": 0 } } }, "PasswordPolicyRequest": { "type": "object", "description": "Body of `PUT /v1/identity/password-policy`. Every password set after the change is\nchecked against it; existing passwords stay valid. Passwords are also checked against\nthe list of common passwords, for sequences and repetition and for the user name;\nthose checks cannot be switched off.", "required": [ "minLength", "maxLength" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Text for administrators (kept when absent)." }, "maxLength": { "type": "integer", "description": "Longest password, at most `maxLengthCeiling` (256) and not below `minLength`.", "minimum": 0 }, "minLength": { "type": "integer", "description": "Shortest password, at least `minLengthFloor` (12).", "minimum": 0 } } }, "PasswordPolicyView": { "type": "object", "description": "The local password policy.", "required": [ "description", "minLength", "maxLength", "minLengthFloor", "maxLengthCeiling" ], "properties": { "description": { "type": "string", "description": "Text for administrators." }, "maxLength": { "type": "integer", "description": "Longest password accepted, in characters.", "minimum": 0 }, "maxLengthCeiling": { "type": "integer", "description": "The largest value `maxLength` may take (fixed by the product).", "minimum": 0 }, "minLength": { "type": "integer", "description": "Shortest password accepted, in characters.", "minimum": 0 }, "minLengthFloor": { "type": "integer", "description": "The smallest value `minLength` may take (fixed by the product).", "minimum": 0 } } }, "PendingModeView": { "type": "object", "description": "A mode switch that waits for confirmation.", "required": [ "revertTo", "revertAt" ], "properties": { "revertAt": { "type": "string", "description": "When (RFC 3339)." }, "revertTo": { "$ref": "#/components/schemas/ModeView", "description": "Mode restored when the switch is not confirmed." } } }, "PermissionView": { "type": "object", "description": "A permission.", "required": [ "id", "entityId", "principal", "roleId", "propagate" ], "properties": { "entityId": { "type": "string", "description": "Entity id." }, "id": { "type": "string", "description": "Permission id." }, "principal": { "$ref": "#/components/schemas/PrincipalView", "description": "Principal." }, "propagate": { "type": "boolean", "description": "Propagate to descendants." }, "roleId": { "type": "string", "description": "Role id." } } }, "PlanHoursView": { "type": "object", "description": "Hours on one plan.", "required": [ "plan", "planName", "hours" ], "properties": { "hours": { "type": "number", "format": "double", "description": "Hours in the month." }, "plan": { "type": "string", "description": "Plan." }, "planName": { "type": "string", "description": "Its name." } } }, "PlanView": { "type": "object", "description": "A VM plan.", "required": [ "name", "vcpus", "memoryMib", "diskGib" ], "properties": { "allowedImages": { "type": "array", "items": { "type": "string" }, "description": "Images that may be used (empty: every catalogue image)." }, "bandwidthMbit": { "type": [ "integer", "null" ], "format": "int32", "description": "Bandwidth cap (Mbit/s).", "minimum": 0 }, "description": { "type": "string", "description": "Description." }, "diskGib": { "type": "integer", "format": "int64", "description": "Disk (GiB).", "minimum": 0 }, "diskType": { "type": "string", "description": "`thin` or `thick`." }, "id": { "type": "string", "description": "`vmplan-N` (ignored in requests)." }, "ipv6": { "type": "boolean", "description": "An IPv6 /64." }, "memoryMib": { "type": "integer", "format": "int64", "description": "Memory (MiB).", "minimum": 0 }, "name": { "type": "string", "description": "Unique name." }, "orderable": { "type": "boolean", "description": "Orderable by tenants." }, "publicIpv4": { "type": "integer", "format": "int32", "description": "Public IPv4 addresses included.", "minimum": 0 }, "trafficAction": { "type": "string", "description": "`notify` or `throttle` at 100 % of the monthly traffic." }, "trafficGibMonth": { "type": "integer", "format": "int64", "description": "Traffic per month (GiB, 0 = unmetered).", "minimum": 0 }, "vcpus": { "type": "integer", "format": "int32", "description": "vCPUs.", "minimum": 0 } } }, "PolicyBody": { "type": "object", "description": "Create or replace a policy. `rules` on `PUT` replaces the rules (a rule with the\n`id` of an existing one keeps its number); absent, the rules stay.", "required": [ "name", "category" ], "properties": { "appliedTo": { "type": "array", "items": { "type": "string" }, "description": "Groups the policy applies to (empty: every vNIC; a tenant's: its own vNICs)." }, "category": { "$ref": "#/components/schemas/CategoryView", "description": "Category; tenants may use `environment` and `application` only." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled (default true)." }, "name": { "type": "string", "description": "Name (unique in its scope; `sys:` is reserved)." }, "rules": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RuleBody" }, "description": "Rules in order." }, "sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Order inside the category (lower first). Default: after the scope's last policy.", "minimum": 0 }, "stateful": { "type": "boolean", "description": "Replies are allowed automatically (default true)." } }, "additionalProperties": false }, "PolicyInput": { "type": "object", "description": "The settable part of a traffic policy.", "properties": { "action": { "$ref": "#/components/schemas/TrafficAction", "description": "Action at 100 %." }, "anchorDay": { "type": [ "integer", "null" ], "format": "int32", "description": "Anchor day (1 to 28); absent: the tenant's or the 1st.", "minimum": 0 }, "monthlyLimitBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes per period; absent: no limit.", "minimum": 0 }, "tenant": { "type": [ "string", "null" ], "description": "Tenant (events)." }, "throttleKbps": { "type": [ "integer", "null" ], "format": "int64", "description": "Throttle rate (kbit/s); absent: the site default.", "minimum": 0 } } }, "PolicyStatsView": { "type": "object", "description": "Counters of a policy's rules.", "required": [ "policy", "rules" ], "properties": { "policy": { "type": "string", "description": "Policy id." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleStatsView" }, "description": "Per rule, in policy order." } } }, "PolicyView": { "type": "object", "description": "A policy with its rules.", "required": [ "id", "version", "builtin", "name", "category", "sequence", "stateful", "appliedTo", "enabled", "rules" ], "properties": { "appliedTo": { "type": "array", "items": { "type": "string" }, "description": "Applied-to groups." }, "builtin": { "type": "boolean", "description": "Built in (read-only)." }, "category": { "$ref": "#/components/schemas/CategoryView", "description": "Category." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled." }, "expiresAt": { "type": [ "string", "null" ], "description": "End of an emergency bypass (RFC 3339)." }, "fwVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Store version of this write.", "minimum": 0 }, "id": { "type": "string", "description": "`fwpolicy-N`." }, "name": { "type": "string", "description": "Name." }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/IssueView" }, "description": "Validation notes of this write (rules that can match nothing)." }, "pendingHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts that had not applied the change when `?wait=realized` timed out." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleView" }, "description": "Rules in order." }, "sequence": { "type": "integer", "format": "int32", "description": "Sequence.", "minimum": 0 }, "stateful": { "type": "boolean", "description": "Stateful." }, "tenant": { "type": [ "string", "null" ], "description": "Owner (`null`: provider)." }, "version": { "type": "integer", "format": "int64", "description": "Record version.", "minimum": 0 } } }, "PoolIpv6View": { "type": "object", "description": "The IPv6 side of a pool.", "required": [ "prefix", "prefixLen" ], "properties": { "gateway": { "type": [ "string", "null" ], "description": "Default gateway of the guests (the router's link-local or on-link address)." }, "prefix": { "type": "string", "description": "Prefix (host bits zero), e.g. `2001:db8:100::`." }, "prefixLen": { "type": "integer", "format": "int32", "description": "Prefix length (32 to 127, shorter than `serverPrefixLen`); block 0 stays with the\nrouter.", "minimum": 0 }, "reserved": { "type": "array", "items": { "type": "string" }, "description": "Addresses inside the prefix used by others (the host's own address): their blocks\nare never handed out." }, "serverPrefixLen": { "type": [ "integer", "null" ], "format": "int32", "description": "Length of every server's block, 64 to 128 (default 64; 112 for a /112 per VPS from\na host's single /64).", "minimum": 0 } } }, "PoolLease": { "type": "object", "description": "A primary address from an IP pool: it replaces the range lease of the NIC and carries\nthe pool's subnet, gateway and DNS servers.", "required": [ "address", "prefix_len" ], "properties": { "address": { "type": "string", "description": "The address." }, "dns_servers": { "type": "array", "items": { "type": "string" }, "description": "The pool's DNS servers; empty: the network's." }, "gateway": { "type": [ "string", "null" ], "description": "The pool's gateway." }, "prefix_len": { "type": "integer", "format": "int32", "description": "Prefix length of the pool's subnet.", "minimum": 0 } }, "additionalProperties": false }, "PoolUsage": { "type": "object", "description": "Counts of a pool.", "required": [ "capacity", "allocated", "quarantined", "free", "ipv6Capacity", "ipv6Allocated", "ipv6Quarantined", "ipv6Free" ], "properties": { "allocated": { "type": "integer", "format": "int64", "description": "Allocated.", "minimum": 0 }, "capacity": { "type": "integer", "format": "int64", "description": "Addresses the pool can hand out (ranges minus gateway, reserved, network and\nbroadcast addresses).", "minimum": 0 }, "free": { "type": "integer", "format": "int64", "description": "Free now.", "minimum": 0 }, "ipv6Allocated": { "type": "integer", "format": "int64", "description": "/64 prefixes allocated.", "minimum": 0 }, "ipv6Capacity": { "type": "integer", "format": "int64", "description": "/64 prefixes the pool can hand out (0 without IPv6).", "minimum": 0 }, "ipv6Free": { "type": "integer", "format": "int64", "description": "IPv6 blocks free now (0 without IPv6).", "minimum": 0 }, "ipv6Quarantined": { "type": "integer", "format": "int64", "description": "IPv6 blocks in quarantine (not yet free again).", "minimum": 0 }, "quarantined": { "type": "integer", "format": "int64", "description": "In quarantine (not yet free again).", "minimum": 0 } } }, "PortgroupIpv6": { "type": "object", "description": "IPv6 settings of a distributed port group.", "required": [ "prefix" ], "properties": { "dhcp": { "type": "boolean", "description": "Answer DHCPv6 with the port's address (router advertisements with the managed flag\ncome from the network's router)." }, "prefix": { "type": "string", "description": "The /64 prefix (`2001:db8:10::/64`)." } }, "additionalProperties": false }, "PortgroupIpv6Request": { "type": "object", "description": "IPv6 settings of a port group.", "required": [ "prefix" ], "properties": { "dhcp": { "type": [ "boolean", "null" ], "description": "Answer DHCPv6 (default true)." }, "prefix": { "type": "string", "description": "The /64 prefix (`2001:db8:10::/64`)." } }, "additionalProperties": false }, "PostEventRequest": { "type": "object", "description": "Inject a typed event into the native event log (`PostEvent`).", "required": [ "eventType" ], "properties": { "attributes": { "type": "object", "description": "Extra attributes.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "chainId": { "type": [ "string", "null" ], "description": "Correlation id; a new id is allocated when omitted." }, "entityId": { "type": [ "string", "null" ], "description": "Optional target inventory object id." }, "eventType": { "type": "string", "description": "Event type in vSphere style (`GeneralUserEvent`, `EventEx`, …)." }, "message": { "type": [ "string", "null" ], "description": "Free-form message text (stored as message arg `msg` when set)." }, "messageId": { "type": [ "string", "null" ], "description": "Localisable message key; defaults to `event.user` when `message` is set, else `event.posted`." }, "severity": { "oneOf": [ { "$ref": "#/components/schemas/SeverityView", "description": "Severity; defaults to `user` when `eventType` is `GeneralUserEvent`, else `info`." }, { "type": "null" } ] } } }, "PowerRequest": { "type": "object", "description": "Optional idempotency key for power operations.", "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." } } }, "PowerResultView": { "type": "object", "description": "`TaskView.result` of VM power operations (`powerOn` / `powerOff` / `reset` / `suspend`).", "required": [ "powerState", "generation" ], "properties": { "generation": { "type": "integer", "format": "int64", "description": "Desired-state generation the agent must converge to.", "minimum": 0 }, "powerState": { "type": "string", "description": "Desired power state after the operation (`powered_on`, `powered_off`, `suspended`, `paused`)." } } }, "PowerState": { "type": "string", "description": "VM power state as the control plane records it (desired and observed).\n\n`PoweredOn`, `PoweredOff` and `Suspended` are the vSphere-compatible values; `Paused`\nis the Compute team's `paused` (vCPUs stopped, memory live), which tools see as\npowered on. The agent's full lifecycle set (`starting`, `stopping`, `migrating`, ...)\nis kept separately in [`VmRuntime::lifecycle`].", "enum": [ "powered_off", "powered_on", "suspended", "paused" ] }, "PrincipalView": { "type": "object", "description": "A principal.", "required": [ "type", "name" ], "properties": { "name": { "type": "string", "description": "Name." }, "type": { "type": "string", "description": "`user` or `group`." } } }, "PrivilegeView": { "type": "object", "description": "A catalogue privilege.", "required": [ "id", "description" ], "properties": { "description": { "type": "string", "description": "Description." }, "id": { "type": "string", "description": "Id." } } }, "ProfileBody": { "type": "object", "description": "A default profile.", "required": [ "name", "inbound", "outbound" ], "properties": { "baseline": { "type": [ "string", "null" ], "description": "Baseline policy (a provider Application policy evaluated after every tenant rule)." }, "inbound": { "$ref": "#/components/schemas/DefaultActionView", "description": "Default for traffic arriving at the vNIC." }, "name": { "type": "string", "description": "Name." }, "outbound": { "$ref": "#/components/schemas/DefaultActionView", "description": "Default for traffic leaving the vNIC." }, "selectable": { "type": "boolean", "description": "Tenants may choose it." } }, "additionalProperties": false }, "ProfileView": { "allOf": [ { "$ref": "#/components/schemas/ProfileBody", "description": "The definition." }, { "type": "object", "required": [ "id", "version", "builtin" ], "properties": { "builtin": { "type": "boolean", "description": "Built in (may be overridden, not deleted)." }, "id": { "type": "string", "description": "Built-in name (`public-default`, `private-default`, `closed`, `open`) or\n`fwprofile-N`." }, "version": { "type": "integer", "format": "int64", "description": "Record version (0: the built-in as shipped).", "minimum": 0 } } } ], "description": "A profile." }, "ProposalView": { "type": "object", "description": "A proposal from a monitor report.", "required": [ "rules" ], "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleBody" }, "description": "Allow rules for the other inbound TCP and UDP ports seen." }, "template": { "type": [ "string", "null" ], "description": "A template whose ports were all seen (`web`, `mail-server`)." } } }, "ProtectionView": { "type": "object", "description": "Protection of a vNIC.", "required": [ "state" ], "properties": { "reason": { "type": [ "string", "null" ], "description": "Why a vNIC is unprotected (Linux bridge, port security off, not on a host bridge)." }, "state": { "type": "string", "description": "`enforced`, `monitor`, `off` or `unprotected`." } } }, "PtrBody": { "type": "object", "description": "Set a PTR name.", "properties": { "ptr": { "type": [ "string", "null" ], "description": "Host name; `null` or empty removes the record." } }, "additionalProperties": false }, "PtrRejectBody": { "type": "object", "description": "Body of `POST .../ptr/rejected`.", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Why (shown to the tenant)." } }, "additionalProperties": false }, "PtrStatus": { "type": "string", "description": "State of a PTR name in reverse DNS.", "enum": [ "applied", "requested", "rejected", "to_remove" ] }, "QuiesceModeView": { "type": "string", "description": "OpenAPI stand-in for `QuiesceMode` (model lives in kyvernon-backup).", "enum": [ "NONE", "PREFERRED", "REQUIRED" ] }, "QuotaAmounts": { "type": "object", "description": "Amounts of the quota resources (current use, or the change an operation makes).", "required": [ "vcpus", "memoryMib", "diskGib", "vms", "publicIpv4", "snapshots" ], "properties": { "diskGib": { "type": "integer", "format": "int64", "description": "Provisioned disk (GiB, rounded up per disk).", "minimum": 0 }, "memoryMib": { "type": "integer", "format": "int64", "description": "Memory (MiB).", "minimum": 0 }, "publicIpv4": { "type": "integer", "format": "int64", "description": "Public IPv4 addresses.", "minimum": 0 }, "snapshots": { "type": "integer", "format": "int64", "description": "Snapshots.", "minimum": 0 }, "vcpus": { "type": "integer", "format": "int64", "description": "vCPUs.", "minimum": 0 }, "vms": { "type": "integer", "format": "int64", "description": "VMs.", "minimum": 0 } } }, "QuotaView": { "type": "object", "description": "Tenant limits (`null`: unlimited).", "properties": { "diskGib": { "type": [ "integer", "null" ], "format": "int64", "description": "Disk (GiB).", "minimum": 0 }, "fwGroupMembers": { "type": [ "integer", "null" ], "format": "int64", "description": "Firewall group members (`null`: 1,000).", "minimum": 0 }, "fwGroups": { "type": [ "integer", "null" ], "format": "int64", "description": "Firewall groups (`null`: 100).", "minimum": 0 }, "fwPolicies": { "type": [ "integer", "null" ], "format": "int64", "description": "Firewall policies (`null`: 50).", "minimum": 0 }, "fwRules": { "type": [ "integer", "null" ], "format": "int64", "description": "Firewall rules (`null`: 500).", "minimum": 0 }, "memoryMib": { "type": [ "integer", "null" ], "format": "int64", "description": "Memory (MiB).", "minimum": 0 }, "publicIpv4": { "type": [ "integer", "null" ], "format": "int64", "description": "Public IPv4 addresses.", "minimum": 0 }, "snapshots": { "type": [ "integer", "null" ], "format": "int64", "description": "Snapshots.", "minimum": 0 }, "trafficGibMonth": { "type": [ "integer", "null" ], "format": "int64", "description": "Traffic per month (GiB; enforced by the traffic accounting).", "minimum": 0 }, "vcpus": { "type": [ "integer", "null" ], "format": "int64", "description": "vCPUs.", "minimum": 0 }, "vms": { "type": [ "integer", "null" ], "format": "int64", "description": "VMs.", "minimum": 0 } } }, "RangeView": { "type": "object", "description": "An IPv4 range.", "required": [ "start", "end" ], "properties": { "end": { "type": "string", "description": "Last address (inclusive)." }, "start": { "type": "string", "description": "First address." } } }, "RdnsMode": { "type": "string", "description": "How a pool's PTR names reach DNS.", "enum": [ "provider", "manual" ] }, "ReconfigureClusterRequest": { "type": "object", "description": "Body of `POST /v1/clusters/{id}/reconfigure` (HA/DRS/migration-policy thin slice).", "properties": { "allowPostcopy": { "type": [ "boolean", "null" ], "description": "Flip `Cluster.migration.allow_postcopy` when set." }, "downtimeLimitMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Set `Cluster.migration.downtime_limit_ms`. Clear with `modify=false`.", "minimum": 0 }, "haEnabled": { "type": [ "boolean", "null" ], "description": "Flip `Cluster.ha.enabled` when set." }, "maxBandwidthMibS": { "type": [ "integer", "null" ], "format": "int64", "description": "Set `Cluster.migration.max_bandwidth_mib_s` (MiB/s). Clear with `modify=false`.", "minimum": 0 }, "modify": { "type": "boolean", "description": "Merge provided fields (default) or replace missing with false/cleared." }, "schedulerAutomatic": { "type": [ "boolean", "null" ], "description": "Flip `Cluster.scheduler.automatic` when set." }, "schedulerEnabled": { "type": [ "boolean", "null" ], "description": "Flip `Cluster.scheduler.enabled` when set." } }, "additionalProperties": false }, "ReconfigureResultView": { "type": "object", "description": "`TaskView.result` of `VirtualMachine.reconfigure`.", "required": [ "generation" ], "properties": { "generation": { "type": "integer", "format": "int64", "description": "Desired-state generation after the change.", "minimum": 0 }, "grownDisks": { "type": "array", "items": { "$ref": "#/components/schemas/GrownDiskView" }, "description": "Disks the task grew, when any." } } }, "ReconfigureScheduledTaskRequest": { "type": "object", "description": "Request to reconfigure a scheduled task (entity is fixed).", "required": [ "name", "action" ], "properties": { "action": { "$ref": "#/components/schemas/ScheduledAction", "description": "Power action." }, "activeTime": { "type": [ "string", "null" ], "description": "Optional scheduler active time." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled." }, "expireTime": { "type": [ "string", "null" ], "description": "Optional scheduler expire time." }, "name": { "type": "string", "description": "Display name." }, "notification": { "type": [ "string", "null" ], "description": "Optional notification address (SMTP send when `[smtp] enabled`)." }, "recurrence": { "$ref": "#/components/schemas/ScheduledRecurrence", "description": "Scheduler cadence." }, "runAt": { "type": [ "string", "null" ], "description": "One-shot run time / create-time anchor (RFC 3339). Defaults to now." } } }, "ReconfigureVmRequest": { "type": "object", "description": "VM reconfigure request.", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/VmConfig", "description": "Body in the `VmConfig` schema (the full desired configuration)." }, "createDisks": { "type": "array", "items": { "$ref": "#/components/schemas/DiskFileRequest" }, "description": "Disk files to create for disks `config` adds (empty images or from an image)." }, "deleteDisks": { "type": "array", "items": { "$ref": "#/components/schemas/DiskFileRequest" }, "description": "Disk files to delete after they leave `config.disks` (detach and destroy). Omit a\nremoved disk here to detach and keep the file on the datastore." }, "growDisks": { "type": "array", "items": { "$ref": "#/components/schemas/DiskFileRequest" }, "description": "Disks of `config` whose capacity grows: the file is grown to `sizeBytes`. On a\nrunning VM the host grows it online where the runtime can; otherwise the change\napplies at the next start (the task result says which)." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "name": { "type": [ "string", "null" ], "description": "New display name (unique within the folder)." } } }, "RecordMetaView": { "type": "object", "description": "Store metadata of a record.", "required": [ "id", "uuid", "version", "createdVersion", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string", "description": "Creation time (RFC 3339)." }, "createdVersion": { "type": "integer", "format": "int64", "description": "Version at creation.", "minimum": 0 }, "id": { "type": "string", "description": "MoRef-compatible id, e.g. `vm-42`." }, "name": { "type": [ "string", "null" ], "description": "Display name." }, "parentId": { "type": [ "string", "null" ], "description": "Parent id in the inventory tree." }, "updatedAt": { "type": "string", "description": "Last update time (RFC 3339)." }, "uuid": { "type": "string", "description": "Globally unique id." }, "version": { "type": "integer", "format": "int64", "description": "Version of the last change (compare-and-set token).", "minimum": 0 } } }, "RecoveryCodesResponse": { "type": "object", "description": "Recovery codes (shown once).", "required": [ "recoveryCodes" ], "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" }, "description": "Ten single-use codes `xxxx-xxxx-xxxx-xxxx`." } } }, "RegisterVmRequest": { "type": "object", "description": "Register an existing VM from a datastore path (`POST /v1/vms/register`,\nSOAP `Folder.RegisterVM_Task`).\n\nReads `[ds] name/.kyvernon-vm.json` written by unregister (or an equivalent\npath such as `[ds] name/name.vmx`) and restores inventory without recreating\ndisks.", "required": [ "folderId", "path" ], "properties": { "asTemplate": { "type": "boolean", "description": "Register as a template." }, "folderId": { "type": "string", "description": "Destination VM folder (`group-vN`)." }, "host": { "type": [ "string", "null" ], "description": "Host (`host-N`). Optional placement hint." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "name": { "type": [ "string", "null" ], "description": "Display name; defaults to the name in the on-disk manifest." }, "path": { "type": "string", "description": "Datastore path (`[ds] name/name.vmx` or `[ds] name/.kyvernon-vm.json`)." }, "resourcePool": { "type": [ "string", "null" ], "description": "Resource pool (`resgroup-N`). Required unless `asTemplate` is true." } } }, "ReinstallServerRequest": { "type": "object", "description": "Request to reinstall a server (its addresses stay).", "properties": { "image": { "type": [ "string", "null" ], "description": "Image (default: the current one)." }, "password": { "type": "boolean", "description": "Generate a password (always when no SSH keys are given)." }, "sshKeys": { "type": "array", "items": { "type": "string" }, "description": "SSH public keys." }, "userData": { "type": [ "string", "null" ], "description": "cloud-init user data." } } }, "ReleasedAddress": { "type": "object", "description": "An address returned to its pool.", "required": [ "pool", "address" ], "properties": { "address": { "type": "string", "description": "The address or /64 prefix." }, "pool": { "type": "string", "description": "The pool." } } }, "RelocateDiskLocator": { "type": "object", "description": "One cold per-disk storage relocate locator (`RelocateVM_Task.spec.disk`).", "required": [ "diskKey", "datastore" ], "properties": { "datastore": { "type": "string", "description": "Destination datastore (`datastore-N`)." }, "diskKey": { "type": "integer", "format": "int32", "description": "Virtual disk device key (`VirtualDevice.key`, typically 2000+).", "minimum": 0 } } }, "RelocateNicChange": { "type": "object", "description": "One RelocateVM Ethernet Edit (`RelocateVM_Task.spec.deviceChange` NIC backing).", "required": [ "nicKey", "network" ], "properties": { "network": { "type": "string", "description": "Destination network or distributed port group (`network-N` / `dvportgroup-N`)." }, "nicKey": { "type": "integer", "format": "int32", "description": "Virtual NIC device key (`VirtualDevice.key`, typically 4000+).", "minimum": 0 } } }, "RelocateVmRequest": { "type": "object", "description": "Relocate a VM (`POST /v1/vms/{id}/relocate`, SOAP `RelocateVM_Task`).\n\nCold storage relocate (`datastore` and/or per-disk `disks` locators) copies\ndisks of a powered-off VM without snapshots onto datastores mounted on the\ncurrent host. `nics` rebinds Ethernet network backing (SOAP\n`spec.deviceChange` Edit). Host / pool / folder placement fields share the\nsame task engine as SOAP. Live Storage vMotion stays refused.", "properties": { "datastore": { "type": [ "string", "null" ], "description": "Destination datastore (`datastore-N`) for every disk not listed in `disks`." }, "disks": { "type": "array", "items": { "$ref": "#/components/schemas/RelocateDiskLocator" }, "description": "Per-disk locators (`diskKey` + datastore). Overrides `datastore` for those keys." }, "folderId": { "type": [ "string", "null" ], "description": "Destination VM folder (`group-vN`)." }, "host": { "type": [ "string", "null" ], "description": "Destination host (`host-N`). Optional; pool placement may choose one." }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "nics": { "type": "array", "items": { "$ref": "#/components/schemas/RelocateNicChange" }, "description": "Ethernet network rebinds (`nicKey` + network). SOAP `deviceChange` Edit." }, "resourcePool": { "type": [ "string", "null" ], "description": "Destination resource pool (`resgroup-N`)." } } }, "RelocatedDiskView": { "type": "object", "description": "One disk relocated by cold storage relocate.", "required": [ "datastore", "path" ], "properties": { "datastore": { "type": "string", "description": "Destination datastore id." }, "path": { "type": "string", "description": "Path below the datastore root." } } }, "RelocatedNicView": { "type": "object", "description": "One NIC rebinding from RelocateVM `deviceChange` / native `nics`.", "required": [ "nicKey", "network" ], "properties": { "network": { "type": "string", "description": "Destination network id." }, "nicKey": { "type": "integer", "format": "int32", "description": "Virtual NIC device key.", "minimum": 0 } } }, "RemovedSnapshotsResultView": { "type": "object", "description": "`TaskView.result` of remove-snapshot / remove-all-snapshots.", "required": [ "removed" ], "properties": { "removed": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Snapshot keys that were removed." } } }, "RenameRequest": { "type": "object", "description": "Body of `POST /v1/inventory/objects/{id}/rename`.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The new name, 1 to 80 characters." } }, "additionalProperties": false }, "RenameResultView": { "type": "object", "description": "`TaskView.result` of rename.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New name." } } }, "RenameSnapshotRequest": { "type": "object", "description": "Rename a snapshot (`POST /v1/vms/{id}/snapshots/{key}/rename`, SOAP\n`VirtualMachineSnapshot.RenameSnapshot`). At least one of `name` or\n`description` is required.", "properties": { "description": { "type": [ "string", "null" ], "description": "New free-text description (empty string clears it)." }, "name": { "type": [ "string", "null" ], "description": "New display name (1..=80 characters, no surrounding spaces)." } } }, "RescueServerRequest": { "type": "object", "description": "Request to boot the rescue image.", "properties": { "image": { "type": [ "string", "null" ], "description": "Rescue image (default: the first catalogue entry marked `rescue`)." } } }, "ResizeServerRequest": { "type": "object", "description": "Request to resize a server.", "required": [ "plan" ], "properties": { "plan": { "type": "string", "description": "The larger plan." } } }, "ResolveMigrationRequest": { "type": "object", "description": "Body for `POST /v1/vms/{id}/resolve-migration`.", "required": [ "resolution" ], "properties": { "host": { "type": [ "string", "null" ], "description": "Destination host (`host-N`). Required when `resolution` is\n`destination-keeps` so inventory placement moves off the source." }, "resolution": { "$ref": "#/components/schemas/FenceResolutionView", "description": "Who keeps the guest (`source-keeps` or `destination-keeps`)." } } }, "ResolveMigrationView": { "type": "object", "description": "Result of resolving a fenced migration.", "required": [ "resolution", "host" ], "properties": { "host": { "type": "string", "description": "Host that now owns the inventory placement." }, "resolution": { "$ref": "#/components/schemas/FenceResolutionView", "description": "Resolution applied." } } }, "ResourceAllocation": { "type": "object", "description": "Reservation/limit/shares for one resource.", "properties": { "expandable_reservation": { "type": "boolean", "description": "Whether the reservation may grow when the parent has headroom." }, "limit": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum amount, `None` for unlimited.", "minimum": 0 }, "reservation": { "type": "integer", "format": "int64", "description": "Guaranteed amount (MHz or MiB).", "minimum": 0 }, "shares": { "type": "integer", "format": "int32", "description": "Custom shares (when level is `Custom`).", "minimum": 0 }, "shares_level": { "$ref": "#/components/schemas/SharesLevel", "description": "Shares level." } }, "additionalProperties": false }, "ResourcePool": { "type": "object", "description": "A resource pool.", "required": [ "name" ], "properties": { "cpu": { "$ref": "#/components/schemas/ResourceAllocation", "description": "CPU allocation in MHz." }, "memory": { "$ref": "#/components/schemas/ResourceAllocation", "description": "Memory allocation in MiB." }, "name": { "type": "string", "description": "Display name (`Resources` for a root pool)." } }, "additionalProperties": false }, "RestorePointRequest": { "type": "object", "description": "Body of `POST /v1/backup/points/{id}/restore`.", "properties": { "datastoreId": { "type": [ "string", "null" ], "description": "Datastore for the new disks (default: the verification pool, else the first usable)." }, "folderId": { "type": [ "string", "null" ], "description": "Folder of the new virtual machine (default: the folder of the source)." }, "hostId": { "type": [ "string", "null" ], "description": "Host of the new virtual machine (default: the host of the source)." }, "mode": { "type": [ "string", "null" ], "description": "`new` (default; also `new_vm`): a new virtual machine with the backed-up disks and\nthe configuration of the source. `in-place` (also `in_place`): the disks of the\nsource, which must be powered off, are replaced by those of the point (task\n`VirtualMachine.restoreBackupInPlace`); `name`, `folderId`, `datastoreId`,\n`hostId` and `powerOn` do not apply." }, "name": { "type": [ "string", "null" ], "description": "Name of the new virtual machine (default: ` (restored)`)." }, "powerOn": { "type": "boolean", "description": "Power the virtual machine on when the restore is done (default false)." }, "verify": { "oneOf": [ { "$ref": "#/components/schemas/VerifySpec", "description": "After the restore, verify the point in quarantine: a separate VM from the point\non this quarantine network, booted and probed (`Global.Settings`). The task fails\nwhen the verification fails; the restored VM stays." }, { "type": "null" } ] } } }, "RestoreSession": { "type": "object", "description": "A restore session as the verification sees it.", "required": [ "vmId", "state", "startedAt", "destroyed" ], "properties": { "backupSessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The backup session restored, for nightly runs." }, "destroyed": { "type": "boolean", "description": "The VM was destroyed after the verdict." }, "evidence": { "oneOf": [ { "$ref": "#/components/schemas/Evidence", "description": "Evidence (present once collected)." }, { "type": "null" } ] }, "finishedAt": { "type": [ "integer", "null" ], "format": "int64", "description": "End, Unix seconds." }, "reason": { "type": [ "string", "null" ], "description": "Message key of the failure." }, "sourceVmId": { "type": [ "string", "null" ], "format": "uuid", "description": "The VM the backup was taken from, for nightly runs." }, "startedAt": { "type": "integer", "format": "int64", "description": "Start, Unix seconds." }, "state": { "$ref": "#/components/schemas/VerifyState", "description": "State." }, "verified": { "type": [ "boolean", "null" ], "description": "The verdict; `None` while running." }, "vmId": { "type": "string", "format": "uuid", "description": "The restored VM's instance uuid." } } }, "RevertSnapshotRequest": { "type": "object", "description": "Revert to a snapshot (`POST /v1/vms/{id}/snapshots/{key}/revert`).", "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "suppressPowerOn": { "type": "boolean", "description": "Do not power the guest on after a memory snapshot revert." } } }, "RoleRequest": { "type": "object", "description": "Role create/update body.", "required": [ "name", "privileges" ], "properties": { "description": { "type": "string", "description": "Description." }, "name": { "type": "string", "description": "Name." }, "privileges": { "type": "array", "items": { "type": "string" }, "description": "Privileges from the catalogue." } } }, "RoleView": { "type": "object", "description": "A role.", "required": [ "id", "name", "description", "privileges", "system" ], "properties": { "description": { "type": "string", "description": "Description." }, "id": { "type": "string", "description": "Role id." }, "name": { "type": "string", "description": "Name." }, "privileges": { "type": "array", "items": { "type": "string" }, "description": "Privileges." }, "system": { "type": "boolean", "description": "Built-in." } } }, "RuleBody": { "type": "object", "description": "A rule as written by a client.", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/ActionView", "description": "Action." }, "appliedTo": { "type": "array", "items": { "type": "string" }, "description": "Groups the rule applies to (empty: the policy's)." }, "destinations": { "type": "array", "items": { "type": "string" }, "description": "Destinations (empty: any)." }, "destinationsNegated": { "type": "boolean", "description": "Match everything except the destinations." }, "direction": { "$ref": "#/components/schemas/DirectionView", "description": "Direction (default `in-out`)." }, "enabled": { "type": "boolean", "description": "Enabled (default true)." }, "id": { "type": [ "string", "null" ], "description": "Id of an existing rule (policy `PUT`: keeps its number and counters); ignored\nwhen a rule is added." }, "ipVersion": { "$ref": "#/components/schemas/IpVersionView", "description": "IP families (default `any`)." }, "logged": { "type": "boolean", "description": "Log matches." }, "name": { "type": "string", "description": "Display name." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEntryView" }, "description": "Services (empty: any IP traffic)." }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Sources: group ids, addresses or prefixes (empty: any)." }, "sourcesNegated": { "type": "boolean", "description": "Match everything except the sources." } }, "additionalProperties": false }, "RuleStatsView": { "type": "object", "description": "Counters of one rule.", "required": [ "number", "supported", "packets", "bytes", "hosts" ], "properties": { "bytes": { "type": "integer", "format": "int64", "description": "Bytes, all hosts.", "minimum": 0 }, "hosts": { "type": "object", "description": "Per host.", "additionalProperties": { "$ref": "#/components/schemas/HostCountView" }, "propertyNames": { "type": "string" } }, "lastHit": { "type": [ "string", "null" ], "description": "Last report with a non-zero count." }, "number": { "type": "integer", "format": "int32", "description": "Rule number.", "minimum": 0 }, "packets": { "type": "integer", "format": "int64", "description": "Packets, all hosts.", "minimum": 0 }, "policy": { "type": [ "string", "null" ], "description": "Policy id (when the rule still exists)." }, "supported": { "type": "boolean", "description": "Hit counters are kept for this rule (host bridges, and segment ports when the\ncontroller reads the Southbound database; `false` otherwise, §6.3)." } } }, "RuleView": { "allOf": [ { "$ref": "#/components/schemas/RuleBody", "description": "The rule (`id` is set)." }, { "type": "object", "required": [ "number", "policy", "position" ], "properties": { "fwVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Store version of this write.", "minimum": 0 }, "number": { "type": "integer", "format": "int32", "description": "Domain-unique rule number (logs, counters, flow cookies).", "minimum": 0 }, "pendingHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts that had not applied the change when `?wait=realized` timed out." }, "policy": { "type": "string", "description": "Policy id." }, "position": { "type": "integer", "format": "int32", "description": "Position in the policy (0 first).", "minimum": 0 }, "version": { "type": [ "integer", "null" ], "format": "int64", "description": "Policy record version after this write (writes only).", "minimum": 0 } } } ], "description": "A rule." }, "ScheduledAction": { "type": "string", "description": "Power action a scheduled task may invoke (M1-CP-03 thin slice).", "enum": [ "power_on", "power_off" ] }, "ScheduledRecurrence": { "oneOf": [ { "type": "object", "description": "`OnceTaskScheduler` (uses `ScheduledTask.run_at`).", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "once" ] } } }, { "type": "object", "description": "`HourlyTaskScheduler`: every `interval` hours at `minute`.", "required": [ "interval", "minute", "kind" ], "properties": { "interval": { "type": "integer", "format": "int32", "description": "Hours between runs (`RecurrentTaskScheduler.interval`, min 1).", "minimum": 0 }, "kind": { "type": "string", "enum": [ "hourly" ] }, "minute": { "type": "integer", "format": "int32", "description": "Minute of the hour (0 to 59).", "minimum": 0 } } }, { "type": "object", "description": "`DailyTaskScheduler`: every `interval` days at `hour`:`minute`.", "required": [ "interval", "hour", "minute", "kind" ], "properties": { "hour": { "type": "integer", "format": "int32", "description": "Hour of day (0 to 23, UTC).", "minimum": 0 }, "interval": { "type": "integer", "format": "int32", "description": "Days between runs (min 1).", "minimum": 0 }, "kind": { "type": "string", "enum": [ "daily" ] }, "minute": { "type": "integer", "format": "int32", "description": "Minute of the hour (0 to 59).", "minimum": 0 } } }, { "type": "object", "description": "`WeeklyTaskScheduler`: selected weekdays every `interval` weeks.", "required": [ "interval", "hour", "minute", "kind" ], "properties": { "friday": { "type": "boolean", "description": "Friday." }, "hour": { "type": "integer", "format": "int32", "description": "Hour of day (0 to 23, UTC).", "minimum": 0 }, "interval": { "type": "integer", "format": "int32", "description": "Weeks between runs (min 1).", "minimum": 0 }, "kind": { "type": "string", "enum": [ "weekly" ] }, "minute": { "type": "integer", "format": "int32", "description": "Minute of the hour (0 to 59).", "minimum": 0 }, "monday": { "type": "boolean", "description": "Monday." }, "saturday": { "type": "boolean", "description": "Saturday." }, "sunday": { "type": "boolean", "description": "Sunday." }, "thursday": { "type": "boolean", "description": "Thursday." }, "tuesday": { "type": "boolean", "description": "Tuesday." }, "wednesday": { "type": "boolean", "description": "Wednesday." } } }, { "type": "object", "description": "`MonthlyByDayTaskScheduler`: day-of-month every `interval` months.", "required": [ "interval", "hour", "minute", "day", "kind" ], "properties": { "day": { "type": "integer", "format": "int32", "description": "Day of month (`1` to `31`), or `-1` for the last day." }, "hour": { "type": "integer", "format": "int32", "description": "Hour of day (0 to 23, UTC).", "minimum": 0 }, "interval": { "type": "integer", "format": "int32", "description": "Months between runs (min 1).", "minimum": 0 }, "kind": { "type": "string", "enum": [ "monthly_by_day" ] }, "minute": { "type": "integer", "format": "int32", "description": "Minute of the hour (0 to 59).", "minimum": 0 } } }, { "type": "object", "description": "`MonthlyByWeekdayTaskScheduler`: Nth weekday every `interval` months.", "required": [ "interval", "hour", "minute", "offset", "weekday", "kind" ], "properties": { "hour": { "type": "integer", "format": "int32", "description": "Hour of day (0 to 23, UTC).", "minimum": 0 }, "interval": { "type": "integer", "format": "int32", "description": "Months between runs (min 1).", "minimum": 0 }, "kind": { "type": "string", "enum": [ "monthly_by_weekday" ] }, "minute": { "type": "integer", "format": "int32", "description": "Minute of the hour (0 to 59).", "minimum": 0 }, "offset": { "$ref": "#/components/schemas/MonthWeekOffset", "description": "Week-of-month offset (`first`…`fourth` / `last`)." }, "weekday": { "type": "integer", "format": "int32", "description": "Weekday (`0` = Sunday … `6` = Saturday).", "minimum": 0 } } } ], "description": "Scheduler kind persisted for a scheduled task (M1-CP-03).\n\nOne-shot tasks use [`ScheduledTask::run_at`]. Recurrent variants store their\ncadence here; missing field deserialises as [`ScheduledRecurrence::Once`]." }, "ScheduledTaskState": { "type": "string", "description": "Lifecycle of a scheduled task (maps to `TaskInfoState` on the wire).", "enum": [ "queued", "running", "success", "error" ] }, "ScheduledTaskView": { "type": "object", "description": "A scheduled power task (native `/v1/scheduled-tasks`, M1-CP-03).", "required": [ "id", "name", "description", "entityId", "enabled", "action", "recurrence", "runAt", "state", "createdBy" ], "properties": { "action": { "$ref": "#/components/schemas/ScheduledAction", "description": "Power action." }, "activeTaskId": { "type": [ "string", "null" ], "description": "Active power-task id, if any." }, "activeTime": { "type": [ "string", "null" ], "description": "Optional scheduler active time." }, "createdBy": { "type": "string", "description": "Creating user." }, "description": { "type": "string", "description": "Description." }, "enabled": { "type": "boolean", "description": "Enabled." }, "entityId": { "type": "string", "description": "Target VM id." }, "expireTime": { "type": [ "string", "null" ], "description": "Optional scheduler expire time." }, "id": { "type": "string", "description": "Scheduled-task id (`schedule-N`)." }, "lastError": { "type": [ "string", "null" ], "description": "Last error message when `state` is `error`." }, "name": { "type": "string", "description": "Display name." }, "nextRunTime": { "type": [ "string", "null" ], "description": "Next run time." }, "notification": { "type": [ "string", "null" ], "description": "Optional notification address (SMTP send when `[smtp] enabled`)." }, "prevRunTime": { "type": [ "string", "null" ], "description": "Previous run time." }, "recurrence": { "$ref": "#/components/schemas/ScheduledRecurrence", "description": "Scheduler cadence." }, "runAt": { "type": "string", "description": "One-shot run time / create-time anchor (RFC 3339)." }, "state": { "$ref": "#/components/schemas/ScheduledTaskState", "description": "Lifecycle state." } } }, "SerialLogView": { "type": "object", "description": "Tail of a VM's serial console log (Kyvernon VMM has no graphical console yet).", "required": [ "text", "bytes", "totalBytes", "truncated", "available" ], "properties": { "available": { "type": "boolean", "description": "True when a serial log file is configured for the VM." }, "bytes": { "type": "integer", "format": "int64", "description": "Bytes returned.", "minimum": 0 }, "text": { "type": "string", "description": "Log text (lossy UTF-8). Empty when the file is not there yet." }, "totalBytes": { "type": "integer", "format": "int64", "description": "Total size of the log file on the host when read.", "minimum": 0 }, "truncated": { "type": "boolean", "description": "True when the file was larger than the returned window." } } }, "SeriesView": { "type": "object", "description": "One series, column-oriented: `values[i]` was measured over the interval ending at\n`timestamps[i]`.", "required": [ "entity", "counterId", "counter", "instance", "unit", "interval", "timestamps", "values" ], "properties": { "counter": { "type": "string", "description": "Counter name." }, "counterId": { "type": "integer", "format": "int32", "description": "Counter id." }, "entity": { "type": "string", "description": "Entity id." }, "entityName": { "type": [ "string", "null" ], "description": "Entity name." }, "instance": { "type": "string", "description": "Instance (`\"\"` = aggregate)." }, "interval": { "type": "integer", "format": "int32", "description": "Sampling period of the points.", "minimum": 0 }, "timestamps": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Interval end times, Unix seconds, ascending." }, "unit": { "type": "string", "description": "Unit key; percent values are 0..100." }, "values": { "type": "array", "items": { "type": "number", "format": "double" }, "description": "Values." } } }, "ServerAddressBody": { "type": "object", "description": "Body of `POST /v1/vms/{id}/addresses`.", "properties": { "ipv6": { "type": [ "boolean", "null" ], "description": "Also a /64 when the pool has IPv6 (default true)." }, "pool": { "type": [ "string", "null" ], "description": "Pool (absent: the first pool on the VM's networks with a free address)." }, "reference": { "type": [ "string", "null" ], "description": "Caller reference." }, "tenant": { "type": [ "string", "null" ], "description": "Tenant (quota)." } }, "additionalProperties": false }, "ServerAddressUsage": { "type": "object", "description": "Public addresses of one server.", "required": [ "vm", "primaryIpv4", "extraIpv4", "extra", "ipv6Prefixes" ], "properties": { "extra": { "type": "array", "items": { "$ref": "#/components/schemas/AddressSince" }, "description": "The extra addresses with the time they were allocated (for proration)." }, "extraIpv4": { "type": "integer", "format": "int32", "description": "Extra IPv4 addresses (billed as add-on).", "minimum": 0 }, "ipv6Prefixes": { "type": "integer", "format": "int32", "description": "/64 prefixes.", "minimum": 0 }, "primaryIpv4": { "type": "integer", "format": "int32", "description": "Primary addresses (one per NIC; part of the plan).", "minimum": 0 }, "vm": { "type": "string", "description": "VM id." } } }, "ServerAddresses": { "type": "object", "description": "What server create gets back: the addresses to put in the guest's configuration.", "required": [ "mac", "prefixLen", "dnsServers" ], "properties": { "dnsServers": { "type": "array", "items": { "type": "string" }, "description": "DNS servers." }, "gateway": { "type": [ "string", "null" ], "description": "IPv4 gateway." }, "ipv4": { "type": [ "string", "null" ], "description": "Primary IPv4 address (the NIC's DHCP lease)." }, "ipv6Address": { "type": [ "string", "null" ], "description": "The suggested IPv6 address (`::1`, the block itself for a /128), configured\nwith `ipv6OnlinkLen`." }, "ipv6Gateway": { "type": [ "string", "null" ], "description": "The IPv6 gateway (the router's link-local or on-link address)." }, "ipv6OnlinkLen": { "type": [ "integer", "null" ], "format": "int32", "description": "Prefix length the guest configures on `ipv6Address` (the segment's on-link prefix,\nat least 64), so the gateway is on-link with a standard configuration.", "minimum": 0 }, "ipv6Prefix": { "type": [ "string", "null" ], "description": "The server's IPv6 block (a /64 by default, a /112 per VPS on a shared /64)." }, "ipv6PrefixLen": { "type": [ "integer", "null" ], "format": "int32", "description": "Length of the server's block (`ipv6Prefix/ipv6PrefixLen`): what port security allows.", "minimum": 0 }, "mac": { "type": "string", "description": "NIC MAC the addresses are bound to." }, "pool": { "type": [ "string", "null" ], "description": "The pool." }, "prefixLen": { "type": "integer", "format": "int32", "description": "Prefix length of the IPv4 subnet.", "minimum": 0 } } }, "ServerPowerRequest": { "type": "object", "description": "A power action.", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "`on`, `off` (hard), `shutdown` (through the guest, then hard), `reboot` or\n`reset`." } } }, "ServerSnapshotRequest": { "type": "object", "description": "Request to snapshot a server.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Snapshot name (1..=80 characters)." } } }, "ServerSnapshotView": { "type": "object", "description": "A snapshot of a server.", "required": [ "key", "name", "createdAt" ], "properties": { "createdAt": { "type": "string", "description": "Taken." }, "key": { "type": "integer", "format": "int32", "description": "Key.", "minimum": 0 }, "name": { "type": "string", "description": "Name." } } }, "ServerTaskView": { "type": "object", "description": "The answer of a server operation: its task, and a generated password once.", "required": [ "taskId", "serverId" ], "properties": { "password": { "type": [ "string", "null" ], "description": "The generated password: shown only in this answer, never stored in clear." }, "rebootRequired": { "type": "boolean", "description": "The operation reboots the server (resize)." }, "serverId": { "type": "string", "description": "The server." }, "taskId": { "type": "string", "description": "The task to poll (`GET /v1/tasks/{id}`)." } } }, "ServerUsageView": { "type": "object", "description": "One server's usage in a month.", "required": [ "server", "hostname", "state", "plans", "snapshotGibHours" ], "properties": { "hostname": { "type": "string", "description": "Host name." }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanHoursView" }, "description": "Hours per plan (proration over a resize)." }, "server": { "type": "string", "description": "Server." }, "snapshotGibHours": { "type": "number", "format": "double", "description": "Snapshot GiB-hours (provisioned size of the VM's disks per snapshot)." }, "state": { "type": "string", "description": "State now." }, "vm": { "type": [ "string", "null" ], "description": "VM (while it exists)." } } }, "ServerView": { "type": "object", "description": "A self-service server.", "required": [ "id", "tenant", "hostname", "state", "plan", "planName", "image", "imageName", "addresses", "snapshots", "passwordPending", "createdAt" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "Public addresses." }, "createTask": { "type": [ "string", "null" ], "description": "The create task." }, "createdAt": { "type": "string", "description": "Created." }, "deletedAt": { "type": [ "string", "null" ], "description": "Deleted." }, "error": { "type": "string", "description": "Why the create failed." }, "hostname": { "type": "string", "description": "Host name." }, "id": { "type": "string", "description": "`server-N`." }, "image": { "type": "string", "description": "Image." }, "imageName": { "type": "string", "description": "Image name." }, "passwordPending": { "type": "boolean", "description": "A new password is applied at the next boot." }, "plan": { "type": "string", "description": "Plan." }, "planName": { "type": "string", "description": "Plan name." }, "powerState": { "type": [ "string", "null" ], "description": "Power state of the VM." }, "rescueSince": { "type": [ "string", "null" ], "description": "In rescue mode since." }, "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/ServerSnapshotView" }, "description": "Snapshots." }, "state": { "type": "string", "description": "`creating`, `active`, `rescue`, `deleted` or `failed`." }, "tenant": { "type": "string", "description": "Tenant." }, "vmId": { "type": [ "string", "null" ], "description": "The VM." } } }, "ServiceAccountRequest": { "type": "object", "description": "Service-account flag.", "required": [ "serviceAccount" ], "properties": { "serviceAccount": { "type": "boolean", "description": "Whether the account is a service account." } } }, "ServiceBody": { "type": "object", "description": "Create or replace a named service.", "required": [ "name", "entries" ], "properties": { "description": { "type": "string", "description": "Description." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEntryView" }, "description": "Entries (no named services inside)." }, "name": { "type": "string", "description": "Name." } }, "additionalProperties": false }, "ServiceEntryView": { "type": "object", "description": "One service entry: `tcp`, `udp` or `sctp` with destination ports (`\"443\"`,\n`\"1000-1999\"`; empty: any port), `icmp4` or `icmp6` with an optional type and code,\n`ip` with a protocol number, or `named` with the id of a named service.", "required": [ "protocol" ], "properties": { "icmpCode": { "type": [ "integer", "null" ], "format": "int32", "description": "ICMP code (needs a type).", "minimum": 0 }, "icmpType": { "type": [ "integer", "null" ], "format": "int32", "description": "ICMP type.", "minimum": 0 }, "id": { "type": [ "string", "null" ], "description": "Named service id (`named`)." }, "number": { "type": [ "integer", "null" ], "format": "int32", "description": "IP protocol number (`ip`).", "minimum": 0 }, "ports": { "type": "array", "items": { "type": "string" }, "description": "Destination ports or ranges (TCP, UDP, SCTP)." }, "protocol": { "type": "string", "description": "`tcp`, `udp`, `sctp`, `icmp4`, `icmp6`, `ip` or `named`." }, "sourcePorts": { "type": "array", "items": { "type": "string" }, "description": "Source ports or ranges (TCP, UDP, SCTP; empty: any)." } }, "additionalProperties": false }, "ServiceView": { "allOf": [ { "$ref": "#/components/schemas/ServiceBody", "description": "The definition." }, { "type": "object", "required": [ "id", "version", "builtin" ], "properties": { "builtin": { "type": "boolean", "description": "Built in (read-only)." }, "fwVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Store version of this write.", "minimum": 0 }, "id": { "type": "string", "description": "`fwsvc-N`." }, "pendingHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts that had not applied the change when `?wait=realized` timed out." }, "tenant": { "type": [ "string", "null" ], "description": "Owner (`null`: provider)." }, "version": { "type": "integer", "format": "int64", "description": "Record version.", "minimum": 0 } } } ], "description": "A named service." }, "SessionInfoView": { "type": "object", "description": "A session (administrator view; no token material).", "required": [ "id", "username", "kind", "createdAt", "lastActive", "expiresAt", "clientAddress", "breakGlass" ], "properties": { "breakGlass": { "type": "boolean", "description": "Break-glass." }, "clientAddress": { "type": "string", "description": "Client address." }, "createdAt": { "type": "string", "description": "Created." }, "expiresAt": { "type": "string", "description": "Expires." }, "id": { "type": "string", "description": "Session id." }, "kind": { "type": "string", "description": "`interactive` or `api`." }, "lastActive": { "type": "string", "description": "Last activity." }, "username": { "type": "string", "description": "Username." } } }, "SessionStateView": { "type": "string", "description": "OpenAPI stand-in for `SessionState`.", "enum": [ "REQUESTED", "SNAPSHOT_TAKEN", "EXPORTING", "COMPLETED", "ABORTED", "EXPIRED" ] }, "SessionView": { "type": "object", "description": "An issued session.", "required": [ "token", "sessionId", "expiresAt", "user", "passwordRotationRequired", "mfaEnrolmentRequired" ], "properties": { "expiresAt": { "type": "string", "description": "Hard expiry." }, "mfaEnrolmentRequired": { "type": "boolean", "description": "MFA enrolment must be completed before other calls succeed." }, "passwordRotationRequired": { "type": "boolean", "description": "The password must be changed before other calls succeed." }, "sessionId": { "type": "string", "description": "Session id." }, "token": { "type": "string", "description": "Bearer token; shown once." }, "user": { "$ref": "#/components/schemas/UserView", "description": "User." } } }, "SetEnabledRequest": { "type": "object", "description": "Enable/disable request.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enabled." } } }, "SetPermissionRequest": { "type": "object", "description": "Set-permission request.", "required": [ "entityId", "principal", "roleId" ], "properties": { "entityId": { "type": "string", "description": "Entity id." }, "principal": { "$ref": "#/components/schemas/PrincipalView", "description": "Principal." }, "propagate": { "type": "boolean", "description": "Propagate (default true)." }, "roleId": { "type": "string", "description": "Role id." } } }, "SetSoftwareIscsiRequest": { "type": "object", "description": "Body for `PUT /v1/hosts/{id}/iscsi/software`.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Enable or disable the software iSCSI initiator." } }, "additionalProperties": false }, "SettingsView": { "type": "object", "description": "Domain-wide firewall settings.", "required": [ "logRatePps", "rejectRatePps", "flowLimitPerBridge", "ctLimitPerPort", "monitorReportDays", "enforceNew" ], "properties": { "ctLimitPerPort": { "type": "integer", "format": "int32", "description": "Connection-tracking entries per vNIC.", "minimum": 0 }, "enforceNew": { "type": "boolean", "description": "vNICs added to VMs from now on start in mode `enforce` (default `false`: mode\n`off`); existing vNICs are not changed." }, "flowLimitPerBridge": { "type": "integer", "format": "int32", "description": "Firewall flows per host bridge.", "minimum": 0 }, "logRatePps": { "type": "integer", "format": "int32", "description": "Log rate per host (packets per second, meter `kyv-fw-log`).", "minimum": 0 }, "monitorReportDays": { "type": "integer", "format": "int32", "description": "Days a monitor report covers.", "minimum": 0 }, "rejectRatePps": { "type": "integer", "format": "int32", "description": "Reject answers per second per bridge (meter `kyv-fw-reject`).", "minimum": 0 }, "version": { "type": "integer", "format": "int64", "description": "Record version (ignored in requests).", "minimum": 0 } }, "additionalProperties": false }, "SeverityView": { "type": "string", "description": "Event severity.", "enum": [ "info", "warning", "error", "user" ] }, "SharesLevel": { "type": "string", "description": "Shares level for a resource allocation.", "enum": [ "low", "normal", "high", "custom" ] }, "ShutdownRequest": { "type": "object", "description": "Graceful shutdown of a VM (`POST /v1/vms/{id}/shutdown`).", "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key." }, "timeoutSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long the guest gets to shut down before the VM is powered off hard (seconds,\n1 to 3600; default 90).", "minimum": 0 } } }, "SimulateBody": { "type": "object", "description": "A packet to evaluate at a vNIC.", "required": [ "vm", "direction", "protocol", "peer" ], "properties": { "direction": { "type": "string", "description": "`in` (to the vNIC) or `out` (from it)." }, "icmpCode": { "type": [ "integer", "null" ], "format": "int32", "description": "ICMP code.", "minimum": 0 }, "icmpType": { "type": [ "integer", "null" ], "format": "int32", "description": "ICMP type.", "minimum": 0 }, "local": { "type": [ "string", "null" ], "description": "The vNIC's own address (default: its first address of the peer's family)." }, "nic": { "type": [ "string", "null" ], "description": "NIC key (default: the VM's first host-bridge NIC)." }, "peer": { "type": "string", "description": "The other end's address." }, "port": { "type": [ "integer", "null" ], "format": "int32", "description": "Destination port (TCP, UDP).", "minimum": 0 }, "protocol": { "type": "string", "description": "`tcp`, `udp`, `icmp4`, `icmp6` or a protocol number." }, "state": { "type": [ "string", "null" ], "description": "Connection state: `new` (default), `established`." }, "vm": { "type": "string", "description": "VM id." } }, "additionalProperties": false }, "SimulateView": { "type": "object", "description": "The verdict of a simulated packet (the vNIC evaluated as if in mode `enforce`).", "required": [ "verdict", "rule", "stage", "mode" ], "properties": { "category": { "oneOf": [ { "$ref": "#/components/schemas/CategoryView", "description": "Category of that rule." }, { "type": "null" } ] }, "mode": { "$ref": "#/components/schemas/ModeView", "description": "The vNIC's current mode (in `monitor` a drop is forwarded and reported; in `off`\nnothing is evaluated)." }, "policy": { "type": [ "string", "null" ], "description": "Policy of that rule." }, "rule": { "type": "integer", "format": "int32", "description": "Rule number that decided (0: default, state or system traffic).", "minimum": 0 }, "stage": { "type": "string", "description": "`system`, `state`, `rule`, `default` (where the decision was made)." }, "verdict": { "type": "string", "description": "`allow`, `drop` or `reject`." } } }, "SmtpBody": { "type": "object", "description": "Body of `PUT /v1/vms/{id}/smtp`.", "required": [ "unblocked" ], "properties": { "reason": { "type": [ "string", "null" ], "description": "Why (stored in the audit event, e.g. the portal's ticket)." }, "unblocked": { "type": "boolean", "description": "`true`: allow port 25 for this VM in both families; `false`: the pools' setting." } }, "additionalProperties": false }, "SmtpPolicy": { "type": "string", "description": "Outgoing SMTP (TCP 25) of the guests of a pool, per address family.", "enum": [ "allowed", "blocked" ] }, "SmtpView": { "type": "object", "description": "SMTP state of one VM.", "required": [ "vm", "unblocked", "ipv4Blocked", "ipv6Blocked" ], "properties": { "ipv4Blocked": { "type": "boolean", "description": "Outgoing SMTP over IPv4 is dropped now." }, "ipv6Blocked": { "type": "boolean", "description": "Outgoing SMTP over IPv6 is dropped now." }, "unblocked": { "type": "boolean", "description": "The VM is unblocked (its pools' blocks do not apply)." }, "vm": { "type": "string", "description": "VM id." } } }, "SnapshotKeyResultView": { "type": "object", "description": "`TaskView.result` of revert-snapshot (the key that is now current).", "required": [ "snapshot" ], "properties": { "snapshot": { "type": "integer", "format": "int32", "description": "Snapshot key.", "minimum": 0 } } }, "StartBackupRequest": { "type": "object", "description": "Body of `POST /v1/backup/points`.", "required": [ "vmId" ], "properties": { "full": { "type": [ "boolean", "null" ], "description": "Transfer every allocated area even when change tracking could give an incremental\nbackup." }, "quiesce": { "oneOf": [ { "$ref": "#/components/schemas/QuiesceModeView", "description": "Quiescing; default: `defaultQuiesce` of the backup settings." }, { "type": "null" } ] }, "vmId": { "type": "string", "description": "Virtual machine: instance uuid or id (`vm-N`)." } } }, "SubscriptionView": { "type": "object", "description": "A webhook subscription (secret never returned).", "required": [ "id", "name", "url", "eventTypes", "labels", "enabled", "maxAttempts", "deadLetters", "delivered", "failed" ], "properties": { "deadLetters": { "type": "integer", "format": "int32", "description": "Dead letters currently parked.", "minimum": 0 }, "delivered": { "type": "integer", "format": "int64", "description": "Successful deliveries.", "minimum": 0 }, "enabled": { "type": "boolean", "description": "Enabled." }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Event types delivered (empty = all)." }, "failed": { "type": "integer", "format": "int64", "description": "Failed deliveries (after all attempts).", "minimum": 0 }, "id": { "type": "string", "description": "Id." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels (alarm actions reference them)." }, "maxAttempts": { "type": "integer", "format": "int32", "description": "Delivery attempts per event.", "minimum": 0 }, "name": { "type": "string", "description": "Name." }, "tenant": { "type": [ "string", "null" ], "description": "Tenant filter (`tenant-N`): only that tenant's self-service events." }, "url": { "type": "string", "description": "Target URL." } } }, "Tag": { "type": "object", "description": "A tag. Its parent record is its category; attachments are stored on the\ntag so that listing tags of an object is one lookup through `attached_to`.", "required": [ "name" ], "properties": { "attached_to": { "type": "array", "items": { "type": "string" }, "description": "Objects this tag is attached to." }, "description": { "type": "string", "description": "Description." }, "name": { "type": "string", "description": "Display name." } }, "additionalProperties": false }, "TagCategory": { "type": "object", "description": "A tag category.", "required": [ "name" ], "properties": { "associable_kinds": { "type": "array", "items": { "type": "string" }, "description": "Kinds the tags may be attached to (empty = any inventory kind)." }, "cardinality": { "$ref": "#/components/schemas/Cardinality", "description": "Cardinality." }, "description": { "type": "string", "description": "Description." }, "name": { "type": "string", "description": "Display name." }, "provider_managed": { "type": "boolean", "description": "Tags of this category are attached by the provider only, and only they count in\nthe tag criteria of provider firewall groups (`docs/network/DFW-HOSTBRIDGE.md` §5).\nTenant users cannot attach or detach them." } }, "additionalProperties": false }, "TagCategoryBody": { "type": "object", "description": "Body of `PUT /v1/firewall/tag-categories/{id}`.", "required": [ "providerManaged" ], "properties": { "providerManaged": { "type": "boolean", "description": "Provider-managed." } }, "additionalProperties": false }, "TagCategoryView": { "type": "object", "description": "A tag category and whether it is provider-managed.", "required": [ "id", "name", "providerManaged" ], "properties": { "id": { "type": "string", "description": "`category-N`." }, "name": { "type": "string", "description": "Name." }, "providerManaged": { "type": "boolean", "description": "Only the provider attaches its tags; provider groups evaluate only such categories." } } }, "TagObjectsRequest": { "type": "object", "description": "Body of `POST /v1/tags/{id}/attach` and `POST /v1/tags/{id}/detach`.", "required": [ "objectIds" ], "properties": { "objectIds": { "type": "array", "items": { "type": "string" }, "description": "Inventory object ids (at most 1000). Every object is checked before any change is\nmade: one refusal leaves all objects as they were." } }, "additionalProperties": false }, "TagView": { "type": "object", "description": "A tag: category name and value.", "required": [ "category", "value" ], "properties": { "category": { "type": "string", "description": "Category name." }, "value": { "type": "string", "description": "Tag name." } }, "additionalProperties": false }, "TaggedObjectView": { "type": "object", "description": "An object a tag is attached to.", "required": [ "id", "kind", "name" ], "properties": { "id": { "type": "string", "description": "Object id." }, "kind": { "type": "string", "description": "Kind (`virtual_machine`, `host`, ...)." }, "name": { "type": "string", "description": "Name." } } }, "TaskRef": { "type": "object", "description": "Reference to a task created by a long-running operation.", "required": [ "taskId" ], "properties": { "taskId": { "type": "string", "description": "The task id to poll." } } }, "TaskResultView": { "oneOf": [ { "$ref": "#/components/schemas/PowerResultView" }, { "$ref": "#/components/schemas/ReconfigureResultView" }, { "$ref": "#/components/schemas/CreatedObjectResultView" }, { "$ref": "#/components/schemas/SnapshotKeyResultView" }, { "$ref": "#/components/schemas/RemovedSnapshotsResultView" }, { "$ref": "#/components/schemas/RenameResultView" }, { "$ref": "#/components/schemas/MaintenanceModeResultView" }, { "$ref": "#/components/schemas/CustomizeResultView" }, { "$ref": "#/components/schemas/MigrateResultView" } ], "description": "Success payload of a completed task. Shape depends on the operation: power → `PowerResultView`; reconfigure → `ReconfigureResultView`; create/clone/AddHost/CreateSnapshot → `CreatedObjectResultView`; revert snapshot → `SnapshotKeyResultView`; remove snapshots → `RemovedSnapshotsResultView`; rename → `RenameResultView`; enter/exit maintenance → `MaintenanceModeResultView`; customize → `CustomizeResultView`; migrate/relocate → `MigrateResultView`. Destroy and similar operations leave `result` null." }, "TaskStateView": { "type": "string", "description": "Task state.", "enum": [ "queued", "running", "success", "error", "cancelled" ] }, "TaskView": { "type": "object", "description": "A task.", "required": [ "id", "descriptionId", "messageId", "args", "state", "progress", "targetName", "initiator", "chainId", "queuedAt", "retryable", "attempt", "cancelRequested" ], "properties": { "args": { "type": "object", "description": "Message arguments.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "attempt": { "type": "integer", "format": "int32", "description": "Attempts so far.", "minimum": 0 }, "cancelRequested": { "type": "boolean", "description": "Cancellation requested." }, "chainId": { "type": "string", "description": "Correlation id grouping tasks and events of one action." }, "completedAt": { "type": [ "string", "null" ], "description": "Completed at." }, "descriptionId": { "type": "string", "description": "Operation id in vSphere style (`VirtualMachine.powerOn`)." }, "error": { "oneOf": [ { "$ref": "#/components/schemas/ErrorBody", "description": "Error when failed." }, { "type": "null" } ] }, "id": { "type": "string", "description": "Task id (`task-N`)." }, "initiator": { "type": "string", "description": "Submitting user." }, "messageId": { "type": "string", "description": "Localisable message key (`task.virtual_machine.power_on`)." }, "progress": { "type": "integer", "format": "int32", "description": "Progress 0..=100.", "minimum": 0 }, "queuedAt": { "type": "string", "description": "Queued at." }, "result": { "oneOf": [ { "$ref": "#/components/schemas/TaskResultView", "description": "Result on success (`TaskResultView`: oneOf of the known operation payloads).\nDestroy and similar leave it null." }, { "type": "null" } ] }, "retryable": { "type": "boolean", "description": "Whether the failure is retryable." }, "startedAt": { "type": [ "string", "null" ], "description": "Started at." }, "state": { "$ref": "#/components/schemas/TaskStateView", "description": "State." }, "targetId": { "type": [ "string", "null" ], "description": "Target object id." }, "targetName": { "type": "string", "description": "Target name at submission." }, "targetType": { "type": [ "string", "null" ], "description": "Target short type." } } }, "TcpEvidence": { "type": "object", "description": "Host-side TCP checks from the quarantine probe netns.", "properties": { "address": { "type": [ "string", "null" ], "description": "Address that was probed (the leased address)." }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/TcpPortEvidence" }, "description": "Per-port results (empty when no TCP check was requested)." } } }, "TcpPortEvidence": { "type": "object", "description": "One TCP port checked from the quarantine probe.", "required": [ "port", "ok", "elapsedMs" ], "properties": { "elapsedMs": { "type": "integer", "format": "int64", "description": "Wall time of the attempt.", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Short error when `ok` is false." }, "ok": { "type": "boolean", "description": "Whether the connect succeeded." }, "port": { "type": "integer", "format": "int32", "description": "Port number.", "minimum": 0 } } }, "TemplateBody": { "type": "object", "description": "Body of `PUT /v1/firewall/templates/{id}` (a provider template).", "required": [ "rules" ], "properties": { "description": { "type": "string", "description": "What it opens." }, "note": { "type": [ "string", "null" ], "description": "What to know before applying it." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateRuleBody" }, "description": "The rules (1 to 50)." } }, "additionalProperties": false }, "TemplateRuleBody": { "type": "object", "description": "One rule of a provider template: allow, direction `in`.", "required": [ "services" ], "properties": { "from": { "type": "array", "items": { "type": "string" }, "description": "Sources allowed (addresses or prefixes; empty: any)." }, "ipVersion": { "$ref": "#/components/schemas/IpVersionView", "description": "IP families (default `any`)." }, "name": { "type": "string", "description": "Rule name (default: the template id)." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEntryView" }, "description": "Services: entries of the native form; `named` names a built-in or provider service." } }, "additionalProperties": false }, "TemplateView": { "type": "object", "description": "A rule template (§6.6): rules added to the VM's own policy, direction `in`.", "required": [ "id", "description", "rules" ], "properties": { "builtin": { "type": "boolean", "description": "Built in (read-only); the provider's own templates are not." }, "description": { "type": "string", "description": "What it opens." }, "id": { "type": "string", "description": "`ssh-only`, `web`, `mail-server`." }, "note": { "type": [ "string", "null" ], "description": "What to know before applying it." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleBody" }, "description": "The rules it adds." }, "version": { "type": [ "integer", "null" ], "format": "int64", "description": "Record version of a provider template (for `If-Match`).", "minimum": 0 } } }, "TenantNetworkUsage": { "type": "object", "description": "Network usage of one tenant in one period (for `GET /v1/tenants/{t}/usage`).", "required": [ "traffic", "addresses" ], "properties": { "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/ServerAddressUsage" }, "description": "Public addresses per server." }, "traffic": { "$ref": "#/components/schemas/TrafficReport", "description": "Traffic per server and the tenant total." } } }, "TenantTraffic": { "type": "object", "description": "Traffic of one tenant in a period.", "required": [ "tenant", "name", "vms", "inBytes", "outBytes", "billableBytes" ], "properties": { "billableBytes": { "type": "integer", "format": "int64", "description": "Billable bytes (sum of the VMs' billable bytes).", "minimum": 0 }, "inBytes": { "type": "integer", "format": "int64", "description": "Inbound bytes.", "minimum": 0 }, "name": { "type": "string", "description": "Tenant name as last seen." }, "outBytes": { "type": "integer", "format": "int64", "description": "Outbound bytes.", "minimum": 0 }, "tenant": { "type": "string", "description": "Tenant id." }, "vms": { "type": "integer", "format": "int32", "description": "VMs with traffic.", "minimum": 0 } } }, "TenantUsageView": { "type": "object", "description": "A tenant's usage in a month (`docs/cloud/SELF_SERVICE.md` §5).", "required": [ "tenant", "month", "from", "to", "servers", "planHours", "snapshotGibHours" ], "properties": { "from": { "type": "string", "description": "Start (inclusive, UTC)." }, "month": { "type": "string", "description": "`YYYY-MM`." }, "network": { "oneOf": [ { "$ref": "#/components/schemas/TenantNetworkUsage", "description": "Traffic per VM (in the tenant's traffic period, from its anchor day) and the\npublic addresses held, primary and extra (§4, from the IP pools); absent when the\ntraffic ledger is not configured." }, { "type": "null" } ] }, "planHours": { "type": "array", "items": { "$ref": "#/components/schemas/PlanHoursView" }, "description": "Hours per plan over all servers." }, "servers": { "type": "array", "items": { "$ref": "#/components/schemas/ServerUsageView" }, "description": "Per server." }, "snapshotGibHours": { "type": "number", "format": "double", "description": "Snapshot GiB-hours over all servers." }, "tenant": { "type": "string", "description": "Tenant." }, "to": { "type": "string", "description": "End (exclusive; now for the current month)." } } }, "TenantView": { "type": "object", "description": "A tenant.", "required": [ "id", "name", "displayName", "state", "externalRef", "labels", "quota", "used", "folders", "pools", "createdAt", "destroyed" ], "properties": { "anchorDay": { "type": [ "integer", "null" ], "format": "int32", "description": "Day of the month the traffic period starts.", "minimum": 0 }, "closedAt": { "type": [ "string", "null" ], "description": "Closed at." }, "createdAt": { "type": "string", "description": "Created." }, "destroyAfter": { "type": [ "string", "null" ], "description": "When a closed tenant's VMs are destroyed." }, "destroyed": { "type": "boolean", "description": "Whether that has happened." }, "displayName": { "type": "string", "description": "Display name." }, "externalRef": { "type": "string", "description": "The portal's account id." }, "folders": { "type": "array", "items": { "type": "string" }, "description": "VM folders (`group-vN`), one per datacenter." }, "id": { "type": "string", "description": "`tenant-N`." }, "labels": { "type": "object", "description": "Labels.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Short name." }, "pools": { "type": "array", "items": { "type": "string" }, "description": "Resource pools, one per cluster." }, "quota": { "$ref": "#/components/schemas/QuotaView", "description": "Limits." }, "state": { "type": "string", "description": "`active`, `suspended` or `closed`." }, "suspendedAt": { "type": [ "string", "null" ], "description": "Suspended at." }, "used": { "$ref": "#/components/schemas/QuotaAmounts", "description": "Current use." } } }, "ToolsStatus": { "type": "string", "description": "Guest agent tools state.", "enum": [ "not_installed", "not_running", "running" ] }, "TotpCodeRequest": { "type": "object", "description": "A TOTP code.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Six-digit code." } } }, "TotpEnrolResponse": { "type": "object", "description": "`POST /v1/auth/totp/enrol` response.", "required": [ "otpauthUri", "secret", "algorithm", "digits", "period" ], "properties": { "algorithm": { "type": "string", "description": "Algorithm (`SHA1`), digits (6) and period (30 s), for display." }, "digits": { "type": "integer", "format": "int32", "description": "Digits.", "minimum": 0 }, "otpauthUri": { "type": "string", "description": "`otpauth://totp/Kyvernon:?secret=...&issuer=Kyvernon...` for the QR code." }, "period": { "type": "integer", "format": "int32", "description": "Period in seconds.", "minimum": 0 }, "secret": { "type": "string", "description": "Base32 seed for manual entry; shown once." } } }, "TrafficAction": { "type": "string", "description": "What happens at 100 % of the limit.", "enum": [ "notify", "throttle" ] }, "TrafficDay": { "type": "object", "description": "One day of a VM's traffic (graph).", "required": [ "day", "inBytes", "outBytes" ], "properties": { "day": { "type": "string", "description": "The day (`YYYY-MM-DD`)." }, "inBytes": { "type": "integer", "format": "int64", "description": "Inbound bytes.", "minimum": 0 }, "outBytes": { "type": "integer", "format": "int64", "description": "Outbound bytes.", "minimum": 0 } } }, "TrafficPackage": { "type": "object", "description": "An extra traffic package for one period.", "required": [ "periodStart", "bytes", "addedAt" ], "properties": { "addedAt": { "type": "string", "description": "When it was added." }, "bytes": { "type": "integer", "format": "int64", "description": "Bytes added to the period's limit.", "minimum": 0 }, "periodStart": { "type": "string", "description": "First day of the period it applies to (`YYYY-MM-DD`)." }, "reference": { "type": [ "string", "null" ], "description": "The caller's reference (order item)." } }, "additionalProperties": false }, "TrafficPolicy": { "type": "object", "description": "Traffic limit and state of one VM (record name: the VM id).\n\nMapping to plans: `monthly_limit_bytes` is the plan's traffic per month,\n`action` the plan's action at 100 %, `throttle_kbps` the plan's (or the site's default)\nthrottle rate. Server create and resize set them from the `vm_plan`; until plans exist\nan operator or the portal sets them through `PUT /v1/vms/{id}/traffic-policy`.", "required": [ "name", "vm" ], "properties": { "action": { "$ref": "#/components/schemas/TrafficAction", "description": "Action at 100 %." }, "anchorDay": { "type": [ "integer", "null" ], "format": "int32", "description": "Anchor day of the period (1 to 28); `None`: the tenant's or the 1st.", "minimum": 0 }, "monthlyLimitBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes per period; `None`: no limit (accounting only).", "minimum": 0 }, "name": { "type": "string", "description": "Record name: the VM id (one policy per VM, enforced by the store's unique names)." }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficPackage" }, "description": "Extra packages." }, "smtpUnblocked": { "type": "boolean", "description": "Outgoing SMTP (TCP 25) is allowed for this VM although its pools block it\n(`PUT /v1/vms/{id}/smtp`; the record is the VM's network policy)." }, "state": { "$ref": "#/components/schemas/TrafficState", "description": "Enforcement state." }, "tenant": { "type": [ "string", "null" ], "description": "Tenant (for the events)." }, "throttleKbps": { "type": [ "integer", "null" ], "format": "int64", "description": "Throttle rate in kbit/s; `None`: the site default.", "minimum": 0 }, "vm": { "type": "string", "description": "The VM." } }, "additionalProperties": false }, "TrafficReport": { "type": "object", "description": "A traffic report for one period.", "required": [ "periodStart", "periodEnd", "billable", "vms", "tenants" ], "properties": { "billable": { "$ref": "#/components/schemas/Billable", "description": "Billed direction." }, "periodEnd": { "type": "string", "description": "Last day of the period (inclusive)." }, "periodStart": { "type": "string", "description": "First day of the period (`YYYY-MM-DD`)." }, "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/TenantTraffic" }, "description": "Per tenant." }, "vms": { "type": "array", "items": { "$ref": "#/components/schemas/VmTraffic" }, "description": "Per VM." } } }, "TrafficState": { "type": "object", "description": "Enforcement state of the current period.", "properties": { "limitBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "The limit in force at the last check (plan plus packages).", "minimum": 0 }, "notified": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Thresholds already notified in the period." }, "periodStart": { "type": [ "string", "null" ], "description": "First day of the period the state is about." }, "throttled": { "type": "boolean", "description": "The VM is throttled." }, "usedBytes": { "type": "integer", "format": "int64", "description": "Billable bytes at the last check.", "minimum": 0 } }, "additionalProperties": false }, "UpdateAlarmRequest": { "type": "object", "description": "Change an alarm definition (`PUT /v1/alarms/{id}`). Absent fields keep their value;\nthe body of `POST /v1/alarms` is accepted as it is (a full replacement). The states\nstay unless the trigger or the scope changes.", "properties": { "actions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AlarmAction" }, "description": "Actions (replaces the list)." }, "description": { "type": [ "string", "null" ], "description": "Description." }, "enabled": { "type": [ "boolean", "null" ], "description": "Enabled. A disabled alarm is not evaluated." }, "expectedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Version the client read (`version` of the alarm record); `CONFLICT` when it changed.", "minimum": 0 }, "name": { "type": [ "string", "null" ], "description": "Name." }, "scopeId": { "type": [ "string", "null" ], "description": "Scope entity id. A new scope needs `Alarm.Create` there and clears the states." }, "trigger": { "oneOf": [ { "$ref": "#/components/schemas/AlarmTrigger", "description": "Trigger. A metric trigger names a metric (`cpu.usage`) or a counter\n(`cpu.usage.average`) of `GET /v1/metrics/counters`; thresholds are in the counter's\nunit (percent as 0 to 100)." }, { "type": "null" } ] } }, "additionalProperties": false }, "UpdateDistributedPortgroupRequest": { "type": "object", "description": "Body of `PUT /v1/distributed-portgroups/{id}`: the fields to change; `null` for\n`ipv4` or `ipv6` removes the settings.", "required": [ "expectedVersion" ], "properties": { "expectedVersion": { "type": "integer", "format": "int64", "description": "Version the change is based on.", "minimum": 0 }, "ipv4": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeIpv4Request", "description": "IPv4 settings." }, { "type": "null" } ] }, "ipv6": { "oneOf": [ { "$ref": "#/components/schemas/PortgroupIpv6Request", "description": "IPv6 settings." }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ], "description": "Name." }, "staticAddresses": { "type": [ "object", "null" ], "description": "Fixed IPv4 addresses by MAC (replaces the map).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "vlanId": { "type": [ "integer", "null" ], "format": "int32", "description": "VLAN id (clears `vni`).", "minimum": 0 }, "vni": { "type": [ "integer", "null" ], "format": "int32", "description": "VNI (replaces the VLAN).", "minimum": 0 } }, "additionalProperties": false }, "UpdateDistributedSwitchRequest": { "type": "object", "description": "Body of `PUT /v1/distributed-switches/{id}`: the fields to change.", "required": [ "expectedVersion" ], "properties": { "expectedVersion": { "type": "integer", "format": "int64", "description": "Version the change is based on.", "minimum": 0 }, "hostUplinks": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/HostUplinksRequest" }, "description": "The physical NICs of member hosts (replaces the list)." }, "hosts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Member hosts." }, "mtu": { "type": [ "integer", "null" ], "format": "int32", "description": "MTU.", "minimum": 0 }, "name": { "type": [ "string", "null" ], "description": "Name." }, "uplinkNames": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Uplink names." }, "uplinks": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of uplinks.", "minimum": 0 } }, "additionalProperties": false }, "UpdateGroupRequest": { "type": "object", "description": "Body of `PUT /v1/identity/groups/{name}`. Absent fields keep their value.", "properties": { "description": { "type": [ "string", "null" ], "description": "New description." }, "name": { "type": [ "string", "null" ], "description": "New name. Memberships of users and groups and the permissions granted to the group\nfollow the rename." } }, "additionalProperties": false }, "UpdateNetworkRequest": { "type": "object", "description": "Update a host-bridge network (`PUT /v1/networks/{id}`).\n\nCompare-and-set on `expectedVersion`. Omitted fields keep their current value.\nExisting DHCP leases are preserved when the backing is rewritten.", "required": [ "expectedVersion" ], "properties": { "backing": { "oneOf": [ { "$ref": "#/components/schemas/HostBridgeBackingRequest", "description": "Replace host-bridge backing (leases and the policy are kept)." }, { "type": "null" } ] }, "expectedVersion": { "type": "integer", "format": "int64", "description": "Version the client read; fails with `CONFLICT` if it changed.", "minimum": 0 }, "hosts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Replace the hosts list." }, "name": { "type": [ "string", "null" ], "description": "New display name." }, "vlanId": { "type": [ "integer", "null" ], "format": "int32", "description": "New VLAN id.", "minimum": 0 } } }, "UpdateObjectRequest": { "type": "object", "description": "Inventory update request (compare-and-set).", "required": [ "expectedVersion", "data" ], "properties": { "data": { "$ref": "#/components/schemas/ObjectBody", "description": "New body, in the kind's schema." }, "expectedVersion": { "type": "integer", "format": "int64", "description": "Version the client read; the update fails with `CONFLICT` if it changed.", "minimum": 0 } } }, "UpdateSessionFileView": { "type": "object", "description": "File on an update session.", "required": [ "name", "sourceType", "bytesTransferred", "status" ], "properties": { "bytesTransferred": { "type": "integer", "format": "int64", "description": "Bytes transferred." }, "errorMessage": { "type": [ "string", "null" ], "description": "Error message when status is ERROR." }, "name": { "type": "string", "description": "File name." }, "size": { "type": [ "integer", "null" ], "format": "int64", "description": "Expected or actual size." }, "sourceType": { "type": "string", "description": "`PUSH`." }, "status": { "type": "string", "description": "Transfer status." }, "uploadEndpoint": { "type": [ "string", "null" ], "description": "Relative upload URI for PUSH." } } }, "UpdateSessionView": { "type": "object", "description": "Content library update session (`GET/POST /v1/content/update-sessions`).", "required": [ "id", "libraryItemId", "state", "clientProgress", "expirationTime", "creationTime", "lastModifiedTime" ], "properties": { "clientProgress": { "type": "integer", "format": "int64", "description": "Client progress 0..=100." }, "creationTime": { "type": "string", "description": "Creation time." }, "errorMessage": { "type": [ "string", "null" ], "description": "Error message when state is ERROR." }, "expirationTime": { "type": "string", "description": "Expiration time." }, "id": { "type": "string", "description": "Session id." }, "lastModifiedTime": { "type": "string", "description": "Last modification time." }, "libraryItemId": { "type": "string", "description": "Library item being updated." }, "state": { "type": "string", "description": "`ACTIVE`, `DONE`, `ERROR`, or `CANCELED`." } } }, "UpdateSubscriptionRequest": { "type": "object", "description": "Body of `PUT /v1/webhooks/{id}`: the fields of the create request. Absent optional\nfields keep their value; an absent `secret` keeps the stored one.", "required": [ "name", "url" ], "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "On or off." }, "eventTypes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Event types (empty: all)." }, "labels": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Labels that alarm actions reference." }, "maxAttempts": { "type": [ "integer", "null" ], "format": "int32", "description": "Attempts per event.", "minimum": 0 }, "name": { "type": "string", "description": "Name." }, "secret": { "type": [ "string", "null" ], "description": "New shared secret (at least 16 bytes); absent keeps the stored one." }, "tenant": { "type": [ "string", "null" ], "description": "Tenant filter (`tenant-N`); `null` removes it." }, "url": { "type": "string", "description": "Target URL (`https://`; loopback and private addresses need an allow-list entry)." } } }, "UpdateTagCategoryRequest": { "type": "object", "description": "Body of `PUT /v1/tag-categories/{id}`. Absent fields keep their value. Cardinality can\nchange from `single` to `multiple` only, and associable kinds can only be added: both\nwould otherwise break existing assignments.", "properties": { "associableKinds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The new list of associable kinds (a superset of the current one)." }, "cardinality": { "type": [ "string", "null" ], "description": "`multiple`." }, "description": { "type": [ "string", "null" ], "description": "New description." }, "expectedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Version the client read; `CONFLICT` when the category changed since.", "minimum": 0 }, "name": { "type": [ "string", "null" ], "description": "New name." } }, "additionalProperties": false }, "UpdateTagRequest": { "type": "object", "description": "Body of `PUT /v1/tags/{id}`. Absent fields keep their value.", "properties": { "description": { "type": [ "string", "null" ], "description": "New description." }, "expectedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Version the client read; `CONFLICT` when the tag changed since.", "minimum": 0 }, "name": { "type": [ "string", "null" ], "description": "New name." } }, "additionalProperties": false }, "UpdateUserRequest": { "type": "object", "description": "Body of `PUT /v1/identity/users/{username}`. Absent fields keep their value.", "properties": { "displayName": { "type": [ "string", "null" ], "description": "Display name." }, "email": { "type": [ "string", "null" ], "description": "E-mail address." }, "groups": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The local groups the user is a direct member of (replaces the set; groups that\ncome from an identity provider stay)." } }, "additionalProperties": false }, "UplinkMode": { "type": "string", "description": "How a host-bridge network reaches the provider's network.", "enum": [ "bridged", "proxy" ] }, "UsageLineView": { "type": "object", "description": "One usage line.", "required": [ "period", "key", "name", "vms", "poweredOnHours", "vcpuHours", "ramGibHours", "provisionedGibHours", "usedGibHours", "netRxGib", "netTxGib", "netRxBytes", "netTxBytes" ], "properties": { "key": { "type": "string", "description": "Group id." }, "name": { "type": "string", "description": "Group name." }, "netRxBytes": { "type": "integer", "format": "int64", "description": "Bytes received.", "minimum": 0 }, "netRxGib": { "type": "number", "format": "double", "description": "GiB received." }, "netTxBytes": { "type": "integer", "format": "int64", "description": "Bytes sent.", "minimum": 0 }, "netTxGib": { "type": "number", "format": "double", "description": "GiB sent." }, "period": { "type": "string", "description": "`YYYY-MM-DD`, `YYYY-MM` or `from/to`." }, "poweredOnHours": { "type": "number", "format": "double", "description": "Powered-on hours." }, "provisionedGibHours": { "type": "number", "format": "double", "description": "GiB-hours of provisioned storage." }, "ramGibHours": { "type": "number", "format": "double", "description": "GiB-hours of configured memory while powered on." }, "usedGibHours": { "type": "number", "format": "double", "description": "GiB-hours of used storage." }, "vcpuHours": { "type": "number", "format": "double", "description": "vCPU-hours." }, "vms": { "type": "integer", "format": "int32", "description": "Distinct VMs.", "minimum": 0 } } }, "UsageReportView": { "type": "object", "description": "A usage report.", "required": [ "from", "to", "groupBy", "period", "lines" ], "properties": { "from": { "type": "string", "description": "First day." }, "groupBy": { "type": "string", "description": "Grouping." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLineView" }, "description": "Lines." }, "period": { "type": "string", "description": "Period." }, "to": { "type": "string", "description": "Last day (inclusive)." } } }, "UserView": { "type": "object", "description": "Secret-free user view.", "required": [ "username", "displayName", "email", "source", "enabled", "groups", "mfaEnrolled", "breakGlass", "passwordRotationRequired" ], "properties": { "apiTokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenView" }, "description": "API tokens (without secrets)." }, "breakGlass": { "type": "boolean", "description": "Break-glass account." }, "displayName": { "type": "string", "description": "Display name." }, "email": { "type": "string", "description": "E-mail." }, "enabled": { "type": "boolean", "description": "Enabled." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Groups." }, "lastLogin": { "type": [ "string", "null" ], "description": "Last login." }, "locked": { "type": "boolean", "description": "True while the account is locked after too many failed logins (`lockedUntil` is in\nthe future); an administrator reads it here before lifting the lockout." }, "lockedUntil": { "type": [ "string", "null" ], "description": "Locked until." }, "mfaEnrolled": { "type": "boolean", "description": "MFA enrolled." }, "passwordRotationRequired": { "type": "boolean", "description": "Must rotate password." }, "recoveryCodesRemaining": { "type": "integer", "description": "Unused TOTP recovery codes.", "minimum": 0 }, "serviceAccount": { "type": "boolean", "description": "Service account (automation only; no browser login)." }, "source": { "type": "string", "description": "`local` or `oidc`." }, "tenant": { "type": [ "string", "null" ], "description": "The tenant of a tenant user (`tenant-N`)." }, "username": { "type": "string", "description": "Username." } } }, "VerificationRecord": { "type": "object", "description": "The last nightly run of one VM.", "required": [ "vmId", "vmName", "runAt", "passed" ], "properties": { "backupSessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The backup session restored." }, "evidence": { "oneOf": [ { "$ref": "#/components/schemas/Evidence", "description": "Evidence." }, { "type": "null" } ] }, "passed": { "type": "boolean", "description": "Verdict." }, "reason": { "type": [ "string", "null" ], "description": "Message key of the failure." }, "restoredVmId": { "type": [ "string", "null" ], "format": "uuid", "description": "The restored VM (may be destroyed already)." }, "runAt": { "type": "integer", "format": "int64", "description": "Run time, Unix seconds." }, "vmId": { "type": "string", "format": "uuid", "description": "The VM that was backed up." }, "vmName": { "type": "string", "description": "Its name." } } }, "VerificationReport": { "type": "object", "description": "`GET /v1/backup/verification`.", "required": [ "runs", "neverVerified" ], "properties": { "neverVerified": { "type": "array", "items": { "type": "string" }, "description": "VMs flagged for verification that have never been verified." }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationRecord" }, "description": "Last run per VM, by VM name." } } }, "VerifySpec": { "type": "object", "description": "What to verify against.", "required": [ "network" ], "properties": { "destroy": { "type": "boolean", "description": "Destroy the restored VM after the verdict (default: keep it powered off)." }, "network": { "type": "string", "description": "The quarantine network: id or name." }, "serialMarkers": { "type": "array", "items": { "type": "string" }, "description": "Serial markers that count as an operating system (default: [`OS_MARKERS`])." }, "tcpPorts": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "TCP ports to check from the host probe after boot and lease (empty: no TCP check)." }, "timeoutSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Give up after this many seconds (default 300, at most 3600).", "minimum": 0 } } }, "VerifyState": { "type": "string", "description": "State of a restore verification.", "enum": [ "running", "passed", "failed" ] }, "VimMoRefView": { "type": "object", "description": "Managed-object reference embedded in create/clone/AddHost/snapshot results\n(`TaskInfo.result` for the SOAP facade).", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "vim type name (`VirtualMachine`, `HostSystem`, `VirtualMachineSnapshot`)." }, "value": { "type": "string", "description": "MoRef value (`vm-42`, `host-7`, `vm-42-snapshot-1`)." } } }, "VirtualCdrom": { "type": "object", "description": "A virtual CD-ROM drive (`VirtualCdrom`), optionally with an ISO image inserted.", "required": [ "key" ], "properties": { "connected": { "type": "boolean", "description": "Connected at power on." }, "datastore": { "type": [ "string", "null" ], "description": "Datastore holding the inserted ISO image; `None` is an empty tray." }, "iso_path": { "type": "string", "description": "ISO path relative to the datastore root; empty for an empty tray." }, "key": { "type": "integer", "format": "int32", "description": "Stable device key within the VM (3000, 3001, ...).", "minimum": 0 } }, "additionalProperties": false }, "VirtualDisk": { "type": "object", "description": "A virtual disk.", "required": [ "key", "capacity_bytes", "datastore", "path" ], "properties": { "capacity_bytes": { "type": "integer", "format": "int64", "description": "Capacity.", "minimum": 0 }, "cbt_enabled": { "type": "boolean", "description": "Changed-block tracking enabled." }, "datastore": { "type": "string", "description": "Datastore holding the backing file." }, "independent": { "type": "boolean", "description": "Excluded from snapshots (`diskMode = independent_persistent`, ESX-V-07)." }, "key": { "type": "integer", "format": "int32", "description": "Stable device key within the VM.", "minimum": 0 }, "nonpersistent": { "type": "boolean", "description": "Independent non-persistent (`diskMode = independent_nonpersistent`): power-cycle\noverlay discarded on stop. Implies `independent`." }, "path": { "type": "string", "description": "Backing path relative to the datastore root." }, "thin": { "type": "boolean", "description": "Thin provisioned." } }, "additionalProperties": false }, "VirtualMachine": { "type": "object", "description": "A virtual machine.", "required": [ "name", "instance_uuid", "resource_pool", "config" ], "properties": { "config": { "$ref": "#/components/schemas/VmConfig", "description": "Desired configuration." }, "current_snapshot": { "type": [ "integer", "null" ], "format": "int32", "description": "The snapshot the running state descends from (`snapshot.currentSnapshot`).", "minimum": 0 }, "desired_power_state": { "$ref": "#/components/schemas/PowerState", "description": "The power state the control plane wants; the host agent reconciles\n`runtime.power_state` towards it and reports back." }, "generation": { "type": "integer", "format": "int64", "description": "Desired-state generation; bumped on every config change or power\nrequest so the host agent knows what to reconcile.", "minimum": 0 }, "guest": { "$ref": "#/components/schemas/VmGuest", "description": "Guest information." }, "instance_uuid": { "type": "string", "format": "uuid", "description": "Stable instance UUID exposed to the guest (SMBIOS)." }, "name": { "type": "string", "description": "Display name." }, "reset_epoch": { "type": "integer", "format": "int64", "description": "Incremented by every reset request; the host resets the VM once per increment\n(a reset does not change the desired power state).", "minimum": 0 }, "resource_pool": { "type": "string", "description": "Resource pool the VM belongs to." }, "runtime": { "$ref": "#/components/schemas/VmRuntime", "description": "Observed runtime state." }, "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/VmSnapshot" }, "description": "Snapshot tree, flat (each snapshot names its parent), in creation order." } }, "additionalProperties": false }, "VirtualNic": { "type": "object", "description": "A virtual NIC.", "required": [ "key", "network", "mac_address" ], "properties": { "connected": { "type": "boolean", "description": "Connected at power on." }, "firewall": { "type": "object", "description": "Distributed firewall mode and profile of the vNIC (`DFW-HOSTBRIDGE.md` §4); the\ndefault (mode `off`) is not written." }, "key": { "type": "integer", "format": "int32", "description": "Stable device key within the VM.", "minimum": 0 }, "mac_address": { "type": "string", "description": "MAC address, lower-case colon-separated." }, "model": { "type": "string", "description": "Device model (`virtio`, `e1000e`, `vmxnet3`-compatible profile, ...)." }, "network": { "type": "string", "description": "Network or distributed portgroup." } }, "additionalProperties": false }, "VmAddress": { "type": "object", "description": "One address of a VM, across pools.", "required": [ "pool", "poolName", "address", "role", "allocatedAt" ], "properties": { "address": { "type": "string", "description": "IPv4 address, or the server's IPv6 address (`::1`)." }, "allocatedAt": { "type": "string", "description": "Allocation time." }, "mac": { "type": [ "string", "null" ], "description": "NIC MAC." }, "pool": { "type": "string", "description": "The pool." }, "poolName": { "type": "string", "description": "The pool's name." }, "prefix": { "type": [ "string", "null" ], "description": "For IPv6: the block (`/`, e.g. `/64` or `/112`)." }, "prefixLen": { "type": [ "integer", "null" ], "format": "int32", "description": "For IPv6: the block length (64 to 128). A PTR may only be set for the server\naddress `address`, which lies in this block.", "minimum": 0 }, "ptr": { "type": [ "string", "null" ], "description": "Reverse DNS name." }, "ptrReason": { "type": [ "string", "null" ], "description": "Why the operator rejected the name." }, "ptrStatus": { "oneOf": [ { "$ref": "#/components/schemas/PtrStatus", "description": "State of the name: `applied`, `requested` (manual mode, waiting for the operator)\nor `rejected`." }, { "type": "null" } ] }, "role": { "type": "string", "description": "`primary`, `extra` or `ipv6`." } } }, "VmConfig": { "type": "object", "description": "The configuration of a VM (what the user asked for).", "required": [ "num_cpus", "memory_mib" ], "properties": { "annotation": { "type": "string", "description": "Annotation / notes." }, "cdroms": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualCdrom" }, "description": "CD-ROM drives." }, "change_tracking": { "type": "boolean", "description": "Changed-block tracking (`config.changeTrackingEnabled`); the disks' `cbt_enabled`\nfollow it." }, "change_version": { "type": "integer", "format": "int64", "description": "Monotonic change counter the facade exposes as `config.changeVersion`.", "minimum": 0 }, "cores_per_socket": { "type": "integer", "format": "int32", "description": "Cores per socket (0 = let the hypervisor decide).", "minimum": 0 }, "disks": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualDisk" }, "description": "Disks." }, "extra_config": { "type": "object", "description": "Free-form `extraConfig`-style options (`guestinfo.*`, ...).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "firmware": { "$ref": "#/components/schemas/FirmwareKind", "description": "Firmware." }, "guest_id": { "type": "string", "description": "Guest OS identifier (vSphere-style `guestId`, e.g. `ubuntu64Guest`)." }, "memory_mib": { "type": "integer", "format": "int64", "description": "Memory.", "minimum": 0 }, "nics": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualNic" }, "description": "NICs." }, "num_cpus": { "type": "integer", "format": "int32", "description": "Virtual CPUs.", "minimum": 0 }, "secure_boot": { "type": "boolean", "description": "Secure Boot enabled (EFI only)." }, "template": { "type": "boolean", "description": "Whether this VM is a template." }, "vtpm": { "type": "boolean", "description": "Virtual TPM present." } }, "additionalProperties": false }, "VmGuest": { "type": "object", "description": "Guest information (from the guest agent).", "properties": { "agent_version": { "type": "string", "description": "Version of the guest agent while it runs." }, "files_allowed": { "type": "boolean", "description": "The guest agent allows file operations (`guest-file-*`)." }, "hostname": { "type": "string", "description": "Guest hostname." }, "ip_address": { "type": "string", "description": "Primary IP address." }, "ip_addresses": { "type": "array", "items": { "type": "string" }, "description": "All IP addresses." }, "nics": { "type": "array", "items": { "$ref": "#/components/schemas/GuestNic" }, "description": "Network interfaces the guest agent reports (without the loopback), each with its\nMAC address and addresses. The SOAP facade's `guest.net` is projected from them." }, "operations_note": { "type": "string", "description": "Why guest operations are not allowed (the commands the agent has disabled and the\nremedy); empty when they are or while the agent does not run." }, "os_family": { "type": "string", "description": "Detected guest OS family (`linux`, `windows`, ...)." }, "os_name": { "type": "string", "description": "Detected guest OS full name." }, "processes_allowed": { "type": "boolean", "description": "The guest agent allows process operations (`guest-exec`): `StartProgramInGuest`\nand friends can work. The RHEL-family agent blocks them by default." }, "tools_status": { "$ref": "#/components/schemas/ToolsStatus", "description": "Guest agent state." } }, "additionalProperties": false }, "VmRuntime": { "type": "object", "description": "Runtime state of a VM (reported by the host agent).", "properties": { "boot_time": { "type": [ "string", "null" ], "description": "Time of last power on." }, "cpu_usage_mhz": { "type": "integer", "format": "int32", "description": "Current CPU usage.", "minimum": 0 }, "host": { "type": [ "string", "null" ], "description": "Host the VM currently runs on (or last ran on)." }, "lifecycle": { "oneOf": [ { "$ref": "#/components/schemas/LifecycleState", "description": "The agent's full lifecycle state (`starting`, `running`, `paused`, `stopping`,\n`migrating`, `incoming`, `crashed`, ...); `power_state` is its projection." }, { "type": "null" } ] }, "memory_usage_mib": { "type": "integer", "format": "int64", "description": "Guest memory in use on the host.", "minimum": 0 }, "observed_generation": { "type": "integer", "format": "int64", "description": "Desired-state reconciliation generation last acknowledged by the host.", "minimum": 0 }, "pid": { "type": [ "integer", "null" ], "format": "int32", "description": "Hypervisor process id on the host, when running.", "minimum": 0 }, "power_state": { "$ref": "#/components/schemas/PowerState", "description": "Power state." }, "reconcile_error": { "type": [ "string", "null" ], "description": "The last reconciliation error the host reported for this VM, cleared by the\nnext successful report." } }, "additionalProperties": false }, "VmSnapshot": { "type": "object", "description": "A point-in-time snapshot of a VM (`VirtualMachineSnapshot`).\n\nThe control plane keeps the tree and the configuration at snapshot time (a revert\nrestores it, as in vSphere); the disk and memory state lives on the host under the\nruntime name, which the agent uses as its snapshot tag.", "required": [ "key", "name", "created_at", "power_state", "runtime_name", "config" ], "properties": { "config": { "$ref": "#/components/schemas/VmConfig", "description": "The VM configuration when the snapshot was taken." }, "created_at": { "type": "string", "description": "Creation time." }, "description": { "type": "string", "description": "Free text." }, "key": { "type": "integer", "format": "int32", "description": "Number unique within the VM; the MoRef value is `-snapshot-`.", "minimum": 0 }, "memory": { "type": "boolean", "description": "Includes the memory state (a revert resumes the running guest)." }, "name": { "type": "string", "description": "Display name (not unique; vSphere allows duplicates)." }, "parent": { "type": [ "integer", "null" ], "format": "int32", "description": "Parent snapshot key; `None` for a root.", "minimum": 0 }, "power_state": { "$ref": "#/components/schemas/PowerState", "description": "Power state of the VM when the snapshot was taken." }, "quiesced": { "type": "boolean", "description": "Guest file systems were quiesced through the guest channel." }, "runtime_name": { "type": "string", "description": "Snapshot tag on the host (`[A-Za-z0-9_.-]{1,64}`)." } }, "additionalProperties": false }, "VmTraffic": { "type": "object", "description": "Traffic of one VM in a period.", "required": [ "vm", "name", "tenant", "inBytes", "outBytes", "billableBytes" ], "properties": { "billableBytes": { "type": "integer", "format": "int64", "description": "Billable bytes.", "minimum": 0 }, "inBytes": { "type": "integer", "format": "int64", "description": "Bytes received by the VM (inbound).", "minimum": 0 }, "name": { "type": "string", "description": "VM name as last seen." }, "outBytes": { "type": "integer", "format": "int64", "description": "Bytes sent by the VM (outbound).", "minimum": 0 }, "tenant": { "type": "string", "description": "Tenant as last seen in the ledger." }, "vm": { "type": "string", "description": "VM id." } } }, "VmTrafficView": { "type": "object", "description": "One VM's traffic in a period, with its limit state and daily series.", "required": [ "vm", "periodStart", "periodEnd", "inBytes", "outBytes", "billableBytes", "throttled", "days" ], "properties": { "billableBytes": { "type": "integer", "format": "int64", "description": "Billable bytes.", "minimum": 0 }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficDay" }, "description": "Bytes per day." }, "inBytes": { "type": "integer", "format": "int64", "description": "Inbound bytes.", "minimum": 0 }, "limitBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "The limit of the period (plan plus packages); absent: none.", "minimum": 0 }, "outBytes": { "type": "integer", "format": "int64", "description": "Outbound bytes.", "minimum": 0 }, "percent": { "type": [ "number", "null" ], "format": "double", "description": "Billable bytes as per cent of the limit." }, "periodEnd": { "type": "string", "description": "Last day of the period (inclusive)." }, "periodStart": { "type": "string", "description": "First day of the period." }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/TrafficPolicy", "description": "The policy, when one is set." }, { "type": "null" } ] }, "throttled": { "type": "boolean", "description": "The VM is throttled now." }, "vm": { "type": "string", "description": "VM id." } } }, "VmfsCreateOptionView": { "type": "object", "description": "One VMFS create-option template (`QueryVmfsDatastoreCreateOptions`).", "required": [ "diskUuid", "canonicalName", "devicePath", "capacityBytes", "majorVersion", "blockSizeMb" ], "properties": { "blockSizeMb": { "type": "integer", "format": "int32", "description": "Suggested block size in MiB." }, "canonicalName": { "type": "string", "description": "Canonical name (`naa.…`)." }, "capacityBytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "devicePath": { "type": "string", "description": "Host device path." }, "diskUuid": { "type": "string", "description": "Disk WWID (`VmfsDatastoreSpec.diskUuid`)." }, "majorVersion": { "type": "integer", "format": "int32", "description": "Suggested major version." } } }, "VmfsDiskView": { "type": "object", "description": "One available disk for VMFS create (`QueryAvailableDisksForVmfs`).", "required": [ "wwid", "canonicalName", "devicePath", "capacityBytes", "target", "portal", "lun" ], "properties": { "canonicalName": { "type": "string", "description": "Canonical name (`naa.…`)." }, "capacityBytes": { "type": "integer", "format": "int64", "description": "Capacity in bytes.", "minimum": 0 }, "devicePath": { "type": "string", "description": "Host device path." }, "lun": { "type": "integer", "format": "int32", "description": "LUN number.", "minimum": 0 }, "portal": { "type": "string", "description": "Portal used for login." }, "target": { "type": "string", "description": "Target IQN." }, "wwid": { "type": "string", "description": "Multipath / by-id WWID." } } }, "VnicFirewallView": { "type": "object", "description": "The firewall of one vNIC.", "required": [ "vm", "nicKey", "network", "mac", "mode", "profile", "profileExplicit", "protection", "public", "defaultIn", "defaultOut", "rules" ], "properties": { "appliedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Plan version the host holds as applied.", "minimum": 0 }, "defaultIn": { "$ref": "#/components/schemas/DefaultActionView", "description": "Default for inbound traffic." }, "defaultOut": { "$ref": "#/components/schemas/DefaultActionView", "description": "Default for outbound traffic." }, "host": { "type": [ "string", "null" ], "description": "Host." }, "mac": { "type": "string", "description": "MAC." }, "mode": { "$ref": "#/components/schemas/ModeView", "description": "Mode." }, "network": { "type": "string", "description": "Network id." }, "nicKey": { "type": "string", "description": "NIC key (`4000`)." }, "pending": { "oneOf": [ { "$ref": "#/components/schemas/PendingModeView", "description": "The mode before a switch that waits for confirmation, and when it is restored." }, { "type": "null" } ] }, "profile": { "type": "string", "description": "Profile id." }, "profileExplicit": { "type": "boolean", "description": "The profile was set on the vNIC (else it follows the NIC kind)." }, "protection": { "$ref": "#/components/schemas/ProtectionView", "description": "Protection." }, "public": { "type": "boolean", "description": "Public (an IP pool address)." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/EffectiveRule" }, "description": "Rules in evaluation order, the two defaults last." }, "vm": { "type": "string", "description": "VM id." }, "wantedVersion": { "type": [ "integer", "null" ], "format": "int64", "description": "Plan version last sent to the host.", "minimum": 0 } } }, "VnicView": { "type": "object", "description": "A vNIC: VM id and NIC key (`4000`, or `nic4000`).", "required": [ "vm", "nic" ], "properties": { "nic": { "type": "string", "description": "NIC key." }, "vm": { "type": "string", "description": "VM id (`vm-7`)." } }, "additionalProperties": false }, "WebhookDeliveryView": { "type": "object", "description": "One delivery in the delivery log of a subscription.", "required": [ "eventId", "eventType", "startedAt", "durationMs", "attempts", "status", "delivered" ], "properties": { "attempts": { "type": "integer", "format": "int32", "description": "Attempts made.", "minimum": 0 }, "delivered": { "type": "boolean", "description": "Whether a 2xx was received." }, "durationMs": { "type": "integer", "format": "int64", "description": "From the first attempt to the outcome, retry waits included, milliseconds.", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error of the last attempt." }, "eventId": { "type": "string", "description": "CloudEvents id (the event, alarm or document id)." }, "eventType": { "type": "string", "description": "CloudEvents type." }, "startedAt": { "type": "string", "description": "When the first attempt started (RFC 3339)." }, "status": { "type": "integer", "format": "int32", "description": "HTTP status of the last attempt (0: no response).", "minimum": 0 } } }, "WhoAmI": { "type": "object", "description": "The caller's identity.", "required": [ "username", "groups", "sessionId", "kind", "mfaPending", "passwordRotationRequired", "breakGlass" ], "properties": { "breakGlass": { "type": "boolean", "description": "Break-glass session." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Groups." }, "kind": { "type": "string", "description": "`interactive` or `api`." }, "mfaPending": { "type": "boolean", "description": "MFA pending." }, "passwordRotationRequired": { "type": "boolean", "description": "Password rotation required." }, "sessionId": { "type": "string", "description": "Session id." }, "username": { "type": "string", "description": "Username." } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque session token" } } }, "tags": [ { "name": "system", "description": "Health, metrics, service information" }, { "name": "auth", "description": "Browser login (decision L-113): access token in the body, rotating refresh token in the HttpOnly cookie kyv_refresh (Path=/v1/auth), CSRF double submit with the kyv_csrf cookie and the X-Kyvernon-CSRF header, Origin checks, forced password change and TOTP enrolment, API tokens. See docs/control-plane/SECURITY.md" }, { "name": "identity", "description": "Login, sessions, users, roles, permissions, audit" }, { "name": "inventory", "description": "Inventory tree, objects, change feed" }, { "name": "vms", "description": "Virtual machine lifecycle (long-running operations)" }, { "name": "hosts", "description": "Host lifecycle (enter/exit maintenance mode)" }, { "name": "networks", "description": "Host-bridge networks / standard port groups (create, update, delete)" }, { "name": "datastores", "description": "Datastore files: folders, listing, streamed upload and download (also at /folder, the vSphere-compatible datastore endpoint)" }, { "name": "tasks", "description": "Tasks" }, { "name": "events", "description": "Events" }, { "name": "alarms", "description": "Alarms" }, { "name": "scheduled-tasks", "description": "Scheduled power tasks (Once/Hourly/Daily/Weekly/Monthly*)" }, { "name": "webhooks", "description": "Webhook subscriptions" }, { "name": "metrics", "description": "Performance counters and samples of hosts, VMs and datastores (20 s realtime, 5 min to 1 day rollups)" }, { "name": "usage", "description": "Usage ledger for chargeback: vCPU, memory, storage and network per VM, tenant and day" }, { "name": "backup", "description": "Consistent backup points, changed-block areas and NBD exports (HX-GT-02); restore-to-new-disk" }, { "name": "content", "description": "Local content libraries and ISO/OVF items that reference datastore files (Wave C4 thin slice)" }, { "name": "guest", "description": "Guest operations through the guest agent (GuestOperationsManager)" }, { "name": "ovf", "description": "OVF descriptor parse and import-spec planning (ParseDescriptor / CreateImportSpec)" }, { "name": "nfc", "description": "ImportVApp / ExportVm HttpNfcLease lifecycle and file transfer" }, { "name": "licence", "description": "Offline licence entitlements and free-tier limits (decision L-121)" }, { "name": "tenants", "description": "Multi-tenant self-service (docs/cloud/SELF_SERVICE.md section 2): tenants with their folders and pools, quota, suspend/resume/close, tenant users and API tokens, monthly usage" }, { "name": "servers", "description": "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" }, { "name": "plans", "description": "VM plans and the self-service image catalogue (operator-managed)" }, { "name": "ip-pools", "description": "Public IP pools on host-bridge networks, address allocation bound to VM NICs, reverse DNS (L-127)" }, { "name": "traffic", "description": "Monthly traffic per VM and tenant, limits, threshold webhooks, throttling and extra packages (L-127)" }, { "name": "firewall", "description": "Distributed firewall at the vNIC (docs/network/DFW-HOSTBRIDGE.md, ADR-011)" } ] }