API: hosts

Host lifecycle (enter/exit maintenance mode)

POST `/v1/clusters/{id}/hosts`

Adds a pending (disconnected) host to a cluster. The agent on that machine registers with the join token and the same name to connect it.

CLI: kyvernon cluster add-host <id> --name <name>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the cluster (`domain-cN`)

Request body

application/json: AddHostRequest

Name	Type	Required	Description
`force`	`boolean` or `null`		When true, return an existing same-name host instead of failing; a registered host in this cluster is reset (its certificate revoked) so its agent can join again with the join token.
`managementAddress`	`string` or `null`		Optional management address; defaults to `name`.
`name`	`string`	yes	Host display name / FQDN (must match the agent's `hostname` at join).

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`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`

POST `/v1/clusters/{id}/move-hosts`

Moves hosts into a cluster (Host.Inventory.EditCluster on the cluster, Host.Inventory.MoveHost on each host). Each host must be in maintenance mode (error.host.not_in_maintenance) and have no virtual machines (error.host_has_vms). Runs as a task (ClusterComputeResource.moveInto).

CLI: kyvernon cluster move-hosts <id> <host>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the cluster (`domain-cN`)

Request body

application/json: MoveHostsRequest

Name	Type	Required	Description
`list`	array of `string`	yes	Host ids (`host-N`), each in maintenance mode and without virtual machines.

Responses

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

POST `/v1/clusters/{id}/reconfigure`

Reconfigures cluster HA / scheduler / migration policy (ReconfigureComputeResource_Task).

CLI: kyvernon cluster reconfigure <id> --ha-enabled true --max-bandwidth-mib-s 48

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the cluster (`domain-cN`)

Request body

application/json: ReconfigureClusterRequest

Name	Type	Description
`allowPostcopy`	`boolean` or `null`	Flip `Cluster.migration.allow_postcopy` when set.
`downtimeLimitMs`	`integer` (int64) or `null`	Set `Cluster.migration.downtime_limit_ms`. Clear with `modify=false`.
`haEnabled`	`boolean` or `null`	Flip `Cluster.ha.enabled` when set.
`maxBandwidthMibS`	`integer` (int64) or `null`	Set `Cluster.migration.max_bandwidth_mib_s` (MiB/s). Clear with `modify=false`.
`modify`	`boolean`	Merge provided fields (default) or replace missing with false/cleared.
`schedulerAutomatic`	`boolean` or `null`	Flip `Cluster.scheduler.automatic` when set.
`schedulerEnabled`	`boolean` or `null`	Flip `Cluster.scheduler.enabled` when set.

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`

GET `/v1/hosts/join-token`

The join token and the controller endpoint a new host needs (Host.Inventory.AddHostToCluster on the root folder). 404 when the controller has no join token file.

CLI: kyvernon host join-token

Responses

Status	Description	Schema
200	OK	`JoinTokenView`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`

DELETE `/v1/hosts/{id}`

Removes a host with no VMs placed on it (HostSystem.Destroy_Task).

CLI: kyvernon host destroy <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

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

POST `/v1/hosts/{id}/datastores`

Creates a local, NFS, or VMFS datastore on the host (SOAP HostDatastoreSystem).

CLI: kyvernon host create-datastore <id> --type local --name <name> --path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: CreateHostDatastoreRequest

Name	Type	Required	Description
`accessMode`	`string` or `null`		`readWrite` or `readOnly` (default `readWrite`).
`disk`	`string` or `null`		Disk key for VMFS create: WWID, `naa.…`, or device path.
`name`	`string`	yes	Datastore display name (`CreateLocalDatastore.name` / `HostNasVolumeSpec.localPath` / `HostVmfsSpec.volumeName`).
`nfsType`	`string` or `null`		`NFS` or `NFS41` (default `NFS`).
`path`	`string` or `null`		Absolute host path for a local datastore.
`remoteHost`	`string` or `null`		NFS server (`CreateNasDatastore`).
`remotePath`	`string` or `null`		NFS export path.
`securityType`	`string` or `null`		NFS security flavour (default `sys`).
`type`	`string`	yes	`local`, `nfs`, or `vmfs` (SOAP CreateLocal / CreateNas / CreateVmfs).

Responses

Status	Description	Schema
201	Created	`ObjectView`
400	Invalid argument; the error body names the field	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`
409	Conflict: the object exists, or `expectedVersion` is stale	`ErrorBody`

DELETE `/v1/hosts/{id}/datastores/{dsId}`

Removes a datastore mounted on the host (SOAP RemoveDatastore).

CLI: kyvernon host remove-datastore <id> <ds-id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)
`dsId`	path	`string`	yes	datastore-N

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/hosts/{id}/disconnect`

Disconnects a host (HostSystem.DisconnectHost_Task). Heartbeats stay disconnected until reconnect.

CLI: kyvernon host disconnect <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
404	Not found (or not visible to the caller)	`ErrorBody`

POST `/v1/hosts/{id}/enter-maintenance`

Puts a host into maintenance mode.

CLI: kyvernon host enter-maintenance <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

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

POST `/v1/hosts/{id}/exit-maintenance`

Takes a host out of maintenance mode.

CLI: kyvernon host exit-maintenance <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

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

GET `/v1/hosts/{id}/iscsi`

The software iSCSI configuration of a host: adapter, CHAP (without secrets), send and static targets, what the last rescan found (Host.Config.Storage on the host).

CLI: kyvernon host iscsi <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

Status	Description	Schema
200	OK	`IscsiConfigView`
403	Permission denied; `args.privilege` names the missing privilege	`ErrorBody`
404	Not found (or not visible to the caller)	`ErrorBody`

PUT `/v1/hosts/{id}/iscsi/authentication`

Updates adapter-level or per-target CHAP (UpdateInternetScsiAuthenticationProperties).

CLI: kyvernon host set-iscsi-auth <id> --chap-enabled --chap-name <name> --chap-secret <secret>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: IscsiAuthenticationRequest

Name	Type	Required	Description
`chapAuthEnabled`	`boolean`	yes	`chapAuthEnabled`.
`chapName`	`string` or `null`		`chapName`.
`chapSecret`	`string` or `null`		`chapSecret` (omit to reuse existing secret for the same name).
`mutualChapAuthenticationType`	`string` or `null`		Mutual CHAP type; omit / empty / `chapProhibited` disables mutual.
`mutualChapName`	`string` or `null`		`mutualChapName`.
`mutualChapSecret`	`string` or `null`		`mutualChapSecret`.
`targetSet`	`IscsiTargetSetBody` or `null`

Responses

Status	Description	Schema
204	Done; no body
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`

POST `/v1/hosts/{id}/iscsi/rescan`

Rescans one HBA (RescanHba); software iSCSI vmhba64 only.

CLI: kyvernon host rescan-iscsi <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: IscsiRescanRequest

Name	Type	Required	Description
`hbaDevice`	`string` or `null`		HBA device (`vmhba64`); defaults to the software iSCSI HBA.

Responses

Status	Description	Schema
204	Done; no body
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`

POST `/v1/hosts/{id}/iscsi/rescan-all`

Rescans every projected HBA (RescanAllHba).

CLI: kyvernon host rescan-all-iscsi <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

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

POST `/v1/hosts/{id}/iscsi/send-targets`

Adds iSCSI send targets (AddInternetScsiSendTargets).

CLI: kyvernon host add-iscsi-send-targets <id> --address <addr>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: IscsiSendTargetsRequest

Name	Type	Required	Description
`targets`	array of `IscsiSendTargetBody`	yes	Send targets to add or remove.

Responses

Status	Description	Schema
204	Done; no body
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`

DELETE `/v1/hosts/{id}/iscsi/send-targets`

Removes iSCSI send targets (RemoveInternetScsiSendTargets).

CLI: kyvernon host remove-iscsi-send-targets <id> --address <addr>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: IscsiSendTargetsRequest

Name	Type	Required	Description
`targets`	array of `IscsiSendTargetBody`	yes	Send targets to add or remove.

Responses

Status	Description	Schema
204	Done; no body
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`

PUT `/v1/hosts/{id}/iscsi/software`

Enables or disables software iSCSI (UpdateSoftwareInternetScsiEnabled).

CLI: kyvernon host set-software-iscsi <id> --enabled

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: SetSoftwareIscsiRequest

Name	Type	Required	Description
`enabled`	`boolean`	yes	Enable or disable the software iSCSI initiator.

Responses

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

POST `/v1/hosts/{id}/iscsi/static-targets`

Adds iSCSI static targets (AddInternetScsiStaticTargets).

CLI: kyvernon host add-iscsi-static-targets <id> --address <addr> --iqn <iqn>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: IscsiStaticTargetsRequest

Name	Type	Required	Description
`targets`	array of `IscsiStaticTargetBody`	yes	Static targets to add or remove.

Responses

Status	Description	Schema
204	Done; no body
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`

DELETE `/v1/hosts/{id}/iscsi/static-targets`

Removes iSCSI static targets (RemoveInternetScsiStaticTargets).

CLI: kyvernon host remove-iscsi-static-targets <id> --address <addr> --iqn <iqn>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: IscsiStaticTargetsRequest

Name	Type	Required	Description
`targets`	array of `IscsiStaticTargetBody`	yes	Static targets to add or remove.

Responses

Status	Description	Schema
204	Done; no body
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/hosts/{id}/network-health`

Host-bridge VLAN/MTU realisation health (ESX-N-17 / M1-NET-01).

CLI: kyvernon host network-health <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

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

GET `/v1/hosts/{id}/network-hints`

Lists LLDP/CDP neighbours for a host (HostNetworkSystem.QueryNetworkHint).

CLI: kyvernon host network-hints <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)
`device`	query	`string` or `null`		Optional physical NIC device names (SOAP `device`; repeat `device=` or omit).

