salt.states.esxi

Manage VMware ESXi Hosts.

New in version 2015.8.4.

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 ESXi State 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 state module may depend on the type of license attached to the ESXi host.

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 state module was written to be used in conjunction with Salt's ESXi Proxy Minion. For a tutorial on how to use Salt's ESXi Proxy Minion, please refer to the ESXi Proxy Minion Tutorial for configuration examples, dependency installation instructions, how to run remote execution functions against ESXi hosts via a Salt Proxy Minion, and a larger state example.

salt.states.esxi.coredump_configured(name, enabled, dump_ip, host_vnic='vmk0', dump_port=6500)

Ensures a host's core dump configuration.

name

Name of the state.

enabled

Sets whether or not ESXi core dump collection should be enabled. This is a boolean value set to True or False to enable or disable core dumps.

Note that ESXi requires that the core dump must be enabled before any other parameters may be set. This also affects the changes results in the state return dictionary. If enabled is False, we can't obtain any previous settings to compare other state variables, resulting in many old references returning None.

Once enabled is True the changes dictionary comparisons will be more accurate. This is due to the way the system coredemp network configuration command returns data.

dump_ip

The IP address of host that will accept the dump.

host_vnic

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

dump_port

TCP port to use for the dump. Defaults to 6500.

Example:

configure-host-coredump:
  esxi.coredump_configured:
    - enabled: True
    - dump_ip: 'my-coredump-ip.example.com'
salt.states.esxi.diskgroups_configured(name, diskgroups, erase_disks=False)

Configures the disk groups to use for vsan.

This function will do the following:

  1. Check whether or not all disks in the diskgroup spec exist, and raises and errors if they do not.

  2. Create diskgroups with the correct disk configurations if diskgroup (identified by the cache disk canonical name) doesn't exist

  3. Adds extra capacity disks to the existing diskgroup

Example:

{
    'cache_scsi_addr': 'vmhba1:C0:T0:L0',
    'capacity_scsi_addrs': [
        'vmhba2:C0:T0:L0',
        'vmhba3:C0:T0:L0',
        'vmhba4:C0:T0:L0',
    ]
}
name

Mandatory state name

diskgroups

Disk group representation containing scsi disk addresses. Scsi addresses are expected for disks in the diskgroup:

erase_disks

Specifies whether to erase all partitions on all disks member of the disk group before the disk group is created. Default value is False.

salt.states.esxi.host_cache_configured(name, enabled, datastore, swap_size='100%', dedicated_backing_disk=False, erase_backing_disk=False)

Configures the host cache used for swapping.

It will do the following:

  1. Checks if backing disk exists

  2. Creates the VMFS datastore if doesn't exist (datastore partition will be created and use the entire disk)

  3. Raises an error if dedicated_backing_disk is True and partitions already exist on the backing disk

  4. Configures host_cache to use a portion of the datastore for caching (either a specific size or a percentage of the datastore)

Examples

