API: backup

Consistent backup points, changed-block areas and NBD exports (HX-GT-02); restore-to-new-disk

GET `/v1/backup/controller`

The archives of the controller's own state (System.Read on the root folder): where they go, when they are taken, the last run and the archives kept. Status of the controller that answers.

CLI: kyvernon system controller-backups

Responses

Status	Description	Schema
200	OK	`ControllerBackupStatusView`

PUT `/v1/backup/controller`

Changes the schedule, target folder and retention of the archives of the controller state (Global.Settings; audited). Kept in the replicated store over the [backup] keys controller_schedule, controller_target, controller_retention and applied by every controller; the folder must be absolute and creatable.

CLI: kyvernon system set-controller-backup --target <dir> --schedule 02:30

Request body

application/json: ControllerBackupRequest

Name	Type	Required	Description
`enabled`	`boolean`	yes	Take archives on the schedule.
`retention`	`integer`	yes	Archives kept (1 to 365).
`schedule`	`string`		`HH:MM` UTC or an interval such as `6h`; needed when `enabled`.
`target`	`string`	yes	Folder on the controller the archives go to (absolute).

Responses

Status	Description	Schema
200	OK	`ControllerBackupStatusView`
400	Invalid argument; the error body names the field	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/backup/controller/run`

Archives the controller's state now (Global.Settings; task ServiceInstance.backupControllerState, run by the leader for its own state): a consistent copy of the store and the metrics, the other files of the state directory and the configuration, read back and checked before it counts.

CLI: kyvernon system controller-backup

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/backup/disks/{diskId}/invalidate`

POST /v1/backup/disks/{diskId}/invalidate

CLI: kyvernon backup invalidate <disk-id> --vm <uuid> --reason <reason>

Parameters

Name	In	Type	Required	Description
`diskId`	path	`string` (uuid)	yes	Stable disk id

Request body

application/json: InvalidateRequestView

Name	Type	Required	Description
`reason`	`InvalidationReasonView`	yes	Why change tracking restarts for the disk.
`vmId`	`string` (uuid)	yes	VM instance UUID.

Responses

Status	Description	Schema
204	Tracking restarted

GET `/v1/backup/info`

GET /v1/backup/info

CLI: kyvernon backup info

Responses

Status	Description	Schema
200	Backup service capabilities	`ApiInfoView`

GET `/v1/backup/points`

The backup points in the repository, newest first (System.Read on the virtual machine; without vmId, the points of every virtual machine the caller can see, and of deleted ones for callers who can read the root folder).

CLI: kyvernon backup points

Parameters

Name	In	Type	Required	Description
`vmId`	query	`string` or `null`		Only the backup points of this virtual machine: its instance uuid or its id (`vm-N`).

Responses