Responses

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

POST `/v1/hosts/{id}/reboot`

Reboots a host. Needs Host.Config.Maintenance on the host and, without force, the host in maintenance mode (error.host.not_in_maintenance). The host's agent must declare the host-power capability (error.host_capability_missing).

CLI: kyvernon host reboot <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: HostPowerRequest

Name	Type	Required	Description
`force`	`boolean`		Reboot or shut down although the host is not in maintenance mode (default false). Virtual machines that still run on the host stop with it.

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`
501	The host agent cannot restart its machine (`error.host_capability_missing`)	`ErrorBody`

POST `/v1/hosts/{id}/reconnect`

Clears an admin disconnect (HostSystem.ReconnectHost_Task).

CLI: kyvernon host reconnect <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
404	Not found (or not visible to the caller)	`ErrorBody`

POST `/v1/hosts/{id}/shutdown`

Shuts a host down (powers the machine off). Same rules as reboot; the host stays off until someone powers it on (out-of-band management).

CLI: kyvernon host shutdown <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Request body

application/json: HostPowerRequest

Name	Type	Required	Description
`force`	`boolean`		Reboot or shut down although the host is not in maintenance mode (default false). Virtual machines that still run on the host stop with it.

Responses

Status	Description	Schema
202	Accepted: the body names the task to poll (`GET /v1/tasks/{id}/wait`)	`TaskRef`
404	Not found (or not visible to the caller)	`ErrorBody`
412	Failed precondition; the error body says which	`ErrorBody`
501	The host agent cannot power its machine off (`error.host_capability_missing`)	`ErrorBody`

GET `/v1/hosts/{id}/vmfs-create-options`

Lists VMFS create options for a disk (QueryVmfsDatastoreCreateOptions).

CLI: kyvernon host vmfs-create-options <id> --device-path <path>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)
`devicePath`	query	`string`	yes	Device path, WWID, or `naa.…` (SOAP `devicePath`).

Responses

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

GET `/v1/hosts/{id}/vmfs-disks`

Lists iSCSI LUNs available for VMFS create (QueryAvailableDisksForVmfs).

CLI: kyvernon host vmfs-disks <id>

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Id of the host (`host-N`)

Responses

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

API: hosts

POST /v1/clusters/{id}/hosts

Parameters

Request body

Responses

POST /v1/clusters/{id}/move-hosts

Parameters

Request body

Responses

POST /v1/clusters/{id}/reconfigure

Parameters

Request body

Responses

GET /v1/hosts/join-token

Responses

DELETE /v1/hosts/{id}

Parameters

Responses

POST /v1/hosts/{id}/datastores

Parameters

Request body

Responses

DELETE /v1/hosts/{id}/datastores/{dsId}

Parameters

Responses

POST /v1/hosts/{id}/disconnect

Parameters

Responses

POST /v1/hosts/{id}/enter-maintenance

Parameters

Responses

POST /v1/hosts/{id}/exit-maintenance

Parameters

Responses

GET /v1/hosts/{id}/iscsi

Parameters

Responses

PUT /v1/hosts/{id}/iscsi/authentication

Parameters

Request body

Responses

POST /v1/hosts/{id}/iscsi/rescan

Parameters

Request body

Responses

POST /v1/hosts/{id}/iscsi/rescan-all

Parameters

Responses

POST /v1/hosts/{id}/iscsi/send-targets

Parameters

Request body

Responses

DELETE /v1/hosts/{id}/iscsi/send-targets

Parameters

Request body

Responses

PUT /v1/hosts/{id}/iscsi/software

Parameters

Request body

Responses

POST /v1/hosts/{id}/iscsi/static-targets

Parameters

Request body

Responses

DELETE /v1/hosts/{id}/iscsi/static-targets

Parameters

Request body

Responses

GET /v1/hosts/{id}/network-health

Parameters

Responses

GET /v1/hosts/{id}/network-hints

Parameters

Responses

POST /v1/hosts/{id}/reboot

Parameters

Request body

Responses

POST /v1/hosts/{id}/reconnect

Parameters

POST `/v1/clusters/{id}/hosts`

POST `/v1/clusters/{id}/move-hosts`

POST `/v1/clusters/{id}/reconfigure`

GET `/v1/hosts/join-token`

DELETE `/v1/hosts/{id}`

POST `/v1/hosts/{id}/datastores`

DELETE `/v1/hosts/{id}/datastores/{dsId}`

POST `/v1/hosts/{id}/disconnect`

POST `/v1/hosts/{id}/enter-maintenance`

POST `/v1/hosts/{id}/exit-maintenance`

GET `/v1/hosts/{id}/iscsi`

PUT `/v1/hosts/{id}/iscsi/authentication`

POST `/v1/hosts/{id}/iscsi/rescan`

POST `/v1/hosts/{id}/iscsi/rescan-all`

POST `/v1/hosts/{id}/iscsi/send-targets`

DELETE `/v1/hosts/{id}/iscsi/send-targets`

PUT `/v1/hosts/{id}/iscsi/software`

POST `/v1/hosts/{id}/iscsi/static-targets`

DELETE `/v1/hosts/{id}/iscsi/static-targets`

GET `/v1/hosts/{id}/network-health`

GET `/v1/hosts/{id}/network-hints`

POST `/v1/hosts/{id}/reboot`

POST `/v1/hosts/{id}/reconnect`

POST `/v1/hosts/{id}/shutdown`

GET `/v1/hosts/{id}/vmfs-create-options`

GET `/v1/hosts/{id}/vmfs-disks`