# salt.pillar.vmware_pillar

Pillar data from vCenter or an ESXi host

Added in version 2017.7.0.

depends:

  - pyVmomi

This external pillar can pull attributes from objects in vCenter or an ESXi host and provide those attributes as pillar data to minions. This can allow for pillar based targeting of minions on ESXi host, Datastore, VM configuration, etc. This setup requires only the salt master have access to the vCenter server/ESXi hosts.

The pillar will return an empty dict if the 'os' or 'virtual' grain are not 'VMWare', 'ESXi', or 'VMWare ESXi'.

## Defaults

- The external pillar will search for Virtual Machines with the VM name matching the minion id.

- Data will be returned into the 'vmware' pillar key.

- The external pillar has a default set of properties to return for both VirtualMachine and HostSystem types.

## Configuring the VMWare pillar

The required minimal configuration in the salt master ext_pillar setup:

    ext_pillar:
        - vmware:
            host: <vcenter/esx host>
            username: <user to connect with>
            password: <password>

Optionally, the following keyword arguments can be passed to the ext_pillar for customized configuration:

> pillar_key

>   Optionally set the pillar key to return the data into. Default is `vmware`.

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

> property_name

>   Property name to match the minion id against. Defaults to `name`.

> property_types

>   Optionally specify a list of pyVmomi vim types to search for the minion id in 'property_name'. Default is `['VirtualMachine']`.

>   For example, to search both vim.VirtualMachine and vim.HostSystem object types:

>       ext_pillar:
>           - vmware:
>               host: myesx
>               username: root
>               password: complex_password
>               property_types:
>                 - VirtualMachine
>                 - HostSystem

>   Additionally, the list of property types can be dicts, the item of the dict being a list specifying the attribute to return for that vim object type.

>   The pillar will attempt to recurse the attribute and return all child attributes.

>   To explicitly specify deeper attributes without attempting to recurse an attribute, convert the list item to a dict with the item of the dict being the child attributes to return. Follow this pattern to return attributes as deep within the object as necessary.

>   Note

>   Be careful when specifying custom attributes! Many attributes have objects as attributes which have the parent object as an attribute and which will cause the pillar to fail due to the attempt to convert all sub-objects recursively (i.e. infinite attribute loops). Specifying only the sub-attributes you would like returned will keep the infinite recursion from occurring.

>   A maximum recursion exception will occur in this case and the pillar will not return as desired.

>       ext_pillar:
>           - vmware:
>               host: myvcenter
>               username: my_user
>               password: my_pass
>               replace_default_attributes: True
>               property_types:
>                 - VirtualMachine:
>                     - config:
>                        - bootOptions:
>                            - bootDelay
>                            - bootRetryDelay
>                 - HostSystem:
>                     - datastore:
>                        - name

>   The above ext_pillar example would return a pillar like the following for a VirtualMachine object that's name matched the minion id:

>       vmware:
>         config:
>           bootOptions:
>             bootDelay: 1000
>             bootRetryDelay: 1000

>   If you were to retrieve these virtual machine attributes via pyVmomi directly, this would be the same as

>       vmObject.config.bootOptions.bootDelay
>       vmObject.config.bootOptionis.bootRetryDelay

>   The above ext_pillar example would return a pillar like the following for a HostySystem object that's name matched the minion id:

>       vmware:
>         datastore:
>            - name: Datastore1
>            - name: Datastore2

>   The 'datastore' property of a HostSystem object is a list of datastores, thus a list is returned.

> replace_default_attributes

>   If custom attributes are specified by the property_types parameter, replace_default_attributes determines if those will be added to default attributes (False) or replace the default attributes completely (True). The default setting is 'False'.

>   Note

>   vCenter "Custom Attributes" (i.e. Annotations) will always be returned if it exists on the object as part of the pillar regardless of this setting.

salt.pillar.vmware_pillar.ext_pillar(minion_id, pillar, **kwargs)

  Check vmware/vcenter for all data