Status	Description	Schema
200	OK	array of `BackupPointView`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/backup/points`

Backs a virtual machine up to the repository now (task VirtualMachine.backupToRepository; VirtualMachine.Provisioning.DiskRandomRead and VirtualMachine.State.CreateSnapshot on the VM). The controller takes the backup point, reads every disk over its export into the repository and writes the manifest when the session committed. Incremental when the newest point of the VM has change ids for its disks, unless full. Change tracking is turned on when it is off.

CLI: kyvernon vm backup <id>

Request body

application/json: StartBackupRequest

Name	Type	Required	Description
`full`	`boolean` or `null`		Transfer every allocated area even when change tracking could give an incremental backup.
`quiesce`	`QuiesceModeView` or `null`
`vmId`	`string`	yes	Virtual machine: instance uuid or id (`vm-N`).

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

DELETE `/v1/backup/points/{id}`

Deletes a backup point from the repository: its manifest and disk images (Global.Settings on the root folder; logged).

CLI: kyvernon backup delete-point <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the backup point

Responses

Status	Description	Schema
204	Done; no body
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

POST `/v1/backup/points/{id}/restore`

Restores a backup point. new: to a new virtual machine (VirtualMachine.Inventory.Create on the folder, VirtualMachine.Provisioning.DiskRandomAccess on the source; task VirtualMachine.restoreBackup). in-place: into the powered-off source, whose disks are replaced (VirtualMachine.Config.AddNewDisk and VirtualMachine.Config.RemoveDisk; task VirtualMachine.restoreBackupInPlace; the old disks come back when it fails). With verify, the point is then verified in quarantine.

CLI: kyvernon backup restore-point <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the backup point

Request body

application/json: RestorePointRequest

Name	Type	Description
`datastoreId`	`string` or `null`	Datastore for the new disks (default: the verification pool, else the first usable).
`folderId`	`string` or `null`	Folder of the new virtual machine (default: the folder of the source).
`hostId`	`string` or `null`	Host of the new virtual machine (default: the host of the source).
`mode`	`string` or `null`	`new` (default; also `new_vm`): a new virtual machine with the backed-up disks and the configuration of the source. `in-place` (also `in_place`): the disks of the source, which must be powered off, are replaced by those of the point (task `VirtualMachine.restoreBackupInPlace`); `name`, `folderId`, `datastoreId`, `hostId` and `powerOn` do not apply.
`name`	`string` or `null`	Name of the new virtual machine (default: `<source> (restored)`).
`powerOn`	`boolean`	Power the virtual machine on when the restore is done (default false).
`verify`	`VerifySpec` or `null`

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
400	Invalid argument; the error body names the field	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

GET `/v1/backup/repository`

The backup repository: configured or not, number of points (System.Read on the root folder).

CLI: kyvernon backup repository

Responses

Status	Description	Schema
200	OK	`BackupRepositoryView`

POST `/v1/backup/restores`

POST /v1/backup/restores

CLI: kyvernon backup restores begin --body <json>

Request body

application/json: BeginRestoreRequest

Name	Type	Required	Description
`capacity`	`integer` (int64)	yes	Capacity in bytes.
`deviceKey`	`integer` (int32)	yes	Device key the restored disk will use.
`pool`	`string`	yes	Target pool / datastore name (recorded; simulate attaches using an existing datastore).
`thin`	`boolean`		Thin provisioning.
`verify`	`VerifySpec` or `null`
`vmId`	`string` (uuid)	yes	Target VM instance UUID (new or powered-off).

Responses

Status	Description	Schema
201	Writable NBD export for the restore target	`NbdExportView`

GET `/v1/backup/restores/{vmId}`

GET /v1/backup/restores/{vmId}: the verification state of a restored VM.

CLI: kyvernon backup restores get <vm>

Parameters

Name	In	Type	Required	Description
`vmId`	path	`string` (uuid)	yes	Restored VM instance UUID

Responses

Status	Description	Schema
200	OK	`RestoreSession`

POST `/v1/backup/restores/{vmId}/disks/{deviceKey}/finish`

POST /v1/backup/restores/{vmId}/disks/{deviceKey}/finish

CLI: kyvernon backup restores finish <vm> <device-key>

Parameters

Name	In	Type	Required	Description
`vmId`	path	`string` (uuid)	yes	VM instance UUID
`deviceKey`	path	`integer` (int32)	yes	Device key

Request body

application/json: FinishRestoreRequest

Name	Type	Required	Description
`commit`	`boolean`	yes	Commit the written image and attach it; false discards.

Responses

Status	Description	Schema
204	Restore finished

POST `/v1/backup/restores/{vmId}/verify`

POST /v1/backup/restores/{vmId}/verify: verifies a restored VM now.

CLI: kyvernon backup restores verify <vm> --network <network>

Parameters

Name	In	Type	Required	Description
`vmId`	path	`string` (uuid)	yes	Restored VM instance UUID

Request body

application/json: VerifySpec

Name	Type	Required	Description
`destroy`	`boolean`		Destroy the restored VM after the verdict (default: keep it powered off).
`network`	`string`	yes	The quarantine network: id or name.
`serialMarkers`	array of `string`		Serial markers that count as an operating system (default: [`OS_MARKERS`]).
`tcpPorts`	array of `integer` (int32)		TCP ports to check from the host probe after boot and lease (empty: no TCP check).
`timeoutSeconds`	`integer` (int64) or `null`		Give up after this many seconds (default 300, at most 3600).

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`RestoreSession`

GET `/v1/backup/schedules`

The backup schedules (System.Read on the root folder).

CLI: kyvernon backup schedules list

Responses

Status	Description	Schema
200	OK	array of `BackupScheduleView`

POST `/v1/backup/schedules`

Creates a backup schedule (Global.Settings; audited). It backs up every virtual machine of its scope at the time, UTC, keeping retention points per VM.

CLI: kyvernon backup schedules create <name> --scope <id> --hour 2

Request body

application/json: BackupScheduleRequest

Name	Type	Required	Description
`enabled`	`boolean`		Runs when true.
`frequency`	`string`	yes	`daily` or `weekly`.
`fullEvery`	`integer` (int32)		A full transfer every n points (default 7).
`hour`	`integer` (int32)	yes	Hour, UTC.
`minute`	`integer` (int32)		Minute.
`name`	`string`	yes	Name.
`quiesce`	`QuiesceModeView`		Quiescing.
`retention`	`integer` (int32)		Points kept per virtual machine (default 14; 0: all).
`scope`	`string`	yes	Inventory id of the folder, datacenter, cluster, resource pool, host or virtual machine.
`weekdays`	array of `integer` (int32)		Weekdays, 0 is Sunday (weekly only).

Responses

Status	Description	Schema
201	Created	`BackupScheduleView`
400	Invalid argument; the error body names the field	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`

