esxi add maintenance mode (#196)

* esxi add maintenance mode

* move get_host to utils

* run pre

* run pre

* autodocs

* pre

* fix pre

* fix timeout

* to lower doc Host

* write test

* write state test

* add state test test

Author: cmcmarrow

src/saltext/vmware/modules/esxi.py

@@ -2288,3 +2288,128 @@ def get(
         return ret
     except DEFAULT_EXCEPTIONS as exc:
         raise salt.exceptions.SaltException(str(exc))
+
+
+def in_maintenance_mode(host, service_instance=None):
+    """
+    Check if host is in maintenance mode.
+
+    host
+        Host IP or HostSystem/ManagedObjectReference (required).
+
+    service_instance
+        Use this vCenter service connection instance instead of creating a new one (optional).
+
+    .. code-block:: bash
+
+        salt '*' vmware_esxi.in_maintenance_mode '10.288.6.117'
+    """
+    if isinstance(host, vim.HostSystem):
+        host_ref = host
+    else:
+        if service_instance is None:
+            service_instance = get_service_instance(opts=__opts__, pillar=__pillar__)
+        host_ref = utils_esxi.get_host(host, service_instance)
+    mode = "normal"
+    if host_ref.runtime.inMaintenanceMode:
+        mode = "inMaintenance"
+    return {"maintenanceMode": mode}
+
+
+def maintenance_mode(
+    host,
+    timeout=0,
+    evacuate_powered_off_vms=False,
+    maintenance_spec=None,
+    catch_task_error=True,
+    service_instance=None,
+):
+    """
+    Put host into maintenance mode.
+
+    host
+        Host IP or HostSystem/ManagedObjectReference (required).
+
+    timeout
+        If value is greater than 0 then task will timeout if not completed with in window (optional).
+
+    evacuate_powered_off_vms
+        Only supported by VirtualCenter (optional).
+         If True, for DRS will fail unless all powered-off VMs have been manually registered.
+         If False, task will successed with powered-off VMs.
+
+    maintenance_spec
+        HostMaintenanceSpec (optional).
+
+    catch_task_error
+        If False and task failed then a salt exception will be thrown (optional).
+
+    service_instance
+        Use this vCenter service connection instance instead of creating a new one (optional).
+
+    .. code-block:: bash
+
+        salt '*' vmware_esxi.maintenance_mode '10.288.6.117'
+    """
+    if isinstance(host, vim.HostSystem):
+        host_ref = host
+    else:
+        if service_instance is None:
+            service_instance = get_service_instance(opts=__opts__, pillar=__pillar__)
+        host_ref = utils_esxi.get_host(host, service_instance)
+    mode = in_maintenance_mode(host_ref)
+    if mode["maintenanceMode"] == "inMaintenance":
+        mode["changes"] = False
+        return mode
+    try:
+        task = host_ref.EnterMaintenanceMode_Task(
+            timeout, evacuate_powered_off_vms, maintenance_spec
+        )
+        utils_common.wait_for_task(task, host_ref.name, "maintenanceMode")
+    except salt.exceptions.SaltException as exc:
+        if not catch_task_error:
+            raise exc
+    mode = in_maintenance_mode(host_ref, service_instance)
+    mode["changes"] = mode["maintenanceMode"] == "inMaintenance"
+    return mode
+
+
+def exit_maintenance_mode(host, timeout=0, catch_task_error=True, service_instance=None):
+    """
+    Put host out of maintenance mode.
+
+    host
+        Host IP or HostSystem/ManagedObjectReference (required).
+
+    timeout
+        If value is greater than 0 then task will timeout if not completed with in window (optional).
+
+    catch_task_error
+        If False and task failed then a salt exception will be thrown (optional).
+
+    service_instance
+        Use this vCenter service connection instance instead of creating a new one (optional).
+
+    .. code-block:: bash
+
+        salt '*' vmware_esxi.exit_maintenance_mode '10.288.6.117'
+    """
+    if isinstance(host, vim.HostSystem):
+        host_ref = host
+    else:
+        if service_instance is None:
+            service_instance = get_service_instance(opts=__opts__, pillar=__pillar__)
+        host_ref = utils_esxi.get_host(host, service_instance)
+    mode = in_maintenance_mode(host_ref)
+    if mode["maintenanceMode"] == "normal":
+        mode["changes"] = False
+        return mode
+    try:
+        task = host_ref.ExitMaintenanceMode_Task(timeout)
+        utils_common.wait_for_task(task, host_ref.name, "maintenanceMode")
+    except salt.exceptions.SaltException as exc:
+        if not catch_task_error:
+            raise exc
+    mode = in_maintenance_mode(host_ref, service_instance)
+    mode["changes"] = mode["maintenanceMode"] == "normal"
+    return mode

src/saltext/vmware/states/esxi.py

@@ -651,3 +651,91 @@ def user_absent(
         ret["comment"] = "User {} doesn't exist on {} host(s).".format(name, no_user)
         ret["result"] = None
     return ret
+
+
+def maintenance_mode(
+    name,
+    enter_maintenance_mode,
+    timeout=0,
+    evacuate_powered_off_vms=False,
+    maintenance_spec=None,
+    service_instance=None,
+):
+    """
+    Put host into or out of maintenance mode.
+
+    name
+        Host IP or HostSystem/ManagedObjectReference (required).
+
+    enter_maintenance_mode
+        If True, put host into maintenance mode.
+        If False, put host out of maintenance mode.
+
+    timeout
+        If value is greater than 0 then task will timeout if not completed with in window (optional).
+
+    evacuate_powered_off_vms
+        Only supported by VirtualCenter (optional).
+         If True, for DRS will fail unless all powered-off VMs have been manually registered.
+         If False, task will successed with powered-off VMs.
+         Only relevant if enter_maintenance_mode must be True.
+
+    maintenance_spec
+        HostMaintenanceSpec (optional).
+         Only relevant if enter_maintenance_mode must be True.
+
+    service_instance
+        Use this vCenter service connection instance instead of creating a new one (optional).
+
+    .. code-block:: bash
+
+        salt '*' vmware_esxi.maintenance_mode '10.288.6.117'
+    .. code-block:: yaml
+
+        Maintenance Mode:
+          vmware_esxi.maintenance_mode:
+            - host: '10.288.6.117'
+            - enter_maintenance_mode: true
+    """
+    ret = {"name": name, "changes": {}, "result": True, "comment": ""}
+
+    # check that host is not all ready in maintenance state.
+    host_state = __salt__["vmware_esxi.in_maintenance_mode"](
+        host=name, service_instance=service_instance
+    )
+    if (host_state["maintenanceMode"] == "inMaintenance") == enter_maintenance_mode:
+        ret["comment"] = f"Already in {'Maintenance' if enter_maintenance_mode else 'Normal'} mode."
+        return ret
+
+    if __opts__["test"]:
+        ret["result"] = None
+        ret["changes"] = {
+            "new": f"Host will enter {'Maintenance' if enter_maintenance_mode else 'Normal'} mode."
+        }
+        ret["comment"] = "These options are set to change."
+        return ret
+
+    if enter_maintenance_mode:
+        host_state = __salt__["vmware_esxi.maintenance_mode"](
+            host=name,
+            timeout=timeout,
+            evacuate_powered_off_vms=evacuate_powered_off_vms,
+            maintenance_spec=maintenance_spec,
+            catch_task_error=True,
+            service_instance=service_instance,
+        )
+    else:
+        host_state = __salt__["vmware_esxi.exit_maintenance_mode"](
+            host=name, timeout=timeout, catch_task_error=True, service_instance=service_instance
+        )
+
+    ret["result"] = (host_state["maintenanceMode"] == "inMaintenance") == enter_maintenance_mode
+    if ret["result"]:
+        ret["changes"] = {
+            "new": f"Host entered {'Maintenance' if enter_maintenance_mode else 'Normal'} mode."
+        }
+    else:
+        ret[
+            "comment"
+        ] = f"Failed to put host {str(name)} in {'Maintenance' if enter_maintenance_mode else 'Normal'} mode."
+    return ret

src/saltext/vmware/utils/esxi.py

@@ -330,3 +330,7 @@ def add_host(
     task = cluster_ref.AddHost_Task(connect_spec, connect)
     host_ref = utils_common.wait_for_task(task, host, "add host task")
     return host_ref.summary.runtime.connectionState
+
+
+def get_host(host, service_instance):
+    return utils_common.get_mor_by_property(service_instance, vim.HostSystem, host)

tests/integration/modules/test_esxi.py

@@ -658,3 +658,29 @@ def test_add_update_remove_vmkernel_adapter(service_instance):
     assert ret
     for host in ret:
         assert not ret[host]
+
+
+def test_maintenance_mode(service_instance):
+    hosts = list(esxi.get(service_instance=service_instance))
+    assert hosts
+    host = hosts[0]
+    ret = esxi.in_maintenance_mode(host, service_instance)
+    assert ret == dict(maintenanceMode="normal")
+
+    try:
+        for i in range(3):
+            ret = esxi.maintenance_mode(host, 120, service_instance=service_instance)
+            assert ret == dict(maintenanceMode="inMaintenance", changes=not i)
+    except Exception as e:
+        esxi.exit_maintenance_mode(host, 120, service_instance=service_instance)
+        raise e
+
+    ret = esxi.in_maintenance_mode(host, service_instance)
+    assert ret == dict(maintenanceMode="inMaintenance")
+
+    for i in range(3):
+        ret = esxi.exit_maintenance_mode(host, 120, service_instance=service_instance)
+        assert ret == dict(maintenanceMode="normal", changes=not i)
+
+    ret = esxi.in_maintenance_mode(host, service_instance)
+    assert ret == dict(maintenanceMode="normal")

tests/integration/states/test_esxi.py

@@ -277,3 +277,38 @@ def test_vmkernel_adapter_present(vmware_datacenter, service_instance):
     )
     assert not delete_ret["result"]
     assert not delete_ret["changes"]
+
+
+def test_maintenance_mode(service_instance):
+    hosts = list(esxi_mod.get(service_instance=service_instance))
+    assert hosts
+    host = hosts[0]
+    try:
+        for i in range(3):
+            ret = esxi.maintenance_mode(host, True, 120, service_instance=service_instance)
+            assert ret["result"]
+            if not i:
+                assert ret["changes"]
+            else:
+                assert not ret["changes"]
+    except Exception as e:
+        esxi.maintenance_mode(host, False, 120, service_instance=service_instance)
+        raise e
+
+    for i in range(3):
+        ret = esxi.maintenance_mode(host, False, 120, service_instance=service_instance)
+        assert ret["result"]
+        if not i:
+            assert ret["changes"]
+        else:
+            assert not ret["changes"]
+
+
+def test_maintenance_mode_dry_run(service_instance, dry_run):
+    hosts = list(esxi_mod.get(service_instance=service_instance))
+    assert hosts
+    host = hosts[0]
+    ret = esxi.maintenance_mode(host, True, 120, service_instance=service_instance)
+    assert ret["result"] is None
+    assert ret["changes"]
+    assert ret["comment"] == "These options are set to change."