Manage VMware vCenter servers and ESXi hosts.
New in version 2015.8.4.
codeauthor: | Alexandru Bleotu <alexandru.bleotu@morganstaley.com> |
---|
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.
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.
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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
root
.-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.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.vmk0
.6500
.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.
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
.
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)
https
.443
.True
.True
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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
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.
root
.https
.443
.host
is a vCenter host, then use esxi_hosts to execute this function
on a list of one or more ESXi machines.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)¶