"""
Manage VMware vCenter servers and ESXi hosts.

.. versionadded:: 2015.8.4

:codeauthor: Alexandru Bleotu <alexandru.bleotu@morganstaley.com>

Dependencies
============

- pyVmomi Python Module
- ESXCLI

pyVmomi
-------

PyVmomi can be installed via pip:

.. code-block:: bash

    pip install pyVmomi

.. note::

    Version 6.0 of pyVmomi has some problems with SSL error handling on certain
    versions of Python. If using version 6.0 of pyVmomi, Python 2.7.9,
    or newer must be present. This is due to an upstream dependency
    in pyVmomi 6.0 that is not supported in Python versions 2.7 to 2.7.8. If the
    version of Python is not in the supported range, you will need to install an
    earlier version of pyVmomi. See `Issue #29537`_ for more information.

.. _Issue #29537: https://github.com/saltstack/salt/issues/29537

Based on the note above, to install an earlier version of pyVmomi than the
version currently listed in PyPi, run the following:

.. code-block:: bash

    pip install pyVmomi==5.5.0.2014.1.1

The 5.5.0.2014.1.1 is a known stable version that this original vSphere Execution
Module was developed against.

vSphere Automation SDK
----------------------

vSphere Automation SDK can be installed via pip:

.. code-block:: bash

    pip install --upgrade pip setuptools
    pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git

.. note::

    The SDK also requires OpenSSL 1.0.1+ if you want to connect to vSphere 6.5+ in order to support
    TLS1.1 & 1.2.

    In order to use the tagging functions in this module, vSphere Automation SDK is necessary to
    install.

The module is currently in version 1.0.3
(as of 8/26/2019)

ESXCLI
------

Currently, about a third of the functions used in the vSphere Execution Module require
the ESXCLI package be installed on the machine running the Proxy Minion process.

The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware
provides vCLI package installation instructions for `vSphere 5.5`_ and
`vSphere 6.0`_.

.. _vSphere 5.5: http://pubs.vmware.com/vsphere-55/index.jsp#com.vmware.vcli.getstart.doc/cli_install.4.2.html
.. _vSphere 6.0: http://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.vcli.getstart.doc/cli_install.4.2.html

Once all of the required dependencies are in place and the vCLI package is
installed, you can check to see if you can connect to your ESXi host or vCenter
server by running the following command:

.. code-block:: bash

    esxcli -s <host-location> -u <username> -p <password> system syslog config get

If the connection was successful, ESXCLI was successfully installed on your system.
You should see output related to the ESXi host's syslog configuration.

.. note::

    Be aware that some functionality in this execution module may depend on the
    type of license attached to a vCenter Server or ESXi host(s).

    For example, certain services are only available to manipulate service state
    or policies with a VMware vSphere Enterprise or Enterprise Plus license, while
    others are available with a Standard license. The ``ntpd`` service is restricted
    to an Enterprise Plus license, while ``ssh`` is available via the Standard
    license.

    Please see the `vSphere Comparison`_ page for more information.

.. _vSphere Comparison: https://www.vmware.com/products/vsphere/compare


About
=====

This execution module was designed to be able to handle connections both to a
vCenter Server, as well as to an ESXi host. It utilizes the pyVmomi Python
library and the ESXCLI package to run remote execution functions against either
the defined vCenter server or the ESXi host.

Whether or not the function runs against a vCenter Server or an ESXi host depends
entirely upon the arguments passed into the function. Each function requires a
``host`` location, ``username``, and ``password``. If the credentials provided
apply to a vCenter Server, then the function will be run against the vCenter
Server. For example, when listing hosts using vCenter credentials, you'll get a
list of hosts associated with that vCenter Server:

.. code-block:: bash

    # salt my-minion vsphere.list_hosts <vcenter-ip> <vcenter-user> <vcenter-password>
    my-minion:
    - esxi-1.example.com
    - esxi-2.example.com

However, some functions should be used against ESXi hosts, not vCenter Servers.
Functionality such as getting a host's coredump network configuration should be
performed against a host and not a vCenter server. If the authentication
information you're using is against a vCenter server and not an ESXi host, you
can provide the host name that is associated with the vCenter server in the
command, as a list, using the ``host_names`` or ``esxi_host`` kwarg. For
example:

.. code-block:: bash

    # salt my-minion vsphere.get_coredump_network_config <vcenter-ip> <vcenter-user> \
        <vcenter-password> esxi_hosts='[esxi-1.example.com, esxi-2.example.com]'
    my-minion:
    ----------
        esxi-1.example.com:
            ----------
            Coredump Config:
                ----------
                enabled:
                    False
        esxi-2.example.com:
            ----------
            Coredump Config:
                ----------
                enabled:
                    True
                host_vnic:
                    vmk0
                ip:
                    coredump-location.example.com
                port:
                    6500

You can also use these functions against an ESXi host directly by establishing a
connection to an ESXi host using the host's location, username, and password. If ESXi
connection credentials are used instead of vCenter credentials, the ``host_names`` and
``esxi_hosts`` arguments are not needed.

.. code-block:: bash

    # salt my-minion vsphere.get_coredump_network_config esxi-1.example.com root <host-password>
    local:
    ----------
        10.4.28.150:
            ----------
            Coredump Config:
                ----------
                enabled:
                    True
                host_vnic:
                    vmk0
                ip:
                    coredump-location.example.com
                port:
                    6500
"""

import datetime
import logging
import sys
from functools import wraps

import salt.utils.args
import salt.utils.dictupdate as dictupdate
import salt.utils.http
import salt.utils.path
import salt.utils.pbm
import salt.utils.vmware
import salt.utils.vsan
from salt.config.schemas.esxcluster import (
    ESXClusterConfigSchema,
    ESXClusterEntitySchema,
)
from salt.config.schemas.esxi import (
    DiskGroupsDiskIdSchema,
    SimpleHostCacheSchema,
    VmfsDatastoreSchema,
)
from salt.config.schemas.esxvm import (
    ESXVirtualMachineDeleteSchema,
    ESXVirtualMachineUnregisterSchema,
)
from salt.config.schemas.vcenter import VCenterEntitySchema
from salt.exceptions import (
    ArgumentValueError,
    CommandExecutionError,
    InvalidConfigError,
    InvalidEntityError,
    VMwareApiError,
    VMwareObjectExistsError,
    VMwareObjectRetrievalError,
    VMwareSaltError,
)
from salt.utils.decorators import depends, ignores_kwargs
from salt.utils.dictdiffer import recursive_diff
from salt.utils.listdiffer import list_diff

log = logging.getLogger(__name__)

try:
    import jsonschema

    HAS_JSONSCHEMA = True
except ImportError:
    HAS_JSONSCHEMA = False

try:
    # pylint: disable=no-name-in-module
    from pyVmomi import VmomiSupport, pbm, vim, vmodl

    # pylint: enable=no-name-in-module
    # We check the supported vim versions to infer the pyVmomi version
    if (
        "vim25/6.0" in VmomiSupport.versionMap
        and sys.version_info > (2, 7)
        and sys.version_info < (2, 7, 9)
    ):

        log.debug(
            "pyVmomi not loaded: Incompatible versions of Python. See Issue #29537."
        )
        raise ImportError()
    HAS_PYVMOMI = True
except ImportError:
    HAS_PYVMOMI = False

# vSphere SDK Automation
# pylint: disable=unused-import
try:
    from com.vmware.cis.tagging_client import (
        Category,
        CategoryModel,
        Tag,
        TagAssociation,
        TagModel,
    )

    # Error Handling
    from com.vmware.vapi.std.errors_client import (
        AlreadyExists,
        InvalidArgument,
        NotFound,
        Unauthenticated,
        Unauthorized,
    )
    from com.vmware.vapi.std_client import DynamicID
    from com.vmware.vcenter_client import Cluster

    vsphere_errors = (
        AlreadyExists,
        InvalidArgument,
        NotFound,
        Unauthenticated,
        Unauthorized,
    )
    HAS_VSPHERE_SDK = True
except ImportError:
    HAS_VSPHERE_SDK = False
# pylint: enable=unused-import

# ESXI
esx_cli = salt.utils.path.which("esxcli")
if esx_cli:
    HAS_ESX_CLI = True
else:
    HAS_ESX_CLI = False

__virtualname__ = "vsphere"
__proxyenabled__ = ["esxi", "esxcluster", "esxdatacenter", "vcenter", "esxvm"]


def __virtual__():
    return __virtualname__


def _deprecation_message(function):
    """
    Decorator wrapper to warn about azurearm deprecation
    """

    @wraps(function)
    def wrapped(*args, **kwargs):
        salt.utils.versions.warn_until(
            3008,
            "The 'vsphere' functionality in Salt has been deprecated and its "
            "functionality will be removed in version 3008 in favor of the "
            "saltext.vmware Salt Extension. "
            "(https://github.com/saltstack/salt-ext-modules-vmware)",
            category=FutureWarning,
        )
        ret = function(*args, **salt.utils.args.clean_kwargs(**kwargs))
        return ret

    return wrapped


@_deprecation_message
def get_proxy_type():
    """
    Returns the proxy type retrieved either from the pillar of from the proxy
    minion's config.  Returns ``<undefined>`` otherwise.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.get_proxy_type
    """
    if __pillar__.get("proxy", {}).get("proxytype"):
        return __pillar__["proxy"]["proxytype"]
    if __opts__.get("proxy", {}).get("proxytype"):
        return __opts__["proxy"]["proxytype"]
    return "<undefined>"


def _get_proxy_connection_details():
    """
    Returns the connection details of the following proxies: esxi
    """
    proxytype = get_proxy_type()
    if proxytype == "esxi":
        details = __salt__["esxi.get_details"]()
    elif proxytype == "esxcluster":
        details = __salt__["esxcluster.get_details"]()
    elif proxytype == "esxdatacenter":
        details = __salt__["esxdatacenter.get_details"]()
    elif proxytype == "vcenter":
        details = __salt__["vcenter.get_details"]()
    elif proxytype == "esxvm":
        details = __salt__["esxvm.get_details"]()
    else:
        raise CommandExecutionError(f"'{proxytype}' proxy is not supported")
    proxy_details = [
        details.get("vcenter") if "vcenter" in details else details.get("host"),
        details.get("username"),
        details.get("password"),
        details.get("protocol"),
        details.get("port"),
        details.get("mechanism"),
        details.get("principal"),
        details.get("domain"),
    ]
    if "verify_ssl" in details:
        proxy_details.append(details.get("verify_ssl"))
    return tuple(proxy_details)


def _supports_proxies(*proxy_types):
    """
    Decorator to specify which proxy types are supported by a function

    proxy_types:
        Arbitrary list of strings with the supported types of proxies
    """

    def _supports_proxies_(fn):
        @wraps(fn)
        def __supports_proxies_(*args, **kwargs):
            proxy_type = get_proxy_type()
            if proxy_type not in proxy_types:
                raise CommandExecutionError(
                    "'{}' proxy is not supported by function {}".format(
                        proxy_type, fn.__name__
                    )
                )
            return fn(*args, **salt.utils.args.clean_kwargs(**kwargs))

        return __supports_proxies_

    return _supports_proxies_


def _gets_service_instance_via_proxy(fn):
    """
    Decorator that connects to a target system (vCenter or ESXi host) using the
    proxy details and passes the connection (vim.ServiceInstance) to
    the decorated function.

    Supported proxies: esxi, esxcluster, esxdatacenter.

    Notes:
        1. The decorated function must have a ``service_instance`` parameter
        or a ``**kwarg`` type argument (name of argument is not important);
        2. If the ``service_instance`` parameter is already defined, the value
        is passed through to the decorated function;
        3. If the ``service_instance`` parameter in not defined, the
        connection is created using the proxy details and the service instance
        is returned.
    """
    fn_name = fn.__name__
    (
        arg_names,
        args_name,
        kwargs_name,
        default_values,
    ) = salt.utils.args.get_function_argspec(fn)
    default_values = default_values if default_values is not None else []

    @wraps(fn)
    def _gets_service_instance_via_proxy_(*args, **kwargs):
        if "service_instance" not in arg_names and not kwargs_name:
            raise CommandExecutionError(
                "Function {} must have either a 'service_instance', or a "
                "'**kwargs' type parameter".format(fn_name)
            )
        connection_details = _get_proxy_connection_details()
        # Figure out how to pass in the connection value
        local_service_instance = None
        if "service_instance" in arg_names:
            idx = arg_names.index("service_instance")
            if idx >= len(arg_names) - len(default_values):
                # 'service_instance' has a default value:
                #     we check if we need to instantiate it or
                #     pass it through
                #
                # NOTE: if 'service_instance' doesn't have a default value
                # it must be explicitly set in the function call so we pass it
                # through

                # There are two cases:
                #   1. service_instance was passed in as a positional parameter
                #   2. service_instance was passed in as a named paramter
                if len(args) > idx:
                    # case 1: The call was made with enough positional
                    # parameters to include 'service_instance'
                    if not args[idx]:
                        local_service_instance = salt.utils.vmware.get_service_instance(  # pylint: disable=no-value-for-parameter
                            *connection_details
                        )
                        # Tuples are immutable, so if we want to change what
                        # was passed in, we need to first convert to a list.
                        args = list(args)
                        args[idx] = local_service_instance
                else:
                    # case 2: Not enough positional parameters so
                    # 'service_instance' must be a named parameter
                    if not kwargs.get("service_instance"):
                        local_service_instance = salt.utils.vmware.get_service_instance(  # pylint: disable=no-value-for-parameter
                            *connection_details
                        )
                        kwargs["service_instance"] = local_service_instance
        else:
            # 'service_instance' is not a paremter in the function definition
            # but it will be caught by the **kwargs parameter
            if not kwargs.get("service_instance"):
                local_service_instance = salt.utils.vmware.get_service_instance(  # pylint: disable=no-value-for-parameter
                    *connection_details
                )
                kwargs["service_instance"] = local_service_instance
        try:
            ret = fn(*args, **salt.utils.args.clean_kwargs(**kwargs))
            # Disconnect if connected in the decorator
            if local_service_instance:
                salt.utils.vmware.disconnect(local_service_instance)
            return ret
        except Exception as e:  # pylint: disable=broad-except
            # Disconnect if connected in the decorator
            if local_service_instance:
                salt.utils.vmware.disconnect(local_service_instance)
            # raise original exception and traceback
            raise

    return _gets_service_instance_via_proxy_


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter", "vcenter", "esxvm")
@_deprecation_message
def get_service_instance_via_proxy(service_instance=None):
    """
    Returns a service instance to the proxied endpoint (vCenter/ESXi host).

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    Note:
        Should be used by state functions not invoked directly.

    CLI Example:

        See note above
    """
    connection_details = _get_proxy_connection_details()
    return salt.utils.vmware.get_service_instance(  # pylint: disable=no-value-for-parameter
        *connection_details
    )


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter", "vcenter", "esxvm")
@_deprecation_message
def disconnect(service_instance):
    """
    Disconnects from a vCenter or ESXi host

    Note:
        Should be used by state functions, not invoked directly.

    service_instance
        Service instance (vim.ServiceInstance)

    CLI Example:

        See note above.
    """
    salt.utils.vmware.disconnect(service_instance)
    return True


