# salt.states.esxi

Manage VMware ESXi Hosts.

Warning

This module will be deprecated in a future release of Salt. VMware strongly recommends using the VMware Salt extensions instead of the ESXi module. Because the Salt extensions are newer and actively supported by VMware, they are more compatible with current versions of ESXi and they work well with the latest features in the VMware product line.

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