salt.modules.vsphere

Manage VMware vCenter servers and ESXi hosts.

New in version 2015.8.4.

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

Dependencies

  • pyVmomi Python Module
  • ESXCLI

pyVmomi

PyVmomi can be installed via pip:

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.6, 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.

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

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.

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.

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:

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.

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:

# 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:

# 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.

# 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
salt.modules.vsphere.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:

# 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]'
salt.modules.vsphere.disconnect(*args, **kwargs)
salt.modules.vsphere.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.
Returns:A standard cmd.run_all dictionary, per host.

CLI Example:

# 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]'
salt.modules.vsphere.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:

# 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]'
salt.modules.vsphere.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.
Returns: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:

# 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]'
salt.modules.vsphere.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.
Returns: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:

# 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]'
salt.modules.vsphere.get_proxy_type()

Returns the proxy type

CLI Example:

salt '*' vsphere.get_proxy_type
salt.modules.vsphere.get_service_instance_via_proxy(*args, **kwargs)
salt.modules.vsphere.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.
Returns:Dictionary with keys and values corresponding to the syslog configuration, per host.

CLI Example:

# 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]'
salt.modules.vsphere.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.

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.

CLI Example:
None, this is a decorator
salt.modules.vsphere.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.
Returns: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:

syslog_config can be passed as a quoted, comma-separated string, e.g.

# 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]'
salt.modules.vsphere.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.
Returns: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:

# 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]'
salt.modules.vsphere.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.
Returns: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:

# 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]'
salt.modules.vsphere.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
salt.modules.vsphere.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.
Returns: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:

# 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]'
salt.modules.vsphere.test_vcenter_connection(*args, **kwargs)