GET `/v1/backup/schedules/{id}`

One backup schedule.

CLI: kyvernon backup schedules get <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Schedule id (bkschedule-N).

Responses

Status	Description	Schema
200	OK	`BackupScheduleView`
404	Not found (or not visible to the caller)	`ErrorBody`

PUT `/v1/backup/schedules/{id}`

Changes a backup schedule (Global.Settings; audited). Its next run counts from now.

CLI: kyvernon backup schedules update <id> --name <name> --scope <id> --hour 2

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Schedule id (bkschedule-N).

Request body

application/json: BackupScheduleRequest

Name	Type	Required	Description
`enabled`	`boolean`		Runs when true.
`frequency`	`string`	yes	`daily` or `weekly`.
`fullEvery`	`integer` (int32)		A full transfer every n points (default 7).
`hour`	`integer` (int32)	yes	Hour, UTC.
`minute`	`integer` (int32)		Minute.
`name`	`string`	yes	Name.
`quiesce`	`QuiesceModeView`		Quiescing.
`retention`	`integer` (int32)		Points kept per virtual machine (default 14; 0: all).
`scope`	`string`	yes	Inventory id of the folder, datacenter, cluster, resource pool, host or virtual machine.
`weekdays`	array of `integer` (int32)		Weekdays, 0 is Sunday (weekly only).

Responses

Status	Description	Schema
200	OK	`BackupScheduleView`
400	Invalid argument; the error body names the field	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`

DELETE `/v1/backup/schedules/{id}`

Deletes a backup schedule (Global.Settings; audited). Its backup points stay.

CLI: kyvernon backup schedules delete <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Schedule id (bkschedule-N).

Responses

Status	Description	Schema
204	Done; no body
404	Not found (or not visible to the caller)	`ErrorBody`

POST `/v1/backup/schedules/{id}/run`

Runs a backup schedule now (Global.Settings): one backup task per virtual machine of its scope, as at its time. Answers the schedule with lastRunAt set.

CLI: kyvernon backup schedules run <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Schedule id (bkschedule-N).

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`BackupScheduleView`
404	Not found (or not visible to the caller)	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`