Percentage swap size (can't be 100%)

{
    'enabled': true,
    'datastore': {
        'backing_disk_scsi_addr': 'vmhba0:C0:T0:L0',
        'vmfs_version': 5,
        'name': 'hostcache'
        }
    'dedicated_backing_disk': false
    'swap_size': '98%',
}

Fixed sized swap size

{
    'enabled': true,
    'datastore': {
        'backing_disk_scsi_addr': 'vmhba0:C0:T0:L0',
        'vmfs_version': 5,
        'name': 'hostcache'
        }
    'dedicated_backing_disk': true
    'swap_size': '10GiB',
}
name

Mandatory state name.

enabled

Specifies whether the host cache is enabled.

datastore

Specifies the host cache datastore.

swap_size

Specifies the size of the host cache swap. Can be a percentage or a value in GiB. Default value is 100%.

dedicated_backing_disk

Specifies whether the backing disk is dedicated to the host cache which means it must have no other partitions. Default is False

erase_backing_disk

Specifies whether to erase all partitions on the backing disk before the datastore is created. Default value is False.

salt.states.esxi.ntp_configured(name, service_running, ntp_servers=None, service_policy=None, service_restart=False, update_datetime=False)

Ensures a host's NTP server configuration such as setting NTP servers, ensuring the NTP daemon is running or stopped, or restarting the NTP daemon for the ESXi host.

name

Name of the state.

service_running

Ensures the running state of the ntp daemon for the host. Boolean value where True indicates that ntpd should be running and False indicates that it should be stopped.

ntp_servers

A list of servers that should be added to the ESXi host's NTP configuration.

service_policy

The policy to set for the NTP service.

Note

When setting the service policy to off or on, you must quote the setting. If you don't, the yaml parser will set the string to a boolean, which will cause trouble checking for stateful changes and will error when trying to set the policy on the ESXi host.

service_restart

If set to True, the ntp daemon will be restarted, regardless of its previous running state. Default is False.

update_datetime

If set to True, the date/time on the given host will be updated to UTC. Default setting is False. This option should be used with caution since network delays and execution delays can result in time skews.

Example:

configure-host-ntp:
  esxi.ntp_configured:
    - service_running: True
    - ntp_servers:
      - 192.174.1.100
      - 192.174.1.200
    - service_policy: 'on'
    - service_restart: True
salt.states.esxi.password_present(name, password)

Ensures the given password is set on the ESXi host. Passwords cannot be obtained from host, so if a password is set in this state, the vsphere.update_host_password function will always run (except when using test=True functionality) and the state's changes dictionary will always be populated.

The username for which the password will change is the same username that is used to authenticate against the ESXi host via the Proxy Minion. For example, if the pillar definition for the proxy username is defined as root, then the username that the password will be updated for via this state is root.

name

Name of the state.

password

The new password to change on the host.

Example:

configure-host-password:
  esxi.password_present:
    - password: 'new-bad-password'
salt.states.esxi.ssh_configured(name, service_running, ssh_key=None, ssh_key_file=None, service_policy=None, service_restart=False, certificate_verify=None)

Manage the SSH configuration for a host including whether or not SSH is running or the presence of a given SSH key. Note: Only one ssh key can be uploaded for root. Uploading a second key will replace any existing key.

name

Name of the state.

service_running

Ensures whether or not the SSH service should be running on a host. Represented as a boolean value where True indicates that SSH should be running and False indicates that SSH should stopped.

In order to update SSH keys, the SSH service must be running.

ssh_key

Public SSH key to added to the authorized_keys file on the ESXi host. You can use ssh_key or ssh_key_file, but not both.

ssh_key_file

File containing the public SSH key to be added to the authorized_keys file on the ESXi host. You can use ssh_key_file or ssh_key, but not both.

service_policy

The policy to set for the NTP service.

Note

When setting the service policy to off or on, you must quote the setting. If you don't, the yaml parser will set the string to a boolean, which will cause trouble checking for stateful changes and will error when trying to set the policy on the ESXi host.

service_restart

If set to True, the SSH service will be restarted, regardless of its previous running state. Default is False.

certificate_verify

If set to True, the SSL connection must present a valid certificate. Default is True.

Example:

configure-host-ssh:
  esxi.ssh_configured:
    - service_running: True
    - ssh_key_file: /etc/salt/ssh_keys/my_key.pub
    - service_policy: 'on'
    - service_restart: True
    - certificate_verify: True
salt.states.esxi.syslog_configured(name, syslog_configs, firewall=True, reset_service=True, reset_syslog_config=False, reset_configs=None)

Ensures the specified syslog configuration parameters. By default, this state will reset the syslog service after any new or changed parameters are set successfully.

name

Name of the state.

syslog_configs

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

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

Each syslog_config option also needs a configuration value to set. For example, loghost requires 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)

firewall

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

reset_service

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

reset_syslog_config

Resets the syslog service to its default settings. Defaults to False. If set to True, default settings defined by the list of syslog configs in reset_configs will be reset before running any other syslog settings.

reset_configs

A comma-delimited list of parameters to reset. Only runs if reset_syslog_config is set to True. If reset_syslog_config is set to True, but no syslog configs are listed in reset_configs, then reset_configs will be set to all by default.

See syslog_configs parameter above for a list of valid options.

Example:

configure-host-syslog:
  esxi.syslog_configured:
    - syslog_configs:
        loghost: ssl://localhost:5432,tcp://10.1.0.1:1514
        default-timeout: 120
    - firewall: True
    - reset_service: True
    - reset_syslog_config: True
    - reset_configs: loghost,default-timeout
salt.states.esxi.vmotion_configured(name, enabled, device='vmk0')

Configures a host's VMotion properties such as enabling VMotion and setting the device VirtualNic that VMotion will use.

name

Name of the state.

enabled

Ensures whether or not VMotion should be enabled on a host as a boolean value where True indicates that VMotion should be enabled and False indicates that VMotion should be disabled.

device

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

Example:

configure-vmotion:
  esxi.vmotion_configured:
    - enabled: True
    - device: sample-device
salt.states.esxi.vsan_configured(name, enabled, add_disks_to_vsan=False)

Configures a host's VSAN properties such as enabling or disabling VSAN, or adding VSAN-eligible disks to the VSAN system for the host.

name

Name of the state.

enabled

Ensures whether or not VSAN should be enabled on a host as a boolean value where True indicates that VSAN should be enabled and False indicates that VSAN should be disabled.

add_disks_to_vsan

If set to True, any VSAN-eligible disks for the given host will be added to the host's VSAN system. Default is False.

Example:

configure-host-vsan:
  esxi.vsan_configured:
    - enabled: True
    - add_disks_to_vsan: True