Host System Enter Maintenance Mode Task
Puts the host in maintenance mode.
While this task is running and when the host is in maintenance mode, no virtual machines can be powered on and no provisioning operations can be performed on the host. Once the call completes, it is safe to turn off a host without disrupting any virtual machines.
The task completes once there are no powered-on virtual machines on the host and no provisioning operations in progress on the host. The operation does not directly initiate any operations to evacuate or power-down powered-on virtual machines. However, if the host is part of a cluster with VMware DRS enabled, DRS provides migration recommendations to evacuate the powered-on virtual machines. If DRS is in fully-automatic mode, these are automatically scheduled.
If the host is part of a cluster and the task is issued through VirtualCenter with evacuatePoweredOffVms set to true, the task will not succeed unless all the powered-off virtual machines are reregistered to other hosts. If VMware DRS is enabled, vCenter Server will automatically evacuate powered-off virtual machines.
If this API is called directly on the ESXi host, then the user is responsible for powering off, suspending or evacuating all powered-on virtual machines. The task is cancellable.
Required privileges: Host.Config.Maintenance
The unique identifier for the managed object to which the method attaches; the serialized managed object reference for a request has the form moType/moId
, in this case HostSystem/{moId}
.
The vSphere release schema. The current specification covers vSphere 8.0.2.0 APIs.
{
"timeout": 0,
"evacuatePoweredOffVms": false,
"maintenanceSpec": {
"_typeName": "string",
"vsanMode": {
"_typeName": "string",
"objectAction": "string"
},
"purpose": "string"
}
}
The task completes when the host successfully enters maintenance mode or the timeout expires, and in the latter case the task contains a Timeout fault. If the timeout is less than or equal to zero, there is no timeout. The timeout is specified in seconds.
This is a parameter only supported by VirtualCenter. If set to true, for a DRS disabled cluster, the task will not succeed unless all powered-off virtual machines have been manually reregistered; for a DRS enabled cluster, VirtualCenter will automatically reregister powered-off virtual machines and a powered-off virtual machine may remain at the host only for two reasons: (a) no compatible host found for reregistration, (b) DRS is disabled for the virtual machine. If set to false, powered-off virtual machines do not need to be moved.
The HostMaintenanceSpec data object may be used to specify actions to be taken by a host upon entering maintenance mode.
If the HostMaintenanceSpec or any of its fields are omitted in a call to EnterMaintenanceMode_Task, default actions will be chosen as documented for each field's type.
See also EnterMaintenanceMode_Task, VsanHostDecommissionMode.
This method returns a Task object with which to monitor the operation.
{
"_typeName": "string",
"type": "string",
"value": "string"
}
InvalidState: if the host is already in maintenance mode.
Timedout: if the operation timed out.
RequestCanceled: if the operation is canceled.
{
"_typeName": "string",
"faultCause": "MethodFault Object",
"faultMessage": [
{
"_typeName": "string",
"key": "string",
"arg": [
{
"_typeName": "string",
"key": "string",
"value": {
"_typeName": "string"
}
}
],
"message": "string"
}
]
}