GET `/v1/backup/sessions`

GET /v1/backup/sessions

CLI: kyvernon backup sessions list

Parameters

Name	In	Type	Required	Description
`vmId`	query	`string` (uuid) or `null`		Filter to one VM instance UUID.

Responses

Status	Description	Schema
200	Sessions, newest first	array of `BackupSessionView`

POST `/v1/backup/sessions`

POST /v1/backup/sessions

CLI: kyvernon backup sessions begin --body <json>

Request body

application/json: BeginBackupRequestView

Name	Type	Required	Description
`disks`	array of `DiskSelectionView`		Disk selections; empty means every CBT-enabled disk with `*`.
`fallbackToFull`	`boolean`		Fall back to a full backup when a change id is stale.
`fleecing`	`boolean`		Fleecing requested.
`quiesce`	`QuiesceModeView`		Quiesce mode (`NONE` / `PREFERRED` / `REQUIRED`).
`ttlSeconds`	`integer` (int64) or `null`		Session TTL in seconds.
`vmId`	`string` (uuid)	yes	VM instance UUID.

Responses

Status	Description	Schema
201	Session in EXPORTING	`BackupSessionView`

GET `/v1/backup/sessions/{id}`

GET /v1/backup/sessions/{id}

CLI: kyvernon backup sessions get <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string` (uuid)	yes	Session id

Responses

Status	Description	Schema
200	Backup session	`BackupSessionView`

GET `/v1/backup/sessions/{id}/disks/{deviceKey}/changed-areas`

GET /v1/backup/sessions/{id}/disks/{deviceKey}/changed-areas

CLI: kyvernon backup sessions changed-areas <id> <device-key>

Parameters

Name	In	Type	Required	Description
`id`	path	`string` (uuid)	yes	Session id
`deviceKey`	path	`integer` (int32)	yes	Disk device key
`startOffset`	query	`integer` (int64) or `null`		Byte offset (granularity-aligned).
`maxAreas`	query	`integer` or `null`		Page size.

Responses

Status	Description	Schema
200	Changed areas page	`DiskChangeInfoView`

POST `/v1/backup/sessions/{id}/end`

POST /v1/backup/sessions/{id}/end

CLI: kyvernon backup sessions end <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string` (uuid)	yes	Session id

Request body

application/json: EndBackupRequestView

Name	Type	Required	Description
`outcome`	`EndOutcomeView`	yes	`SUCCESS` or `FAILURE`.

Responses

Status	Description	Schema
200	Terminal session	`BackupSessionView`

POST `/v1/backup/sessions/{id}/keepalive`

POST /v1/backup/sessions/{id}/keepalive

CLI: kyvernon backup sessions keepalive <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string` (uuid)	yes	Session id

Responses

Status	Description	Schema
200	Session with extended deadline	`BackupSessionView`

GET `/v1/backup/settings`

The backup settings (System.Read on the root folder).

CLI: kyvernon backup settings get

Responses

Status	Description	Schema
200	OK	`BackupSettingsView`

PUT `/v1/backup/settings`

Changes the backup settings (Global.Settings; audited). The repository must be an absolute directory this controller can create, the network a quarantine network and the pool a datastore. remoteExports is set in the configuration and ignored here.

CLI: kyvernon backup settings set --repository <dir>

Request body

application/json: BackupSettingsRequest

Name	Type	Required	Description
`defaultQuiesce`	`QuiesceModeView`	yes	Quiescing of backups that do not say.
`remoteExports`	`boolean` or `null`		Ignored (configuration only).
`repository`	`string`	yes	Repository directory, absolute; empty: none.
`verifyDestroy`	`boolean`	yes	Destroy verification VMs after the verdict.
`verifyNetwork`	`string`		Quarantine network (id or name); empty: none.
`verifyPool`	`string`		Datastore restored disks go to; empty: the first usable one.
`verifySchedule`	`string`		Nightly verification schedule; empty: off.
`verifyTimeoutSeconds`	`integer` (int64)	yes	Timeout of one verification, 30 to 3600 seconds.

Responses

Status	Description	Schema
200	OK	`BackupSettingsView`
400	Invalid argument; the error body names the field	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`