@depends(HAS_ESX_CLI)
@_deprecation_message
def esxcli_cmd(
    cmd_str,
    host=None,
    username=None,
    password=None,
    protocol=None,
    port=None,
    esxi_hosts=None,
    credstore=None,
):
    """
    Run an ESXCLI command directly on the host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    cmd_str
        The ESXCLI command to run. Note: This should not include the ``-s``, ``-u``,
        ``-p``, ``-h``, ``--protocol``, or ``--portnumber`` arguments that are
        frequently passed when using a bare ESXCLI command from the command line.
        Those arguments are handled by this function via the other args and kwargs.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.esxcli_cmd my.esxi.host root bad-password \
            'system coredump network get'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.esxcli_cmd my.vcenter.location root bad-password \
            'system coredump network get' esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd_str,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            if response["retcode"] != 0:
                ret.update({esxi_host: {"Error": response.get("stdout")}})
            else:
                ret.update({esxi_host: response})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd_str,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        if response["retcode"] != 0:
            ret.update({host: {"Error": response.get("stdout")}})
        else:
            ret.update({host: response})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def get_coredump_network_config(
    host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None
):
    """
    Retrieve information on ESXi or vCenter network dump collection and
    format it into a dictionary.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: A dictionary with the network configuration, or, if getting
             the network config failed, a an error message retrieved from the
             standard cmd.run_all dictionary, per host.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.get_coredump_network_config my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_coredump_network_config my.vcenter.location root bad-password \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'

    """
    cmd = "system coredump network get"
    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            if response["retcode"] != 0:
                ret.update({esxi_host: {"Error": response.get("stdout")}})
            else:
                # format the response stdout into something useful
                ret.update(
                    {esxi_host: {"Coredump Config": _format_coredump_stdout(response)}}
                )
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        if response["retcode"] != 0:
            ret.update({host: {"Error": response.get("stdout")}})
        else:
            # format the response stdout into something useful
            stdout = _format_coredump_stdout(response)
            ret.update({host: {"Coredump Config": stdout}})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def coredump_network_enable(
    host,
    username,
    password,
    enabled,
    protocol=None,
    port=None,
    esxi_hosts=None,
    credstore=None,
):
    """
    Enable or disable ESXi core dump collection. Returns ``True`` if coredump is enabled
    and returns ``False`` if core dump is not enabled. If there was an error, the error
    will be the value printed in the ``Error`` key dictionary for the given host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    enabled
        Python True or False to enable or disable coredumps.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.coredump_network_enable my.esxi.host root bad-password True

        # Used for connecting to a vCenter Server
        salt '*' vsphere.coredump_network_enable my.vcenter.location root bad-password True \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    if enabled:
        enable_it = 1
    else:
        enable_it = 0
    cmd = f"system coredump network set -e {enable_it}"

    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            if response["retcode"] != 0:
                ret.update({esxi_host: {"Error": response.get("stdout")}})
            else:
                ret.update({esxi_host: {"Coredump Enabled": enabled}})

    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        if response["retcode"] != 0:
            ret.update({host: {"Error": response.get("stdout")}})
        else:
            ret.update({host: {"Coredump Enabled": enabled}})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def set_coredump_network_config(
    host,
    username,
    password,
    dump_ip,
    protocol=None,
    port=None,
    host_vnic="vmk0",
    dump_port=6500,
    esxi_hosts=None,
    credstore=None,
):
    """

    Set the network parameters for a network coredump collection.
    Note that ESXi requires that the dumps first be enabled (see
    `coredump_network_enable`) before these parameters may be set.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    dump_ip
        IP address of host that will accept the dump.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    host_vnic
        Host VNic port through which to communicate. Defaults to ``vmk0``.

    dump_port
        TCP port to use for the dump, defaults to ``6500``.

    credstore
        Optionally set to path to the credential store file.

    :return: A standard cmd.run_all dictionary with a `success` key added, per host.
             `success` will be True if the set succeeded, False otherwise.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.set_coredump_network_config my.esxi.host root bad-password 'dump_ip.host.com'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.set_coredump_network_config my.vcenter.location root bad-password 'dump_ip.host.com' \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    cmd = "system coredump network set -v {} -i {} -o {}".format(
        host_vnic, dump_ip, dump_port
    )
    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            if response["retcode"] != 0:
                response["success"] = False
            else:
                response["success"] = True

            # Update the cmd.run_all dictionary for each particular host.
            ret.update({esxi_host: response})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        if response["retcode"] != 0:
            response["success"] = False
        else:
            response["success"] = True
        ret.update({host: response})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def get_firewall_status(
    host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None
):
    """
    Show status of all firewall rule sets.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: Nested dictionary with two toplevel keys ``rulesets`` and ``success``
             ``success`` will be True or False depending on query success
             ``rulesets`` will list the rulesets and their statuses if ``success``
             was true, per host.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.get_firewall_status my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_firewall_status my.vcenter.location root bad-password \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    cmd = "network firewall ruleset list"

    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            if response["retcode"] != 0:
                ret.update(
                    {
                        esxi_host: {
                            "Error": response["stdout"],
                            "success": False,
                            "rulesets": None,
                        }
                    }
                )
            else:
                # format the response stdout into something useful
                ret.update({esxi_host: _format_firewall_stdout(response)})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        if response["retcode"] != 0:
            ret.update(
                {
                    host: {
                        "Error": response["stdout"],
                        "success": False,
                        "rulesets": None,
                    }
                }
            )
        else:
            # format the response stdout into something useful
            ret.update({host: _format_firewall_stdout(response)})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def enable_firewall_ruleset(
    host,
    username,
    password,
    ruleset_enable,
    ruleset_name,
    protocol=None,
    port=None,
    esxi_hosts=None,
    credstore=None,
):
    """
    Enable or disable an ESXi firewall rule set.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    ruleset_enable
        True to enable the ruleset, false to disable.

    ruleset_name
        Name of ruleset to target.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: A standard cmd.run_all dictionary, per host.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.enable_firewall_ruleset my.esxi.host root bad-password True 'syslog'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.enable_firewall_ruleset my.vcenter.location root bad-password True 'syslog' \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    cmd = "network firewall ruleset set --enabled {} --ruleset-id={}".format(
        ruleset_enable, ruleset_name
    )

    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            ret.update({esxi_host: response})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        ret.update({host: response})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def syslog_service_reload(
    host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None
):
    """
    Reload the syslog service so it will pick up any changes.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: A standard cmd.run_all dictionary.  This dictionary will at least
             have a `retcode` key.  If `retcode` is 0 the command was successful.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.syslog_service_reload my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.syslog_service_reload my.vcenter.location root bad-password \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    cmd = "system syslog reload"

    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            ret.update({esxi_host: response})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        ret.update({host: response})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def set_syslog_config(
    host,
    username,
    password,
    syslog_config,
    config_value,
    protocol=None,
    port=None,
    firewall=True,
    reset_service=True,
    esxi_hosts=None,
    credstore=None,
):
    """
    Set the specified syslog configuration parameter. By default, this function will
    reset the syslog service after the configuration is set.

    host
        ESXi or vCenter host to connect to.

    username
        User to connect as, usually root.

    password
        Password to connect with.

    syslog_config
        Name of parameter to set (corresponds to the command line switch for
        esxcli without the double dashes (--))

        Valid syslog_config values are ``logdir``, ``loghost``, ``default-rotate`,
        ``default-size``, ``default-timeout``, and ``logdir-unique``.

    config_value
        Value for the above parameter. For ``loghost``, URLs or IP addresses to
        use for logging. Multiple log servers can be specified by listing them,
        comma-separated, but without spaces before or after commas.

        (reference: https://blogs.vmware.com/vsphere/2012/04/configuring-multiple-syslog-servers-for-esxi-5.html)

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    firewall
        Enable the firewall rule set for syslog. Defaults to ``True``.

    reset_service
        After a successful parameter set, reset the service. Defaults to ``True``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: Dictionary with a top-level key of 'success' which indicates
             if all the parameters were reset, and individual keys
             for each parameter indicating which succeeded or failed, per host.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.set_syslog_config my.esxi.host root bad-password \
            loghost ssl://localhost:5432,tcp://10.1.0.1:1514

        # Used for connecting to a vCenter Server
        salt '*' vsphere.set_syslog_config my.vcenter.location root bad-password \
            loghost ssl://localhost:5432,tcp://10.1.0.1:1514 \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'

    """
    ret = {}

    # First, enable the syslog firewall ruleset, for each host, if needed.
    if firewall and syslog_config == "loghost":
        if esxi_hosts:
            if not isinstance(esxi_hosts, list):
                raise CommandExecutionError("'esxi_hosts' must be a list.")

            for esxi_host in esxi_hosts:
                response = enable_firewall_ruleset(
                    host,
                    username,
                    password,
                    ruleset_enable=True,
                    ruleset_name="syslog",
                    protocol=protocol,
                    port=port,
                    esxi_hosts=[esxi_host],
                    credstore=credstore,
                ).get(esxi_host)
                if response["retcode"] != 0:
                    ret.update(
                        {
                            esxi_host: {
                                "enable_firewall": {
                                    "message": response["stdout"],
                                    "success": False,
                                }
                            }
                        }
                    )
                else:
                    ret.update({esxi_host: {"enable_firewall": {"success": True}}})
        else:
            # Handles a single host or a vCenter connection when no esxi_hosts are provided.
            response = enable_firewall_ruleset(
                host,
                username,
                password,
                ruleset_enable=True,
                ruleset_name="syslog",
                protocol=protocol,
                port=port,
                credstore=credstore,
            ).get(host)
            if response["retcode"] != 0:
                ret.update(
                    {
                        host: {
                            "enable_firewall": {
                                "message": response["stdout"],
                                "success": False,
                            }
                        }
                    }
                )
            else:
                ret.update({host: {"enable_firewall": {"success": True}}})

    # Set the config value on each esxi_host, if provided.
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = _set_syslog_config_helper(
                host,
                username,
                password,
                syslog_config,
                config_value,
                protocol=protocol,
                port=port,
                reset_service=reset_service,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            # Ensure we don't overwrite any dictionary data already set
            # By updating the esxi_host directly.
            if ret.get(esxi_host) is None:
                ret.update({esxi_host: {}})
            ret[esxi_host].update(response)

    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = _set_syslog_config_helper(
            host,
            username,
            password,
            syslog_config,
            config_value,
            protocol=protocol,
            port=port,
            reset_service=reset_service,
            credstore=credstore,
        )
        # Ensure we don't overwrite any dictionary data already set
        # By updating the host directly.
        if ret.get(host) is None:
            ret.update({host: {}})
        ret[host].update(response)

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def get_syslog_config(
    host, username, password, protocol=None, port=None, esxi_hosts=None, credstore=None
):
    """
    Retrieve the syslog configuration.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: Dictionary with keys and values corresponding to the
             syslog configuration, per host.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.get_syslog_config my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_syslog_config my.vcenter.location root bad-password \
            esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    cmd = "system syslog config get"

    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            # format the response stdout into something useful
            ret.update({esxi_host: _format_syslog_config(response)})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response = salt.utils.vmware.esxcli(
            host,
            username,
            password,
            cmd,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        # format the response stdout into something useful
        ret.update({host: _format_syslog_config(response)})

    return ret


@depends(HAS_ESX_CLI)
@_deprecation_message
def reset_syslog_config(
    host,
    username,
    password,
    protocol=None,
    port=None,
    syslog_config=None,
    esxi_hosts=None,
    credstore=None,
):
    """
    Reset the syslog service to its default settings.

    Valid syslog_config values are ``logdir``, ``loghost``, ``logdir-unique``,
    ``default-rotate``, ``default-size``, ``default-timeout``,
    or ``all`` for all of these.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    syslog_config
        List of parameters to reset, provided as a comma-delimited string, or 'all' to
        reset all syslog configuration parameters. Required.

    esxi_hosts
        If ``host`` is a vCenter host, then use esxi_hosts to execute this function
        on a list of one or more ESXi machines.

    credstore
        Optionally set to path to the credential store file.

    :return: Dictionary with a top-level key of 'success' which indicates
             if all the parameters were reset, and individual keys
             for each parameter indicating which succeeded or failed, per host.

    .. note::

        ``syslog_config`` can be passed as a quoted, comma-separated string. See CLI Example for details.

    CLI Example:

    .. code-block:: bash

        # Used for ESXi host connection information
        salt '*' vsphere.reset_syslog_config my.esxi.host root bad-password \
            syslog_config='logdir,loghost'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.reset_syslog_config my.vcenter.location root bad-password \
            syslog_config='logdir,loghost' esxi_hosts='[esxi-1.host.com, esxi-2.host.com]'
    """
    if not syslog_config:
        raise CommandExecutionError(
            "The 'reset_syslog_config' function requires a 'syslog_config' setting."
        )

    valid_resets = [
        "logdir",
        "loghost",
        "default-rotate",
        "default-size",
        "default-timeout",
        "logdir-unique",
    ]
    cmd = "system syslog config set --reset="
    if "," in syslog_config:
        resets = [ind_reset.strip() for ind_reset in syslog_config.split(",")]
    elif syslog_config == "all":
        resets = valid_resets
    else:
        resets = [syslog_config]

    ret = {}
    if esxi_hosts:
        if not isinstance(esxi_hosts, list):
            raise CommandExecutionError("'esxi_hosts' must be a list.")

        for esxi_host in esxi_hosts:
            response_dict = _reset_syslog_config_params(
                host,
                username,
                password,
                cmd,
                resets,
                valid_resets,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            ret.update({esxi_host: response_dict})
    else:
        # Handles a single host or a vCenter connection when no esxi_hosts are provided.
        response_dict = _reset_syslog_config_params(
            host,
            username,
            password,
            cmd,
            resets,
            valid_resets,
            protocol=protocol,
            port=port,
            credstore=credstore,
        )
        ret.update({host: response_dict})

    return ret


@ignores_kwargs("credstore")
@_deprecation_message
def upload_ssh_key(
    host,
    username,
    password,
    ssh_key=None,
    ssh_key_file=None,
    protocol=None,
    port=None,
    certificate_verify=None,
):
    """
    Upload an ssh key for root to an ESXi host via http PUT.
    This function only works for ESXi, not vCenter.
    Only one ssh key can be uploaded for root.  Uploading a second key will
    replace any existing key.

    :param host: The location of the ESXi Host
    :param username: Username to connect as
    :param password: Password for the ESXi web endpoint
    :param ssh_key: Public SSH key, will be added to authorized_keys on ESXi
    :param ssh_key_file: File containing the SSH key.  Use 'ssh_key' or
                         ssh_key_file, but not both.
    :param protocol: defaults to https, can be http if ssl is disabled on ESXi
    :param port: defaults to 443 for https
    :param certificate_verify: If true require that the SSL connection present
                               a valid certificate. Default: True
    :return: Dictionary with a 'status' key, True if upload is successful.
             If upload is unsuccessful, 'status' key will be False and
             an 'Error' key will have an informative message.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.upload_ssh_key my.esxi.host root bad-password ssh_key_file='/etc/salt/my_keys/my_key.pub'

    """
    if protocol is None:
        protocol = "https"
    if port is None:
        port = 443
    if certificate_verify is None:
        certificate_verify = True

    url = f"{protocol}://{host}:{port}/host/ssh_root_authorized_keys"
    ret = {}
    result = None
    try:
        if ssh_key:
            result = salt.utils.http.query(
                url,
                status=True,
                text=True,
                method="PUT",
                username=username,
                password=password,
                data=ssh_key,
                verify_ssl=certificate_verify,
            )
        elif ssh_key_file:
            result = salt.utils.http.query(
                url,
                status=True,
                text=True,
                method="PUT",
                username=username,
                password=password,
                data_file=ssh_key_file,
                data_render=False,
                verify_ssl=certificate_verify,
            )
        if result.get("status") == 200:
            ret["status"] = True
        else:
            ret["status"] = False
            ret["Error"] = result["error"]
    except Exception as msg:  # pylint: disable=broad-except
        ret["status"] = False
        ret["Error"] = msg

    return ret


@ignores_kwargs("credstore")
@_deprecation_message
def get_ssh_key(
    host, username, password, protocol=None, port=None, certificate_verify=None
):
    """
    Retrieve the authorized_keys entry for root.
    This function only works for ESXi, not vCenter.

    :param host: The location of the ESXi Host
    :param username: Username to connect as
    :param password: Password for the ESXi web endpoint
    :param protocol: defaults to https, can be http if ssl is disabled on ESXi
    :param port: defaults to 443 for https
    :param certificate_verify: If true require that the SSL connection present
                               a valid certificate. Default: True
    :return: True if upload is successful

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.get_ssh_key my.esxi.host root bad-password certificate_verify=True

    """
    if protocol is None:
        protocol = "https"
    if port is None:
        port = 443
    if certificate_verify is None:
        certificate_verify = True

    url = f"{protocol}://{host}:{port}/host/ssh_root_authorized_keys"
    ret = {}
    try:
        result = salt.utils.http.query(
            url,
            status=True,
            text=True,
            method="GET",
            username=username,
            password=password,
            verify_ssl=certificate_verify,
        )
        if result.get("status") == 200:
            ret["status"] = True
            ret["key"] = result["text"]
        else:
            ret["status"] = False
            ret["Error"] = result["error"]
    except Exception as msg:  # pylint: disable=broad-except
        ret["status"] = False
        ret["Error"] = msg

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_host_datetime(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Get the date/time information for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to get date/time information.

        If host_names is not provided, the date/time information will be retrieved for the
        ``host`` location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_host_datetime my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_host_datetime my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        date_time_manager = _get_date_time_mgr(host_ref)
        date_time = date_time_manager.QueryDateTime()
        ret.update({host_name: date_time})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_ntp_config(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Get the NTP configuration information for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to get ntp configuration information.

        If host_names is not provided, the NTP configuration will be retrieved for the
        ``host`` location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_ntp_config my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_ntp_config my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        ntp_config = host_ref.configManager.dateTimeSystem.dateTimeInfo.ntpConfig.server
        ret.update({host_name: ntp_config})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_service_policy(
    host,
    username,
    password,
    service_name,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Get the service name's policy for a given host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    service_name
        The name of the service for which to retrieve the policy. Supported service names are:
          - DCUI
          - TSM
          - SSH
          - lbtd
          - lsassd
          - lwiod
          - netlogond
          - ntpd
          - sfcbd-watchdog
          - snmpd
          - vprobed
          - vpxa
          - xorg

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to get service policy information.

        If host_names is not provided, the service policy information will be retrieved
        for the ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_service_policy my.esxi.host root bad-password 'ssh'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_service_policy my.vcenter.location root bad-password 'ntpd' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    valid_services = [
        "DCUI",
        "TSM",
        "SSH",
        "ssh",
        "lbtd",
        "lsassd",
        "lwiod",
        "netlogond",
        "ntpd",
        "sfcbd-watchdog",
        "snmpd",
        "vprobed",
        "vpxa",
        "xorg",
    ]
    host_names = _check_hosts(service_instance, host, host_names)

    ret = {}
    for host_name in host_names:
        # Check if the service_name provided is a valid one.
        # If we don't have a valid service, return. The service will be invalid for all hosts.
        if service_name not in valid_services:
            ret.update(
                {host_name: {"Error": f"{service_name} is not a valid service name."}}
            )
            return ret

        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        services = host_ref.configManager.serviceSystem.serviceInfo.service

        # Don't require users to know that VMware lists the ssh service as TSM-SSH
        if service_name == "SSH" or service_name == "ssh":
            temp_service_name = "TSM-SSH"
        else:
            temp_service_name = service_name

        # Loop through services until we find a matching name
        for service in services:
            if service.key == temp_service_name:
                ret.update({host_name: {service_name: service.policy}})
                # We've found a match - break out of the loop so we don't overwrite the
                # Updated host_name value with an error message.
                break
            else:
                msg = "Could not find service '{}' for host '{}'.".format(
                    service_name, host_name
                )
                ret.update({host_name: {"Error": msg}})

        # If we made it this far, something else has gone wrong.
        if ret.get(host_name) is None:
            msg = f"'vsphere.get_service_policy' failed for host {host_name}."
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_service_running(
    host,
    username,
    password,
    service_name,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Get the service name's running state for a given host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    service_name
        The name of the service for which to retrieve the policy. Supported service names are:
          - DCUI
          - TSM
          - SSH
          - lbtd
          - lsassd
          - lwiod
          - netlogond
          - ntpd
          - sfcbd-watchdog
          - snmpd
          - vprobed
          - vpxa
          - xorg

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to get the service's running state.

        If host_names is not provided, the service's running state will be retrieved
        for the ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_service_running my.esxi.host root bad-password 'ssh'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_service_running my.vcenter.location root bad-password 'ntpd' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    valid_services = [
        "DCUI",
        "TSM",
        "SSH",
        "ssh",
        "lbtd",
        "lsassd",
        "lwiod",
        "netlogond",
        "ntpd",
        "sfcbd-watchdog",
        "snmpd",
        "vprobed",
        "vpxa",
        "xorg",
    ]
    host_names = _check_hosts(service_instance, host, host_names)

    ret = {}
    for host_name in host_names:
        # Check if the service_name provided is a valid one.
        # If we don't have a valid service, return. The service will be invalid for all hosts.
        if service_name not in valid_services:
            ret.update(
                {host_name: {"Error": f"{service_name} is not a valid service name."}}
            )
            return ret

        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        services = host_ref.configManager.serviceSystem.serviceInfo.service

        # Don't require users to know that VMware lists the ssh service as TSM-SSH
        if service_name == "SSH" or service_name == "ssh":
            temp_service_name = "TSM-SSH"
        else:
            temp_service_name = service_name

        # Loop through services until we find a matching name
        for service in services:
            if service.key == temp_service_name:
                ret.update({host_name: {service_name: service.running}})
                # We've found a match - break out of the loop so we don't overwrite the
                # Updated host_name value with an error message.
                break
            else:
                msg = "Could not find service '{}' for host '{}'.".format(
                    service_name, host_name
                )
                ret.update({host_name: {"Error": msg}})

        # If we made it this far, something else has gone wrong.
        if ret.get(host_name) is None:
            msg = f"'vsphere.get_service_running' failed for host {host_name}."
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_vmotion_enabled(
    host,
    username,
    password,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Get the VMotion enabled status for a given host or a list of host_names. Returns ``True``
    if VMotion is enabled, ``False`` if it is not enabled.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts to check if VMotion is enabled.

        If host_names is not provided, the VMotion status will be retrieved for the
        ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_vmotion_enabled my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_vmotion_enabled my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vmotion_vnic = host_ref.configManager.vmotionSystem.netConfig.selectedVnic
        if vmotion_vnic:
            ret.update({host_name: {"VMotion Enabled": True}})
        else:
            ret.update({host_name: {"VMotion Enabled": False}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_vsan_enabled(
    host,
    username,
    password,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Get the VSAN enabled status for a given host or a list of host_names. Returns ``True``
    if VSAN is enabled, ``False`` if it is not enabled, and ``None`` if a VSAN Host Config
    is unset, per host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts to check if VSAN enabled.

        If host_names is not provided, the VSAN status will be retrieved for the
        ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_vsan_enabled my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_vsan_enabled my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vsan_config = host_ref.config.vsanHostConfig

        # We must have a VSAN Config in place get information about VSAN state.
        if vsan_config is None:
            msg = f"VSAN System Config Manager is unset for host '{host_name}'."
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
        else:
            ret.update({host_name: {"VSAN Enabled": vsan_config.enabled}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def get_vsan_eligible_disks(
    host,
    username,
    password,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Returns a list of VSAN-eligible disks for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts to check if any VSAN-eligible disks are available.

        If host_names is not provided, the VSAN-eligible disks will be retrieved
        for the ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.get_vsan_eligible_disks my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.get_vsan_eligible_disks my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    response = _get_vsan_eligible_disks(service_instance, host, host_names)

    ret = {}
    for host_name, value in response.items():
        error = value.get("Error")
        if error:
            ret.update({host_name: {"Error": error}})
            continue

        disks = value.get("Eligible")
        # If we have eligible disks, it will be a list of disk objects
        if disks and isinstance(disks, list):
            disk_names = []
            # We need to return ONLY the disk names, otherwise
            # MessagePack can't deserialize the disk objects.
            for disk in disks:
                disk_names.append(disk.canonicalName)
            ret.update({host_name: {"Eligible": disk_names}})
        else:
            # If we have disks, but it's not a list, it's actually a
            # string message that we're passing along.
            ret.update({host_name: {"Eligible": disks}})

    return ret


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter", "vcenter", "esxvm")
@_gets_service_instance_via_proxy
@_deprecation_message
def test_vcenter_connection(service_instance=None):
    """
    Checks if a connection is to a vCenter

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.test_vcenter_connection
    """
    try:
        if salt.utils.vmware.is_connection_to_a_vcenter(service_instance):
            return True
    except VMwareSaltError:
        return False
    return False


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def system_info(
    host,
    username,
    password,
    protocol=None,
    port=None,
    verify_ssl=True,
):
    """
    Return system information about a VMware environment.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.system_info 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    ret = salt.utils.vmware.get_inventory(service_instance).about.__dict__
    if "apiType" in ret:
        if ret["apiType"] == "HostAgent":
            ret = dictupdate.update(
                ret, salt.utils.vmware.get_hardware_grains(service_instance)
            )
    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_datacenters(
    host, username, password, protocol=None, port=None, verify_ssl=True
):
    """
    Returns a list of datacenters for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_datacenters 1.2.3.4 root bad-password

    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_datacenters(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_clusters(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of clusters for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_clusters 1.2.3.4 root bad-password

    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_clusters(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_datastore_clusters(
    host, username, password, protocol=None, port=None, verify_ssl=True
):
    """
    Returns a list of datastore clusters for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_datastore_clusters 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_datastore_clusters(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_datastores(
    host, username, password, protocol=None, port=None, verify_ssl=True
):
    """
    Returns a list of datastores for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_datastores 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_datastores(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_hosts(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of hosts for the specified VMware environment.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_hosts 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_hosts(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_resourcepools(
    host, username, password, protocol=None, port=None, verify_ssl=True
):
    """
    Returns a list of resource pools for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_resourcepools 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_resourcepools(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_networks(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of networks for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_networks 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_networks(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_vms(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of VMs for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_vms 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_vms(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_folders(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of folders for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_folders 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_folders(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_dvs(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of distributed virtual switches for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_dvs 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_dvs(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_vapps(host, username, password, protocol=None, port=None, verify_ssl=True):
    """
    Returns a list of vApps for the specified host.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # List vapps from all minions
        salt '*' vsphere.list_vapps 1.2.3.4 root bad-password
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    return salt.utils.vmware.list_vapps(service_instance)


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_ssds(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Returns a list of SSDs for the given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter the hosts for which to retrieve SSDs.

        If host_names is not provided, SSDs will be retrieved for the
        ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.list_ssds my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.list_ssds my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    names = []
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        disks = _get_host_ssds(host_ref)
        for disk in disks:
            names.append(disk.canonicalName)
        ret.update({host_name: names})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def list_non_ssds(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Returns a list of Non-SSD disks for the given host or list of host_names.

    .. note::

        In the pyVmomi StorageSystem, ScsiDisks may, or may not have an ``ssd`` attribute.
        This attribute indicates if the ScsiDisk is SSD backed. As this option is optional,
        if a relevant disk in the StorageSystem does not have ``ssd = true``, it will end
        up in the ``non_ssds`` list here.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter the hosts for which to retrieve Non-SSD disks.

        If host_names is not provided, Non-SSD disks will be retrieved for the
        ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.list_non_ssds my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.list_non_ssds my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    names = []
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        disks = _get_host_non_ssds(host_ref)
        for disk in disks:
            names.append(disk.canonicalName)
        ret.update({host_name: names})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def set_ntp_config(
    host,
    username,
    password,
    ntp_servers,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Set NTP configuration for a given host of list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    ntp_servers
        A list of servers that should be added to and configured for the specified
        host's NTP configuration.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter which hosts to configure ntp servers.

        If host_names is not provided, the NTP servers will be configured for the
        ``host`` location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.ntp_configure my.esxi.host root bad-password '[192.174.1.100, 192.174.1.200]'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.ntp_configure my.vcenter.location root bad-password '[192.174.1.100, 192.174.1.200]' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    if not isinstance(ntp_servers, list):
        raise CommandExecutionError("'ntp_servers' must be a list.")

    # Get NTP Config Object from ntp_servers
    ntp_config = vim.HostNtpConfig(server=ntp_servers)

    # Get DateTimeConfig object from ntp_config
    date_config = vim.HostDateTimeConfig(ntpConfig=ntp_config)

    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        date_time_manager = _get_date_time_mgr(host_ref)
        log.debug("Configuring NTP Servers '%s' for host '%s'.", ntp_servers, host_name)

        try:
            date_time_manager.UpdateDateTimeConfig(config=date_config)
        except vim.fault.HostConfigFault as err:
            msg = f"vsphere.ntp_configure_servers failed: {err}"
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
            continue

        ret.update({host_name: {"NTP Servers": ntp_config}})
    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def service_start(
    host,
    username,
    password,
    service_name,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Start the named service for the given host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    service_name
        The name of the service for which to set the policy. Supported service names are:
          - DCUI
          - TSM
          - SSH
          - lbtd
          - lsassd
          - lwiod
          - netlogond
          - ntpd
          - sfcbd-watchdog
          - snmpd
          - vprobed
          - vpxa
          - xorg

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to start the service.

        If host_names is not provided, the service will be started for the ``host``
        location instead. This is useful for when service instance connection information
        is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.service_start my.esxi.host root bad-password 'ntpd'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.service_start my.vcenter.location root bad-password 'ntpd' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    valid_services = [
        "DCUI",
        "TSM",
        "SSH",
        "ssh",
        "lbtd",
        "lsassd",
        "lwiod",
        "netlogond",
        "ntpd",
        "sfcbd-watchdog",
        "snmpd",
        "vprobed",
        "vpxa",
        "xorg",
    ]
    ret = {}

    # Don't require users to know that VMware lists the ssh service as TSM-SSH
    if service_name == "SSH" or service_name == "ssh":
        temp_service_name = "TSM-SSH"
    else:
        temp_service_name = service_name

    for host_name in host_names:
        # Check if the service_name provided is a valid one.
        # If we don't have a valid service, return. The service will be invalid for all hosts.
        if service_name not in valid_services:
            ret.update(
                {host_name: {"Error": f"{service_name} is not a valid service name."}}
            )
            return ret

        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        service_manager = _get_service_manager(host_ref)
        log.debug("Starting the '%s' service on %s.", service_name, host_name)

        # Start the service
        try:
            service_manager.StartService(id=temp_service_name)
        except vim.fault.HostConfigFault as err:
            msg = "'vsphere.service_start' failed for host {}: {}".format(
                host_name, err
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
            continue
        # Some services are restricted by the vSphere License Level.
        except vim.fault.RestrictedVersion as err:
            log.debug(err)
            ret.update({host_name: {"Error": err}})
            continue

        ret.update({host_name: {"Service Started": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def service_stop(
    host,
    username,
    password,
    service_name,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Stop the named service for the given host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    service_name
        The name of the service for which to set the policy. Supported service names are:
          - DCUI
          - TSM
          - SSH
          - lbtd
          - lsassd
          - lwiod
          - netlogond
          - ntpd
          - sfcbd-watchdog
          - snmpd
          - vprobed
          - vpxa
          - xorg

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to stop the service.

        If host_names is not provided, the service will be stopped for the ``host``
        location instead. This is useful for when service instance connection information
        is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.service_stop my.esxi.host root bad-password 'ssh'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.service_stop my.vcenter.location root bad-password 'ssh' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    valid_services = [
        "DCUI",
        "TSM",
        "SSH",
        "ssh",
        "lbtd",
        "lsassd",
        "lwiod",
        "netlogond",
        "ntpd",
        "sfcbd-watchdog",
        "snmpd",
        "vprobed",
        "vpxa",
        "xorg",
    ]
    ret = {}

    # Don't require users to know that VMware lists the ssh service as TSM-SSH
    if service_name == "SSH" or service_name == "ssh":
        temp_service_name = "TSM-SSH"
    else:
        temp_service_name = service_name

    for host_name in host_names:
        # Check if the service_name provided is a valid one.
        # If we don't have a valid service, return. The service will be invalid for all hosts.
        if service_name not in valid_services:
            ret.update(
                {host_name: {"Error": f"{service_name} is not a valid service name."}}
            )
            return ret

        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        service_manager = _get_service_manager(host_ref)
        log.debug("Stopping the '%s' service on %s.", service_name, host_name)

        # Stop the service.
        try:
            service_manager.StopService(id=temp_service_name)
        except vim.fault.HostConfigFault as err:
            msg = f"'vsphere.service_stop' failed for host {host_name}: {err}"
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
            continue
        # Some services are restricted by the vSphere License Level.
        except vim.fault.RestrictedVersion as err:
            log.debug(err)
            ret.update({host_name: {"Error": err}})
            continue

        ret.update({host_name: {"Service Stopped": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def service_restart(
    host,
    username,
    password,
    service_name,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Restart the named service for the given host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    service_name
        The name of the service for which to set the policy. Supported service names are:
          - DCUI
          - TSM
          - SSH
          - lbtd
          - lsassd
          - lwiod
          - netlogond
          - ntpd
          - sfcbd-watchdog
          - snmpd
          - vprobed
          - vpxa
          - xorg

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to restart the service.

        If host_names is not provided, the service will be restarted for the ``host``
        location instead. This is useful for when service instance connection information
        is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.service_restart my.esxi.host root bad-password 'ntpd'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.service_restart my.vcenter.location root bad-password 'ntpd' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    valid_services = [
        "DCUI",
        "TSM",
        "SSH",
        "ssh",
        "lbtd",
        "lsassd",
        "lwiod",
        "netlogond",
        "ntpd",
        "sfcbd-watchdog",
        "snmpd",
        "vprobed",
        "vpxa",
        "xorg",
    ]
    ret = {}

    # Don't require users to know that VMware lists the ssh service as TSM-SSH
    if service_name == "SSH" or service_name == "ssh":
        temp_service_name = "TSM-SSH"
    else:
        temp_service_name = service_name

    for host_name in host_names:
        # Check if the service_name provided is a valid one.
        # If we don't have a valid service, return. The service will be invalid for all hosts.
        if service_name not in valid_services:
            ret.update(
                {host_name: {"Error": f"{service_name} is not a valid service name."}}
            )
            return ret

        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        service_manager = _get_service_manager(host_ref)
        log.debug("Restarting the '%s' service on %s.", service_name, host_name)

        # Restart the service.
        try:
            service_manager.RestartService(id=temp_service_name)
        except vim.fault.HostConfigFault as err:
            msg = "'vsphere.service_restart' failed for host {}: {}".format(
                host_name, err
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
            continue
        # Some services are restricted by the vSphere License Level.
        except vim.fault.RestrictedVersion as err:
            log.debug(err)
            ret.update({host_name: {"Error": err}})
            continue

        ret.update({host_name: {"Service Restarted": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def set_service_policy(
    host,
    username,
    password,
    service_name,
    service_policy,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Set the service name's policy for a given host or list of hosts.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    service_name
        The name of the service for which to set the policy. Supported service names are:
          - DCUI
          - TSM
          - SSH
          - lbtd
          - lsassd
          - lwiod
          - netlogond
          - ntpd
          - sfcbd-watchdog
          - snmpd
          - vprobed
          - vpxa
          - xorg

    service_policy
        The policy to set for the service. For example, 'automatic'.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to tell
        vCenter the hosts for which to set the service policy.

        If host_names is not provided, the service policy information will be retrieved
        for the ``host`` location instead. This is useful for when service instance
        connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.set_service_policy my.esxi.host root bad-password 'ntpd' 'automatic'

        # Used for connecting to a vCenter Server
        salt '*' vsphere.set_service_policy my.vcenter.location root bad-password 'ntpd' 'automatic' \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    valid_services = [
        "DCUI",
        "TSM",
        "SSH",
        "ssh",
        "lbtd",
        "lsassd",
        "lwiod",
        "netlogond",
        "ntpd",
        "sfcbd-watchdog",
        "snmpd",
        "vprobed",
        "vpxa",
        "xorg",
    ]
    ret = {}

    for host_name in host_names:
        # Check if the service_name provided is a valid one.
        # If we don't have a valid service, return. The service will be invalid for all hosts.
        if service_name not in valid_services:
            ret.update(
                {host_name: {"Error": f"{service_name} is not a valid service name."}}
            )
            return ret

        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        service_manager = _get_service_manager(host_ref)
        services = host_ref.configManager.serviceSystem.serviceInfo.service

        # Services are stored in a general list - we need loop through the list and find
        # service key that matches our service name.
        for service in services:
            service_key = None

            # Find the service key based on the given service_name
            if service.key == service_name:
                service_key = service.key
            elif service_name == "ssh" or service_name == "SSH":
                if service.key == "TSM-SSH":
                    service_key = "TSM-SSH"

            # If we have a service_key, we've found a match. Update the policy.
            if service_key:
                try:
                    service_manager.UpdateServicePolicy(
                        id=service_key, policy=service_policy
                    )
                except vim.fault.NotFound:
                    msg = f"The service name '{service_name}' was not found."
                    log.debug(msg)
                    ret.update({host_name: {"Error": msg}})
                    continue
                # Some services are restricted by the vSphere License Level.
                except vim.fault.HostConfigFault as err:
                    msg = "'vsphere.set_service_policy' failed for host {}: {}".format(
                        host_name, err
                    )
                    log.debug(msg)
                    ret.update({host_name: {"Error": msg}})
                    continue

                ret.update({host_name: True})

            # If we made it this far, something else has gone wrong.
            if ret.get(host_name) is None:
                msg = "Could not find service '{}' for host '{}'.".format(
                    service_name, host_name
                )
                log.debug(msg)
                ret.update({host_name: {"Error": msg}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def update_host_datetime(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Update the date/time on the given host or list of host_names. This function should be
    used with caution since network delays and execution delays can result in time skews.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts should update their date/time.

        If host_names is not provided, the date/time will be updated for the ``host``
        location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.update_date_time my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.update_date_time my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        date_time_manager = _get_date_time_mgr(host_ref)
        try:
            date_time_manager.UpdateDateTime(datetime.datetime.utcnow())
        except vim.fault.HostConfigFault as err:
            msg = "'vsphere.update_date_time' failed for host {}: {}".format(
                host_name, err
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
            continue

        ret.update({host_name: {"Datetime Updated": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def update_host_password(
    host, username, password, new_password, protocol=None, port=None, verify_ssl=True
):
    """
    Update the password for a given host.

    .. note:: Currently only works with connections to ESXi hosts. Does not work with vCenter servers.

    host
        The location of the ESXi host.

    username
        The username used to login to the ESXi host, such as ``root``.

    password
        The password used to login to the ESXi host.

    new_password
        The new password that will be updated for the provided username on the ESXi host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.update_host_password my.esxi.host root original-bad-password new-bad-password

    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    # Get LocalAccountManager object
    account_manager = salt.utils.vmware.get_inventory(service_instance).accountManager

    # Create user account specification object and assign id and password attributes
    user_account = vim.host.LocalAccountManager.AccountSpecification()
    user_account.id = username
    user_account.password = new_password

    # Update the password
    try:
        account_manager.UpdateUser(user_account)
    except vmodl.fault.SystemError as err:
        raise CommandExecutionError(err.msg)
    except vim.fault.UserNotFound:
        raise CommandExecutionError(
            "'vsphere.update_host_password' failed for host {}: "
            "User was not found.".format(host)
        )
    # If the username and password already exist, we don't need to do anything.
    except vim.fault.AlreadyExists:
        pass

    return True


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def vmotion_disable(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Disable vMotion for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts should disable VMotion.

        If host_names is not provided, VMotion will be disabled for the ``host``
        location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.vmotion_disable my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.vmotion_disable my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vmotion_system = host_ref.configManager.vmotionSystem

        # Disable VMotion for the host by removing the VNic selected to use for VMotion.
        try:
            vmotion_system.DeselectVnic()
        except vim.fault.HostConfigFault as err:
            msg = f"vsphere.vmotion_disable failed: {err}"
            log.debug(msg)
            ret.update({host_name: {"Error": msg, "VMotion Disabled": False}})
            continue

        ret.update({host_name: {"VMotion Disabled": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def vmotion_enable(
    host,
    username,
    password,
    protocol=None,
    port=None,
    host_names=None,
    device="vmk0",
    verify_ssl=True,
):
    """
    Enable vMotion for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts should enable VMotion.

        If host_names is not provided, VMotion will be enabled for the ``host``
        location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    device
        The device that uniquely identifies the VirtualNic that will be used for
        VMotion for each host. Defaults to ``vmk0``.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.vmotion_enable my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.vmotion_enable my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vmotion_system = host_ref.configManager.vmotionSystem

        # Enable VMotion for the host by setting the given device to provide the VNic to use for VMotion.
        try:
            vmotion_system.SelectVnic(device)
        except vim.fault.HostConfigFault as err:
            msg = f"vsphere.vmotion_disable failed: {err}"
            log.debug(msg)
            ret.update({host_name: {"Error": msg, "VMotion Enabled": False}})
            continue

        ret.update({host_name: {"VMotion Enabled": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def vsan_add_disks(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Add any VSAN-eligible disks to the VSAN System for the given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts need to add any VSAN-eligible disks to the host's
        VSAN system.

        If host_names is not provided, VSAN-eligible disks will be added to the hosts's
        VSAN system for the ``host`` location instead. This is useful for when service
        instance connection information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.vsan_add_disks my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.vsan_add_disks my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    host_names = _check_hosts(service_instance, host, host_names)
    response = _get_vsan_eligible_disks(service_instance, host, host_names)

    ret = {}
    for host_name, value in response.items():
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vsan_system = host_ref.configManager.vsanSystem

        # We must have a VSAN Config in place before we can manipulate it.
        if vsan_system is None:
            msg = (
                "VSAN System Config Manager is unset for host '{}'. "
                "VSAN configuration cannot be changed without a configured "
                "VSAN System.".format(host_name)
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
        else:
            eligible = value.get("Eligible")
            error = value.get("Error")

            if eligible and isinstance(eligible, list):
                # If we have eligible, matching disks, add them to VSAN.
                try:
                    task = vsan_system.AddDisks(eligible)
                    salt.utils.vmware.wait_for_task(
                        task, host_name, "Adding disks to VSAN", sleep_seconds=3
                    )
                except vim.fault.InsufficientDisks as err:
                    log.debug(err.msg)
                    ret.update({host_name: {"Error": err.msg}})
                    continue
                except Exception as err:  # pylint: disable=broad-except
                    msg = "'vsphere.vsan_add_disks' failed for host {}: {}".format(
                        host_name, err
                    )
                    log.debug(msg)
                    ret.update({host_name: {"Error": msg}})
                    continue

                log.debug(
                    "Successfully added disks to the VSAN system for host '%s'.",
                    host_name,
                )
                # We need to return ONLY the disk names, otherwise Message Pack can't deserialize the disk objects.
                disk_names = []
                for disk in eligible:
                    disk_names.append(disk.canonicalName)
                ret.update({host_name: {"Disks Added": disk_names}})
            elif eligible and isinstance(eligible, str):
                # If we have a string type in the eligible value, we don't
                # have any VSAN-eligible disks. Pull the message through.
                ret.update({host_name: {"Disks Added": eligible}})
            elif error:
                # If we hit an error, populate the Error return dict for state functions.
                ret.update({host_name: {"Error": error}})
            else:
                # If we made it this far, we somehow have eligible disks, but they didn't
                # match the disk list and just got an empty list of matching disks.
                ret.update(
                    {
                        host_name: {
                            "Disks Added": (
                                "No new VSAN-eligible disks were found to add."
                            )
                        }
                    }
                )

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def vsan_disable(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Disable VSAN for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts should disable VSAN.

        If host_names is not provided, VSAN will be disabled for the ``host``
        location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.vsan_disable my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.vsan_disable my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    # Create a VSAN Configuration Object and set the enabled attribute to True
    vsan_config = vim.vsan.host.ConfigInfo()
    vsan_config.enabled = False

    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vsan_system = host_ref.configManager.vsanSystem

        # We must have a VSAN Config in place before we can manipulate it.
        if vsan_system is None:
            msg = (
                "VSAN System Config Manager is unset for host '{}'. "
                "VSAN configuration cannot be changed without a configured "
                "VSAN System.".format(host_name)
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
        else:
            try:
                # Disable vsan on the host
                task = vsan_system.UpdateVsan_Task(vsan_config)
                salt.utils.vmware.wait_for_task(
                    task, host_name, "Disabling VSAN", sleep_seconds=3
                )
            except vmodl.fault.SystemError as err:
                log.debug(err.msg)
                ret.update({host_name: {"Error": err.msg}})
                continue
            except Exception as err:  # pylint: disable=broad-except
                msg = "'vsphere.vsan_disable' failed for host {}: {}".format(
                    host_name, err
                )
                log.debug(msg)
                ret.update({host_name: {"Error": msg}})
                continue

            ret.update({host_name: {"VSAN Disabled": True}})

    return ret


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def vsan_enable(
    host, username, password, protocol=None, port=None, host_names=None, verify_ssl=True
):
    """
    Enable VSAN for a given host or list of host_names.

    host
        The location of the host.

    username
        The username used to login to the host, such as ``root``.

    password
        The password used to login to the host.

    protocol
        Optionally set to alternate protocol if the host is not using the default
        protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the host is not using the default
        port. Default port is ``443``.

    host_names
        List of ESXi host names. When the host, username, and password credentials
        are provided for a vCenter Server, the host_names argument is required to
        tell vCenter which hosts should enable VSAN.

        If host_names is not provided, VSAN will be enabled for the ``host``
        location instead. This is useful for when service instance connection
        information is used for a single ESXi host.

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        # Used for single ESXi host connection information
        salt '*' vsphere.vsan_enable my.esxi.host root bad-password

        # Used for connecting to a vCenter Server
        salt '*' vsphere.vsan_enable my.vcenter.location root bad-password \
        host_names='[esxi-1.host.com, esxi-2.host.com]'
    """
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    # Create a VSAN Configuration Object and set the enabled attribute to True
    vsan_config = vim.vsan.host.ConfigInfo()
    vsan_config.enabled = True

    host_names = _check_hosts(service_instance, host, host_names)
    ret = {}
    for host_name in host_names:
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vsan_system = host_ref.configManager.vsanSystem

        # We must have a VSAN Config in place before we can manipulate it.
        if vsan_system is None:
            msg = (
                "VSAN System Config Manager is unset for host '{}'. "
                "VSAN configuration cannot be changed without a configured "
                "VSAN System.".format(host_name)
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
        else:
            try:
                # Enable vsan on the host
                task = vsan_system.UpdateVsan_Task(vsan_config)
                salt.utils.vmware.wait_for_task(
                    task, host_name, "Enabling VSAN", sleep_seconds=3
                )
            except vmodl.fault.SystemError as err:
                log.debug(err.msg)
                ret.update({host_name: {"Error": err.msg}})
                continue
            except vim.fault.VsanFault as err:
                msg = "'vsphere.vsan_enable' failed for host {}: {}".format(
                    host_name, err
                )
                log.debug(msg)
                ret.update({host_name: {"Error": msg}})
                continue

            ret.update({host_name: {"VSAN Enabled": True}})

    return ret


def _get_dvs_config_dict(dvs_name, dvs_config):
    """
    Returns the dict representation of the DVS config

    dvs_name
        The name of the DVS

    dvs_config
        The DVS config
    """
    log.trace("Building the dict of the DVS '%s' config", dvs_name)
    conf_dict = {
        "name": dvs_name,
        "contact_email": dvs_config.contact.contact,
        "contact_name": dvs_config.contact.name,
        "description": dvs_config.description,
        "lacp_api_version": dvs_config.lacpApiVersion,
        "network_resource_control_version": dvs_config.networkResourceControlVersion,
        "network_resource_management_enabled": dvs_config.networkResourceManagementEnabled,
        "max_mtu": dvs_config.maxMtu,
    }
    if isinstance(dvs_config.uplinkPortPolicy, vim.DVSNameArrayUplinkPortPolicy):
        conf_dict.update({"uplink_names": dvs_config.uplinkPortPolicy.uplinkPortName})
    return conf_dict


def _get_dvs_link_discovery_protocol(dvs_name, dvs_link_disc_protocol):
    """
    Returns the dict representation of the DVS link discovery protocol

    dvs_name
        The name of the DVS

    dvs_link_disc_protocl
        The DVS link discovery protocol
    """
    log.trace("Building the dict of the DVS '%s' link discovery protocol", dvs_name)
    return {
        "operation": dvs_link_disc_protocol.operation,
        "protocol": dvs_link_disc_protocol.protocol,
    }


def _get_dvs_product_info(dvs_name, dvs_product_info):
    """
    Returns the dict representation of the DVS product_info

    dvs_name
        The name of the DVS

    dvs_product_info
        The DVS product info
    """
    log.trace("Building the dict of the DVS '%s' product info", dvs_name)
    return {
        "name": dvs_product_info.name,
        "vendor": dvs_product_info.vendor,
        "version": dvs_product_info.version,
    }


def _get_dvs_capability(dvs_name, dvs_capability):
    """
    Returns the dict representation of the DVS product_info

    dvs_name
        The name of the DVS

    dvs_capability
        The DVS capability
    """
    log.trace("Building the dict of the DVS '%s' capability", dvs_name)
    return {
        "operation_supported": dvs_capability.dvsOperationSupported,
        "portgroup_operation_supported": dvs_capability.dvPortGroupOperationSupported,
        "port_operation_supported": dvs_capability.dvPortOperationSupported,
    }


def _get_dvs_infrastructure_traffic_resources(dvs_name, dvs_infra_traffic_ress):
    """
    Returns a list of dict representations of the DVS infrastructure traffic
    resource

    dvs_name
        The name of the DVS

    dvs_infra_traffic_ress
        The DVS infrastructure traffic resources
    """
    log.trace(
        "Building the dicts of the DVS '%s' infrastructure traffic resources", dvs_name
    )
    res_dicts = []
    for res in dvs_infra_traffic_ress:
        res_dict = {
            "key": res.key,
            "limit": res.allocationInfo.limit,
            "reservation": res.allocationInfo.reservation,
        }
        if res.allocationInfo.shares:
            res_dict.update(
                {
                    "num_shares": res.allocationInfo.shares.shares,
                    "share_level": res.allocationInfo.shares.level,
                }
            )
        res_dicts.append(res_dict)
    return res_dicts


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_dvss(datacenter=None, dvs_names=None, service_instance=None):
    """
    Returns a list of distributed virtual switches (DVSs).
    The list can be filtered by the datacenter or DVS names.

    datacenter
        The datacenter to look for DVSs in.
        Default value is None.

    dvs_names
        List of DVS names to look for. If None, all DVSs are returned.
        Default value is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_dvss

        salt '*' vsphere.list_dvss dvs_names=[dvs1,dvs2]
    """
    ret_list = []
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)

    for dvs in salt.utils.vmware.get_dvss(dc_ref, dvs_names, (not dvs_names)):
        dvs_dict = {}
        # XXX: Because of how VMware did DVS object inheritance we can\'t
        # be more restrictive when retrieving the dvs config, we have to
        # retrieve the entire object
        props = salt.utils.vmware.get_properties_of_managed_object(
            dvs, ["name", "config", "capability", "networkResourcePool"]
        )
        dvs_dict = _get_dvs_config_dict(props["name"], props["config"])
        # Product info
        dvs_dict.update(
            {
                "product_info": _get_dvs_product_info(
                    props["name"], props["config"].productInfo
                )
            }
        )
        # Link Discovery Protocol
        if props["config"].linkDiscoveryProtocolConfig:
            dvs_dict.update(
                {
                    "link_discovery_protocol": _get_dvs_link_discovery_protocol(
                        props["name"], props["config"].linkDiscoveryProtocolConfig
                    )
                }
            )
        # Capability
        dvs_dict.update(
            {"capability": _get_dvs_capability(props["name"], props["capability"])}
        )
        # InfrastructureTrafficResourceConfig - available with vSphere 6.0
        if hasattr(props["config"], "infrastructureTrafficResourceConfig"):
            dvs_dict.update(
                {
                    "infrastructure_traffic_resource_pools": _get_dvs_infrastructure_traffic_resources(
                        props["name"],
                        props["config"].infrastructureTrafficResourceConfig,
                    )
                }
            )
        ret_list.append(dvs_dict)
    return ret_list


def _apply_dvs_config(config_spec, config_dict):
    """
    Applies the values of the config dict dictionary to a config spec
    (vim.VMwareDVSConfigSpec)
    """
    if config_dict.get("name"):
        config_spec.name = config_dict["name"]
    if config_dict.get("contact_email") or config_dict.get("contact_name"):
        if not config_spec.contact:
            config_spec.contact = vim.DVSContactInfo()
        config_spec.contact.contact = config_dict.get("contact_email")
        config_spec.contact.name = config_dict.get("contact_name")
    if config_dict.get("description"):
        config_spec.description = config_dict.get("description")
    if config_dict.get("max_mtu"):
        config_spec.maxMtu = config_dict.get("max_mtu")
    if config_dict.get("lacp_api_version"):
        config_spec.lacpApiVersion = config_dict.get("lacp_api_version")
    if config_dict.get("network_resource_control_version"):
        config_spec.networkResourceControlVersion = config_dict.get(
            "network_resource_control_version"
        )
    if config_dict.get("uplink_names"):
        if not config_spec.uplinkPortPolicy or not isinstance(
            config_spec.uplinkPortPolicy, vim.DVSNameArrayUplinkPortPolicy
        ):

            config_spec.uplinkPortPolicy = vim.DVSNameArrayUplinkPortPolicy()
        config_spec.uplinkPortPolicy.uplinkPortName = config_dict["uplink_names"]


def _apply_dvs_link_discovery_protocol(disc_prot_config, disc_prot_dict):
    """
    Applies the values of the disc_prot_dict dictionary to a link discovery
    protocol config object (vim.LinkDiscoveryProtocolConfig)
    """
    disc_prot_config.operation = disc_prot_dict["operation"]
    disc_prot_config.protocol = disc_prot_dict["protocol"]


def _apply_dvs_product_info(product_info_spec, product_info_dict):
    """
    Applies the values of the product_info_dict dictionary to a product info
    spec (vim.DistributedVirtualSwitchProductSpec)
    """
    if product_info_dict.get("name"):
        product_info_spec.name = product_info_dict["name"]
    if product_info_dict.get("vendor"):
        product_info_spec.vendor = product_info_dict["vendor"]
    if product_info_dict.get("version"):
        product_info_spec.version = product_info_dict["version"]


def _apply_dvs_capability(capability_spec, capability_dict):
    """
    Applies the values of the capability_dict dictionary to a DVS capability
    object (vim.vim.DVSCapability)
    """
    if "operation_supported" in capability_dict:
        capability_spec.dvsOperationSupported = capability_dict["operation_supported"]
    if "port_operation_supported" in capability_dict:
        capability_spec.dvPortOperationSupported = capability_dict[
            "port_operation_supported"
        ]
    if "portgroup_operation_supported" in capability_dict:
        capability_spec.dvPortGroupOperationSupported = capability_dict[
            "portgroup_operation_supported"
        ]


def _apply_dvs_infrastructure_traffic_resources(
    infra_traffic_resources, resource_dicts
):
    """
    Applies the values of the resource dictionaries to infra traffic resources,
    creating the infra traffic resource if required
    (vim.DistributedVirtualSwitchProductSpec)
    """
    for res_dict in resource_dicts:
        filtered_traffic_resources = [
            r for r in infra_traffic_resources if r.key == res_dict["key"]
        ]
        if filtered_traffic_resources:
            traffic_res = filtered_traffic_resources[0]
        else:
            traffic_res = vim.DvsHostInfrastructureTrafficResource()
            traffic_res.key = res_dict["key"]
            traffic_res.allocationInfo = (
                vim.DvsHostInfrastructureTrafficResourceAllocation()
            )
            infra_traffic_resources.append(traffic_res)
        if res_dict.get("limit"):
            traffic_res.allocationInfo.limit = res_dict["limit"]
        if res_dict.get("reservation"):
            traffic_res.allocationInfo.reservation = res_dict["reservation"]
        if res_dict.get("num_shares") or res_dict.get("share_level"):
            if not traffic_res.allocationInfo.shares:
                traffic_res.allocationInfo.shares = vim.SharesInfo()
        if res_dict.get("share_level"):
            traffic_res.allocationInfo.shares.level = vim.SharesLevel(
                res_dict["share_level"]
            )
        if res_dict.get("num_shares"):
            # XXX Even though we always set the number of shares if provided,
            # the vCenter will ignore it unless the share level is 'custom'.
            traffic_res.allocationInfo.shares.shares = res_dict["num_shares"]


def _apply_dvs_network_resource_pools(network_resource_pools, resource_dicts):
    """
    Applies the values of the resource dictionaries to network resource pools,
    creating the resource pools if required
    (vim.DVSNetworkResourcePoolConfigSpec)
    """
    for res_dict in resource_dicts:
        ress = [r for r in network_resource_pools if r.key == res_dict["key"]]
        if ress:
            res = ress[0]
        else:
            res = vim.DVSNetworkResourcePoolConfigSpec()
            res.key = res_dict["key"]
            res.allocationInfo = vim.DVSNetworkResourcePoolAllocationInfo()
            network_resource_pools.append(res)
        if res_dict.get("limit"):
            res.allocationInfo.limit = res_dict["limit"]
        if res_dict.get("num_shares") and res_dict.get("share_level"):
            if not res.allocationInfo.shares:
                res.allocationInfo.shares = vim.SharesInfo()
            res.allocationInfo.shares.shares = res_dict["num_shares"]
            res.allocationInfo.shares.level = vim.SharesLevel(res_dict["share_level"])


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_dvs(dvs_dict, dvs_name, service_instance=None):
    """
    Creates a distributed virtual switch (DVS).

    Note: The ``dvs_name`` param will override any name set in ``dvs_dict``.

    dvs_dict
        Dict representation of the new DVS (example in salt.states.dvs)

    dvs_name
        Name of the DVS to be created.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.create_dvs dvs dict=$dvs_dict dvs_name=dvs_name
    """
    log.trace("Creating dvs '%s' with dict = %s", dvs_name, dvs_dict)
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    # Make the name of the DVS consistent with the call
    dvs_dict["name"] = dvs_name
    # Build the config spec from the input
    dvs_create_spec = vim.DVSCreateSpec()
    dvs_create_spec.configSpec = vim.VMwareDVSConfigSpec()
    _apply_dvs_config(dvs_create_spec.configSpec, dvs_dict)
    if dvs_dict.get("product_info"):
        dvs_create_spec.productInfo = vim.DistributedVirtualSwitchProductSpec()
        _apply_dvs_product_info(dvs_create_spec.productInfo, dvs_dict["product_info"])
    if dvs_dict.get("capability"):
        dvs_create_spec.capability = vim.DVSCapability()
        _apply_dvs_capability(dvs_create_spec.capability, dvs_dict["capability"])
    if dvs_dict.get("link_discovery_protocol"):
        dvs_create_spec.configSpec.linkDiscoveryProtocolConfig = (
            vim.LinkDiscoveryProtocolConfig()
        )
        _apply_dvs_link_discovery_protocol(
            dvs_create_spec.configSpec.linkDiscoveryProtocolConfig,
            dvs_dict["link_discovery_protocol"],
        )
    if dvs_dict.get("infrastructure_traffic_resource_pools"):
        dvs_create_spec.configSpec.infrastructureTrafficResourceConfig = []
        _apply_dvs_infrastructure_traffic_resources(
            dvs_create_spec.configSpec.infrastructureTrafficResourceConfig,
            dvs_dict["infrastructure_traffic_resource_pools"],
        )
    log.trace("dvs_create_spec = %s", dvs_create_spec)
    salt.utils.vmware.create_dvs(dc_ref, dvs_name, dvs_create_spec)
    if "network_resource_management_enabled" in dvs_dict:
        dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs_name])
        if not dvs_refs:
            raise VMwareObjectRetrievalError(
                f"DVS '{dvs_name}' wasn't found in datacenter '{datacenter}'"
            )
        dvs_ref = dvs_refs[0]
        salt.utils.vmware.set_dvs_network_resource_management_enabled(
            dvs_ref, dvs_dict["network_resource_management_enabled"]
        )
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def update_dvs(dvs_dict, dvs, service_instance=None):
    """
    Updates a distributed virtual switch (DVS).

    Note: Updating the product info, capability, uplinks of a DVS is not
          supported so the corresponding entries in ``dvs_dict`` will be
          ignored.

    dvs_dict
        Dictionary with the values the DVS should be update with
        (example in salt.states.dvs)

    dvs
        Name of the DVS to be updated.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.update_dvs dvs_dict=$dvs_dict dvs=dvs1
    """
    # Remove ignored properties
    log.trace("Updating dvs '%s' with dict = %s", dvs, dvs_dict)
    for prop in ["product_info", "capability", "uplink_names", "name"]:
        if prop in dvs_dict:
            del dvs_dict[prop]
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs])
    if not dvs_refs:
        raise VMwareObjectRetrievalError(
            f"DVS '{dvs}' wasn't found in datacenter '{datacenter}'"
        )
    dvs_ref = dvs_refs[0]
    # Build the config spec from the input
    dvs_props = salt.utils.vmware.get_properties_of_managed_object(
        dvs_ref, ["config", "capability"]
    )
    dvs_config = vim.VMwareDVSConfigSpec()
    # Copy all of the properties in the config of the of the DVS to a
    # DvsConfigSpec
    skipped_properties = ["host"]
    for prop in dvs_config.__dict__.keys():
        if prop in skipped_properties:
            continue
        if hasattr(dvs_props["config"], prop):
            setattr(dvs_config, prop, getattr(dvs_props["config"], prop))
    _apply_dvs_config(dvs_config, dvs_dict)
    if dvs_dict.get("link_discovery_protocol"):
        if not dvs_config.linkDiscoveryProtocolConfig:
            dvs_config.linkDiscoveryProtocolConfig = vim.LinkDiscoveryProtocolConfig()
        _apply_dvs_link_discovery_protocol(
            dvs_config.linkDiscoveryProtocolConfig, dvs_dict["link_discovery_protocol"]
        )
    if dvs_dict.get("infrastructure_traffic_resource_pools"):
        if not dvs_config.infrastructureTrafficResourceConfig:
            dvs_config.infrastructureTrafficResourceConfig = []
        _apply_dvs_infrastructure_traffic_resources(
            dvs_config.infrastructureTrafficResourceConfig,
            dvs_dict["infrastructure_traffic_resource_pools"],
        )
    log.trace("dvs_config = %s", dvs_config)

    salt.utils.vmware.update_dvs(dvs_ref, dvs_config_spec=dvs_config)
    if "network_resource_management_enabled" in dvs_dict:
        salt.utils.vmware.set_dvs_network_resource_management_enabled(
            dvs_ref, dvs_dict["network_resource_management_enabled"]
        )
    return True


def _get_dvportgroup_out_shaping(pg_name, pg_default_port_config):
    """
    Returns the out shaping policy of a distributed virtual portgroup

    pg_name
        The name of the portgroup

    pg_default_port_config
        The dafault port config of the portgroup
    """
    log.trace("Retrieving portgroup's '%s' out shaping config", pg_name)
    out_shaping_policy = pg_default_port_config.outShapingPolicy
    if not out_shaping_policy:
        return {}
    return {
        "average_bandwidth": out_shaping_policy.averageBandwidth.value,
        "burst_size": out_shaping_policy.burstSize.value,
        "enabled": out_shaping_policy.enabled.value,
        "peak_bandwidth": out_shaping_policy.peakBandwidth.value,
    }


def _get_dvportgroup_security_policy(pg_name, pg_default_port_config):
    """
    Returns the security policy of a distributed virtual portgroup

    pg_name
        The name of the portgroup

    pg_default_port_config
        The dafault port config of the portgroup
    """
    log.trace("Retrieving portgroup's '%s' security policy config", pg_name)
    sec_policy = pg_default_port_config.securityPolicy
    if not sec_policy:
        return {}
    return {
        "allow_promiscuous": sec_policy.allowPromiscuous.value,
        "forged_transmits": sec_policy.forgedTransmits.value,
        "mac_changes": sec_policy.macChanges.value,
    }


def _get_dvportgroup_teaming(pg_name, pg_default_port_config):
    """
    Returns the teaming of a distributed virtual portgroup

    pg_name
        The name of the portgroup

    pg_default_port_config
        The dafault port config of the portgroup
    """
    log.trace("Retrieving portgroup's '%s' teaming config", pg_name)
    teaming_policy = pg_default_port_config.uplinkTeamingPolicy
    if not teaming_policy:
        return {}
    ret_dict = {
        "notify_switches": teaming_policy.notifySwitches.value,
        "policy": teaming_policy.policy.value,
        "reverse_policy": teaming_policy.reversePolicy.value,
        "rolling_order": teaming_policy.rollingOrder.value,
    }
    if teaming_policy.failureCriteria:
        failure_criteria = teaming_policy.failureCriteria
        ret_dict.update(
            {
                "failure_criteria": {
                    "check_beacon": failure_criteria.checkBeacon.value,
                    "check_duplex": failure_criteria.checkDuplex.value,
                    "check_error_percent": failure_criteria.checkErrorPercent.value,
                    "check_speed": failure_criteria.checkSpeed.value,
                    "full_duplex": failure_criteria.fullDuplex.value,
                    "percentage": failure_criteria.percentage.value,
                    "speed": failure_criteria.speed.value,
                }
            }
        )
    if teaming_policy.uplinkPortOrder:
        uplink_order = teaming_policy.uplinkPortOrder
        ret_dict.update(
            {
                "port_order": {
                    "active": uplink_order.activeUplinkPort,
                    "standby": uplink_order.standbyUplinkPort,
                }
            }
        )
    return ret_dict


def _get_dvportgroup_dict(pg_ref):
    """
    Returns a dictionary with a distributed virtual portgroup data


    pg_ref
        Portgroup reference
    """
    props = salt.utils.vmware.get_properties_of_managed_object(
        pg_ref,
        [
            "name",
            "config.description",
            "config.numPorts",
            "config.type",
            "config.defaultPortConfig",
        ],
    )
    pg_dict = {
        "name": props["name"],
        "description": props.get("config.description"),
        "num_ports": props["config.numPorts"],
        "type": props["config.type"],
    }
    if props["config.defaultPortConfig"]:
        dpg = props["config.defaultPortConfig"]
        if dpg.vlan and isinstance(
            dpg.vlan, vim.VmwareDistributedVirtualSwitchVlanIdSpec
        ):

            pg_dict.update({"vlan_id": dpg.vlan.vlanId})
        pg_dict.update(
            {
                "out_shaping": _get_dvportgroup_out_shaping(
                    props["name"], props["config.defaultPortConfig"]
                )
            }
        )
        pg_dict.update(
            {
                "security_policy": _get_dvportgroup_security_policy(
                    props["name"], props["config.defaultPortConfig"]
                )
            }
        )
        pg_dict.update(
            {
                "teaming": _get_dvportgroup_teaming(
                    props["name"], props["config.defaultPortConfig"]
                )
            }
        )
    return pg_dict


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_dvportgroups(dvs=None, portgroup_names=None, service_instance=None):
    """
    Returns a list of distributed virtual switch portgroups.
    The list can be filtered by the portgroup names or by the DVS.

    dvs
        Name of the DVS containing the portgroups.
        Default value is None.

    portgroup_names
        List of portgroup names to look for. If None, all portgroups are
        returned.
        Default value is None

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_dvportgroups

        salt '*' vsphere.list_dvportgroups dvs=dvs1

        salt '*' vsphere.list_dvportgroups portgroup_names=[pg1]

        salt '*' vsphere.list_dvportgroups dvs=dvs1 portgroup_names=[pg1]
    """
    ret_dict = []
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    if dvs:
        dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs])
        if not dvs_refs:
            raise VMwareObjectRetrievalError(f"DVS '{dvs}' was not retrieved")
        dvs_ref = dvs_refs[0]
    get_all_portgroups = True if not portgroup_names else False
    for pg_ref in salt.utils.vmware.get_dvportgroups(
        parent_ref=dvs_ref if dvs else dc_ref,
        portgroup_names=portgroup_names,
        get_all_portgroups=get_all_portgroups,
    ):

        ret_dict.append(_get_dvportgroup_dict(pg_ref))
    return ret_dict


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_uplink_dvportgroup(dvs, service_instance=None):
    """
    Returns the uplink portgroup of a distributed virtual switch.

    dvs
        Name of the DVS containing the portgroup.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_uplink_dvportgroup dvs=dvs_name
    """
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs])
    if not dvs_refs:
        raise VMwareObjectRetrievalError(f"DVS '{dvs}' was not retrieved")
    uplink_pg_ref = salt.utils.vmware.get_uplink_dvportgroup(dvs_refs[0])
    return _get_dvportgroup_dict(uplink_pg_ref)


def _apply_dvportgroup_out_shaping(pg_name, out_shaping, out_shaping_conf):
    """
    Applies the values in out_shaping_conf to an out_shaping object

    pg_name
        The name of the portgroup

    out_shaping
        The vim.DVSTrafficShapingPolicy to apply the config to

    out_shaping_conf
        The out shaping config
    """
    log.trace("Building portgroup's '%s' out shaping policy", pg_name)
    if out_shaping_conf.get("average_bandwidth"):
        out_shaping.averageBandwidth = vim.LongPolicy()
        out_shaping.averageBandwidth.value = out_shaping_conf["average_bandwidth"]
    if out_shaping_conf.get("burst_size"):
        out_shaping.burstSize = vim.LongPolicy()
        out_shaping.burstSize.value = out_shaping_conf["burst_size"]
    if "enabled" in out_shaping_conf:
        out_shaping.enabled = vim.BoolPolicy()
        out_shaping.enabled.value = out_shaping_conf["enabled"]
    if out_shaping_conf.get("peak_bandwidth"):
        out_shaping.peakBandwidth = vim.LongPolicy()
        out_shaping.peakBandwidth.value = out_shaping_conf["peak_bandwidth"]


def _apply_dvportgroup_security_policy(pg_name, sec_policy, sec_policy_conf):
    """
    Applies the values in sec_policy_conf to a security policy object

    pg_name
        The name of the portgroup

    sec_policy
        The vim.DVSTrafficShapingPolicy to apply the config to

    sec_policy_conf
        The out shaping config
    """
    log.trace("Building portgroup's '%s' security policy", pg_name)
    if "allow_promiscuous" in sec_policy_conf:
        sec_policy.allowPromiscuous = vim.BoolPolicy()
        sec_policy.allowPromiscuous.value = sec_policy_conf["allow_promiscuous"]
    if "forged_transmits" in sec_policy_conf:
        sec_policy.forgedTransmits = vim.BoolPolicy()
        sec_policy.forgedTransmits.value = sec_policy_conf["forged_transmits"]
    if "mac_changes" in sec_policy_conf:
        sec_policy.macChanges = vim.BoolPolicy()
        sec_policy.macChanges.value = sec_policy_conf["mac_changes"]


def _apply_dvportgroup_teaming(pg_name, teaming, teaming_conf):
    """
    Applies the values in teaming_conf to a teaming policy object

    pg_name
        The name of the portgroup

    teaming
        The vim.VmwareUplinkPortTeamingPolicy to apply the config to

    teaming_conf
        The teaming config
    """
    log.trace("Building portgroup's '%s' teaming", pg_name)
    if "notify_switches" in teaming_conf:
        teaming.notifySwitches = vim.BoolPolicy()
        teaming.notifySwitches.value = teaming_conf["notify_switches"]
    if "policy" in teaming_conf:
        teaming.policy = vim.StringPolicy()
        teaming.policy.value = teaming_conf["policy"]
    if "reverse_policy" in teaming_conf:
        teaming.reversePolicy = vim.BoolPolicy()
        teaming.reversePolicy.value = teaming_conf["reverse_policy"]
    if "rolling_order" in teaming_conf:
        teaming.rollingOrder = vim.BoolPolicy()
        teaming.rollingOrder.value = teaming_conf["rolling_order"]
    if "failure_criteria" in teaming_conf:
        if not teaming.failureCriteria:
            teaming.failureCriteria = vim.DVSFailureCriteria()
        failure_criteria_conf = teaming_conf["failure_criteria"]
        if "check_beacon" in failure_criteria_conf:
            teaming.failureCriteria.checkBeacon = vim.BoolPolicy()
            teaming.failureCriteria.checkBeacon.value = failure_criteria_conf[
                "check_beacon"
            ]
        if "check_duplex" in failure_criteria_conf:
            teaming.failureCriteria.checkDuplex = vim.BoolPolicy()
            teaming.failureCriteria.checkDuplex.value = failure_criteria_conf[
                "check_duplex"
            ]
        if "check_error_percent" in failure_criteria_conf:
            teaming.failureCriteria.checkErrorPercent = vim.BoolPolicy()
            teaming.failureCriteria.checkErrorPercent.value = failure_criteria_conf[
                "check_error_percent"
            ]
        if "check_speed" in failure_criteria_conf:
            teaming.failureCriteria.checkSpeed = vim.StringPolicy()
            teaming.failureCriteria.checkSpeed.value = failure_criteria_conf[
                "check_speed"
            ]
        if "full_duplex" in failure_criteria_conf:
            teaming.failureCriteria.fullDuplex = vim.BoolPolicy()
            teaming.failureCriteria.fullDuplex.value = failure_criteria_conf[
                "full_duplex"
            ]
        if "percentage" in failure_criteria_conf:
            teaming.failureCriteria.percentage = vim.IntPolicy()
            teaming.failureCriteria.percentage.value = failure_criteria_conf[
                "percentage"
            ]
        if "speed" in failure_criteria_conf:
            teaming.failureCriteria.speed = vim.IntPolicy()
            teaming.failureCriteria.speed.value = failure_criteria_conf["speed"]
    if "port_order" in teaming_conf:
        if not teaming.uplinkPortOrder:
            teaming.uplinkPortOrder = vim.VMwareUplinkPortOrderPolicy()
        if "active" in teaming_conf["port_order"]:
            teaming.uplinkPortOrder.activeUplinkPort = teaming_conf["port_order"][
                "active"
            ]
        if "standby" in teaming_conf["port_order"]:
            teaming.uplinkPortOrder.standbyUplinkPort = teaming_conf["port_order"][
                "standby"
            ]


def _apply_dvportgroup_config(pg_name, pg_spec, pg_conf):
    """
    Applies the values in conf to a distributed portgroup spec

    pg_name
        The name of the portgroup

    pg_spec
        The vim.DVPortgroupConfigSpec to apply the config to

    pg_conf
        The portgroup config
    """
    log.trace("Building portgroup's '%s' spec", pg_name)
    if "name" in pg_conf:
        pg_spec.name = pg_conf["name"]
    if "description" in pg_conf:
        pg_spec.description = pg_conf["description"]
    if "num_ports" in pg_conf:
        pg_spec.numPorts = pg_conf["num_ports"]
    if "type" in pg_conf:
        pg_spec.type = pg_conf["type"]

    if not pg_spec.defaultPortConfig:
        for prop in ["vlan_id", "out_shaping", "security_policy", "teaming"]:
            if prop in pg_conf:
                pg_spec.defaultPortConfig = vim.VMwareDVSPortSetting()
    if "vlan_id" in pg_conf:
        pg_spec.defaultPortConfig.vlan = vim.VmwareDistributedVirtualSwitchVlanIdSpec()
        pg_spec.defaultPortConfig.vlan.vlanId = pg_conf["vlan_id"]
    if "out_shaping" in pg_conf:
        if not pg_spec.defaultPortConfig.outShapingPolicy:
            pg_spec.defaultPortConfig.outShapingPolicy = vim.DVSTrafficShapingPolicy()
        _apply_dvportgroup_out_shaping(
            pg_name, pg_spec.defaultPortConfig.outShapingPolicy, pg_conf["out_shaping"]
        )
    if "security_policy" in pg_conf:
        if not pg_spec.defaultPortConfig.securityPolicy:
            pg_spec.defaultPortConfig.securityPolicy = vim.DVSSecurityPolicy()
        _apply_dvportgroup_security_policy(
            pg_name,
            pg_spec.defaultPortConfig.securityPolicy,
            pg_conf["security_policy"],
        )
    if "teaming" in pg_conf:
        if not pg_spec.defaultPortConfig.uplinkTeamingPolicy:
            pg_spec.defaultPortConfig.uplinkTeamingPolicy = (
                vim.VmwareUplinkPortTeamingPolicy()
            )
        _apply_dvportgroup_teaming(
            pg_name, pg_spec.defaultPortConfig.uplinkTeamingPolicy, pg_conf["teaming"]
        )


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_dvportgroup(portgroup_dict, portgroup_name, dvs, service_instance=None):
    """
    Creates a distributed virtual portgroup.

    Note: The ``portgroup_name`` param will override any name already set
    in ``portgroup_dict``.

    portgroup_dict
        Dictionary with the config values the portgroup should be created with
        (example in salt.states.dvs).

    portgroup_name
        Name of the portgroup to be created.

    dvs
        Name of the DVS that will contain the portgroup.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.create_dvportgroup portgroup_dict=<dict>
            portgroup_name=pg1 dvs=dvs1
    """
    log.trace(
        "Creating portgroup '%s' in dvs '%s' with dict = %s",
        portgroup_name,
        dvs,
        portgroup_dict,
    )
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs])
    if not dvs_refs:
        raise VMwareObjectRetrievalError(f"DVS '{dvs}' was not retrieved")
    # Make the name of the dvportgroup consistent with the parameter
    portgroup_dict["name"] = portgroup_name
    spec = vim.DVPortgroupConfigSpec()
    _apply_dvportgroup_config(portgroup_name, spec, portgroup_dict)
    salt.utils.vmware.create_dvportgroup(dvs_refs[0], spec)
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def update_dvportgroup(portgroup_dict, portgroup, dvs, service_instance=True):
    """
    Updates a distributed virtual portgroup.

    portgroup_dict
        Dictionary with the values the portgroup should be update with
        (example in salt.states.dvs).

    portgroup
        Name of the portgroup to be updated.

    dvs
        Name of the DVS containing the portgroups.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.update_dvportgroup portgroup_dict=<dict>
            portgroup=pg1

        salt '*' vsphere.update_dvportgroup portgroup_dict=<dict>
            portgroup=pg1 dvs=dvs1
    """
    log.trace(
        "Updating portgroup '%s' in dvs '%s' with dict = %s",
        portgroup,
        dvs,
        portgroup_dict,
    )
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs])
    if not dvs_refs:
        raise VMwareObjectRetrievalError(f"DVS '{dvs}' was not retrieved")
    pg_refs = salt.utils.vmware.get_dvportgroups(
        dvs_refs[0], portgroup_names=[portgroup]
    )
    if not pg_refs:
        raise VMwareObjectRetrievalError(f"Portgroup '{portgroup}' was not retrieved")
    pg_props = salt.utils.vmware.get_properties_of_managed_object(
        pg_refs[0], ["config"]
    )
    spec = vim.DVPortgroupConfigSpec()
    # Copy existing properties in spec
    for prop in [
        "autoExpand",
        "configVersion",
        "defaultPortConfig",
        "description",
        "name",
        "numPorts",
        "policy",
        "portNameFormat",
        "scope",
        "type",
        "vendorSpecificConfig",
    ]:
        setattr(spec, prop, getattr(pg_props["config"], prop))
    _apply_dvportgroup_config(portgroup, spec, portgroup_dict)
    salt.utils.vmware.update_dvportgroup(pg_refs[0], spec)
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster")
@_gets_service_instance_via_proxy
@_deprecation_message
def remove_dvportgroup(portgroup, dvs, service_instance=None):
    """
    Removes a distributed virtual portgroup.

    portgroup
        Name of the portgroup to be removed.

    dvs
        Name of the DVS containing the portgroups.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.remove_dvportgroup portgroup=pg1 dvs=dvs1
    """
    log.trace("Removing portgroup '%s' in dvs '%s'", portgroup, dvs)
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    dvs_refs = salt.utils.vmware.get_dvss(dc_ref, dvs_names=[dvs])
    if not dvs_refs:
        raise VMwareObjectRetrievalError(f"DVS '{dvs}' was not retrieved")
    pg_refs = salt.utils.vmware.get_dvportgroups(
        dvs_refs[0], portgroup_names=[portgroup]
    )
    if not pg_refs:
        raise VMwareObjectRetrievalError(f"Portgroup '{portgroup}' was not retrieved")
    salt.utils.vmware.remove_dvportgroup(pg_refs[0])
    return True


def _get_policy_dict(policy):
    """Returns a dictionary representation of a policy"""
    profile_dict = {
        "name": policy.name,
        "description": policy.description,
        "resource_type": policy.resourceType.resourceType,
    }
    subprofile_dicts = []
    if isinstance(policy, pbm.profile.CapabilityBasedProfile) and isinstance(
        policy.constraints, pbm.profile.SubProfileCapabilityConstraints
    ):

        for subprofile in policy.constraints.subProfiles:
            subprofile_dict = {
                "name": subprofile.name,
                "force_provision": subprofile.forceProvision,
            }
            cap_dicts = []
            for cap in subprofile.capability:
                cap_dict = {"namespace": cap.id.namespace, "id": cap.id.id}
                # We assume there is one constraint with one value set
                val = cap.constraint[0].propertyInstance[0].value
                if isinstance(val, pbm.capability.types.Range):
                    val_dict = {"type": "range", "min": val.min, "max": val.max}
                elif isinstance(val, pbm.capability.types.DiscreteSet):
                    val_dict = {"type": "set", "values": val.values}
                else:
                    val_dict = {"type": "scalar", "value": val}
                cap_dict["setting"] = val_dict
                cap_dicts.append(cap_dict)
            subprofile_dict["capabilities"] = cap_dicts
            subprofile_dicts.append(subprofile_dict)
    profile_dict["subprofiles"] = subprofile_dicts
    return profile_dict


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_storage_policies(policy_names=None, service_instance=None):
    """
    Returns a list of storage policies.

    policy_names
        Names of policies to list. If None, all policies are listed.
        Default is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_storage_policies

        salt '*' vsphere.list_storage_policies policy_names=[policy_name]
    """
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    if not policy_names:
        policies = salt.utils.pbm.get_storage_policies(
            profile_manager, get_all_policies=True
        )
    else:
        policies = salt.utils.pbm.get_storage_policies(profile_manager, policy_names)
    return [_get_policy_dict(p) for p in policies]


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_default_vsan_policy(service_instance=None):
    """
    Returns the default vsan storage policy.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_default_vsan_policy
    """
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    policies = salt.utils.pbm.get_storage_policies(
        profile_manager, get_all_policies=True
    )
    def_policies = [
        p for p in policies if p.systemCreatedProfileType == "VsanDefaultProfile"
    ]
    if not def_policies:
        raise VMwareObjectRetrievalError("Default VSAN policy was not retrieved")
    return _get_policy_dict(def_policies[0])


def _get_capability_definition_dict(cap_metadata):
    # We assume each capability definition has one property with the same id
    # as the capability so we display its type as belonging to the capability
    # The object model permits multiple properties
    return {
        "namespace": cap_metadata.id.namespace,
        "id": cap_metadata.id.id,
        "mandatory": cap_metadata.mandatory,
        "description": cap_metadata.summary.summary,
        "type": cap_metadata.propertyMetadata[0].type.typeName,
    }


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_capability_definitions(service_instance=None):
    """
    Returns a list of the metadata of all capabilities in the vCenter.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_capabilities
    """
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    ret_list = [
        _get_capability_definition_dict(c)
        for c in salt.utils.pbm.get_capability_definitions(profile_manager)
    ]
    return ret_list


def _apply_policy_config(policy_spec, policy_dict):
    """Applies a policy dictionary to a policy spec"""
    log.trace("policy_dict = %s", policy_dict)
    if policy_dict.get("name"):
        policy_spec.name = policy_dict["name"]
    if policy_dict.get("description"):
        policy_spec.description = policy_dict["description"]
    if policy_dict.get("subprofiles"):
        # Incremental changes to subprofiles and capabilities are not
        # supported because they would complicate updates too much
        # The whole configuration of all sub-profiles is expected and applied
        policy_spec.constraints = pbm.profile.SubProfileCapabilityConstraints()
        subprofiles = []
        for subprofile_dict in policy_dict["subprofiles"]:
            subprofile_spec = pbm.profile.SubProfileCapabilityConstraints.SubProfile(
                name=subprofile_dict["name"]
            )
            cap_specs = []
            if subprofile_dict.get("force_provision"):
                subprofile_spec.forceProvision = subprofile_dict["force_provision"]
            for cap_dict in subprofile_dict["capabilities"]:
                prop_inst_spec = pbm.capability.PropertyInstance(id=cap_dict["id"])
                setting_type = cap_dict["setting"]["type"]
                if setting_type == "set":
                    prop_inst_spec.value = pbm.capability.types.DiscreteSet()
                    prop_inst_spec.value.values = cap_dict["setting"]["values"]
                elif setting_type == "range":
                    prop_inst_spec.value = pbm.capability.types.Range()
                    prop_inst_spec.value.max = cap_dict["setting"]["max"]
                    prop_inst_spec.value.min = cap_dict["setting"]["min"]
                elif setting_type == "scalar":
                    prop_inst_spec.value = cap_dict["setting"]["value"]
                cap_spec = pbm.capability.CapabilityInstance(
                    id=pbm.capability.CapabilityMetadata.UniqueId(
                        id=cap_dict["id"], namespace=cap_dict["namespace"]
                    ),
                    constraint=[
                        pbm.capability.ConstraintInstance(
                            propertyInstance=[prop_inst_spec]
                        )
                    ],
                )
                cap_specs.append(cap_spec)
            subprofile_spec.capability = cap_specs
            subprofiles.append(subprofile_spec)
        policy_spec.constraints.subProfiles = subprofiles
    log.trace("updated policy_spec = %s", policy_spec)
    return policy_spec


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_storage_policy(policy_name, policy_dict, service_instance=None):
    """
    Creates a storage policy.

    Supported capability types: scalar, set, range.

    policy_name
        Name of the policy to create.
        The value of the argument will override any existing name in
        ``policy_dict``.

    policy_dict
        Dictionary containing the changes to apply to the policy.
        (example in salt.states.pbm)

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.create_storage_policy policy_name='policy name'
            policy_dict="$policy_dict"
    """
    log.trace("create storage policy '%s', dict = %s", policy_name, policy_dict)
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    policy_create_spec = pbm.profile.CapabilityBasedProfileCreateSpec()
    # Hardcode the storage profile resource type
    policy_create_spec.resourceType = pbm.profile.ResourceType(
        resourceType=pbm.profile.ResourceTypeEnum.STORAGE
    )
    # Set name argument
    policy_dict["name"] = policy_name
    log.trace("Setting policy values in policy_update_spec")
    _apply_policy_config(policy_create_spec, policy_dict)
    salt.utils.pbm.create_storage_policy(profile_manager, policy_create_spec)
    return {"create_storage_policy": True}


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def update_storage_policy(policy, policy_dict, service_instance=None):
    """
    Updates a storage policy.

    Supported capability types: scalar, set, range.

    policy
        Name of the policy to update.

    policy_dict
        Dictionary containing the changes to apply to the policy.
        (example in salt.states.pbm)

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.update_storage_policy policy='policy name'
            policy_dict="$policy_dict"
    """
    log.trace("updating storage policy, dict = %s", policy_dict)
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    policies = salt.utils.pbm.get_storage_policies(profile_manager, [policy])
    if not policies:
        raise VMwareObjectRetrievalError(f"Policy '{policy}' was not found")
    policy_ref = policies[0]
    policy_update_spec = pbm.profile.CapabilityBasedProfileUpdateSpec()
    log.trace("Setting policy values in policy_update_spec")
    for prop in ["description", "constraints"]:
        setattr(policy_update_spec, prop, getattr(policy_ref, prop))
    _apply_policy_config(policy_update_spec, policy_dict)
    salt.utils.pbm.update_storage_policy(
        profile_manager, policy_ref, policy_update_spec
    )
    return {"update_storage_policy": True}


@depends(HAS_PYVMOMI)
@_supports_proxies("esxcluster", "esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_default_storage_policy_of_datastore(datastore, service_instance=None):
    """
    Returns a list of datastores assign the storage policies.

    datastore
        Name of the datastore to assign.
        The datastore needs to be visible to the VMware entity the proxy
        points to.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_default_storage_policy_of_datastore datastore=ds1
    """
    log.trace("Listing the default storage policy of datastore '%s'", datastore)
    # Find datastore
    target_ref = _get_proxy_target(service_instance)
    ds_refs = salt.utils.vmware.get_datastores(
        service_instance, target_ref, datastore_names=[datastore]
    )
    if not ds_refs:
        raise VMwareObjectRetrievalError(f"Datastore '{datastore}' was not found")
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    policy = salt.utils.pbm.get_default_storage_policy_of_datastore(
        profile_manager, ds_refs[0]
    )
    return _get_policy_dict(policy)


@depends(HAS_PYVMOMI)
@_supports_proxies("esxcluster", "esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def assign_default_storage_policy_to_datastore(
    policy, datastore, service_instance=None
):
    """
    Assigns a storage policy as the default policy to a datastore.

    policy
        Name of the policy to assign.

    datastore
        Name of the datastore to assign.
        The datastore needs to be visible to the VMware entity the proxy
        points to.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.assign_storage_policy_to_datastore
            policy='policy name' datastore=ds1
    """
    log.trace("Assigning policy %s to datastore %s", policy, datastore)
    profile_manager = salt.utils.pbm.get_profile_manager(service_instance)
    # Find policy
    policies = salt.utils.pbm.get_storage_policies(profile_manager, [policy])
    if not policies:
        raise VMwareObjectRetrievalError(f"Policy '{policy}' was not found")
    policy_ref = policies[0]
    # Find datastore
    target_ref = _get_proxy_target(service_instance)
    ds_refs = salt.utils.vmware.get_datastores(
        service_instance, target_ref, datastore_names=[datastore]
    )
    if not ds_refs:
        raise VMwareObjectRetrievalError(f"Datastore '{datastore}' was not found")
    ds_ref = ds_refs[0]
    salt.utils.pbm.assign_default_storage_policy_to_datastore(
        profile_manager, policy_ref, ds_ref
    )
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "esxcluster", "vcenter", "esxvm")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_datacenters_via_proxy(datacenter_names=None, service_instance=None):
    """
    Returns a list of dict representations of VMware datacenters.
    Connection is done via the proxy details.

    Supported proxies: esxdatacenter

    datacenter_names
        List of datacenter names.
        Default is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_datacenters_via_proxy

        salt '*' vsphere.list_datacenters_via_proxy dc1

        salt '*' vsphere.list_datacenters_via_proxy dc1,dc2

        salt '*' vsphere.list_datacenters_via_proxy datacenter_names=[dc1, dc2]
    """
    if not datacenter_names:
        dc_refs = salt.utils.vmware.get_datacenters(
            service_instance, get_all_datacenters=True
        )
    else:
        dc_refs = salt.utils.vmware.get_datacenters(service_instance, datacenter_names)

    return [
        {"name": salt.utils.vmware.get_managed_object_name(dc_ref)}
        for dc_ref in dc_refs
    ]


@depends(HAS_PYVMOMI)
@_supports_proxies("esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_datacenter(datacenter_name, service_instance=None):
    """
    Creates a datacenter.

    Supported proxies: esxdatacenter

    datacenter_name
        The datacenter name

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.create_datacenter dc1
    """
    salt.utils.vmware.create_datacenter(service_instance, datacenter_name)
    return {"create_datacenter": True}


def _get_cluster_dict(cluster_name, cluster_ref):
    """
    Returns a cluster dict representation from
    a vim.ClusterComputeResource object.

    cluster_name
        Name of the cluster

    cluster_ref
        Reference to the cluster
    """

    log.trace("Building a dictionary representation of cluster '%s'", cluster_name)
    props = salt.utils.vmware.get_properties_of_managed_object(
        cluster_ref, properties=["configurationEx"]
    )
    res = {
        "ha": {"enabled": props["configurationEx"].dasConfig.enabled},
        "drs": {"enabled": props["configurationEx"].drsConfig.enabled},
    }
    # Convert HA properties of interest
    ha_conf = props["configurationEx"].dasConfig
    log.trace("ha_conf = %s", ha_conf)
    res["ha"]["admission_control_enabled"] = ha_conf.admissionControlEnabled
    if ha_conf.admissionControlPolicy and isinstance(
        ha_conf.admissionControlPolicy,
        vim.ClusterFailoverResourcesAdmissionControlPolicy,
    ):
        pol = ha_conf.admissionControlPolicy
        res["ha"]["admission_control_policy"] = {
            "cpu_failover_percent": pol.cpuFailoverResourcesPercent,
            "memory_failover_percent": pol.memoryFailoverResourcesPercent,
        }
    if ha_conf.defaultVmSettings:
        def_vm_set = ha_conf.defaultVmSettings
        res["ha"]["default_vm_settings"] = {
            "isolation_response": def_vm_set.isolationResponse,
            "restart_priority": def_vm_set.restartPriority,
        }
    res["ha"]["hb_ds_candidate_policy"] = ha_conf.hBDatastoreCandidatePolicy
    if ha_conf.hostMonitoring:
        res["ha"]["host_monitoring"] = ha_conf.hostMonitoring
    if ha_conf.option:
        res["ha"]["options"] = [
            {"key": o.key, "value": o.value} for o in ha_conf.option
        ]
    res["ha"]["vm_monitoring"] = ha_conf.vmMonitoring
    # Convert DRS properties
    drs_conf = props["configurationEx"].drsConfig
    log.trace("drs_conf = %s", drs_conf)
    res["drs"]["vmotion_rate"] = 6 - drs_conf.vmotionRate
    res["drs"]["default_vm_behavior"] = drs_conf.defaultVmBehavior
    # vm_swap_placement
    res["vm_swap_placement"] = props["configurationEx"].vmSwapPlacement
    # Convert VSAN properties
    si = salt.utils.vmware.get_service_instance_from_managed_object(cluster_ref)

    if salt.utils.vsan.vsan_supported(si):
        # XXX The correct way of retrieving the VSAN data (on the if branch)
        #  is not supported before 60u2 vcenter
        vcenter_info = salt.utils.vmware.get_service_info(si)
        if int(vcenter_info.build) >= 3634794:  # 60u2
            # VSAN API is fully supported by the VC starting with 60u2
            vsan_conf = salt.utils.vsan.get_cluster_vsan_info(cluster_ref)
            log.trace("vsan_conf = %s", vsan_conf)
            res["vsan"] = {
                "enabled": vsan_conf.enabled,
                "auto_claim_storage": vsan_conf.defaultConfig.autoClaimStorage,
            }
            if vsan_conf.dataEfficiencyConfig:
                data_eff = vsan_conf.dataEfficiencyConfig
                res["vsan"].update(
                    {
                        # We force compression_enabled to be True/False
                        "compression_enabled": data_eff.compressionEnabled or False,
                        "dedup_enabled": data_eff.dedupEnabled,
                    }
                )
        else:  # before 60u2 (no advanced vsan info)
            if props["configurationEx"].vsanConfigInfo:
                default_config = props["configurationEx"].vsanConfigInfo.defaultConfig
                res["vsan"] = {
                    "enabled": props["configurationEx"].vsanConfigInfo.enabled,
                    "auto_claim_storage": default_config.autoClaimStorage,
                }
    return res


@depends(HAS_PYVMOMI)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_cluster(datacenter=None, cluster=None, service_instance=None):
    """
    Returns a dict representation of an ESX cluster.

    datacenter
        Name of datacenter containing the cluster.
        Ignored if already contained by proxy details.
        Default value is None.

    cluster
        Name of cluster.
        Ignored if already contained by proxy details.
        Default value is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        # vcenter proxy
        salt '*' vsphere.list_cluster datacenter=dc1 cluster=cl1

        # esxdatacenter proxy
        salt '*' vsphere.list_cluster cluster=cl1

        # esxcluster proxy
        salt '*' vsphere.list_cluster
    """
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        dc_ref = _get_proxy_target(service_instance)
        if not cluster:
            raise ArgumentValueError("'cluster' needs to be specified")
        cluster_ref = salt.utils.vmware.get_cluster(dc_ref, cluster)
    elif proxy_type == "esxcluster":
        cluster_ref = _get_proxy_target(service_instance)
        cluster = __salt__["esxcluster.get_details"]()["cluster"]
    log.trace(
        "Retrieving representation of cluster '%s' in a %s proxy", cluster, proxy_type
    )
    return _get_cluster_dict(cluster, cluster_ref)


def _apply_cluster_dict(cluster_spec, cluster_dict, vsan_spec=None, vsan_61=True):
    """
    Applies the values of cluster_dict dictionary to a cluster spec
    (vim.ClusterConfigSpecEx).

    All vsan values (cluster_dict['vsan']) will be applied to
    vsan_spec (vim.vsan.cluster.ConfigInfoEx). Can be not omitted
    if not required.

    VSAN 6.1 config needs to be applied differently than the post VSAN 6.1 way.
    The type of configuration desired is dictated by the flag vsan_61.
    """
    log.trace("Applying cluster dict %s", cluster_dict)
    if cluster_dict.get("ha"):
        ha_dict = cluster_dict["ha"]
        if not cluster_spec.dasConfig:
            cluster_spec.dasConfig = vim.ClusterDasConfigInfo()
        das_config = cluster_spec.dasConfig
        if "enabled" in ha_dict:
            das_config.enabled = ha_dict["enabled"]
            if ha_dict["enabled"]:
                # Default values when ha is enabled
                das_config.failoverLevel = 1
        if "admission_control_enabled" in ha_dict:
            das_config.admissionControlEnabled = ha_dict["admission_control_enabled"]
        if "admission_control_policy" in ha_dict:
            adm_pol_dict = ha_dict["admission_control_policy"]
            if not das_config.admissionControlPolicy or not isinstance(
                das_config.admissionControlPolicy,
                vim.ClusterFailoverResourcesAdmissionControlPolicy,
            ):

                das_config.admissionControlPolicy = (
                    vim.ClusterFailoverResourcesAdmissionControlPolicy(
                        cpuFailoverResourcesPercent=adm_pol_dict[
                            "cpu_failover_percent"
                        ],
                        memoryFailoverResourcesPercent=adm_pol_dict[
                            "memory_failover_percent"
                        ],
                    )
                )
        if "default_vm_settings" in ha_dict:
            vm_set_dict = ha_dict["default_vm_settings"]
            if not das_config.defaultVmSettings:
                das_config.defaultVmSettings = vim.ClusterDasVmSettings()
            if "isolation_response" in vm_set_dict:
                das_config.defaultVmSettings.isolationResponse = vm_set_dict[
                    "isolation_response"
                ]
            if "restart_priority" in vm_set_dict:
                das_config.defaultVmSettings.restartPriority = vm_set_dict[
                    "restart_priority"
                ]
        if "hb_ds_candidate_policy" in ha_dict:
            das_config.hBDatastoreCandidatePolicy = ha_dict["hb_ds_candidate_policy"]
        if "host_monitoring" in ha_dict:
            das_config.hostMonitoring = ha_dict["host_monitoring"]
        if "options" in ha_dict:
            das_config.option = []
            for opt_dict in ha_dict["options"]:
                das_config.option.append(vim.OptionValue(key=opt_dict["key"]))
                if "value" in opt_dict:
                    das_config.option[-1].value = opt_dict["value"]
        if "vm_monitoring" in ha_dict:
            das_config.vmMonitoring = ha_dict["vm_monitoring"]
        cluster_spec.dasConfig = das_config
    if cluster_dict.get("drs"):
        drs_dict = cluster_dict["drs"]
        drs_config = vim.ClusterDrsConfigInfo()
        if "enabled" in drs_dict:
            drs_config.enabled = drs_dict["enabled"]
        if "vmotion_rate" in drs_dict:
            drs_config.vmotionRate = 6 - drs_dict["vmotion_rate"]
        if "default_vm_behavior" in drs_dict:
            drs_config.defaultVmBehavior = vim.DrsBehavior(
                drs_dict["default_vm_behavior"]
            )
        cluster_spec.drsConfig = drs_config
    if cluster_dict.get("vm_swap_placement"):
        cluster_spec.vmSwapPlacement = cluster_dict["vm_swap_placement"]
    if cluster_dict.get("vsan"):
        vsan_dict = cluster_dict["vsan"]
        if not vsan_61:  # VSAN is 6.2 and above
            if "enabled" in vsan_dict:
                if not vsan_spec.vsanClusterConfig:
                    vsan_spec.vsanClusterConfig = vim.vsan.cluster.ConfigInfo()
                vsan_spec.vsanClusterConfig.enabled = vsan_dict["enabled"]
            if "auto_claim_storage" in vsan_dict:
                if not vsan_spec.vsanClusterConfig:
                    vsan_spec.vsanClusterConfig = vim.vsan.cluster.ConfigInfo()
                if not vsan_spec.vsanClusterConfig.defaultConfig:
                    vsan_spec.vsanClusterConfig.defaultConfig = (
                        vim.VsanClusterConfigInfoHostDefaultInfo()
                    )
                elif vsan_spec.vsanClusterConfig.defaultConfig.uuid:
                    # If this remains set it caused an error
                    vsan_spec.vsanClusterConfig.defaultConfig.uuid = None
                vsan_spec.vsanClusterConfig.defaultConfig.autoClaimStorage = vsan_dict[
                    "auto_claim_storage"
                ]
            if "compression_enabled" in vsan_dict:
                if not vsan_spec.dataEfficiencyConfig:
                    vsan_spec.dataEfficiencyConfig = vim.vsan.DataEfficiencyConfig()
                vsan_spec.dataEfficiencyConfig.compressionEnabled = vsan_dict[
                    "compression_enabled"
                ]
            if "dedup_enabled" in vsan_dict:
                if not vsan_spec.dataEfficiencyConfig:
                    vsan_spec.dataEfficiencyConfig = vim.vsan.DataEfficiencyConfig()
                vsan_spec.dataEfficiencyConfig.dedupEnabled = vsan_dict["dedup_enabled"]
        # In all cases we need to configure the vsan on the cluster
        # directly so not to have a mismatch between vsan_spec and
        # cluster_spec
        if not cluster_spec.vsanConfig:
            cluster_spec.vsanConfig = vim.VsanClusterConfigInfo()
        vsan_config = cluster_spec.vsanConfig
        if "enabled" in vsan_dict:
            vsan_config.enabled = vsan_dict["enabled"]
        if "auto_claim_storage" in vsan_dict:
            if not vsan_config.defaultConfig:
                vsan_config.defaultConfig = vim.VsanClusterConfigInfoHostDefaultInfo()
            elif vsan_config.defaultConfig.uuid:
                # If this remains set it caused an error
                vsan_config.defaultConfig.uuid = None
            vsan_config.defaultConfig.autoClaimStorage = vsan_dict["auto_claim_storage"]
    log.trace("cluster_spec = %s", cluster_spec)


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_cluster(cluster_dict, datacenter=None, cluster=None, service_instance=None):
    """
    Creates a cluster.

    Note: cluster_dict['name'] will be overridden by the cluster param value

    config_dict
        Dictionary with the config values of the new cluster.

    datacenter
        Name of datacenter containing the cluster.
        Ignored if already contained by proxy details.
        Default value is None.

    cluster
        Name of cluster.
        Ignored if already contained by proxy details.
        Default value is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        # esxdatacenter proxy
        salt '*' vsphere.create_cluster cluster_dict=$cluster_dict cluster=cl1

        # esxcluster proxy
        salt '*' vsphere.create_cluster cluster_dict=$cluster_dict
    """
    # Validate cluster dictionary
    schema = ESXClusterConfigSchema.serialize()
    try:
        jsonschema.validate(cluster_dict, schema)
    except jsonschema.exceptions.ValidationError as exc:
        raise InvalidConfigError(exc)
    # Get required details from the proxy
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
        if not cluster:
            raise ArgumentValueError("'cluster' needs to be specified")
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
        cluster = __salt__["esxcluster.get_details"]()["cluster"]

    if cluster_dict.get("vsan") and not salt.utils.vsan.vsan_supported(
        service_instance
    ):

        raise VMwareApiError("VSAN operations are not supported")
    si = service_instance
    cluster_spec = vim.ClusterConfigSpecEx()
    vsan_spec = None
    ha_config = None
    vsan_61 = None
    if cluster_dict.get("vsan"):
        # XXX The correct way of retrieving the VSAN data (on the if branch)
        #  is not supported before 60u2 vcenter
        vcenter_info = salt.utils.vmware.get_service_info(si)
        if (
            float(vcenter_info.apiVersion) >= 6.0 and int(vcenter_info.build) >= 3634794
        ):  # 60u2
            vsan_spec = vim.vsan.ReconfigSpec(modify=True)
            vsan_61 = False
            # We need to keep HA disabled and enable it afterwards
            if cluster_dict.get("ha", {}).get("enabled"):
                enable_ha = True
                ha_config = cluster_dict["ha"]
                del cluster_dict["ha"]
        else:
            vsan_61 = True
    # If VSAN is 6.1 the configuration of VSAN happens when configuring the
    # cluster via the regular endpoint
    _apply_cluster_dict(cluster_spec, cluster_dict, vsan_spec, vsan_61)
    salt.utils.vmware.create_cluster(dc_ref, cluster, cluster_spec)
    if not vsan_61:
        # Only available after VSAN 61
        if vsan_spec:
            cluster_ref = salt.utils.vmware.get_cluster(dc_ref, cluster)
            salt.utils.vsan.reconfigure_cluster_vsan(cluster_ref, vsan_spec)
        if enable_ha:
            # Set HA after VSAN has been configured
            _apply_cluster_dict(cluster_spec, {"ha": ha_config})
            salt.utils.vmware.update_cluster(cluster_ref, cluster_spec)
            # Set HA back on the object
            cluster_dict["ha"] = ha_config
    return {"create_cluster": True}


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def update_cluster(cluster_dict, datacenter=None, cluster=None, service_instance=None):
    """
    Updates a cluster.

    config_dict
        Dictionary with the config values of the new cluster.

    datacenter
        Name of datacenter containing the cluster.
        Ignored if already contained by proxy details.
        Default value is None.

    cluster
        Name of cluster.
        Ignored if already contained by proxy details.
        Default value is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        # esxdatacenter proxy
        salt '*' vsphere.update_cluster cluster_dict=$cluster_dict cluster=cl1

        # esxcluster proxy
        salt '*' vsphere.update_cluster cluster_dict=$cluster_dict

    """
    # Validate cluster dictionary
    schema = ESXClusterConfigSchema.serialize()
    try:
        jsonschema.validate(cluster_dict, schema)
    except jsonschema.exceptions.ValidationError as exc:
        raise InvalidConfigError(exc)
    # Get required details from the proxy
    proxy_type = get_proxy_type()
    if proxy_type == "esxdatacenter":
        datacenter = __salt__["esxdatacenter.get_details"]()["datacenter"]
        dc_ref = _get_proxy_target(service_instance)
        if not cluster:
            raise ArgumentValueError("'cluster' needs to be specified")
    elif proxy_type == "esxcluster":
        datacenter = __salt__["esxcluster.get_details"]()["datacenter"]
        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
        cluster = __salt__["esxcluster.get_details"]()["cluster"]

    if cluster_dict.get("vsan") and not salt.utils.vsan.vsan_supported(
        service_instance
    ):

        raise VMwareApiError("VSAN operations are not supported")

    cluster_ref = salt.utils.vmware.get_cluster(dc_ref, cluster)
    cluster_spec = vim.ClusterConfigSpecEx()
    props = salt.utils.vmware.get_properties_of_managed_object(
        cluster_ref, properties=["configurationEx"]
    )
    # Copy elements we want to update to spec
    for p in ["dasConfig", "drsConfig"]:
        setattr(cluster_spec, p, getattr(props["configurationEx"], p))
    if props["configurationEx"].vsanConfigInfo:
        cluster_spec.vsanConfig = props["configurationEx"].vsanConfigInfo
    vsan_spec = None
    vsan_61 = None
    if cluster_dict.get("vsan"):
        # XXX The correct way of retrieving the VSAN data (on the if branch)
        #  is not supported before 60u2 vcenter
        vcenter_info = salt.utils.vmware.get_service_info(service_instance)
        if (
            float(vcenter_info.apiVersion) >= 6.0 and int(vcenter_info.build) >= 3634794
        ):  # 60u2
            vsan_61 = False
            vsan_info = salt.utils.vsan.get_cluster_vsan_info(cluster_ref)
            vsan_spec = vim.vsan.ReconfigSpec(modify=True)
            # Only interested in the vsanClusterConfig and the
            # dataEfficiencyConfig
            # vsan_spec.vsanClusterConfig = vsan_info
            vsan_spec.dataEfficiencyConfig = vsan_info.dataEfficiencyConfig
            vsan_info.dataEfficiencyConfig = None
        else:
            vsan_61 = True

    _apply_cluster_dict(cluster_spec, cluster_dict, vsan_spec, vsan_61)
    # We try to reconfigure vsan first as it fails if HA is enabled so the
    # command will abort not having any side-effects
    # also if HA was previously disabled it can be enabled automatically if
    # desired
    if vsan_spec:
        log.trace("vsan_spec = %s", vsan_spec)
        salt.utils.vsan.reconfigure_cluster_vsan(cluster_ref, vsan_spec)

        # We need to retrieve again the properties and reapply them
        # As the VSAN configuration has changed
        cluster_spec = vim.ClusterConfigSpecEx()
        props = salt.utils.vmware.get_properties_of_managed_object(
            cluster_ref, properties=["configurationEx"]
        )
        # Copy elements we want to update to spec
        for p in ["dasConfig", "drsConfig"]:
            setattr(cluster_spec, p, getattr(props["configurationEx"], p))
        if props["configurationEx"].vsanConfigInfo:
            cluster_spec.vsanConfig = props["configurationEx"].vsanConfigInfo
        # We only need to configure the cluster_spec, as if it were a vsan_61
        # cluster
        _apply_cluster_dict(cluster_spec, cluster_dict)
    salt.utils.vmware.update_cluster(cluster_ref, cluster_spec)
    return {"update_cluster": True}


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_datastores_via_proxy(
    datastore_names=None,
    backing_disk_ids=None,
    backing_disk_scsi_addresses=None,
    service_instance=None,
):
    """
    Returns a list of dict representations of the datastores visible to the
    proxy object. The list of datastores can be filtered by datastore names,
    backing disk ids (canonical names) or backing disk scsi addresses.

    Supported proxy types: esxi, esxcluster, esxdatacenter

    datastore_names
        List of the names of datastores to filter on

    backing_disk_ids
        List of canonical names of the backing disks of the datastores to filer.
        Default is None.

    backing_disk_scsi_addresses
        List of scsi addresses of the backing disks of the datastores to filter.
        Default is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_datastores_via_proxy

        salt '*' vsphere.list_datastores_via_proxy datastore_names=[ds1, ds2]
    """
    target = _get_proxy_target(service_instance)
    target_name = salt.utils.vmware.get_managed_object_name(target)
    log.trace("target name = %s", target_name)

    # Default to getting all disks if no filtering is done
    get_all_datastores = (
        True
        if not (datastore_names or backing_disk_ids or backing_disk_scsi_addresses)
        else False
    )
    # Get the ids of the disks with the scsi addresses
    if backing_disk_scsi_addresses:
        log.debug(
            "Retrieving disk ids for scsi addresses '%s'", backing_disk_scsi_addresses
        )
        disk_ids = [
            d.canonicalName
            for d in salt.utils.vmware.get_disks(
                target, scsi_addresses=backing_disk_scsi_addresses
            )
        ]
        log.debug("Found disk ids '%s'", disk_ids)
        backing_disk_ids = (
            backing_disk_ids.extend(disk_ids) if backing_disk_ids else disk_ids
        )
    datastores = salt.utils.vmware.get_datastores(
        service_instance, target, datastore_names, backing_disk_ids, get_all_datastores
    )

    # Search for disk backed datastores if target is host
    # to be able to add the backing_disk_ids
    mount_infos = []
    if isinstance(target, vim.HostSystem):
        storage_system = salt.utils.vmware.get_storage_system(
            service_instance, target, target_name
        )
        props = salt.utils.vmware.get_properties_of_managed_object(
            storage_system, ["fileSystemVolumeInfo.mountInfo"]
        )
        mount_infos = props.get("fileSystemVolumeInfo.mountInfo", [])
    ret_dict = []
    for ds in datastores:
        ds_dict = {
            "name": ds.name,
            "type": ds.summary.type,
            "free_space": ds.summary.freeSpace,
            "capacity": ds.summary.capacity,
        }
        backing_disk_ids = []
        for vol in [
            i.volume
            for i in mount_infos
            if i.volume.name == ds.name and isinstance(i.volume, vim.HostVmfsVolume)
        ]:

            backing_disk_ids.extend([e.diskName for e in vol.extent])
        if backing_disk_ids:
            ds_dict["backing_disk_ids"] = backing_disk_ids
        ret_dict.append(ds_dict)
    return ret_dict


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_vmfs_datastore(
    datastore_name,
    disk_id,
    vmfs_major_version,
    safety_checks=True,
    service_instance=None,
):
    """
    Creates a ESXi host disk group with the specified cache and capacity disks.

    datastore_name
        The name of the datastore to be created.

    disk_id
        The disk id (canonical name) on which the datastore is created.

    vmfs_major_version
        The VMFS major version.

    safety_checks
        Specify whether to perform safety check or to skip the checks and try
        performing the required task. Default is True.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.create_vmfs_datastore datastore_name=ds1 disk_id=
            vmfs_major_version=5
    """
    log.debug("Validating vmfs datastore input")
    schema = VmfsDatastoreSchema.serialize()
    try:
        jsonschema.validate(
            {
                "datastore": {
                    "name": datastore_name,
                    "backing_disk_id": disk_id,
                    "vmfs_version": vmfs_major_version,
                }
            },
            schema,
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise ArgumentValueError(exc)
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    if safety_checks:
        disks = salt.utils.vmware.get_disks(host_ref, disk_ids=[disk_id])
        if not disks:
            raise VMwareObjectRetrievalError(
                f"Disk '{disk_id}' was not found in host '{hostname}'"
            )
    ds_ref = salt.utils.vmware.create_vmfs_datastore(
        host_ref, datastore_name, disks[0], vmfs_major_version
    )
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def rename_datastore(datastore_name, new_datastore_name, service_instance=None):
    """
    Renames a datastore. The datastore needs to be visible to the proxy.

    datastore_name
        Current datastore name.

    new_datastore_name
        New datastore name.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.rename_datastore old_name new_name
    """
    # Argument validation
    log.trace("Renaming datastore %s to %s", datastore_name, new_datastore_name)
    target = _get_proxy_target(service_instance)
    datastores = salt.utils.vmware.get_datastores(
        service_instance, target, datastore_names=[datastore_name]
    )
    if not datastores:
        raise VMwareObjectRetrievalError(f"Datastore '{datastore_name}' was not found")
    ds = datastores[0]
    salt.utils.vmware.rename_datastore(ds, new_datastore_name)
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def remove_datastore(datastore, service_instance=None):
    """
    Removes a datastore. If multiple datastores an error is raised.

    datastore
        Datastore name

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.remove_datastore ds_name
    """
    log.trace("Removing datastore '%s'", datastore)
    target = _get_proxy_target(service_instance)
    datastores = salt.utils.vmware.get_datastores(
        service_instance, reference=target, datastore_names=[datastore]
    )
    if not datastores:
        raise VMwareObjectRetrievalError(f"Datastore '{datastore}' was not found")
    if len(datastores) > 1:
        raise VMwareObjectRetrievalError(
            f"Multiple datastores '{datastore}' were found"
        )
    salt.utils.vmware.remove_datastore(service_instance, datastores[0])
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_licenses(service_instance=None):
    """
    Lists all licenses on a vCenter.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_licenses
    """
    log.trace("Retrieving all licenses")
    licenses = salt.utils.vmware.get_licenses(service_instance)
    ret_dict = [
        {
            "key": l.licenseKey,
            "name": l.name,
            "description": l.labels[0].value if l.labels else None,
            # VMware handles unlimited capacity as 0
            "capacity": l.total if l.total > 0 else sys.maxsize,
            "used": l.used if l.used else 0,
        }
        for l in licenses
    ]
    return ret_dict


@depends(HAS_PYVMOMI)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def add_license(key, description, safety_checks=True, service_instance=None):
    """
    Adds a license to the vCenter or ESXi host

    key
        License key.

    description
        License description added in as a label.

    safety_checks
        Specify whether to perform safety check or to skip the checks and try
        performing the required task

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.add_license key=<license_key> desc='License desc'
    """
    log.trace("Adding license '%s'", key)
    salt.utils.vmware.add_license(service_instance, key, description)
    return True


def _get_entity(service_instance, entity):
    """
    Returns the entity associated with the entity dict representation

    Supported entities: cluster, vcenter

    Expected entity format:

    .. code-block:: python

        cluster:
            {'type': 'cluster',
             'datacenter': <datacenter_name>,
             'cluster': <cluster_name>}
        vcenter:
            {'type': 'vcenter'}

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.

    entity
        Entity dict in the format above
    """

    log.trace("Retrieving entity: %s", entity)
    if entity["type"] == "cluster":
        dc_ref = salt.utils.vmware.get_datacenter(
            service_instance, entity["datacenter"]
        )
        return salt.utils.vmware.get_cluster(dc_ref, entity["cluster"])
    elif entity["type"] == "vcenter":
        return None
    raise ArgumentValueError("Unsupported entity type '{}'".format(entity["type"]))


def _validate_entity(entity):
    """
    Validates the entity dict representation

    entity
        Dictionary representation of an entity.
        See ``_get_entity`` docstrings for format.
    """

    # Validate entity:
    if entity["type"] == "cluster":
        schema = ESXClusterEntitySchema.serialize()
    elif entity["type"] == "vcenter":
        schema = VCenterEntitySchema.serialize()
    else:
        raise ArgumentValueError("Unsupported entity type '{}'".format(entity["type"]))
    try:
        jsonschema.validate(entity, schema)
    except jsonschema.exceptions.ValidationError as exc:
        raise InvalidEntityError(exc)


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_assigned_licenses(
    entity, entity_display_name, license_keys=None, service_instance=None
):
    """
    Lists the licenses assigned to an entity

    entity
        Dictionary representation of an entity.
        See ``_get_entity`` docstrings for format.

    entity_display_name
        Entity name used in logging

    license_keys:
        List of license keys to be retrieved. Default is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_assigned_licenses
            entity={type:cluster,datacenter:dc,cluster:cl}
            entiy_display_name=cl
    """
    log.trace("Listing assigned licenses of entity %s", entity)
    _validate_entity(entity)

    assigned_licenses = salt.utils.vmware.get_assigned_licenses(
        service_instance,
        entity_ref=_get_entity(service_instance, entity),
        entity_name=entity_display_name,
    )

    return [
        {
            "key": l.licenseKey,
            "name": l.name,
            "description": l.labels[0].value if l.labels else None,
            # VMware handles unlimited capacity as 0
            "capacity": l.total if l.total > 0 else sys.maxsize,
        }
        for l in assigned_licenses
        if (license_keys is None) or (l.licenseKey in license_keys)
    ]


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def assign_license(
    license_key,
    license_name,
    entity,
    entity_display_name,
    safety_checks=True,
    service_instance=None,
):
    """
    Assigns a license to an entity

    license_key
        Key of the license to assign
        See ``_get_entity`` docstrings for format.

    license_name
        Display name of license

    entity
        Dictionary representation of an entity

    entity_display_name
        Entity name used in logging

    safety_checks
        Specify whether to perform safety check or to skip the checks and try
        performing the required task. Default is False.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.assign_license license_key=AAAAA-11111-AAAAA-11111-AAAAA
            license_name=test entity={type:cluster,datacenter:dc,cluster:cl}
    """
    log.trace("Assigning license %s to entity %s", license_key, entity)
    _validate_entity(entity)
    if safety_checks:
        licenses = salt.utils.vmware.get_licenses(service_instance)
        if not [l for l in licenses if l.licenseKey == license_key]:
            raise VMwareObjectRetrievalError(f"License '{license_name}' wasn't found")
    salt.utils.vmware.assign_license(
        service_instance,
        license_key,
        license_name,
        entity_ref=_get_entity(service_instance, entity),
        entity_name=entity_display_name,
    )


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter", "vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_hosts_via_proxy(
    hostnames=None, datacenter=None, cluster=None, service_instance=None
):
    """
    Returns a list of hosts for the specified VMware environment. The list
    of hosts can be filtered by datacenter name and/or cluster name

    hostnames
        Hostnames to filter on.

    datacenter_name
        Name of datacenter. Only hosts in this datacenter will be retrieved.
        Default is None.

    cluster_name
        Name of cluster. Only hosts in this cluster will be retrieved. If a
        datacenter is not specified the first cluster with this name will be
        considerred. Default is None.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_hosts_via_proxy

        salt '*' vsphere.list_hosts_via_proxy hostnames=[esxi1.example.com]

        salt '*' vsphere.list_hosts_via_proxy datacenter=dc1 cluster=cluster1
    """
    if cluster:
        if not datacenter:
            raise salt.exceptions.ArgumentValueError(
                "Datacenter is required when cluster is specified"
            )
    get_all_hosts = False
    if not hostnames:
        get_all_hosts = True
    hosts = salt.utils.vmware.get_hosts(
        service_instance,
        datacenter_name=datacenter,
        host_names=hostnames,
        cluster_name=cluster,
        get_all_hosts=get_all_hosts,
    )
    return [salt.utils.vmware.get_managed_object_name(h) for h in hosts]


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_disks(disk_ids=None, scsi_addresses=None, service_instance=None):
    """
    Returns a list of dict representations of the disks in an ESXi host.
    The list of disks can be filtered by disk canonical names or
    scsi addresses.

    disk_ids:
        List of disk canonical names to be retrieved. Default is None.

    scsi_addresses
        List of scsi addresses of disks to be retrieved. Default is None


    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_disks

        salt '*' vsphere.list_disks disk_ids='[naa.00, naa.001]'

        salt '*' vsphere.list_disks
            scsi_addresses='[vmhba0:C0:T0:L0, vmhba1:C0:T0:L0]'
    """
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    log.trace(
        "Retrieving disks of host '%s'; disc ids = %s; scsi_address = %s",
        hostname,
        disk_ids,
        scsi_addresses,
    )
    # Default to getting all disks if no filtering is done
    get_all_disks = True if not (disk_ids or scsi_addresses) else False
    ret_list = []
    scsi_address_to_lun = salt.utils.vmware.get_scsi_address_to_lun_map(
        host_ref, hostname=hostname
    )
    canonical_name_to_scsi_address = {
        lun.canonicalName: scsi_addr for scsi_addr, lun in scsi_address_to_lun.items()
    }
    for d in salt.utils.vmware.get_disks(
        host_ref, disk_ids, scsi_addresses, get_all_disks
    ):
        ret_list.append(
            {
                "id": d.canonicalName,
                "scsi_address": canonical_name_to_scsi_address[d.canonicalName],
            }
        )
    return ret_list


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def erase_disk_partitions(disk_id=None, scsi_address=None, service_instance=None):
    """
    Erases the partitions on a disk.
    The disk can be specified either by the canonical name, or by the
    scsi_address.

    disk_id
        Canonical name of the disk.
        Either ``disk_id`` or ``scsi_address`` needs to be specified
        (``disk_id`` supersedes ``scsi_address``.

    scsi_address
        Scsi address of the disk.
        ``disk_id`` or ``scsi_address`` needs to be specified
        (``disk_id`` supersedes ``scsi_address``.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.erase_disk_partitions scsi_address='vmhaba0:C0:T0:L0'

        salt '*' vsphere.erase_disk_partitions disk_id='naa.000000000000001'
    """
    if not disk_id and not scsi_address:
        raise ArgumentValueError(
            "Either 'disk_id' or 'scsi_address' needs to be specified"
        )
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    if not disk_id:
        scsi_address_to_lun = salt.utils.vmware.get_scsi_address_to_lun_map(host_ref)
        if scsi_address not in scsi_address_to_lun:
            raise VMwareObjectRetrievalError(
                "Scsi lun with address '{}' was not found on host '{}'".format(
                    scsi_address, hostname
                )
            )
        disk_id = scsi_address_to_lun[scsi_address].canonicalName
        log.trace(
            "[%s] Got disk id '%s' for scsi address '%s'",
            hostname,
            disk_id,
            scsi_address,
        )
    log.trace("Erasing disk partitions on disk '%s' in host '%s'", disk_id, hostname)
    salt.utils.vmware.erase_disk_partitions(
        service_instance, host_ref, disk_id, hostname=hostname
    )
    log.info("Erased disk partitions on disk '%s' on host '%s'", disk_id, hostname)
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_disk_partitions(disk_id=None, scsi_address=None, service_instance=None):
    """
    Lists the partitions on a disk.
    The disk can be specified either by the canonical name, or by the
    scsi_address.

    disk_id
        Canonical name of the disk.
        Either ``disk_id`` or ``scsi_address`` needs to be specified
        (``disk_id`` supersedes ``scsi_address``.

    scsi_address`
        Scsi address of the disk.
        ``disk_id`` or ``scsi_address`` needs to be specified
        (``disk_id`` supersedes ``scsi_address``.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_disk_partitions scsi_address='vmhaba0:C0:T0:L0'

        salt '*' vsphere.list_disk_partitions disk_id='naa.000000000000001'
    """
    if not disk_id and not scsi_address:
        raise ArgumentValueError(
            "Either 'disk_id' or 'scsi_address' needs to be specified"
        )
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    if not disk_id:
        scsi_address_to_lun = salt.utils.vmware.get_scsi_address_to_lun_map(host_ref)
        if scsi_address not in scsi_address_to_lun:
            raise VMwareObjectRetrievalError(
                "Scsi lun with address '{}' was not found on host '{}'".format(
                    scsi_address, hostname
                )
            )
        disk_id = scsi_address_to_lun[scsi_address].canonicalName
        log.trace(
            "[%s] Got disk id '%s' for scsi address '%s'",
            hostname,
            disk_id,
            scsi_address,
        )
    log.trace("Listing disk partitions on disk '%s' in host '%s'", disk_id, hostname)
    partition_info = salt.utils.vmware.get_disk_partition_info(host_ref, disk_id)
    ret_list = []
    # NOTE: 1. The layout view has an extra 'None' partition for free space
    #       2. The orders in the layout/partition views are not the same
    for part_spec in partition_info.spec.partition:
        part_layout = [
            p
            for p in partition_info.layout.partition
            if p.partition == part_spec.partition
        ][0]
        part_dict = {
            "hostname": hostname,
            "device": disk_id,
            "format": partition_info.spec.partitionFormat,
            "partition": part_spec.partition,
            "type": part_spec.type,
            "sectors": part_spec.endSector - part_spec.startSector + 1,
            "size_KB": (part_layout.end.block - part_layout.start.block + 1)
            * part_layout.start.blockSize
            / 1024,
        }
        ret_list.append(part_dict)
    return ret_list


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_diskgroups(cache_disk_ids=None, service_instance=None):
    """
    Returns a list of disk group dict representation on an ESXi host.
    The list of disk groups can be filtered by the cache disks
    canonical names. If no filtering is applied, all disk groups are returned.

    cache_disk_ids:
        List of cache disk canonical names of the disk groups to be retrieved.
        Default is None.

    use_proxy_details
        Specify whether to use the proxy minion's details instead of the
        arguments

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.list_diskgroups

        salt '*' vsphere.list_diskgroups cache_disk_ids='[naa.000000000000001]'
    """
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    log.trace("Listing diskgroups in '%s'", hostname)
    get_all_diskgroups = True if not cache_disk_ids else False
    ret_list = []
    for dg in salt.utils.vmware.get_diskgroups(
        host_ref, cache_disk_ids, get_all_diskgroups
    ):
        ret_list.append(
            {
                "cache_disk": dg.ssd.canonicalName,
                "capacity_disks": [d.canonicalName for d in dg.nonSsd],
            }
        )
    return ret_list


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_diskgroup(
    cache_disk_id, capacity_disk_ids, safety_checks=True, service_instance=None
):
    """
    Creates disk group on an ESXi host with the specified cache and
    capacity disks.

    cache_disk_id
        The canonical name of the disk to be used as a cache. The disk must be
        ssd.

    capacity_disk_ids
        A list containing canonical names of the capacity disks. Must contain at
        least one id. Default is True.

    safety_checks
        Specify whether to perform safety check or to skip the checks and try
        performing the required task. Default value is True.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.create_diskgroup cache_disk_id='naa.000000000000001'
            capacity_disk_ids='[naa.000000000000002, naa.000000000000003]'
    """
    log.trace("Validating diskgroup input")
    schema = DiskGroupsDiskIdSchema.serialize()
    try:
        jsonschema.validate(
            {
                "diskgroups": [
                    {"cache_id": cache_disk_id, "capacity_ids": capacity_disk_ids}
                ]
            },
            schema,
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise ArgumentValueError(exc)
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    if safety_checks:
        diskgroups = salt.utils.vmware.get_diskgroups(host_ref, [cache_disk_id])
        if diskgroups:
            raise VMwareObjectExistsError(
                "Diskgroup with cache disk id '{}' already exists ESXi "
                "host '{}'".format(cache_disk_id, hostname)
            )
    disk_ids = capacity_disk_ids[:]
    disk_ids.insert(0, cache_disk_id)
    disks = salt.utils.vmware.get_disks(host_ref, disk_ids=disk_ids)
    for id in disk_ids:
        if not [d for d in disks if d.canonicalName == id]:
            raise VMwareObjectRetrievalError(
                f"No disk with id '{id}' was found in ESXi host '{hostname}'"
            )
    cache_disk = [d for d in disks if d.canonicalName == cache_disk_id][0]
    capacity_disks = [d for d in disks if d.canonicalName in capacity_disk_ids]
    vsan_disk_mgmt_system = salt.utils.vsan.get_vsan_disk_management_system(
        service_instance
    )
    dg = salt.utils.vsan.create_diskgroup(
        service_instance, vsan_disk_mgmt_system, host_ref, cache_disk, capacity_disks
    )
    return True


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def add_capacity_to_diskgroup(
    cache_disk_id, capacity_disk_ids, safety_checks=True, service_instance=None
):
    """
    Adds capacity disks to the disk group with the specified cache disk.

    cache_disk_id
        The canonical name of the cache disk.

    capacity_disk_ids
        A list containing canonical names of the capacity disks to add.

    safety_checks
        Specify whether to perform safety check or to skip the checks and try
        performing the required task. Default value is True.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.add_capacity_to_diskgroup
            cache_disk_id='naa.000000000000001'
            capacity_disk_ids='[naa.000000000000002, naa.000000000000003]'
    """
    log.trace("Validating diskgroup input")
    schema = DiskGroupsDiskIdSchema.serialize()
    try:
        jsonschema.validate(
            {
                "diskgroups": [
                    {"cache_id": cache_disk_id, "capacity_ids": capacity_disk_ids}
                ]
            },
            schema,
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise ArgumentValueError(exc)
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    disks = salt.utils.vmware.get_disks(host_ref, disk_ids=capacity_disk_ids)
    if safety_checks:
        for id in capacity_disk_ids:
            if not [d for d in disks if d.canonicalName == id]:
                raise VMwareObjectRetrievalError(
                    "No disk with id '{}' was found in ESXi host '{}'".format(
                        id, hostname
                    )
                )
    diskgroups = salt.utils.vmware.get_diskgroups(
        host_ref, cache_disk_ids=[cache_disk_id]
    )
    if not diskgroups:
        raise VMwareObjectRetrievalError(
            "No diskgroup with cache disk id '{}' was found in ESXi host '{}'".format(
                cache_disk_id, hostname
            )
        )
    vsan_disk_mgmt_system = salt.utils.vsan.get_vsan_disk_management_system(
        service_instance
    )
    salt.utils.vsan.add_capacity_to_diskgroup(
        service_instance, vsan_disk_mgmt_system, host_ref, diskgroups[0], disks
    )
    return True


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def remove_capacity_from_diskgroup(
    cache_disk_id,
    capacity_disk_ids,
    data_evacuation=True,
    safety_checks=True,
    service_instance=None,
):
    """
    Remove capacity disks from the disk group with the specified cache disk.

    cache_disk_id
        The canonical name of the cache disk.

    capacity_disk_ids
        A list containing canonical names of the capacity disks to add.

    data_evacuation
        Specifies whether to gracefully evacuate the data on the capacity disks
        before removing them from the disk group. Default value is True.

    safety_checks
        Specify whether to perform safety check or to skip the checks and try
        performing the required task. Default value is True.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.remove_capacity_from_diskgroup
            cache_disk_id='naa.000000000000001'
            capacity_disk_ids='[naa.000000000000002, naa.000000000000003]'
    """
    log.trace("Validating diskgroup input")
    schema = DiskGroupsDiskIdSchema.serialize()
    try:
        jsonschema.validate(
            {
                "diskgroups": [
                    {"cache_id": cache_disk_id, "capacity_ids": capacity_disk_ids}
                ]
            },
            schema,
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise ArgumentValueError(str(exc))
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    disks = salt.utils.vmware.get_disks(host_ref, disk_ids=capacity_disk_ids)
    if safety_checks:
        for id in capacity_disk_ids:
            if not [d for d in disks if d.canonicalName == id]:
                raise VMwareObjectRetrievalError(
                    "No disk with id '{}' was found in ESXi host '{}'".format(
                        id, hostname
                    )
                )
    diskgroups = salt.utils.vmware.get_diskgroups(
        host_ref, cache_disk_ids=[cache_disk_id]
    )
    if not diskgroups:
        raise VMwareObjectRetrievalError(
            "No diskgroup with cache disk id '{}' was found in ESXi host '{}'".format(
                cache_disk_id, hostname
            )
        )
    log.trace("data_evacuation = %s", data_evacuation)
    salt.utils.vsan.remove_capacity_from_diskgroup(
        service_instance,
        host_ref,
        diskgroups[0],
        capacity_disks=[d for d in disks if d.canonicalName in capacity_disk_ids],
        data_evacuation=data_evacuation,
    )
    return True


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def remove_diskgroup(cache_disk_id, data_accessibility=True, service_instance=None):
    """
    Remove the diskgroup with the specified cache disk.

    cache_disk_id
        The canonical name of the cache disk.

    data_accessibility
        Specifies whether to ensure data accessibility. Default value is True.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.remove_diskgroup cache_disk_id='naa.000000000000001'
    """
    log.trace("Validating diskgroup input")
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    diskgroups = salt.utils.vmware.get_diskgroups(
        host_ref, cache_disk_ids=[cache_disk_id]
    )
    if not diskgroups:
        raise VMwareObjectRetrievalError(
            "No diskgroup with cache disk id '{}' was found in ESXi host '{}'".format(
                cache_disk_id, hostname
            )
        )
    log.trace("data accessibility = %s", data_accessibility)
    salt.utils.vsan.remove_diskgroup(
        service_instance, host_ref, diskgroups[0], data_accessibility=data_accessibility
    )
    return True


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def get_host_cache(service_instance=None):
    """
    Returns the host cache configuration on the proxy host.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.get_host_cache
    """
    # Default to getting all disks if no filtering is done
    ret_dict = {}
    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    hci = salt.utils.vmware.get_host_cache(host_ref)
    if not hci:
        log.debug("Host cache not configured on host '%s'", hostname)
        ret_dict["enabled"] = False
        return ret_dict

    # TODO Support multiple host cache info objects (on multiple datastores)
    return {
        "enabled": True,
        "datastore": {"name": hci.key.name},
        "swap_size": f"{hci.swapSize}MiB",
    }


@depends(HAS_PYVMOMI)
@depends(HAS_JSONSCHEMA)
@_supports_proxies("esxi")
@_gets_service_instance_via_proxy
@_deprecation_message
def configure_host_cache(
    enabled, datastore=None, swap_size_MiB=None, service_instance=None
):
    """
    Configures the host cache on the selected host.

    enabled
        Boolean flag specifying whether the host cache is enabled.

    datastore
        Name of the datastore that contains the host cache. Must be set if
        enabled is ``true``.

    swap_size_MiB
        Swap size in Mibibytes. Needs to be set if enabled is ``true``. Must be
        smaller than the datastore size.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.configure_host_cache enabled=False

        salt '*' vsphere.configure_host_cache enabled=True datastore=ds1
            swap_size_MiB=1024
    """
    log.debug("Validating host cache input")
    schema = SimpleHostCacheSchema.serialize()
    try:
        jsonschema.validate(
            {
                "enabled": enabled,
                "datastore_name": datastore,
                "swap_size_MiB": swap_size_MiB,
            },
            schema,
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise ArgumentValueError(exc)
    if not enabled:
        raise ArgumentValueError("Disabling the host cache is not supported")
    ret_dict = {"enabled": False}

    host_ref = _get_proxy_target(service_instance)
    hostname = __proxy__["esxi.get_details"]()["esxi_host"]
    if datastore:
        ds_refs = salt.utils.vmware.get_datastores(
            service_instance, host_ref, datastore_names=[datastore]
        )
        if not ds_refs:
            raise VMwareObjectRetrievalError(
                f"Datastore '{datastore}' was not found on host '{hostname}'"
            )
        ds_ref = ds_refs[0]
    salt.utils.vmware.configure_host_cache(host_ref, ds_ref, swap_size_MiB)
    return True


def _check_hosts(service_instance, host, host_names):
    """
    Helper function that checks to see if the host provided is a vCenter Server or
    an ESXi host. If it's an ESXi host, returns a list of a single host_name.

    If a host reference isn't found, we're trying to find a host object for a vCenter
    server. Raises a CommandExecutionError in this case, as we need host references to
    check against.
    """
    if not host_names:
        host_name = _get_host_ref(service_instance, host)
        if host_name:
            host_names = [host]
        else:
            raise CommandExecutionError(
                "No host reference found. If connecting to a "
                "vCenter Server, a list of 'host_names' must be "
                "provided."
            )
    elif not isinstance(host_names, list):
        raise CommandExecutionError("'host_names' must be a list.")

    return host_names


def _format_coredump_stdout(cmd_ret):
    """
    Helper function to format the stdout from the get_coredump_network_config function.

    cmd_ret
        The return dictionary that comes from a cmd.run_all call.
    """
    ret_dict = {}
    for line in cmd_ret["stdout"].splitlines():
        line = line.strip().lower()
        if line.startswith("enabled:"):
            enabled = line.split(":")
            if "true" in enabled[1]:
                ret_dict["enabled"] = True
            else:
                ret_dict["enabled"] = False
                break
        if line.startswith("host vnic:"):
            host_vnic = line.split(":")
            ret_dict["host_vnic"] = host_vnic[1].strip()
        if line.startswith("network server ip:"):
            ip = line.split(":")
            ret_dict["ip"] = ip[1].strip()
        if line.startswith("network server port:"):
            ip_port = line.split(":")
            ret_dict["port"] = ip_port[1].strip()

    return ret_dict


def _format_firewall_stdout(cmd_ret):
    """
    Helper function to format the stdout from the get_firewall_status function.

    cmd_ret
        The return dictionary that comes from a cmd.run_all call.
    """
    ret_dict = {"success": True, "rulesets": {}}
    for line in cmd_ret["stdout"].splitlines():
        if line.startswith("Name"):
            continue
        if line.startswith("---"):
            continue
        ruleset_status = line.split()
        ret_dict["rulesets"][ruleset_status[0]] = bool(ruleset_status[1])

    return ret_dict


def _format_syslog_config(cmd_ret):
    """
    Helper function to format the stdout from the get_syslog_config function.

    cmd_ret
        The return dictionary that comes from a cmd.run_all call.
    """
    ret_dict = {"success": cmd_ret["retcode"] == 0}

    if cmd_ret["retcode"] != 0:
        ret_dict["message"] = cmd_ret["stdout"]
    else:
        for line in cmd_ret["stdout"].splitlines():
            line = line.strip()
            cfgvars = line.split(": ")
            key = cfgvars[0].strip()
            value = cfgvars[1].strip()
            ret_dict[key] = value

    return ret_dict


def _get_date_time_mgr(host_reference):
    """
    Helper function that returns a dateTimeManager object
    """
    return host_reference.configManager.dateTimeSystem


def _get_host_ref(service_instance, host, host_name=None):
    """
    Helper function that returns a host object either from the host location or the host_name.
    If host_name is provided, that is the host_object that will be returned.

    The function will first search for hosts by DNS Name. If no hosts are found, it will
    try searching by IP Address.
    """
    search_index = salt.utils.vmware.get_inventory(service_instance).searchIndex

    # First, try to find the host reference by DNS Name.
    if host_name:
        host_ref = search_index.FindByDnsName(dnsName=host_name, vmSearch=False)
    else:
        host_ref = search_index.FindByDnsName(dnsName=host, vmSearch=False)

    # If we couldn't find the host by DNS Name, then try the IP Address.
    if host_ref is None:
        host_ref = search_index.FindByIp(ip=host, vmSearch=False)

    return host_ref


def _get_host_ssds(host_reference):
    """
    Helper function that returns a list of ssd objects for a given host.
    """
    return _get_host_disks(host_reference).get("SSDs")


def _get_host_non_ssds(host_reference):
    """
    Helper function that returns a list of Non-SSD objects for a given host.
    """
    return _get_host_disks(host_reference).get("Non-SSDs")


def _get_host_disks(host_reference):
    """
    Helper function that returns a dictionary containing a list of SSD and Non-SSD disks.
    """
    storage_system = host_reference.configManager.storageSystem
    disks = storage_system.storageDeviceInfo.scsiLun
    ssds = []
    non_ssds = []

    for disk in disks:
        try:
            has_ssd_attr = disk.ssd
        except AttributeError:
            has_ssd_attr = False
        if has_ssd_attr:
            ssds.append(disk)
        else:
            non_ssds.append(disk)

    return {"SSDs": ssds, "Non-SSDs": non_ssds}


def _get_service_manager(host_reference):
    """
    Helper function that returns a service manager object from a given host object.
    """
    return host_reference.configManager.serviceSystem


def _get_vsan_eligible_disks(service_instance, host, host_names):
    """
    Helper function that returns a dictionary of host_name keys with either a list of eligible
    disks that can be added to VSAN or either an 'Error' message or a message saying no
    eligible disks were found. Possible keys/values look like:

    return = {'host_1': {'Error': 'VSAN System Config Manager is unset ...'},
              'host_2': {'Eligible': 'The host xxx does not have any VSAN eligible disks.'},
              'host_3': {'Eligible': [disk1, disk2, disk3, disk4],
              'host_4': {'Eligible': []}}
    """
    ret = {}
    for host_name in host_names:

        # Get VSAN System Config Manager, if available.
        host_ref = _get_host_ref(service_instance, host, host_name=host_name)
        vsan_system = host_ref.configManager.vsanSystem
        if vsan_system is None:
            msg = (
                "VSAN System Config Manager is unset for host '{}'. "
                "VSAN configuration cannot be changed without a configured "
                "VSAN System.".format(host_name)
            )
            log.debug(msg)
            ret.update({host_name: {"Error": msg}})
            continue

        # Get all VSAN suitable disks for this host.
        suitable_disks = []
        query = vsan_system.QueryDisksForVsan()
        for item in query:
            if item.state == "eligible":
                suitable_disks.append(item)

        # No suitable disks were found to add. Warn and move on.
        # This isn't an error as the state may run repeatedly after all eligible disks are added.
        if not suitable_disks:
            msg = "The host '{}' does not have any VSAN eligible disks.".format(
                host_name
            )
            log.warning(msg)
            ret.update({host_name: {"Eligible": msg}})
            continue

        # Get disks for host and combine into one list of Disk Objects
        disks = _get_host_ssds(host_ref) + _get_host_non_ssds(host_ref)

        # Get disks that are in both the disks list and suitable_disks lists.
        matching = []
        for disk in disks:
            for suitable_disk in suitable_disks:
                if disk.canonicalName == suitable_disk.disk.canonicalName:
                    matching.append(disk)

        ret.update({host_name: {"Eligible": matching}})

    return ret


def _reset_syslog_config_params(
    host,
    username,
    password,
    cmd,
    resets,
    valid_resets,
    protocol=None,
    port=None,
    esxi_host=None,
    credstore=None,
):
    """
    Helper function for reset_syslog_config that resets the config and populates the return dictionary.
    """
    ret_dict = {}
    all_success = True

    if not isinstance(resets, list):
        resets = [resets]

    for reset_param in resets:
        if reset_param in valid_resets:
            ret = salt.utils.vmware.esxcli(
                host,
                username,
                password,
                cmd + reset_param,
                protocol=protocol,
                port=port,
                esxi_host=esxi_host,
                credstore=credstore,
            )
            ret_dict[reset_param] = {}
            ret_dict[reset_param]["success"] = ret["retcode"] == 0
            if ret["retcode"] != 0:
                all_success = False
                ret_dict[reset_param]["message"] = ret["stdout"]
        else:
            all_success = False
            ret_dict[reset_param] = {}
            ret_dict[reset_param]["success"] = False
            ret_dict[reset_param]["message"] = "Invalid syslog configuration parameter"

    ret_dict["success"] = all_success

    return ret_dict


def _set_syslog_config_helper(
    host,
    username,
    password,
    syslog_config,
    config_value,
    protocol=None,
    port=None,
    reset_service=None,
    esxi_host=None,
    credstore=None,
):
    """
    Helper function for set_syslog_config that sets the config and populates the return dictionary.
    """
    cmd = f"system syslog config set --{syslog_config} {config_value}"
    ret_dict = {}

    valid_resets = [
        "logdir",
        "loghost",
        "default-rotate",
        "default-size",
        "default-timeout",
        "logdir-unique",
    ]
    if syslog_config not in valid_resets:
        ret_dict.update(
            {
                "success": False,
                "message": f"'{syslog_config}' is not a valid config variable.",
            }
        )
        return ret_dict

    response = salt.utils.vmware.esxcli(
        host,
        username,
        password,
        cmd,
        protocol=protocol,
        port=port,
        esxi_host=esxi_host,
        credstore=credstore,
    )

    # Update the return dictionary for success or error messages.
    if response["retcode"] != 0:
        ret_dict.update(
            {syslog_config: {"success": False, "message": response["stdout"]}}
        )
    else:
        ret_dict.update({syslog_config: {"success": True}})

    # Restart syslog for each host, if desired.
    if reset_service:
        if esxi_host:
            host_name = esxi_host
            esxi_host = [esxi_host]
        else:
            host_name = host
        response = syslog_service_reload(
            host,
            username,
            password,
            protocol=protocol,
            port=port,
            esxi_hosts=esxi_host,
            credstore=credstore,
        ).get(host_name)
        ret_dict.update({"syslog_restart": {"success": response["retcode"] == 0}})

    return ret_dict


@depends(HAS_PYVMOMI)
@ignores_kwargs("credstore")
@_deprecation_message
def add_host_to_dvs(
    host,
    username,
    password,
    vmknic_name,
    vmnic_name,
    dvs_name,
    target_portgroup_name,
    uplink_portgroup_name,
    protocol=None,
    port=None,
    host_names=None,
    verify_ssl=True,
):
    """
    Adds an ESXi host to a vSphere Distributed Virtual Switch and migrates
    the desired adapters to the DVS from the standard switch.

    host
        The location of the vCenter server.

    username
        The username used to login to the vCenter server.

    password
        The password used to login to the vCenter server.

    vmknic_name
        The name of the virtual NIC to migrate.

    vmnic_name
        The name of the physical NIC to migrate.

    dvs_name
        The name of the Distributed Virtual Switch.

    target_portgroup_name
        The name of the distributed portgroup in which to migrate the
        virtual NIC.

    uplink_portgroup_name
        The name of the uplink portgroup in which to migrate the
        physical NIC.

    protocol
        Optionally set to alternate protocol if the vCenter server or ESX/ESXi host is not
        using the default protocol. Default protocol is ``https``.

    port
        Optionally set to alternate port if the vCenter server or ESX/ESXi host is not
        using the default port. Default port is ``443``.

    host_names:
        An array of VMware host names to migrate

    verify_ssl
        Verify the SSL certificate. Default: True

    CLI Example:

    .. code-block:: bash

        salt some_host vsphere.add_host_to_dvs host='vsphere.corp.com'
            username='administrator@vsphere.corp.com' password='vsphere_password'
            vmknic_name='vmk0' vmnic_name='vnmic0' dvs_name='DSwitch'
            target_portgroup_name='DPortGroup' uplink_portgroup_name='DSwitch1-DVUplinks-181'
            protocol='https' port='443', host_names="['esxi1.corp.com','esxi2.corp.com','esxi3.corp.com']"

    Return Example:

    .. code-block:: yaml

        somehost:
            ----------
            esxi1.corp.com:
                ----------
                dvs:
                    DSwitch
                portgroup:
                    DPortGroup
                status:
                    True
                uplink:
                    DSwitch-DVUplinks-181
                vmknic:
                    vmk0
                vmnic:
                    vmnic0
            esxi2.corp.com:
                ----------
                dvs:
                    DSwitch
                portgroup:
                    DPortGroup
                status:
                    True
                uplink:
                    DSwitch-DVUplinks-181
                vmknic:
                    vmk0
                vmnic:
                    vmnic0
            esxi3.corp.com:
                ----------
                dvs:
                    DSwitch
                portgroup:
                    DPortGroup
                status:
                    True
                uplink:
                    DSwitch-DVUplinks-181
                vmknic:
                    vmk0
                vmnic:
                    vmnic0
            message:
            success:
                True

    This was very difficult to figure out.  VMware's PyVmomi documentation at

    https://github.com/vmware/pyvmomi/blob/master/docs/vim/DistributedVirtualSwitch.rst
    (which is a copy of the official documentation here:
    https://www.vmware.com/support/developer/converter-sdk/conv60_apireference/vim.DistributedVirtualSwitch.html)

    says to create the DVS, create distributed portgroups, and then add the
    host to the DVS specifying which physical NIC to use as the port backing.
    However, if the physical NIC is in use as the only link from the host
    to vSphere, this will fail with an unhelpful "busy" error.

    There is, however, a Powershell PowerCLI cmdlet called Add-VDSwitchPhysicalNetworkAdapter
    that does what we want.  I used Onyx (https://labs.vmware.com/flings/onyx)
    to sniff the SOAP stream from Powershell to our vSphere server and got
    this snippet out:

    .. code-block:: xml

        <UpdateNetworkConfig xmlns="urn:vim25">
          <_this type="HostNetworkSystem">networkSystem-187</_this>
          <config>
            <vswitch>
              <changeOperation>edit</changeOperation>
              <name>vSwitch0</name>
              <spec>
                <numPorts>7812</numPorts>
              </spec>
            </vswitch>
            <proxySwitch>
                <changeOperation>edit</changeOperation>
                <uuid>73 a4 05 50 b0 d2 7e b9-38 80 5d 24 65 8f da 70</uuid>
                <spec>
                <backing xsi:type="DistributedVirtualSwitchHostMemberPnicBacking">
                    <pnicSpec><pnicDevice>vmnic0</pnicDevice></pnicSpec>
                </backing>
                </spec>
            </proxySwitch>
            <portgroup>
              <changeOperation>remove</changeOperation>
              <spec>
                <name>Management Network</name><vlanId>-1</vlanId><vswitchName /><policy />
              </spec>
            </portgroup>
            <vnic>
              <changeOperation>edit</changeOperation>
              <device>vmk0</device>
              <portgroup />
              <spec>
                <distributedVirtualPort>
                  <switchUuid>73 a4 05 50 b0 d2 7e b9-38 80 5d 24 65 8f da 70</switchUuid>
                  <portgroupKey>dvportgroup-191</portgroupKey>
                </distributedVirtualPort>
              </spec>
            </vnic>
          </config>
          <changeMode>modify</changeMode>
        </UpdateNetworkConfig>

    The SOAP API maps closely to PyVmomi, so from there it was (relatively)
    easy to figure out what Python to write.
    """
    ret = {}
    ret["success"] = True
    ret["message"] = []
    service_instance = salt.utils.vmware.get_service_instance(
        host=host,
        username=username,
        password=password,
        protocol=protocol,
        port=port,
        verify_ssl=verify_ssl,
    )
    dvs = salt.utils.vmware._get_dvs(service_instance, dvs_name)
    if not dvs:
        ret["message"].append(
            f"No Distributed Virtual Switch found with name {dvs_name}"
        )
        ret["success"] = False

    target_portgroup = salt.utils.vmware._get_dvs_portgroup(dvs, target_portgroup_name)
    if not target_portgroup:
        ret["message"].append(
            f"No target portgroup found with name {target_portgroup_name}"
        )
        ret["success"] = False

    uplink_portgroup = salt.utils.vmware._get_dvs_uplink_portgroup(
        dvs, uplink_portgroup_name
    )
    if not uplink_portgroup:
        ret["message"].append(
            f"No uplink portgroup found with name {uplink_portgroup_name}"
        )
        ret["success"] = False

    if ret["message"]:
        return ret

    dvs_uuid = dvs.config.uuid
    try:
        host_names = _check_hosts(service_instance, host, host_names)
    except CommandExecutionError as e:
        ret["message"] = f"Error retrieving hosts: {e.msg}"
        return ret

    for host_name in host_names:
        ret[host_name] = {}

        ret[host_name].update(
            {
                "status": False,
                "uplink": uplink_portgroup_name,
                "portgroup": target_portgroup_name,
                "vmknic": vmknic_name,
                "vmnic": vmnic_name,
                "dvs": dvs_name,
            }
        )
        host_ref = _get_host_ref(service_instance, host, host_name)
        if not host_ref:
            ret[host_name].update({"message": "Host {1} not found".format(host_name)})
            ret["success"] = False
            continue

        dvs_hostmember_config = vim.dvs.HostMember.ConfigInfo(host=host_ref)
        dvs_hostmember = vim.dvs.HostMember(config=dvs_hostmember_config)
        p_nics = salt.utils.vmware._get_pnics(host_ref)
        p_nic = [x for x in p_nics if x.device == vmnic_name]
        if not p_nic:
            ret[host_name].update({"message": f"Physical nic {vmknic_name} not found"})
            ret["success"] = False
            continue

        v_nics = salt.utils.vmware._get_vnics(host_ref)
        v_nic = [x for x in v_nics if x.device == vmknic_name]

        if not v_nic:
            ret[host_name].update({"message": f"Virtual nic {vmnic_name} not found"})
            ret["success"] = False
            continue

        v_nic_mgr = salt.utils.vmware._get_vnic_manager(host_ref)
        if not v_nic_mgr:
            ret[host_name].update(
                {"message": "Unable to get the host's virtual nic manager."}
            )
            ret["success"] = False
            continue

        dvs_pnic_spec = vim.dvs.HostMember.PnicSpec(
            pnicDevice=vmnic_name, uplinkPortgroupKey=uplink_portgroup.key
        )
        pnic_backing = vim.dvs.HostMember.PnicBacking(pnicSpec=[dvs_pnic_spec])
        dvs_hostmember_config_spec = vim.dvs.HostMember.ConfigSpec(
            host=host_ref,
            operation="add",
        )
        dvs_config = vim.DVSConfigSpec(
            configVersion=dvs.config.configVersion, host=[dvs_hostmember_config_spec]
        )
        task = dvs.ReconfigureDvs_Task(spec=dvs_config)
        try:
            salt.utils.vmware.wait_for_task(
                task, host_name, "Adding host to the DVS", sleep_seconds=3
            )
        except Exception as e:  # pylint: disable=broad-except
            if hasattr(e, "message") and hasattr(e.message, "msg"):
                if not (
                    host_name in e.message.msg and "already exists" in e.message.msg
                ):
                    ret["success"] = False
                    ret[host_name].update({"message": e.message.msg})
                    continue
            else:
                raise

        network_system = host_ref.configManager.networkSystem

        source_portgroup = None
        for pg in host_ref.config.network.portgroup:
            if pg.spec.name == v_nic[0].portgroup:
                source_portgroup = pg
                break

        if not source_portgroup:
            ret[host_name].update({"message": "No matching portgroup on the vSwitch"})
            ret["success"] = False
            continue

        virtual_nic_config = vim.HostVirtualNicConfig(
            changeOperation="edit",
            device=v_nic[0].device,
            portgroup=source_portgroup.spec.name,
            spec=vim.HostVirtualNicSpec(
                distributedVirtualPort=vim.DistributedVirtualSwitchPortConnection(
                    portgroupKey=target_portgroup.key,
                    switchUuid=target_portgroup.config.distributedVirtualSwitch.uuid,
                )
            ),
        )
        current_vswitch_ports = host_ref.config.network.vswitch[0].numPorts
        vswitch_config = vim.HostVirtualSwitchConfig(
            changeOperation="edit",
            name="vSwitch0",
            spec=vim.HostVirtualSwitchSpec(numPorts=current_vswitch_ports),
        )
        proxyswitch_config = vim.HostProxySwitchConfig(
            changeOperation="edit",
            uuid=dvs_uuid,
            spec=vim.HostProxySwitchSpec(backing=pnic_backing),
        )
        host_network_config = vim.HostNetworkConfig(
            vswitch=[vswitch_config],
            proxySwitch=[proxyswitch_config],
            portgroup=[
                vim.HostPortGroupConfig(
                    changeOperation="remove", spec=source_portgroup.spec
                )
            ],
            vnic=[virtual_nic_config],
        )

        try:
            network_system.UpdateNetworkConfig(
                changeMode="modify", config=host_network_config
            )
            ret[host_name].update({"status": True})
        except Exception as e:  # pylint: disable=broad-except
            if hasattr(e, "msg"):
                ret[host_name].update(
                    {"message": f"Failed to migrate adapters ({e.msg})"}
                )
                continue
            else:
                raise

    return ret


@depends(HAS_PYVMOMI)
@_supports_proxies("esxi", "esxcluster", "esxdatacenter", "vcenter")
def _get_proxy_target(service_instance):
    """
    Returns the target object of a proxy.

    If the object doesn't exist a VMwareObjectRetrievalError is raised

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter/ESXi host.
    """
    proxy_type = get_proxy_type()
    if not salt.utils.vmware.is_connection_to_a_vcenter(service_instance):
        raise CommandExecutionError(
            "'_get_proxy_target' not supported when connected via the ESXi host"
        )
    reference = None
    if proxy_type == "esxcluster":
        (
            host,
            username,
            password,
            protocol,
            port,
            mechanism,
            principal,
            domain,
            datacenter,
            cluster,
        ) = _get_esxcluster_proxy_details()

        dc_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
        reference = salt.utils.vmware.get_cluster(dc_ref, cluster)
    elif proxy_type == "esxdatacenter":
        # esxdatacenter proxy
        (
            host,
            username,
            password,
            protocol,
            port,
            mechanism,
            principal,
            domain,
            datacenter,
        ) = _get_esxdatacenter_proxy_details()

        reference = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    elif proxy_type == "vcenter":
        # vcenter proxy - the target is the root folder
        reference = salt.utils.vmware.get_root_folder(service_instance)
    elif proxy_type == "esxi":
        # esxi proxy
        details = __proxy__["esxi.get_details"]()
        if "vcenter" not in details:
            raise InvalidEntityError(
                "Proxies connected directly to ESXi hosts are not supported"
            )
        references = salt.utils.vmware.get_hosts(
            service_instance, host_names=details["esxi_host"]
        )
        if not references:
            raise VMwareObjectRetrievalError(
                "ESXi host '{}' was not found".format(details["esxi_host"])
            )
        reference = references[0]
    log.trace("reference = %s", reference)
    return reference


def _get_esxdatacenter_proxy_details():
    """
    Returns the running esxdatacenter's proxy details
    """
    det = __salt__["esxdatacenter.get_details"]()
    return (
        det.get("vcenter"),
        det.get("username"),
        det.get("password"),
        det.get("protocol"),
        det.get("port"),
        det.get("mechanism"),
        det.get("principal"),
        det.get("domain"),
        det.get("datacenter"),
    )


def _get_esxcluster_proxy_details():
    """
    Returns the running esxcluster's proxy details
    """
    det = __salt__["esxcluster.get_details"]()
    return (
        det.get("vcenter"),
        det.get("username"),
        det.get("password"),
        det.get("protocol"),
        det.get("port"),
        det.get("mechanism"),
        det.get("principal"),
        det.get("domain"),
        det.get("datacenter"),
        det.get("cluster"),
    )


def _get_esxi_proxy_details():
    """
    Returns the running esxi's proxy details
    """
    det = __proxy__["esxi.get_details"]()
    host = det.get("host")
    if det.get("vcenter"):
        host = det["vcenter"]
    esxi_hosts = None
    if det.get("esxi_host"):
        esxi_hosts = [det["esxi_host"]]
    return (
        host,
        det.get("username"),
        det.get("password"),
        det.get("protocol"),
        det.get("port"),
        det.get("mechanism"),
        det.get("principal"),
        det.get("domain"),
        esxi_hosts,
    )


@depends(HAS_PYVMOMI)
@_gets_service_instance_via_proxy
@_deprecation_message
def get_vm(
    name,
    datacenter=None,
    vm_properties=None,
    traversal_spec=None,
    parent_ref=None,
    service_instance=None,
):
    """
    Returns vm object properties.

    name
        Name of the virtual machine.

    datacenter
        Datacenter name

    vm_properties
        List of vm properties.

    traversal_spec
        Traversal Spec object(s) for searching.

    parent_ref
        Container Reference object for searching under a given object.

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.
    """
    virtual_machine = salt.utils.vmware.get_vm_by_property(
        service_instance,
        name,
        datacenter=datacenter,
        vm_properties=vm_properties,
        traversal_spec=traversal_spec,
        parent_ref=parent_ref,
    )
    return virtual_machine


@depends(HAS_PYVMOMI)
@_gets_service_instance_via_proxy
@_deprecation_message
def get_vm_config_file(name, datacenter, placement, datastore, service_instance=None):
    """
    Queries the virtual machine config file and returns
    vim.host.DatastoreBrowser.SearchResults object on success None on failure

    name
        Name of the virtual machine

    datacenter
        Datacenter name

    datastore
        Datastore where the virtual machine files are stored

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.
    """

    browser_spec = vim.host.DatastoreBrowser.SearchSpec()
    directory = name
    browser_spec.query = [vim.host.DatastoreBrowser.VmConfigQuery()]
    datacenter_object = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    if "cluster" in placement:
        container_object = salt.utils.vmware.get_cluster(
            datacenter_object, placement["cluster"]
        )
    else:
        container_objects = salt.utils.vmware.get_hosts(
            service_instance, datacenter_name=datacenter, host_names=[placement["host"]]
        )
        if not container_objects:
            raise salt.exceptions.VMwareObjectRetrievalError(
                "ESXi host named '{}' wasn't found.".format(placement["host"])
            )
        container_object = container_objects[0]

    # list of vim.host.DatastoreBrowser.SearchResults objects
    files = salt.utils.vmware.get_datastore_files(
        service_instance, directory, [datastore], container_object, browser_spec
    )
    if files and len(files[0].file) > 1:
        raise salt.exceptions.VMwareMultipleObjectsError(
            "Multiple configuration files found in the same virtual machine folder"
        )
    elif files and files[0].file:
        return files[0]
    else:
        return None


def _apply_hardware_version(hardware_version, config_spec, operation="add"):
    """
    Specifies vm container version or schedules upgrade,
    returns True on change and False if nothing have been changed.

    hardware_version
        Hardware version string eg. vmx-08

    config_spec
        Configuration spec object

    operation
        Defines the operation which should be used,
        the possibles values: 'add' and 'edit', the default value is 'add'
    """
    log.trace(
        "Configuring virtual machine hardware version version=%s", hardware_version
    )
    if operation == "edit":
        log.trace("Scheduling hardware version upgrade to %s", hardware_version)
        scheduled_hardware_upgrade = vim.vm.ScheduledHardwareUpgradeInfo()
        scheduled_hardware_upgrade.upgradePolicy = "always"
        scheduled_hardware_upgrade.versionKey = hardware_version
        config_spec.scheduledHardwareUpgradeInfo = scheduled_hardware_upgrade
    elif operation == "add":
        config_spec.version = str(hardware_version)


def _apply_cpu_config(config_spec, cpu_props):
    """
    Sets CPU core count to the given value

    config_spec
        vm.ConfigSpec object

    cpu_props
        CPU properties dict
    """
    log.trace("Configuring virtual machine CPU settings cpu_props=%s", cpu_props)
    if "count" in cpu_props:
        config_spec.numCPUs = int(cpu_props["count"])
    if "cores_per_socket" in cpu_props:
        config_spec.numCoresPerSocket = int(cpu_props["cores_per_socket"])
    if "nested" in cpu_props and cpu_props["nested"]:
        config_spec.nestedHVEnabled = cpu_props["nested"]  # True
    if "hotadd" in cpu_props and cpu_props["hotadd"]:
        config_spec.cpuHotAddEnabled = cpu_props["hotadd"]  # True
    if "hotremove" in cpu_props and cpu_props["hotremove"]:
        config_spec.cpuHotRemoveEnabled = cpu_props["hotremove"]  # True


def _apply_memory_config(config_spec, memory):
    """
    Sets memory size to the given value

    config_spec
        vm.ConfigSpec object

    memory
        Memory size and unit
    """
    log.trace("Configuring virtual machine memory settings memory=%s", memory)
    if "size" in memory and "unit" in memory:
        try:
            if memory["unit"].lower() == "kb":
                memory_mb = memory["size"] / 1024
            elif memory["unit"].lower() == "mb":
                memory_mb = memory["size"]
            elif memory["unit"].lower() == "gb":
                memory_mb = int(float(memory["size"]) * 1024)
        except (TypeError, ValueError):
            memory_mb = int(memory["size"])
        config_spec.memoryMB = memory_mb
    if "reservation_max" in memory:
        config_spec.memoryReservationLockedToMax = memory["reservation_max"]
    if "hotadd" in memory:
        config_spec.memoryHotAddEnabled = memory["hotadd"]


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def get_advanced_configs(vm_name, datacenter, service_instance=None):
    """
    Returns extra config parameters from a virtual machine advanced config list

    vm_name
        Virtual machine name

    datacenter
        Datacenter name where the virtual machine is available

    service_instance
        vCenter service instance for connection and configuration
    """
    current_config = get_vm_config(
        vm_name, datacenter=datacenter, objects=True, service_instance=service_instance
    )
    return current_config["advanced_configs"]


def _apply_advanced_config(config_spec, advanced_config, vm_extra_config=None):
    """
    Sets configuration parameters for the vm

    config_spec
        vm.ConfigSpec object

    advanced_config
        config key value pairs

    vm_extra_config
        Virtual machine vm_ref.config.extraConfig object
    """
    log.trace("Configuring advanced configuration parameters %s", advanced_config)
    if isinstance(advanced_config, str):
        raise salt.exceptions.ArgumentValueError(
            "The specified 'advanced_configs' configuration "
            "option cannot be parsed, please check the parameters"
        )
    for key, value in advanced_config.items():
        if vm_extra_config:
            for option in vm_extra_config:
                if option.key == key and option.value == str(value):
                    continue
        else:
            option = vim.option.OptionValue(key=key, value=value)
            config_spec.extraConfig.append(option)


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def set_advanced_configs(vm_name, datacenter, advanced_configs, service_instance=None):
    """
    Appends extra config parameters to a virtual machine advanced config list

    vm_name
        Virtual machine name

    datacenter
        Datacenter name where the virtual machine is available

    advanced_configs
        Dictionary with advanced parameter key value pairs

    service_instance
        vCenter service instance for connection and configuration
    """
    current_config = get_vm_config(
        vm_name, datacenter=datacenter, objects=True, service_instance=service_instance
    )
    diffs = compare_vm_configs(
        {"name": vm_name, "advanced_configs": advanced_configs}, current_config
    )
    datacenter_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    vm_ref = salt.utils.vmware.get_mor_by_property(
        service_instance,
        vim.VirtualMachine,
        vm_name,
        property_name="name",
        container_ref=datacenter_ref,
    )
    config_spec = vim.vm.ConfigSpec()
    changes = diffs["advanced_configs"].diffs
    _apply_advanced_config(
        config_spec, diffs["advanced_configs"].new_values, vm_ref.config.extraConfig
    )
    if changes:
        salt.utils.vmware.update_vm(vm_ref, config_spec)
    return {"advanced_config_changes": changes}


def _delete_advanced_config(config_spec, advanced_config, vm_extra_config):
    """
    Removes configuration parameters for the vm

    config_spec
        vm.ConfigSpec object

    advanced_config
        List of advanced config keys to be deleted

    vm_extra_config
        Virtual machine vm_ref.config.extraConfig object
    """
    log.trace("Removing advanced configuration parameters %s", advanced_config)
    if isinstance(advanced_config, str):
        raise salt.exceptions.ArgumentValueError(
            "The specified 'advanced_configs' configuration "
            "option cannot be parsed, please check the parameters"
        )
    removed_configs = []
    for key in advanced_config:
        for option in vm_extra_config:
            if option.key == key:
                option = vim.option.OptionValue(key=key, value="")
                config_spec.extraConfig.append(option)
                removed_configs.append(key)
    return removed_configs


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def delete_advanced_configs(
    vm_name, datacenter, advanced_configs, service_instance=None
):
    """
    Removes extra config parameters from a virtual machine

    vm_name
        Virtual machine name

    datacenter
        Datacenter name where the virtual machine is available

    advanced_configs
        List of advanced config values to be removed

    service_instance
        vCenter service instance for connection and configuration
    """
    datacenter_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    vm_ref = salt.utils.vmware.get_mor_by_property(
        service_instance,
        vim.VirtualMachine,
        vm_name,
        property_name="name",
        container_ref=datacenter_ref,
    )
    config_spec = vim.vm.ConfigSpec()
    removed_configs = _delete_advanced_config(
        config_spec, advanced_configs, vm_ref.config.extraConfig
    )
    if removed_configs:
        salt.utils.vmware.update_vm(vm_ref, config_spec)
    return {"removed_configs": removed_configs}


def _get_scsi_controller_key(bus_number, scsi_ctrls):
    """
    Returns key number of the SCSI controller keys

    bus_number
        Controller bus number from the adapter

    scsi_ctrls
        List of SCSI Controller objects (old+newly created)
    """
    # list of new/old VirtualSCSIController objects, both new and old objects
    # should contain a key attribute key should be a negative integer in case
    # of a new object
    keys = [
        ctrl.key for ctrl in scsi_ctrls if scsi_ctrls and ctrl.busNumber == bus_number
    ]
    if not keys:
        raise salt.exceptions.VMwareVmCreationError(
            f"SCSI controller number {bus_number} doesn't exist"
        )
    return keys[0]


def _apply_hard_disk(
    unit_number,
    key,
    operation,
    disk_label=None,
    size=None,
    unit="GB",
    controller_key=None,
    thin_provision=None,
    eagerly_scrub=None,
    datastore=None,
    filename=None,
):
    """
    Returns a vim.vm.device.VirtualDeviceSpec object specifying to add/edit
    a virtual disk device

    unit_number
        Add network adapter to this address

    key
        Device key number

    operation
        Action which should be done on the device add or edit

    disk_label
        Label of the new disk, can be overridden

    size
        Size of the disk

    unit
        Unit of the size, can be GB, MB, KB

    controller_key
        Unique umber of the controller key

    thin_provision
        Boolean for thin provision

    eagerly_scrub
        Boolean for eagerly scrubbing

    datastore
        Datastore name where the disk will be located

    filename
        Full file name of the vm disk
    """
    log.trace(
        "Configuring hard disk %s size=%s, unit=%s, controller_key=%s, "
        "thin_provision=%s, eagerly_scrub=%s, datastore=%s, filename=%s",
        disk_label,
        size,
        unit,
        controller_key,
        thin_provision,
        eagerly_scrub,
        datastore,
        filename,
    )
    disk_spec = vim.vm.device.VirtualDeviceSpec()
    disk_spec.device = vim.vm.device.VirtualDisk()
    disk_spec.device.key = key
    disk_spec.device.unitNumber = unit_number
    disk_spec.device.deviceInfo = vim.Description()
    if size:
        convert_size = salt.utils.vmware.convert_to_kb(unit, size)
        disk_spec.device.capacityInKB = convert_size["size"]
    if disk_label:
        disk_spec.device.deviceInfo.label = disk_label
    if thin_provision is not None or eagerly_scrub is not None:
        disk_spec.device.backing = vim.vm.device.VirtualDisk.FlatVer2BackingInfo()
        disk_spec.device.backing.diskMode = "persistent"
    if thin_provision is not None:
        disk_spec.device.backing.thinProvisioned = thin_provision
    if eagerly_scrub is not None and eagerly_scrub != "None":
        disk_spec.device.backing.eagerlyScrub = eagerly_scrub
    if controller_key:
        disk_spec.device.controllerKey = controller_key
    if operation == "add":
        disk_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
        disk_spec.device.backing.fileName = "[{}] {}".format(
            salt.utils.vmware.get_managed_object_name(datastore), filename
        )
        disk_spec.fileOperation = vim.vm.device.VirtualDeviceSpec.FileOperation.create
    elif operation == "edit":
        disk_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    return disk_spec


def _create_adapter_type(network_adapter, adapter_type, network_adapter_label=""):
    """
    Returns a vim.vm.device.VirtualEthernetCard object specifying a virtual
    ethernet card information

    network_adapter
        None or VirtualEthernet object

    adapter_type
        String, type of adapter

    network_adapter_label
        string, network adapter name
    """
    log.trace(
        "Configuring virtual machine network adapter adapter_type=%s", adapter_type
    )
    if adapter_type in ["vmxnet", "vmxnet2", "vmxnet3", "e1000", "e1000e"]:
        edited_network_adapter = salt.utils.vmware.get_network_adapter_type(
            adapter_type
        )
        if isinstance(network_adapter, type(edited_network_adapter)):
            edited_network_adapter = network_adapter
        else:
            if network_adapter:
                log.trace(
                    "Changing type of '%s' from '%s' to '%s'",
                    network_adapter.deviceInfo.label,
                    type(network_adapter).__name__.rsplit(".", 1)[1][7:].lower(),
                    adapter_type,
                )
    else:
        # If device is edited and type not specified or does not match,
        # don't change adapter type
        if network_adapter:
            if adapter_type:
                log.error(
                    "Cannot change type of '%s' to '%s'. Not changing type",
                    network_adapter.deviceInfo.label,
                    adapter_type,
                )
            edited_network_adapter = network_adapter
        else:
            if not adapter_type:
                log.trace(
                    "The type of '%s' has not been specified. "
                    "Creating of default type 'vmxnet3'",
                    network_adapter_label,
                )
            edited_network_adapter = vim.vm.device.VirtualVmxnet3()
    return edited_network_adapter


def _create_network_backing(network_name, switch_type, parent_ref):
    """
    Returns a vim.vm.device.VirtualDevice.BackingInfo object specifying a
    virtual ethernet card backing information

    network_name
        string, network name

    switch_type
        string, type of switch

    parent_ref
        Parent reference to search for network
    """
    log.trace(
        "Configuring virtual machine network backing network_name=%s "
        "switch_type=%s parent=%s",
        network_name,
        switch_type,
        salt.utils.vmware.get_managed_object_name(parent_ref),
    )
    backing = {}
    if network_name:
        if switch_type == "standard":
            networks = salt.utils.vmware.get_networks(
                parent_ref, network_names=[network_name]
            )
            if not networks:
                raise salt.exceptions.VMwareObjectRetrievalError(
                    f"The network '{network_name}' could not be retrieved."
                )
            network_ref = networks[0]
            backing = vim.vm.device.VirtualEthernetCard.NetworkBackingInfo()
            backing.deviceName = network_name
            backing.network = network_ref
        elif switch_type == "distributed":
            networks = salt.utils.vmware.get_dvportgroups(
                parent_ref, portgroup_names=[network_name]
            )
            if not networks:
                raise salt.exceptions.VMwareObjectRetrievalError(
                    f"The port group '{network_name}' could not be retrieved."
                )
            network_ref = networks[0]
            dvs_port_connection = vim.dvs.PortConnection(
                portgroupKey=network_ref.key,
                switchUuid=network_ref.config.distributedVirtualSwitch.uuid,
            )
            backing = (
                vim.vm.device.VirtualEthernetCard.DistributedVirtualPortBackingInfo()
            )
            backing.port = dvs_port_connection
    return backing


def _apply_network_adapter_config(
    key,
    network_name,
    adapter_type,
    switch_type,
    network_adapter_label=None,
    operation="add",
    connectable=None,
    mac=None,
    parent=None,
):
    """
    Returns a vim.vm.device.VirtualDeviceSpec object specifying to add/edit a
    network device

    network_adapter_label
        Network adapter label

    key
        Unique key for device creation

    network_name
        Network or port group name

    adapter_type
        Type of the adapter eg. vmxnet3

    switch_type
        Type of the switch: standard or distributed

    operation
        Type of operation: add or edit

    connectable
        Dictionary with the device connection properties

    mac
        MAC address of the network adapter

    parent
        Parent object reference
    """
    adapter_type.strip().lower()
    switch_type.strip().lower()
    log.trace(
        "Configuring virtual machine network adapter network_adapter_label=%s "
        "network_name=%s adapter_type=%s switch_type=%s mac=%s",
        network_adapter_label,
        network_name,
        adapter_type,
        switch_type,
        mac,
    )
    network_spec = vim.vm.device.VirtualDeviceSpec()
    network_spec.device = _create_adapter_type(
        network_spec.device, adapter_type, network_adapter_label=network_adapter_label
    )
    network_spec.device.deviceInfo = vim.Description()
    if operation == "add":
        network_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
    elif operation == "edit":
        network_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    if switch_type and network_name:
        network_spec.device.backing = _create_network_backing(
            network_name, switch_type, parent
        )
        network_spec.device.deviceInfo.summary = network_name
    if key:
        # random negative integer for creations, concrete device key
        # for updates
        network_spec.device.key = key
    if network_adapter_label:
        network_spec.device.deviceInfo.label = network_adapter_label
    if mac:
        network_spec.device.macAddress = mac
        network_spec.device.addressType = "Manual"
    network_spec.device.wakeOnLanEnabled = True
    if connectable:
        network_spec.device.connectable = vim.vm.device.VirtualDevice.ConnectInfo()
        network_spec.device.connectable.startConnected = connectable["start_connected"]
        network_spec.device.connectable.allowGuestControl = connectable[
            "allow_guest_control"
        ]
    return network_spec


def _apply_scsi_controller(
    adapter, adapter_type, bus_sharing, key, bus_number, operation
):
    """
    Returns a vim.vm.device.VirtualDeviceSpec object specifying to
    add/edit a SCSI controller

    adapter
        SCSI controller adapter name

    adapter_type
        SCSI controller adapter type eg. paravirtual

    bus_sharing
         SCSI controller bus sharing eg. virtual_sharing

    key
        SCSI controller unique key

    bus_number
        Device bus number property

    operation
        Describes the operation which should be done on the object,
        the possibles values: 'add' and 'edit', the default value is 'add'

    .. code-block:: bash

        scsi:
          adapter: 'SCSI controller 0'
          type: paravirtual or lsilogic or lsilogic_sas
          bus_sharing: 'no_sharing' or 'virtual_sharing' or 'physical_sharing'
    """
    log.trace(
        "Configuring scsi controller adapter=%s adapter_type=%s "
        "bus_sharing=%s key=%s bus_number=%s",
        adapter,
        adapter_type,
        bus_sharing,
        key,
        bus_number,
    )
    scsi_spec = vim.vm.device.VirtualDeviceSpec()
    if adapter_type == "lsilogic":
        summary = "LSI Logic"
        scsi_spec.device = vim.vm.device.VirtualLsiLogicController()
    elif adapter_type == "lsilogic_sas":
        summary = "LSI Logic Sas"
        scsi_spec.device = vim.vm.device.VirtualLsiLogicSASController()
    elif adapter_type == "paravirtual":
        summary = "VMware paravirtual SCSI"
        scsi_spec.device = vim.vm.device.ParaVirtualSCSIController()
    elif adapter_type == "buslogic":
        summary = "Bus Logic"
        scsi_spec.device = vim.vm.device.VirtualBusLogicController()
    if operation == "add":
        scsi_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
    elif operation == "edit":
        scsi_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    scsi_spec.device.key = key
    scsi_spec.device.busNumber = bus_number
    scsi_spec.device.deviceInfo = vim.Description()
    scsi_spec.device.deviceInfo.label = adapter
    scsi_spec.device.deviceInfo.summary = summary
    if bus_sharing == "virtual_sharing":
        # Virtual disks can be shared between virtual machines on
        # the same server
        scsi_spec.device.sharedBus = (
            vim.vm.device.VirtualSCSIController.Sharing.virtualSharing
        )
    elif bus_sharing == "physical_sharing":
        # Virtual disks can be shared between virtual machines on any server
        scsi_spec.device.sharedBus = (
            vim.vm.device.VirtualSCSIController.Sharing.physicalSharing
        )
    elif bus_sharing == "no_sharing":
        # Virtual disks cannot be shared between virtual machines
        scsi_spec.device.sharedBus = (
            vim.vm.device.VirtualSCSIController.Sharing.noSharing
        )
    return scsi_spec


def _create_ide_controllers(ide_controllers):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec objects representing
    IDE controllers

    ide_controllers
        IDE properties
    """
    ide_ctrls = []
    keys = range(-200, -250, -1)
    if ide_controllers:
        devs = [ide["adapter"] for ide in ide_controllers]
        log.trace("Creating IDE controllers %s", devs)
        for ide, key in zip(ide_controllers, keys):
            ide_ctrls.append(
                _apply_ide_controller_config(ide["adapter"], "add", key, abs(key + 200))
            )
    return ide_ctrls


def _apply_ide_controller_config(ide_controller_label, operation, key, bus_number=0):
    """
    Returns a vim.vm.device.VirtualDeviceSpec object specifying to add/edit an
    IDE controller

    ide_controller_label
        Controller label of the IDE adapter

    operation
        Type of operation: add or edit

    key
        Unique key of the device

    bus_number
        Device bus number property
    """
    log.trace(
        "Configuring IDE controller ide_controller_label=%s", ide_controller_label
    )
    ide_spec = vim.vm.device.VirtualDeviceSpec()
    ide_spec.device = vim.vm.device.VirtualIDEController()
    if operation == "add":
        ide_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
    if operation == "edit":
        ide_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    ide_spec.device.key = key
    ide_spec.device.busNumber = bus_number
    if ide_controller_label:
        ide_spec.device.deviceInfo = vim.Description()
        ide_spec.device.deviceInfo.label = ide_controller_label
        ide_spec.device.deviceInfo.summary = ide_controller_label
    return ide_spec


def _create_sata_controllers(sata_controllers):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec objects representing
    SATA controllers

    sata_controllers
        SATA properties
    """
    sata_ctrls = []
    keys = range(-15000, -15050, -1)
    if sata_controllers:
        devs = [sata["adapter"] for sata in sata_controllers]
        log.trace("Creating SATA controllers %s", devs)
        for sata, key in zip(sata_controllers, keys):
            sata_ctrls.append(
                _apply_sata_controller_config(
                    sata["adapter"], "add", key, sata["bus_number"]
                )
            )
    return sata_ctrls


def _apply_sata_controller_config(sata_controller_label, operation, key, bus_number=0):
    """
    Returns a vim.vm.device.VirtualDeviceSpec object specifying to add/edit a
    SATA controller

    sata_controller_label
        Controller label of the SATA adapter

    operation
        Type of operation: add or edit

    key
        Unique key of the device

    bus_number
        Device bus number property
    """
    log.trace(
        "Configuring SATA controller sata_controller_label=%s", sata_controller_label
    )
    sata_spec = vim.vm.device.VirtualDeviceSpec()
    sata_spec.device = vim.vm.device.VirtualAHCIController()
    if operation == "add":
        sata_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
    elif operation == "edit":
        sata_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    sata_spec.device.key = key
    sata_spec.device.controllerKey = 100
    sata_spec.device.busNumber = bus_number
    if sata_controller_label:
        sata_spec.device.deviceInfo = vim.Description()
        sata_spec.device.deviceInfo.label = sata_controller_label
        sata_spec.device.deviceInfo.summary = sata_controller_label
    return sata_spec


def _apply_cd_drive(
    drive_label,
    key,
    device_type,
    operation,
    client_device=None,
    datastore_iso_file=None,
    connectable=None,
    controller_key=200,
    parent_ref=None,
):
    """
    Returns a vim.vm.device.VirtualDeviceSpec object specifying to add/edit a
    CD/DVD drive

    drive_label
        Leble of the CD/DVD drive

    key
        Unique key of the device

    device_type
        Type of the device: client or iso

    operation
        Type of operation: add or edit

    client_device
        Client device properties

    datastore_iso_file
        ISO properties

    connectable
        Connection info for the device

    controller_key
        Controller unique identifier to which we will attach this device

    parent_ref
        Parent object

    .. code-block:: bash

        cd:
            adapter: "CD/DVD drive 1"
            device_type: datastore_iso_file or client_device
            client_device:
              mode: atapi or passthrough
            datastore_iso_file:
              path: "[share] iso/disk.iso"
            connectable:
              start_connected: True
              allow_guest_control:
    """
    log.trace(
        "Configuring CD/DVD drive drive_label=%s device_type=%s "
        "client_device=%s datastore_iso_file=%s",
        drive_label,
        device_type,
        client_device,
        datastore_iso_file,
    )
    drive_spec = vim.vm.device.VirtualDeviceSpec()
    drive_spec.device = vim.vm.device.VirtualCdrom()
    drive_spec.device.deviceInfo = vim.Description()
    if operation == "add":
        drive_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
    elif operation == "edit":
        drive_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    if device_type == "datastore_iso_file":
        drive_spec.device.backing = vim.vm.device.VirtualCdrom.IsoBackingInfo()
        drive_spec.device.backing.fileName = datastore_iso_file["path"]
        datastore = datastore_iso_file["path"].partition("[")[-1].rpartition("]")[0]
        datastore_object = salt.utils.vmware.get_datastores(
            salt.utils.vmware.get_service_instance_from_managed_object(parent_ref),
            parent_ref,
            datastore_names=[datastore],
        )[0]
        if datastore_object:
            drive_spec.device.backing.datastore = datastore_object
        drive_spec.device.deviceInfo.summary = "{}".format(datastore_iso_file["path"])
    elif device_type == "client_device":
        if client_device["mode"] == "passthrough":
            drive_spec.device.backing = (
                vim.vm.device.VirtualCdrom.RemotePassthroughBackingInfo()
            )
        elif client_device["mode"] == "atapi":
            drive_spec.device.backing = (
                vim.vm.device.VirtualCdrom.RemoteAtapiBackingInfo()
            )
    drive_spec.device.key = key
    drive_spec.device.deviceInfo.label = drive_label
    drive_spec.device.controllerKey = controller_key
    drive_spec.device.connectable = vim.vm.device.VirtualDevice.ConnectInfo()
    if connectable:
        drive_spec.device.connectable.startConnected = connectable["start_connected"]
        drive_spec.device.connectable.allowGuestControl = connectable[
            "allow_guest_control"
        ]
    return drive_spec


def _set_network_adapter_mapping(domain, gateway, ip_addr, subnet_mask, mac):
    """
    Returns a vim.vm.customization.AdapterMapping object containing the IP
    properties of a network adapter card

    domain
        Domain of the host

    gateway
        Gateway address

    ip_addr
        IP address

    subnet_mask
        Subnet mask

    mac
        MAC address of the guest
    """
    adapter_mapping = vim.vm.customization.AdapterMapping()
    adapter_mapping.macAddress = mac
    adapter_mapping.adapter = vim.vm.customization.IPSettings()
    if domain:
        adapter_mapping.adapter.dnsDomain = domain
    if gateway:
        adapter_mapping.adapter.gateway = gateway
    if ip_addr:
        adapter_mapping.adapter.ip = vim.vm.customization.FixedIp(ipAddress=ip_addr)
        adapter_mapping.adapter.subnetMask = subnet_mask
    else:
        adapter_mapping.adapter.ip = vim.vm.customization.DhcpIpGenerator()
    return adapter_mapping


def _apply_serial_port(serial_device_spec, key, operation="add"):
    """
    Returns a vim.vm.device.VirtualSerialPort representing a serial port
    component

    serial_device_spec
        Serial device properties

    key
        Unique key of the device

    operation
        Add or edit the given device

    .. code-block:: bash

        serial_ports:
            adapter: 'Serial port 1'
            backing:
              type: uri
              uri: 'telnet://something:port'
              direction: <client|server>
              filename: 'service_uri'
            connectable:
              allow_guest_control: True
              start_connected: True
            yield: False
    """
    log.trace(
        "Creating serial port adapter=%s type=%s connectable=%s yield=%s",
        serial_device_spec["adapter"],
        serial_device_spec["type"],
        serial_device_spec["connectable"],
        serial_device_spec["yield"],
    )
    device_spec = vim.vm.device.VirtualDeviceSpec()
    device_spec.device = vim.vm.device.VirtualSerialPort()
    if operation == "add":
        device_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
    elif operation == "edit":
        device_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
    connect_info = vim.vm.device.VirtualDevice.ConnectInfo()
    type_backing = None

    if serial_device_spec["type"] == "network":
        type_backing = vim.vm.device.VirtualSerialPort.URIBackingInfo()
        if "uri" not in serial_device_spec["backing"].keys():
            raise ValueError("vSPC proxy URI not specified in config")
        if "uri" not in serial_device_spec["backing"].keys():
            raise ValueError("vSPC Direction not specified in config")
        if "filename" not in serial_device_spec["backing"].keys():
            raise ValueError("vSPC Filename not specified in config")
        type_backing.proxyURI = serial_device_spec["backing"]["uri"]
        type_backing.direction = serial_device_spec["backing"]["direction"]
        type_backing.serviceURI = serial_device_spec["backing"]["filename"]
    if serial_device_spec["type"] == "pipe":
        type_backing = vim.vm.device.VirtualSerialPort.PipeBackingInfo()
    if serial_device_spec["type"] == "file":
        type_backing = vim.vm.device.VirtualSerialPort.FileBackingInfo()
    if serial_device_spec["type"] == "device":
        type_backing = vim.vm.device.VirtualSerialPort.DeviceBackingInfo()
    connect_info.allowGuestControl = serial_device_spec["connectable"][
        "allow_guest_control"
    ]
    connect_info.startConnected = serial_device_spec["connectable"]["start_connected"]
    device_spec.device.backing = type_backing
    device_spec.device.connectable = connect_info
    device_spec.device.unitNumber = 1
    device_spec.device.key = key
    device_spec.device.yieldOnPoll = serial_device_spec["yield"]

    return device_spec


def _create_disks(service_instance, disks, scsi_controllers=None, parent=None):
    """
    Returns a list of disk specs representing the disks to be created for a
    virtual machine

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    disks
        List of disks with properties

    scsi_controllers
        List of SCSI controllers

    parent
        Parent object reference

    .. code-block:: bash

        disk:
          adapter: 'Hard disk 1'
          size: 16
          unit: GB
          address: '0:0'
          controller: 'SCSI controller 0'
          thin_provision: False
          eagerly_scrub: False
          datastore: 'myshare'
          filename: 'vm/mydisk.vmdk'
    """
    disk_specs = []
    keys = range(-2000, -2050, -1)
    if disks:
        devs = [disk["adapter"] for disk in disks]
        log.trace("Creating disks %s", devs)
    for disk, key in zip(disks, keys):
        # create the disk
        filename, datastore, datastore_ref = None, None, None
        size = float(disk["size"])
        # when creating both SCSI controller and Hard disk at the same time
        # we need the randomly assigned (temporary) key of the newly created
        # SCSI controller
        controller_key = 1000  # Default is the first SCSI controller
        if "address" in disk:  # 0:0
            controller_bus_number, unit_number = disk["address"].split(":")
            controller_bus_number = int(controller_bus_number)
            unit_number = int(unit_number)
            controller_key = _get_scsi_controller_key(
                controller_bus_number, scsi_ctrls=scsi_controllers
            )
        elif "controller" in disk:
            for contr in scsi_controllers:
                if contr["label"] == disk["controller"]:
                    controller_key = contr["key"]
                    break
            else:
                raise salt.exceptions.VMwareObjectNotFoundError(
                    "The given controller does not exist: {}".format(disk["controller"])
                )
        if "datastore" in disk:
            datastore_ref = salt.utils.vmware.get_datastores(
                service_instance, parent, datastore_names=[disk["datastore"]]
            )[0]
            datastore = disk["datastore"]
        if "filename" in disk:
            filename = disk["filename"]
        # XOR filename, datastore
        if (not filename and datastore) or (filename and not datastore):
            raise salt.exceptions.ArgumentValueError(
                "You must specify both filename and datastore attributes"
                " to place your disk to a specific datastore "
                "{}, {}".format(datastore, filename)
            )
        disk_spec = _apply_hard_disk(
            unit_number,
            key,
            disk_label=disk["adapter"],
            size=size,
            unit=disk["unit"],
            controller_key=controller_key,
            operation="add",
            thin_provision=disk["thin_provision"],
            eagerly_scrub=disk["eagerly_scrub"] if "eagerly_scrub" in disk else None,
            datastore=datastore_ref,
            filename=filename,
        )
        disk_specs.append(disk_spec)
        unit_number += 1
    return disk_specs


def _create_scsi_devices(scsi_devices):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec objects representing
    SCSI controllers

    scsi_devices:
        List of SCSI device properties
    """
    keys = range(-1000, -1050, -1)
    scsi_specs = []
    if scsi_devices:
        devs = [scsi["adapter"] for scsi in scsi_devices]
        log.trace("Creating SCSI devices %s", devs)
        # unitNumber for disk attachment, 0:0 1st 0 is the controller busNumber,
        # 2nd is the unitNumber
        for key, scsi_controller in zip(keys, scsi_devices):
            # create the SCSI controller
            scsi_spec = _apply_scsi_controller(
                scsi_controller["adapter"],
                scsi_controller["type"],
                scsi_controller["bus_sharing"],
                key,
                scsi_controller["bus_number"],
                "add",
            )
            scsi_specs.append(scsi_spec)
    return scsi_specs


def _create_network_adapters(network_interfaces, parent=None):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec objects representing
    the interfaces to be created for a virtual machine

    network_interfaces
        List of network interfaces and properties

    parent
        Parent object reference

    .. code-block:: bash

        interfaces:
          adapter: 'Network adapter 1'
          name: vlan100
          switch_type: distributed or standard
          adapter_type: vmxnet3 or vmxnet, vmxnet2, vmxnet3, e1000, e1000e
          mac: '00:11:22:33:44:55'
    """
    network_specs = []
    nics_settings = []
    keys = range(-4000, -4050, -1)
    if network_interfaces:
        devs = [inter["adapter"] for inter in network_interfaces]
        log.trace("Creating network interfaces %s", devs)
        for interface, key in zip(network_interfaces, keys):
            network_spec = _apply_network_adapter_config(
                key,
                interface["name"],
                interface["adapter_type"],
                interface["switch_type"],
                network_adapter_label=interface["adapter"],
                operation="add",
                connectable=(
                    interface["connectable"] if "connectable" in interface else None
                ),
                mac=interface["mac"],
                parent=parent,
            )
            network_specs.append(network_spec)
            if "mapping" in interface:
                adapter_mapping = _set_network_adapter_mapping(
                    interface["mapping"]["domain"],
                    interface["mapping"]["gateway"],
                    interface["mapping"]["ip_addr"],
                    interface["mapping"]["subnet_mask"],
                    interface["mac"],
                )
                nics_settings.append(adapter_mapping)
    return (network_specs, nics_settings)


def _create_serial_ports(serial_ports):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec objects representing the
    serial ports to be created for a virtual machine

    serial_ports
        Serial port properties
    """
    ports = []
    keys = range(-9000, -9050, -1)
    if serial_ports:
        devs = [serial["adapter"] for serial in serial_ports]
        log.trace("Creating serial ports %s", devs)
        for port, key in zip(serial_ports, keys):
            serial_port_device = _apply_serial_port(port, key, "add")
            ports.append(serial_port_device)
    return ports


def _create_cd_drives(cd_drives, controllers=None, parent_ref=None):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec objects representing the
    CD/DVD drives to be created for a virtual machine

    cd_drives
        CD/DVD drive properties

    controllers
        CD/DVD drive controllers (IDE, SATA)

    parent_ref
        Parent object reference
    """
    cd_drive_specs = []
    keys = range(-3000, -3050, -1)
    if cd_drives:
        devs = [dvd["adapter"] for dvd in cd_drives]
        log.trace("Creating cd/dvd drives %s", devs)
        for drive, key in zip(cd_drives, keys):
            # if a controller is not available/cannot be created we should use the
            #  one which is available by default, this is 'IDE 0'
            controller_key = 200
            if controllers:
                controller = _get_device_by_label(controllers, drive["controller"])
                controller_key = controller.key
            cd_drive_specs.append(
                _apply_cd_drive(
                    drive["adapter"],
                    key,
                    drive["device_type"],
                    "add",
                    client_device=(
                        drive["client_device"] if "client_device" in drive else None
                    ),
                    datastore_iso_file=(
                        drive["datastore_iso_file"]
                        if "datastore_iso_file" in drive
                        else None
                    ),
                    connectable=(
                        drive["connectable"] if "connectable" in drive else None
                    ),
                    controller_key=controller_key,
                    parent_ref=parent_ref,
                )
            )

    return cd_drive_specs


def _get_device_by_key(devices, key):
    """
    Returns the device with the given key, raises error if the device is
    not found.

    devices
        list of vim.vm.device.VirtualDevice objects

    key
        Unique key of device
    """
    device_keys = [d for d in devices if d.key == key]
    if device_keys:
        return device_keys[0]
    else:
        raise salt.exceptions.VMwareObjectNotFoundError(
            f"Virtual machine device with unique key {key} does not exist"
        )


def _get_device_by_label(devices, label):
    """
    Returns the device with the given label, raises error if the device is
    not found.

    devices
        list of vim.vm.device.VirtualDevice objects

    key
        Unique key of device
    """
    device_labels = [d for d in devices if d.deviceInfo.label == label]
    if device_labels:
        return device_labels[0]
    else:
        raise salt.exceptions.VMwareObjectNotFoundError(
            f"Virtual machine device with label {label} does not exist"
        )


def _convert_units(devices):
    """
    Updates the size and unit dictionary values with the new unit values

    devices
        List of device data objects
    """
    if devices:
        for device in devices:
            if "unit" in device and "size" in device:
                device.update(
                    salt.utils.vmware.convert_to_kb(device["unit"], device["size"])
                )
    else:
        return False
    return True


@_deprecation_message
def compare_vm_configs(new_config, current_config):
    """
    Compares virtual machine current and new configuration, the current is the
    one which is deployed now, and the new is the target config. Returns the
    differences between the objects in a dictionary, the keys are the
    configuration parameter keys and the values are differences objects: either
    list or recursive difference

    new_config:
        New config dictionary with every available parameter

    current_config
        Currently deployed configuration
    """
    diffs = {}
    keys = set(new_config.keys())

    # These values identify the virtual machine, comparison is unnecessary
    keys.discard("name")
    keys.discard("datacenter")
    keys.discard("datastore")
    for property_key in ("version", "image"):
        if property_key in keys:
            single_value_diff = recursive_diff(
                {property_key: current_config[property_key]},
                {property_key: new_config[property_key]},
            )
            if single_value_diff.diffs:
                diffs[property_key] = single_value_diff
            keys.discard(property_key)

    if "cpu" in keys:
        keys.remove("cpu")
        cpu_diff = recursive_diff(current_config["cpu"], new_config["cpu"])
        if cpu_diff.diffs:
            diffs["cpu"] = cpu_diff

    if "memory" in keys:
        keys.remove("memory")
        _convert_units([current_config["memory"]])
        _convert_units([new_config["memory"]])
        memory_diff = recursive_diff(current_config["memory"], new_config["memory"])
        if memory_diff.diffs:
            diffs["memory"] = memory_diff

    if "advanced_configs" in keys:
        keys.remove("advanced_configs")
        key = "advanced_configs"
        advanced_diff = recursive_diff(current_config[key], new_config[key])
        if advanced_diff.diffs:
            diffs[key] = advanced_diff

    if "disks" in keys:
        keys.remove("disks")
        _convert_units(current_config["disks"])
        _convert_units(new_config["disks"])
        disk_diffs = list_diff(current_config["disks"], new_config["disks"], "address")
        # REMOVE UNSUPPORTED DIFFERENCES/CHANGES
        # If the disk already exist, the backing properties like eagerly scrub
        # and thin provisioning
        # cannot be updated, and should not be identified as differences
        disk_diffs.remove_diff(diff_key="eagerly_scrub")
        # Filename updates are not supported yet, on VSAN datastores the
        # backing.fileName points to a uid + the vmdk name
        disk_diffs.remove_diff(diff_key="filename")
        # The adapter name shouldn't be changed
        disk_diffs.remove_diff(diff_key="adapter")
        if disk_diffs.diffs:
            diffs["disks"] = disk_diffs

    if "interfaces" in keys:
        keys.remove("interfaces")
        interface_diffs = list_diff(
            current_config["interfaces"], new_config["interfaces"], "mac"
        )
        # The adapter name shouldn't be changed
        interface_diffs.remove_diff(diff_key="adapter")
        if interface_diffs.diffs:
            diffs["interfaces"] = interface_diffs

    # For general items where the identification can be done by adapter
    for key in keys:
        if key not in current_config or key not in new_config:
            raise ValueError(
                "A general device {} configuration was "
                "not supplied or it was not retrieved from "
                "remote configuration".format(key)
            )
        device_diffs = list_diff(current_config[key], new_config[key], "adapter")
        if device_diffs.diffs:
            diffs[key] = device_diffs

    return diffs


@_gets_service_instance_via_proxy
@_deprecation_message
def get_vm_config(name, datacenter=None, objects=True, service_instance=None):
    """
    Queries and converts the virtual machine properties to the available format
    from the schema. If the objects attribute is True the config objects will
    have extra properties, like 'object' which will include the
    vim.vm.device.VirtualDevice, this is necessary for deletion and update
    actions.

    name
        Name of the virtual machine

    datacenter
        Datacenter's name where the virtual machine is available

    objects
        Indicates whether to return the vmware object properties
        (eg. object, key) or just the properties which can be set

    service_instance
        vCenter service instance for connection and configuration
    """
    properties = [
        "config.hardware.device",
        "config.hardware.numCPU",
        "config.hardware.numCoresPerSocket",
        "config.nestedHVEnabled",
        "config.cpuHotAddEnabled",
        "config.cpuHotRemoveEnabled",
        "config.hardware.memoryMB",
        "config.memoryReservationLockedToMax",
        "config.memoryHotAddEnabled",
        "config.version",
        "config.guestId",
        "config.extraConfig",
        "name",
    ]
    virtual_machine = salt.utils.vmware.get_vm_by_property(
        service_instance, name, vm_properties=properties, datacenter=datacenter
    )
    parent_ref = salt.utils.vmware.get_datacenter(
        service_instance=service_instance, datacenter_name=datacenter
    )
    current_config = {"name": name}
    current_config["cpu"] = {
        "count": virtual_machine["config.hardware.numCPU"],
        "cores_per_socket": virtual_machine["config.hardware.numCoresPerSocket"],
        "nested": virtual_machine["config.nestedHVEnabled"],
        "hotadd": virtual_machine["config.cpuHotAddEnabled"],
        "hotremove": virtual_machine["config.cpuHotRemoveEnabled"],
    }

    current_config["memory"] = {
        "size": virtual_machine["config.hardware.memoryMB"],
        "unit": "MB",
        "reservation_max": virtual_machine["config.memoryReservationLockedToMax"],
        "hotadd": virtual_machine["config.memoryHotAddEnabled"],
    }
    current_config["image"] = virtual_machine["config.guestId"]
    current_config["version"] = virtual_machine["config.version"]
    current_config["advanced_configs"] = {}
    for extra_conf in virtual_machine["config.extraConfig"]:
        try:
            current_config["advanced_configs"][extra_conf.key] = int(extra_conf.value)
        except ValueError:
            current_config["advanced_configs"][extra_conf.key] = extra_conf.value

    current_config["disks"] = []
    current_config["scsi_devices"] = []
    current_config["interfaces"] = []
    current_config["serial_ports"] = []
    current_config["cd_drives"] = []
    current_config["sata_controllers"] = []

    for device in virtual_machine["config.hardware.device"]:
        if isinstance(device, vim.vm.device.VirtualSCSIController):
            controller = {}
            controller["adapter"] = device.deviceInfo.label
            controller["bus_number"] = device.busNumber
            bus_sharing = device.sharedBus
            if bus_sharing == "noSharing":
                controller["bus_sharing"] = "no_sharing"
            elif bus_sharing == "virtualSharing":
                controller["bus_sharing"] = "virtual_sharing"
            elif bus_sharing == "physicalSharing":
                controller["bus_sharing"] = "physical_sharing"
            if isinstance(device, vim.vm.device.ParaVirtualSCSIController):
                controller["type"] = "paravirtual"
            elif isinstance(device, vim.vm.device.VirtualBusLogicController):
                controller["type"] = "buslogic"
            elif isinstance(device, vim.vm.device.VirtualLsiLogicController):
                controller["type"] = "lsilogic"
            elif isinstance(device, vim.vm.device.VirtualLsiLogicSASController):
                controller["type"] = "lsilogic_sas"
            if objects:
                # int list, stores the keys of the disks which are attached
                # to this controller
                controller["device"] = device.device
                controller["key"] = device.key
                controller["object"] = device
            current_config["scsi_devices"].append(controller)
        if isinstance(device, vim.vm.device.VirtualDisk):
            disk = {}
            disk["adapter"] = device.deviceInfo.label
            disk["size"] = device.capacityInKB
            disk["unit"] = "KB"
            controller = _get_device_by_key(
                virtual_machine["config.hardware.device"], device.controllerKey
            )
            disk["controller"] = controller.deviceInfo.label
            disk["address"] = str(controller.busNumber) + ":" + str(device.unitNumber)
            disk["datastore"] = salt.utils.vmware.get_managed_object_name(
                device.backing.datastore
            )
            disk["thin_provision"] = device.backing.thinProvisioned
            disk["eagerly_scrub"] = device.backing.eagerlyScrub
            if objects:
                disk["key"] = device.key
                disk["unit_number"] = device.unitNumber
                disk["bus_number"] = controller.busNumber
                disk["controller_key"] = device.controllerKey
                disk["object"] = device
            current_config["disks"].append(disk)
        if isinstance(device, vim.vm.device.VirtualEthernetCard):
            interface = {}
            interface["adapter"] = device.deviceInfo.label
            interface["adapter_type"] = (
                salt.utils.vmware.get_network_adapter_object_type(device)
            )
            interface["connectable"] = {
                "allow_guest_control": device.connectable.allowGuestControl,
                "connected": device.connectable.connected,
                "start_connected": device.connectable.startConnected,
            }
            interface["mac"] = device.macAddress
            if isinstance(
                device.backing,
                vim.vm.device.VirtualEthernetCard.DistributedVirtualPortBackingInfo,
            ):
                interface["switch_type"] = "distributed"
                pg_key = device.backing.port.portgroupKey
                network_ref = salt.utils.vmware.get_mor_by_property(
                    service_instance,
                    vim.DistributedVirtualPortgroup,
                    pg_key,
                    property_name="key",
                    container_ref=parent_ref,
                )
            elif isinstance(
                device.backing, vim.vm.device.VirtualEthernetCard.NetworkBackingInfo
            ):
                interface["switch_type"] = "standard"
                network_ref = device.backing.network
            interface["name"] = salt.utils.vmware.get_managed_object_name(network_ref)
            if objects:
                interface["key"] = device.key
                interface["object"] = device
            current_config["interfaces"].append(interface)
        if isinstance(device, vim.vm.device.VirtualCdrom):
            drive = {}
            drive["adapter"] = device.deviceInfo.label
            controller = _get_device_by_key(
                virtual_machine["config.hardware.device"], device.controllerKey
            )
            drive["controller"] = controller.deviceInfo.label
            if isinstance(
                device.backing, vim.vm.device.VirtualCdrom.RemotePassthroughBackingInfo
            ):
                drive["device_type"] = "client_device"
                drive["client_device"] = {"mode": "passthrough"}
            if isinstance(
                device.backing, vim.vm.device.VirtualCdrom.RemoteAtapiBackingInfo
            ):
                drive["device_type"] = "client_device"
                drive["client_device"] = {"mode": "atapi"}
            if isinstance(device.backing, vim.vm.device.VirtualCdrom.IsoBackingInfo):
                drive["device_type"] = "datastore_iso_file"
                drive["datastore_iso_file"] = {"path": device.backing.fileName}
            drive["connectable"] = {
                "allow_guest_control": device.connectable.allowGuestControl,
                "connected": device.connectable.connected,
                "start_connected": device.connectable.startConnected,
            }
            if objects:
                drive["key"] = device.key
                drive["controller_key"] = device.controllerKey
                drive["object"] = device
            current_config["cd_drives"].append(drive)
        if isinstance(device, vim.vm.device.VirtualSerialPort):
            port = {}
            port["adapter"] = device.deviceInfo.label
            if isinstance(
                device.backing, vim.vm.device.VirtualSerialPort.URIBackingInfo
            ):
                port["type"] = "network"
                port["backing"] = {
                    "uri": device.backing.proxyURI,
                    "direction": device.backing.direction,
                    "filename": device.backing.serviceURI,
                }
            if isinstance(
                device.backing, vim.vm.device.VirtualSerialPort.PipeBackingInfo
            ):
                port["type"] = "pipe"
            if isinstance(
                device.backing, vim.vm.device.VirtualSerialPort.FileBackingInfo
            ):
                port["type"] = "file"
            if isinstance(
                device.backing, vim.vm.device.VirtualSerialPort.DeviceBackingInfo
            ):
                port["type"] = "device"
            port["yield"] = device.yieldOnPoll
            port["connectable"] = {
                "allow_guest_control": device.connectable.allowGuestControl,
                "connected": device.connectable.connected,
                "start_connected": device.connectable.startConnected,
            }
            if objects:
                port["key"] = device.key
                port["object"] = device
            current_config["serial_ports"].append(port)
        if isinstance(device, vim.vm.device.VirtualSATAController):
            sata = {}
            sata["adapter"] = device.deviceInfo.label
            sata["bus_number"] = device.busNumber
            if objects:
                sata["device"] = device.device  # keys of the connected devices
                sata["key"] = device.key
                sata["object"] = device
            current_config["sata_controllers"].append(sata)

    return current_config


def _update_disks(disks_old_new):
    """
    Changes the disk size and returns the config spec objects in a list.
    The controller property cannot be updated, because controller address
    identifies the disk by the unit and bus number properties.

    disks_diffs
        List of old and new disk properties, the properties are dictionary
        objects
    """
    disk_changes = []
    if disks_old_new:
        devs = [disk["old"]["address"] for disk in disks_old_new]
        log.trace("Updating disks %s", devs)
        for item in disks_old_new:
            current_disk = item["old"]
            next_disk = item["new"]
            difference = recursive_diff(current_disk, next_disk)
            difference.ignore_unset_values = False
            if difference.changed():
                if next_disk["size"] < current_disk["size"]:
                    raise salt.exceptions.VMwareSaltError(
                        "Disk cannot be downsized size={} unit={} "
                        "controller_key={} "
                        "unit_number={}".format(
                            next_disk["size"],
                            next_disk["unit"],
                            current_disk["controller_key"],
                            current_disk["unit_number"],
                        )
                    )
                log.trace(
                    "Virtual machine disk will be updated size=%s unit=%s "
                    "controller_key=%s unit_number=%s",
                    next_disk["size"],
                    next_disk["unit"],
                    current_disk["controller_key"],
                    current_disk["unit_number"],
                )
                device_config_spec = _apply_hard_disk(
                    current_disk["unit_number"],
                    current_disk["key"],
                    "edit",
                    size=next_disk["size"],
                    unit=next_disk["unit"],
                    controller_key=current_disk["controller_key"],
                )
                # The backing didn't change and we must supply one for
                # reconfigure
                device_config_spec.device.backing = current_disk["object"].backing
                disk_changes.append(device_config_spec)

    return disk_changes


def _update_scsi_devices(scsis_old_new, current_disks):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec specifying  the scsi
    properties as input the old and new configs are defined in a dictionary.

    scsi_diffs
        List of old and new scsi properties
    """
    device_config_specs = []
    if scsis_old_new:
        devs = [scsi["old"]["adapter"] for scsi in scsis_old_new]
        log.trace("Updating SCSI controllers %s", devs)
        for item in scsis_old_new:
            next_scsi = item["new"]
            current_scsi = item["old"]
            difference = recursive_diff(current_scsi, next_scsi)
            difference.ignore_unset_values = False
            if difference.changed():
                log.trace(
                    "Virtual machine scsi device will be updated key=%s "
                    "bus_number=%s type=%s bus_sharing=%s",
                    current_scsi["key"],
                    current_scsi["bus_number"],
                    next_scsi["type"],
                    next_scsi["bus_sharing"],
                )
                # The sharedBus property is not optional
                # The type can only be updated if we delete the original
                # controller, create a new one with the properties and then
                # attach the disk object to the newly created controller, even
                # though the controller key stays the same the last step is
                # mandatory
                if next_scsi["type"] != current_scsi["type"]:
                    device_config_specs.append(_delete_device(current_scsi["object"]))
                    device_config_specs.append(
                        _apply_scsi_controller(
                            current_scsi["adapter"],
                            next_scsi["type"],
                            next_scsi["bus_sharing"],
                            current_scsi["key"],
                            current_scsi["bus_number"],
                            "add",
                        )
                    )
                    disks_to_update = []
                    for disk_key in current_scsi["device"]:
                        disk_objects = [disk["object"] for disk in current_disks]
                        disks_to_update.append(
                            _get_device_by_key(disk_objects, disk_key)
                        )
                    for current_disk in disks_to_update:
                        disk_spec = vim.vm.device.VirtualDeviceSpec()
                        disk_spec.device = current_disk
                        disk_spec.operation = "edit"
                        device_config_specs.append(disk_spec)
                else:
                    device_config_specs.append(
                        _apply_scsi_controller(
                            current_scsi["adapter"],
                            current_scsi["type"],
                            next_scsi["bus_sharing"],
                            current_scsi["key"],
                            current_scsi["bus_number"],
                            "edit",
                        )
                    )
    return device_config_specs


def _update_network_adapters(interface_old_new, parent):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec specifying
    configuration(s) for changed network adapters, the adapter type cannot
    be changed, as input the old and new configs are defined in a dictionary.

    interface_old_new
        Dictionary with old and new keys which contains the current and the
        next config for a network device

    parent
        Parent managed object reference
    """
    network_changes = []
    if interface_old_new:
        devs = [inter["old"]["mac"] for inter in interface_old_new]
        log.trace("Updating network interfaces %s", devs)
        for item in interface_old_new:
            current_interface = item["old"]
            next_interface = item["new"]
            difference = recursive_diff(current_interface, next_interface)
            difference.ignore_unset_values = False
            if difference.changed():
                log.trace(
                    "Virtual machine network adapter will be updated "
                    "switch_type=%s name=%s adapter_type=%s mac=%s",
                    next_interface["switch_type"],
                    next_interface["name"],
                    current_interface["adapter_type"],
                    current_interface["mac"],
                )
                device_config_spec = _apply_network_adapter_config(
                    current_interface["key"],
                    next_interface["name"],
                    current_interface["adapter_type"],
                    next_interface["switch_type"],
                    operation="edit",
                    mac=current_interface["mac"],
                    parent=parent,
                )
                network_changes.append(device_config_spec)
    return network_changes


def _update_serial_ports(serial_old_new):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec specifying to edit a
    deployed serial port configuration to the new given config

    serial_old_new
         Dictionary with old and new keys which contains the current and the
          next config for a serial port device
    """
    serial_changes = []
    if serial_old_new:
        devs = [serial["old"]["adapter"] for serial in serial_old_new]
        log.trace("Updating serial ports %s", devs)
        for item in serial_old_new:
            current_serial = item["old"]
            next_serial = item["new"]
            difference = recursive_diff(current_serial, next_serial)
            difference.ignore_unset_values = False
            if difference.changed():
                serial_changes.append(
                    _apply_serial_port(next_serial, current_serial["key"], "edit")
                )
        return serial_changes


def _update_cd_drives(drives_old_new, controllers=None, parent=None):
    """
    Returns a list of vim.vm.device.VirtualDeviceSpec specifying to edit a
    deployed cd drive configuration to the new given config

    drives_old_new
        Dictionary with old and new keys which contains the current and the
        next config for a cd drive

    controllers
        Controller device list

    parent
        Managed object reference of the parent object
    """
    cd_changes = []
    if drives_old_new:
        devs = [drive["old"]["adapter"] for drive in drives_old_new]
        log.trace("Updating cd/dvd drives %s", devs)
        for item in drives_old_new:
            current_drive = item["old"]
            new_drive = item["new"]
            difference = recursive_diff(current_drive, new_drive)
            difference.ignore_unset_values = False
            if difference.changed():
                if controllers:
                    controller = _get_device_by_label(
                        controllers, new_drive["controller"]
                    )
                    controller_key = controller.key
                else:
                    controller_key = current_drive["controller_key"]
                cd_changes.append(
                    _apply_cd_drive(
                        current_drive["adapter"],
                        current_drive["key"],
                        new_drive["device_type"],
                        "edit",
                        client_device=(
                            new_drive["client_device"]
                            if "client_device" in new_drive
                            else None
                        ),
                        datastore_iso_file=(
                            new_drive["datastore_iso_file"]
                            if "datastore_iso_file" in new_drive
                            else None
                        ),
                        connectable=new_drive["connectable"],
                        controller_key=controller_key,
                        parent_ref=parent,
                    )
                )
    return cd_changes


def _delete_device(device):
    """
    Returns a vim.vm.device.VirtualDeviceSpec specifying to remove a virtual
    machine device

    device
        Device data type object
    """
    log.trace("Deleting device with type %s", type(device))
    device_spec = vim.vm.device.VirtualDeviceSpec()
    device_spec.operation = vim.vm.device.VirtualDeviceSpec.Operation.remove
    device_spec.device = device
    return device_spec


def _get_client(server, username, password, verify_ssl=None, ca_bundle=None):
    """
    Establish client through proxy or with user provided credentials.

    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :returns:
        vSphere Client instance.
    :rtype:
        vSphere.Client
    """
    # Get salted vSphere Client
    details = None
    if not (server and username and password):
        # User didn't provide CLI args so use proxy information
        details = __salt__["vcenter.get_details"]()
        server = details["vcenter"]
        username = details["username"]
        password = details["password"]

    if verify_ssl is None:
        if details is None:
            details = __salt__["vcenter.get_details"]()
        verify_ssl = details.get("verify_ssl", True)
        if verify_ssl is None:
            verify_ssl = True

    if ca_bundle is None:
        if details is None:
            details = __salt__["vcenter.get_details"]()
        ca_bundle = details.get("ca_bundle", None)

    if verify_ssl is False and ca_bundle is not None:
        log.error("Cannot set verify_ssl to False and ca_bundle together")
        return False

    if ca_bundle:
        ca_bundle = salt.utils.http.get_ca_bundle({"ca_bundle": ca_bundle})

    # Establish connection with client
    client = salt.utils.vmware.get_vsphere_client(
        server=server,
        username=username,
        password=password,
        verify_ssl=verify_ssl,
        ca_bundle=ca_bundle,
    )
    # Will return None if utility function causes Unauthenticated error
    return client


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_tag_categories(
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    List existing categories a user has access to.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.list_tag_categories

    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :returns:
        Value(s) of category_id.
    :rtype:
        list of str
    """
    categories = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        categories = client.tagging.Category.list()
    return {"Categories": categories}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_tags(
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    List existing tags a user has access to.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.list_tags

    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :return:
        Value(s) of tag_id.
    :rtype:
        list of str
    """
    tags = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        tags = client.tagging.Tag.list()
    return {"Tags": tags}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def attach_tag(
    object_id,
    tag_id,
    managed_obj="ClusterComputeResource",
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    Attach an existing tag to an input object.

    The tag needs to meet the cardinality (`CategoryModel.cardinality`) and
    associability (`CategoryModel.associable_types`) criteria in order to be
    eligible for attachment. If the tag is already attached to the object,
    then this method is a no-op and an error will not be thrown. To invoke
    this method, you need the attach tag privilege on the tag and the read
    privilege on the object.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.attach_tag domain-c2283 \
                urn:vmomi:InventoryServiceTag:b55ecc77-f4a5-49f8-ab52-38865467cfbe:GLOBAL

    :param str object_id:
        The identifier of the input object.
    :param str tag_id:
        The identifier of the tag object.
    :param str managed_obj:
        Classes that contain methods for creating and deleting resources
        typically contain a class attribute specifying the resource type
        for the resources being created and deleted.
    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :return:
        The list of all tag identifiers that correspond to the
        tags attached to the given object.
    :rtype:
        list of tags
    :raise: Unauthorized
        if you do not have the privilege to read the object.
    :raise: Unauthenticated
        if the user can not be authenticated.
    """
    tag_attached = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        # Create dynamic id object associated with a type and an id.
        # Note, here the default is ClusterComputeResource, which
        # infers a lazy loaded vim.ClusterComputerResource.

        # The ClusterComputeResource data object aggregates the compute
        # resources of associated HostSystem objects into a single compute
        # resource for use by virtual machines.
        dynamic_id = DynamicID(type=managed_obj, id=object_id)
        try:
            tag_attached = client.tagging.TagAssociation.attach(
                tag_id=tag_id, object_id=dynamic_id
            )
        except vsphere_errors:
            log.warning(
                "Unable to attach tag. Check user privileges and"
                " object_id (must be a string)."
            )
    return {"Tag attached": tag_attached}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def list_attached_tags(
    object_id,
    managed_obj="ClusterComputeResource",
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    List existing tags a user has access to.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.list_attached_tags domain-c2283

    :param str object_id:
        The identifier of the input object.
    :param str managed_obj:
        Classes that contain methods for creating and deleting resources
        typically contain a class attribute specifying the resource type
        for the resources being created and deleted.
    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :return:
        The list of all tag identifiers that correspond to the
        tags attached to the given object.
    :rtype:
        list of tags
    :raise: Unauthorized
        if you do not have the privilege to read the object.
    :raise: Unauthenticated
        if the user can not be authenticated.
    """
    attached_tags = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        # Create dynamic id object associated with a type and an id.
        # Note, here the default is ClusterComputeResource, which
        # infers a lazy loaded vim.ClusterComputerResource.

        # The ClusterComputeResource data object aggregates the compute
        # resources of associated HostSystem objects into a single compute
        # resource for use by virtual machines.
        dynamic_id = DynamicID(type=managed_obj, id=object_id)
        try:
            attached_tags = client.tagging.TagAssociation.list_attached_tags(dynamic_id)
        except vsphere_errors:
            log.warning(
                "Unable to list attached tags. Check user privileges"
                " and object_id (must be a string)."
            )
    return {"Attached tags": attached_tags}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_tag_category(
    name,
    description,
    cardinality,
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    Create a category with given cardinality.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.create_tag_category

    :param str name:
        Name of tag category to create (ex. Machine, OS, Availability, etc.)
    :param str description:
        Given description of tag category.
    :param str cardinality:
        The associated cardinality (SINGLE, MULTIPLE) of the category.
    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :return:
        Identifier of the created category.
    :rtype:
        str
    :raise: AlreadyExists
        if the name` provided in the create_spec is the name of an already
        existing category.
    :raise: InvalidArgument
        if any of the information in the create_spec is invalid.
    :raise: Unauthorized
        if you do not have the privilege to create a category.
    """
    category_created = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        if cardinality == "SINGLE":
            cardinality = CategoryModel.Cardinality.SINGLE
        elif cardinality == "MULTIPLE":
            cardinality = CategoryModel.Cardinality.MULTIPLE
        else:
            # Cardinality must be supplied correctly
            cardinality = None

        create_spec = client.tagging.Category.CreateSpec()
        create_spec.name = name
        create_spec.description = description
        create_spec.cardinality = cardinality
        associable_types = set()
        create_spec.associable_types = associable_types
        try:
            category_created = client.tagging.Category.create(create_spec)
        except vsphere_errors:
            log.warning(
                "Unable to create tag category. Check user privilege"
                " and see if category exists."
            )
    return {"Category created": category_created}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def delete_tag_category(
    category_id,
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    Delete a category.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.delete_tag_category

    :param str category_id:
        The identifier of category to be deleted.
        The parameter must be an identifier for the resource type:
        ``com.vmware.cis.tagging.Category``.
    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :raise: NotFound
        if the tag for the given tag_id does not exist in the system.
    :raise: Unauthorized
        if you do not have the privilege to delete the tag.
    :raise: Unauthenticated
        if the user can not be authenticated.
    """
    category_deleted = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        try:
            category_deleted = client.tagging.Category.delete(category_id)
        except vsphere_errors:
            log.warning(
                "Unable to delete tag category. Check user privilege"
                " and see if category exists."
            )
    return {"Category deleted": category_deleted}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_tag(
    name,
    description,
    category_id,
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    Create a tag under a category with given description.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.create_tag

    :param basestring server:
        Target DNS or IP of vCenter client.
    :param basestring username:
         Username associated with the vCenter client.
    :param basestring password:
        Password associated with the vCenter client.
    :param str name:
        Name of tag category to create (ex. Machine, OS, Availability, etc.)
    :param str description:
        Given description of tag category.
    :param str category_id:
        Value of category_id representative of the category created previously.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :return:
        The identifier of the created tag.
    :rtype:
        str
    :raise: AlreadyExists
        if the name provided in the create_spec is the name of an already
        existing tag in the input category.
    :raise: InvalidArgument
        if any of the input information in the create_spec is invalid.
    :raise: NotFound
        if the category for in the given create_spec does not exist in
        the system.
    :raise: Unauthorized
        if you do not have the privilege to create tag.
    """
    tag_created = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        create_spec = client.tagging.Tag.CreateSpec()
        create_spec.name = name
        create_spec.description = description
        create_spec.category_id = category_id
        try:
            tag_created = client.tagging.Tag.create(create_spec)
        except vsphere_errors:
            log.warning(
                "Unable to create tag. Check user privilege and see if category exists."
            )
    return {"Tag created": tag_created}


@depends(HAS_PYVMOMI, HAS_VSPHERE_SDK)
@_supports_proxies("vcenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def delete_tag(
    tag_id,
    server=None,
    username=None,
    password=None,
    service_instance=None,
    verify_ssl=None,
    ca_bundle=None,
):
    """
    Delete a tag.

    CLI Example:

    .. code-block:: bash

            salt vm_minion vsphere.delete_tag

    :param str tag_id:
        The identifier of tag to be deleted.
        The parameter must be an identifier for the resource type:
        ``com.vmware.cis.tagging.Tag``.
    :param basestring server:
        Target DNS or IP of vCenter center.
    :param basestring username:
        Username associated with the vCenter center.
    :param basestring password:
        Password associated with the vCenter center.
    :param boolean verify_ssl:
        Verify the SSL certificate. Default: True
    :param basestring ca_bundle:
        Path to the ca bundle to use when verifying SSL certificates.
    :raise: AlreadyExists
        if the name provided in the create_spec is the name of an already
        existing category.
    :raise: InvalidArgument
        if any of the information in the create_spec is invalid.
    :raise: Unauthorized
        if you do not have the privilege to create a category.
    """
    tag_deleted = None
    client = _get_client(
        server, username, password, verify_ssl=verify_ssl, ca_bundle=ca_bundle
    )

    if client:
        try:
            tag_deleted = client.tagging.Tag.delete(tag_id)
        except vsphere_errors:
            log.warning(
                "Unable to delete category. Check user privileges"
                " and that category exists."
            )
    return {"Tag deleted": tag_deleted}


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def create_vm(
    vm_name,
    cpu,
    memory,
    image,
    version,
    datacenter,
    datastore,
    placement,
    interfaces,
    disks,
    scsi_devices,
    serial_ports=None,
    ide_controllers=None,
    sata_controllers=None,
    cd_drives=None,
    advanced_configs=None,
    service_instance=None,
):
    """
    Creates a virtual machine container.

    CLI Example:

    .. code-block:: bash

        salt vm_minion vsphere.create_vm vm_name=vmname cpu='{count: 2, nested: True}' ...

    vm_name
        Name of the virtual machine

    cpu
        Properties of CPUs for freshly created machines

    memory
        Memory size for freshly created machines

    image
        Virtual machine guest OS version identifier
        VirtualMachineGuestOsIdentifier

    version
        Virtual machine container hardware version

    datacenter
        Datacenter where the virtual machine will be deployed (mandatory)

    datastore
        Datastore where the virtual machine files will be placed

    placement
        Resource pool or cluster or host or folder where the virtual machine
        will be deployed

    devices
        interfaces

        .. code-block:: bash

            interfaces:
              adapter: 'Network adapter 1'
              name: vlan100
              switch_type: distributed or standard
              adapter_type: vmxnet3 or vmxnet, vmxnet2, vmxnet3, e1000, e1000e
              mac: '00:11:22:33:44:55'
              connectable:
                allow_guest_control: True
                connected: True
                start_connected: True

        disks

        .. code-block:: bash

            disks:
              adapter: 'Hard disk 1'
              size: 16
              unit: GB
              address: '0:0'
              controller: 'SCSI controller 0'
              thin_provision: False
              eagerly_scrub: False
              datastore: 'myshare'
              filename: 'vm/mydisk.vmdk'

        scsi_devices

        .. code-block:: bash

            scsi_devices:
              controller: 'SCSI controller 0'
              type: paravirtual
              bus_sharing: no_sharing

        serial_ports

        .. code-block:: bash

            serial_ports:
              adapter: 'Serial port 1'
              type: network
              backing:
                uri: 'telnet://something:port'
                direction: <client|server>
                filename: 'service_uri'
              connectable:
                allow_guest_control: True
                connected: True
                start_connected: True
              yield: False

        cd_drives

        .. code-block:: bash

            cd_drives:
              adapter: 'CD/DVD drive 0'
              controller: 'IDE 0'
              device_type: datastore_iso_file
              datastore_iso_file:
                path: path_to_iso
              connectable:
                allow_guest_control: True
                connected: True
                start_connected: True

    advanced_config
        Advanced config parameters to be set for the virtual machine
    """
    # If datacenter is specified, set the container reference to start search
    # from it instead
    container_object = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    (resourcepool_object, placement_object) = salt.utils.vmware.get_placement(
        service_instance, datacenter, placement=placement
    )
    folder_object = salt.utils.vmware.get_folder(
        service_instance, datacenter, placement
    )
    # Create the config specs
    config_spec = vim.vm.ConfigSpec()
    config_spec.name = vm_name
    config_spec.guestId = image
    config_spec.files = vim.vm.FileInfo()

    # For VSAN disks we need to specify a different vm path name, the vm file
    # full path cannot be used
    datastore_object = salt.utils.vmware.get_datastores(
        service_instance, placement_object, datastore_names=[datastore]
    )[0]
    if not datastore_object:
        raise salt.exceptions.ArgumentValueError(
            f"Specified datastore: '{datastore}' does not exist."
        )
    try:
        ds_summary = salt.utils.vmware.get_properties_of_managed_object(
            datastore_object, "summary.type"
        )
        if "summary.type" in ds_summary and ds_summary["summary.type"] == "vsan":
            log.trace(
                "The vmPathName should be the datastore "
                "name if the datastore type is vsan"
            )
            config_spec.files.vmPathName = f"[{datastore}]"
        else:
            config_spec.files.vmPathName = "[{0}] {1}/{1}.vmx".format(
                datastore, vm_name
            )
    except salt.exceptions.VMwareApiError:
        config_spec.files.vmPathName = "[{0}] {1}/{1}.vmx".format(datastore, vm_name)

    cd_controllers = []
    if version:
        _apply_hardware_version(version, config_spec, "add")
    if cpu:
        _apply_cpu_config(config_spec, cpu)
    if memory:
        _apply_memory_config(config_spec, memory)
    if scsi_devices:
        scsi_specs = _create_scsi_devices(scsi_devices)
        config_spec.deviceChange.extend(scsi_specs)
    if disks:
        scsi_controllers = [spec.device for spec in scsi_specs]
        disk_specs = _create_disks(
            service_instance,
            disks,
            scsi_controllers=scsi_controllers,
            parent=container_object,
        )
        config_spec.deviceChange.extend(disk_specs)
    if interfaces:
        (interface_specs, nic_settings) = _create_network_adapters(
            interfaces, parent=container_object
        )
        config_spec.deviceChange.extend(interface_specs)
    if serial_ports:
        serial_port_specs = _create_serial_ports(serial_ports)
        config_spec.deviceChange.extend(serial_port_specs)
    if ide_controllers:
        ide_specs = _create_ide_controllers(ide_controllers)
        config_spec.deviceChange.extend(ide_specs)
        cd_controllers.extend(ide_specs)
    if sata_controllers:
        sata_specs = _create_sata_controllers(sata_controllers)
        config_spec.deviceChange.extend(sata_specs)
        cd_controllers.extend(sata_specs)
    if cd_drives:
        cd_drive_specs = _create_cd_drives(
            cd_drives, controllers=cd_controllers, parent_ref=container_object
        )
        config_spec.deviceChange.extend(cd_drive_specs)
    if advanced_configs:
        _apply_advanced_config(config_spec, advanced_configs)
    salt.utils.vmware.create_vm(
        vm_name, config_spec, folder_object, resourcepool_object, placement_object
    )

    return {"create_vm": True}


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def update_vm(
    vm_name,
    cpu=None,
    memory=None,
    image=None,
    version=None,
    interfaces=None,
    disks=None,
    scsi_devices=None,
    serial_ports=None,
    datacenter=None,
    datastore=None,
    cd_dvd_drives=None,
    sata_controllers=None,
    advanced_configs=None,
    service_instance=None,
):
    """
    Updates the configuration of the virtual machine if the config differs

    vm_name
        Virtual Machine name to be updated

    cpu
        CPU configuration options

    memory
        Memory configuration options

    version
        Virtual machine container hardware version

    image
        Virtual machine guest OS version identifier
        VirtualMachineGuestOsIdentifier

    interfaces
        Network interfaces configuration options

    disks
        Disks configuration options

    scsi_devices
        SCSI devices configuration options

    serial_ports
        Serial ports configuration options

    datacenter
        Datacenter where the virtual machine is available

    datastore
        Datastore where the virtual machine config files are available

    cd_dvd_drives
        CD/DVD drives configuration options

    advanced_config
        Advanced config parameters to be set for the virtual machine

    service_instance
        vCenter service instance for connection and configuration
    """
    current_config = get_vm_config(
        vm_name, datacenter=datacenter, objects=True, service_instance=service_instance
    )
    diffs = compare_vm_configs(
        {
            "name": vm_name,
            "cpu": cpu,
            "memory": memory,
            "image": image,
            "version": version,
            "interfaces": interfaces,
            "disks": disks,
            "scsi_devices": scsi_devices,
            "serial_ports": serial_ports,
            "datacenter": datacenter,
            "datastore": datastore,
            "cd_drives": cd_dvd_drives,
            "sata_controllers": sata_controllers,
            "advanced_configs": advanced_configs,
        },
        current_config,
    )
    config_spec = vim.vm.ConfigSpec()
    datacenter_ref = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    vm_ref = salt.utils.vmware.get_mor_by_property(
        service_instance,
        vim.VirtualMachine,
        vm_name,
        property_name="name",
        container_ref=datacenter_ref,
    )

    difference_keys = diffs.keys()
    if "cpu" in difference_keys:
        if diffs["cpu"].changed() != set():
            _apply_cpu_config(config_spec, diffs["cpu"].current_dict)
    if "memory" in difference_keys:
        if diffs["memory"].changed() != set():
            _apply_memory_config(config_spec, diffs["memory"].current_dict)
    if "advanced_configs" in difference_keys:
        _apply_advanced_config(
            config_spec, diffs["advanced_configs"].new_values, vm_ref.config.extraConfig
        )
    if "version" in difference_keys:
        _apply_hardware_version(version, config_spec, "edit")
    if "image" in difference_keys:
        config_spec.guestId = image
    new_scsi_devices = []
    if "scsi_devices" in difference_keys and "disks" in current_config:
        scsi_changes = []
        scsi_changes.extend(
            _update_scsi_devices(
                diffs["scsi_devices"].intersect, current_config["disks"]
            )
        )
        for item in diffs["scsi_devices"].removed:
            scsi_changes.append(_delete_device(item["object"]))
        new_scsi_devices = _create_scsi_devices(diffs["scsi_devices"].added)
        scsi_changes.extend(new_scsi_devices)
        config_spec.deviceChange.extend(scsi_changes)
    if "disks" in difference_keys:
        disk_changes = []
        disk_changes.extend(_update_disks(diffs["disks"].intersect))
        for item in diffs["disks"].removed:
            disk_changes.append(_delete_device(item["object"]))
        # We will need the existing and new controllers as well
        scsi_controllers = [dev["object"] for dev in current_config["scsi_devices"]]
        scsi_controllers.extend(
            [device_spec.device for device_spec in new_scsi_devices]
        )
        disk_changes.extend(
            _create_disks(
                service_instance,
                diffs["disks"].added,
                scsi_controllers=scsi_controllers,
                parent=datacenter_ref,
            )
        )
        config_spec.deviceChange.extend(disk_changes)
    if "interfaces" in difference_keys:
        network_changes = []
        network_changes.extend(
            _update_network_adapters(diffs["interfaces"].intersect, datacenter_ref)
        )
        for item in diffs["interfaces"].removed:
            network_changes.append(_delete_device(item["object"]))
        (adapters, nics) = _create_network_adapters(
            diffs["interfaces"].added, datacenter_ref
        )
        network_changes.extend(adapters)
        config_spec.deviceChange.extend(network_changes)
    if "serial_ports" in difference_keys:
        serial_changes = []
        serial_changes.extend(_update_serial_ports(diffs["serial_ports"].intersect))
        for item in diffs["serial_ports"].removed:
            serial_changes.append(_delete_device(item["object"]))
        serial_changes.extend(_create_serial_ports(diffs["serial_ports"].added))
        config_spec.deviceChange.extend(serial_changes)
    new_controllers = []
    if "sata_controllers" in difference_keys:
        # SATA controllers don't have many properties, it does not make sense
        # to update them
        sata_specs = _create_sata_controllers(diffs["sata_controllers"].added)
        for item in diffs["sata_controllers"].removed:
            sata_specs.append(_delete_device(item["object"]))
        new_controllers.extend(sata_specs)
        config_spec.deviceChange.extend(sata_specs)
    if "cd_drives" in difference_keys:
        cd_changes = []
        controllers = [dev["object"] for dev in current_config["sata_controllers"]]
        controllers.extend([device_spec.device for device_spec in new_controllers])
        cd_changes.extend(
            _update_cd_drives(
                diffs["cd_drives"].intersect,
                controllers=controllers,
                parent=datacenter_ref,
            )
        )
        for item in diffs["cd_drives"].removed:
            cd_changes.append(_delete_device(item["object"]))
        cd_changes.extend(
            _create_cd_drives(
                diffs["cd_drives"].added,
                controllers=controllers,
                parent_ref=datacenter_ref,
            )
        )
        config_spec.deviceChange.extend(cd_changes)

    if difference_keys:
        salt.utils.vmware.update_vm(vm_ref, config_spec)
    changes = {}
    for key, properties in diffs.items():
        # We can't display object, although we will need them for delete
        # and update actions, we will need to delete these before we summarize
        # the changes for the users
        if isinstance(properties, salt.utils.listdiffer.ListDictDiffer):
            properties.remove_diff(diff_key="object", diff_list="intersect")
            properties.remove_diff(diff_key="key", diff_list="intersect")
            properties.remove_diff(diff_key="object", diff_list="removed")
            properties.remove_diff(diff_key="key", diff_list="removed")
        changes[key] = properties.diffs

    return changes


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def register_vm(name, datacenter, placement, vmx_path, service_instance=None):
    """
    Registers a virtual machine to the inventory with the given vmx file.
    Returns comments and change list

    name
        Name of the virtual machine

    datacenter
        Datacenter of the virtual machine

    placement
        Placement dictionary of the virtual machine, host or cluster

    vmx_path:
        Full path to the vmx file, datastore name should be included

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.
    """
    log.trace(
        "Registering virtual machine with properties datacenter=%s, "
        "placement=%s, vmx_path=%s",
        datacenter,
        placement,
        vmx_path,
    )
    datacenter_object = salt.utils.vmware.get_datacenter(service_instance, datacenter)
    if "cluster" in placement:
        cluster_obj = salt.utils.vmware.get_cluster(
            datacenter_object, placement["cluster"]
        )
        cluster_props = salt.utils.vmware.get_properties_of_managed_object(
            cluster_obj, properties=["resourcePool"]
        )
        if "resourcePool" in cluster_props:
            resourcepool = cluster_props["resourcePool"]
        else:
            raise salt.exceptions.VMwareObjectRetrievalError(
                "The cluster's resource pool object could not be retrieved."
            )
        salt.utils.vmware.register_vm(datacenter_object, name, vmx_path, resourcepool)
    elif "host" in placement:
        hosts = salt.utils.vmware.get_hosts(
            service_instance, datacenter_name=datacenter, host_names=[placement["host"]]
        )
        if not hosts:
            raise salt.exceptions.VMwareObjectRetrievalError(
                "ESXi host named '{}' wasn't found.".format(placement["host"])
            )
        host_obj = hosts[0]
        host_props = salt.utils.vmware.get_properties_of_managed_object(
            host_obj, properties=["parent"]
        )
        if "parent" in host_props:
            host_parent = host_props["parent"]
            parent = salt.utils.vmware.get_properties_of_managed_object(
                host_parent, properties=["parent"]
            )
            if "parent" in parent:
                resourcepool = parent["parent"]
            else:
                raise salt.exceptions.VMwareObjectRetrievalError(
                    "The host parent's parent object could not be retrieved."
                )
        else:
            raise salt.exceptions.VMwareObjectRetrievalError(
                "The host's parent object could not be retrieved."
            )
        salt.utils.vmware.register_vm(
            datacenter_object, name, vmx_path, resourcepool, host_object=host_obj
        )
    result = {
        "comment": "Virtual machine registration action succeeded",
        "changes": {"register_vm": True},
    }
    return result


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def power_on_vm(name, datacenter=None, service_instance=None):
    """
    Powers on a virtual machine specified by its name.

    name
        Name of the virtual machine

    datacenter
        Datacenter of the virtual machine

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.power_on_vm name=my_vm

    """
    log.trace("Powering on virtual machine %s", name)
    vm_properties = ["name", "summary.runtime.powerState"]
    virtual_machine = salt.utils.vmware.get_vm_by_property(
        service_instance, name, datacenter=datacenter, vm_properties=vm_properties
    )
    if virtual_machine["summary.runtime.powerState"] == "poweredOn":
        result = {
            "comment": "Virtual machine is already powered on",
            "changes": {"power_on": True},
        }
        return result
    salt.utils.vmware.power_cycle_vm(virtual_machine["object"], action="on")
    result = {
        "comment": "Virtual machine power on action succeeded",
        "changes": {"power_on": True},
    }
    return result


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def power_off_vm(name, datacenter=None, service_instance=None):
    """
    Powers off a virtual machine specified by its name.

    name
        Name of the virtual machine

    datacenter
        Datacenter of the virtual machine

    service_instance
        Service instance (vim.ServiceInstance) of the vCenter.
        Default is None.

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.power_off_vm name=my_vm

    """
    log.trace("Powering off virtual machine %s", name)
    vm_properties = ["name", "summary.runtime.powerState"]
    virtual_machine = salt.utils.vmware.get_vm_by_property(
        service_instance, name, datacenter=datacenter, vm_properties=vm_properties
    )
    if virtual_machine["summary.runtime.powerState"] == "poweredOff":
        result = {
            "comment": "Virtual machine is already powered off",
            "changes": {"power_off": True},
        }
        return result
    salt.utils.vmware.power_cycle_vm(virtual_machine["object"], action="off")
    result = {
        "comment": "Virtual machine power off action succeeded",
        "changes": {"power_off": True},
    }
    return result


def _remove_vm(name, datacenter, service_instance, placement=None, power_off=None):
    """
    Helper function to remove a virtual machine

    name
        Name of the virtual machine

    service_instance
        vCenter service instance for connection and configuration

    datacenter
        Datacenter of the virtual machine

    placement
        Placement information of the virtual machine
    """
    results = {}
    if placement:
        (resourcepool_object, placement_object) = salt.utils.vmware.get_placement(
            service_instance, datacenter, placement
        )
    else:
        placement_object = salt.utils.vmware.get_datacenter(
            service_instance, datacenter
        )
    if power_off:
        power_off_vm(name, datacenter, service_instance)
        results["powered_off"] = True
    vm_ref = salt.utils.vmware.get_mor_by_property(
        service_instance,
        vim.VirtualMachine,
        name,
        property_name="name",
        container_ref=placement_object,
    )
    if not vm_ref:
        raise salt.exceptions.VMwareObjectRetrievalError(
            "The virtual machine object {} in datacenter {} was not found".format(
                name, datacenter
            )
        )
    return results, vm_ref


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def delete_vm(name, datacenter, placement=None, power_off=False, service_instance=None):
    """
    Deletes a virtual machine defined by name and placement

    name
        Name of the virtual machine

    datacenter
        Datacenter of the virtual machine

    placement
        Placement information of the virtual machine

    service_instance
        vCenter service instance for connection and configuration

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.delete_vm name=my_vm datacenter=my_datacenter

    """
    results = {}
    schema = ESXVirtualMachineDeleteSchema.serialize()
    try:
        jsonschema.validate(
            {"name": name, "datacenter": datacenter, "placement": placement}, schema
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise InvalidConfigError(exc)
    (results, vm_ref) = _remove_vm(
        name,
        datacenter,
        service_instance=service_instance,
        placement=placement,
        power_off=power_off,
    )
    salt.utils.vmware.delete_vm(vm_ref)
    results["deleted_vm"] = True
    return results


@depends(HAS_PYVMOMI)
@_supports_proxies("esxvm", "esxcluster", "esxdatacenter")
@_gets_service_instance_via_proxy
@_deprecation_message
def unregister_vm(
    name, datacenter, placement=None, power_off=False, service_instance=None
):
    """
    Unregisters a virtual machine defined by name and placement

    name
        Name of the virtual machine

    datacenter
        Datacenter of the virtual machine

    placement
        Placement information of the virtual machine

    service_instance
        vCenter service instance for connection and configuration

    CLI Example:

    .. code-block:: bash

        salt '*' vsphere.unregister_vm name=my_vm datacenter=my_datacenter

    """
    results = {}
    schema = ESXVirtualMachineUnregisterSchema.serialize()
    try:
        jsonschema.validate(
            {"name": name, "datacenter": datacenter, "placement": placement}, schema
        )
    except jsonschema.exceptions.ValidationError as exc:
        raise InvalidConfigError(exc)
    (results, vm_ref) = _remove_vm(
        name,
        datacenter,
        service_instance=service_instance,
        placement=placement,
        power_off=power_off,
    )
    salt.utils.vmware.unregister_vm(vm_ref)
    results["unregistered_vm"] = True
    return results