GET `/v1/backup/verification`

GET /v1/backup/verification: last verification run per VM.

CLI: kyvernon backup verification report

Responses

Status	Description	Schema
200	OK	`VerificationReport`

POST `/v1/backup/verification/run`

POST /v1/backup/verification/run: runs the nightly job now, in the background.

CLI: kyvernon backup verification run

Responses

Status	Description	Schema
202	Started; poll GET /v1/backup/verification

API: backup

GET /v1/backup/controller

Responses

PUT /v1/backup/controller

Request body

Responses

POST /v1/backup/controller/run

Responses

POST /v1/backup/disks/{diskId}/invalidate

Parameters

Request body

Responses

GET /v1/backup/info

Responses

GET /v1/backup/points

Parameters

Responses

POST /v1/backup/points

Request body

Responses

DELETE /v1/backup/points/{id}

Parameters

Responses

POST /v1/backup/points/{id}/restore

Parameters

Request body

Responses

GET /v1/backup/repository

Responses

POST /v1/backup/restores

Request body

Responses

GET /v1/backup/restores/{vmId}

Parameters

Responses

POST /v1/backup/restores/{vmId}/disks/{deviceKey}/finish

Parameters

Request body

Responses

POST /v1/backup/restores/{vmId}/verify

Parameters

Request body

Responses

GET /v1/backup/schedules

Responses

POST /v1/backup/schedules

Request body

Responses

GET /v1/backup/schedules/{id}

Parameters

Responses

PUT /v1/backup/schedules/{id}

Parameters

Request body

Responses

DELETE /v1/backup/schedules/{id}

Parameters

Responses

POST /v1/backup/schedules/{id}/run

Parameters

Responses

GET /v1/backup/sessions

Parameters

Responses

POST /v1/backup/sessions

Request body

Responses

GET /v1/backup/sessions/{id}

Parameters

Responses

GET /v1/backup/sessions/{id}/disks/{deviceKey}/changed-areas

Parameters

Responses

POST /v1/backup/sessions/{id}/end

Parameters

Request body

Responses

POST /v1/backup/sessions/{id}/keepalive

Parameters

Responses

GET `/v1/backup/controller`

PUT `/v1/backup/controller`

POST `/v1/backup/controller/run`

POST `/v1/backup/disks/{diskId}/invalidate`

GET `/v1/backup/info`

GET `/v1/backup/points`

POST `/v1/backup/points`

DELETE `/v1/backup/points/{id}`

POST `/v1/backup/points/{id}/restore`

GET `/v1/backup/repository`

POST `/v1/backup/restores`

GET `/v1/backup/restores/{vmId}`

POST `/v1/backup/restores/{vmId}/disks/{deviceKey}/finish`

POST `/v1/backup/restores/{vmId}/verify`

GET `/v1/backup/schedules`

POST `/v1/backup/schedules`

GET `/v1/backup/schedules/{id}`

PUT `/v1/backup/schedules/{id}`

DELETE `/v1/backup/schedules/{id}`

POST `/v1/backup/schedules/{id}/run`

GET `/v1/backup/sessions`

POST `/v1/backup/sessions`

GET `/v1/backup/sessions/{id}`

GET `/v1/backup/sessions/{id}/disks/{deviceKey}/changed-areas`

POST `/v1/backup/sessions/{id}/end`

POST `/v1/backup/sessions/{id}/keepalive`

GET `/v1/backup/settings`

PUT `/v1/backup/settings`

GET `/v1/backup/verification`

POST `/v1/backup/verification/run`