vmware_vm_info – Return basic info pertaining to a VMware machine guest¶
Synopsis¶
- Return basic information pertaining to a vSphere or ESXi virtual machine guest.
- Cluster name as fact is added in version 2.7.
- This module was called
vmware_vm_facts
before Ansible 2.9. The usage did not change.
Aliases: vmware_vm_facts
Requirements¶
The below requirements are needed on the host that executes this module.
- python >= 2.6
- PyVmomi
Parameters¶
Parameter | Choices/Defaults | Comments |
---|---|---|
folder
string
added in 2.9 |
Specify a folder location of VMs to gather information from.
Examples:
folder: /ha-datacenter/vm
folder: ha-datacenter/vm
folder: /datacenter1/vm
folder: datacenter1/vm
folder: /datacenter1/vm/folder1
folder: datacenter1/vm/folder1
folder: /folder1/datacenter1/vm
folder: folder1/datacenter1/vm
folder: /folder1/datacenter1/vm/folder2
|
|
hostname
string
|
The hostname or IP address of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_HOST will be used instead.Environment variable support added in Ansible 2.6.
|
|
password
string
|
The password of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_PASSWORD will be used instead.Environment variable support added in Ansible 2.6.
aliases: pass, pwd |
|
port
integer
added in 2.5 |
Default: 443
|
The port number of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_PORT will be used instead.Environment variable support added in Ansible 2.6.
|
proxy_host
string
added in 2.9 |
Address of a proxy that will receive all HTTPS requests and relay them.
The format is a hostname or a IP.
If the value is not specified in the task, the value of environment variable
VMWARE_PROXY_HOST will be used instead.This feature depends on a version of pyvmomi greater than v6.7.1.2018.12
|
|
proxy_port
integer
added in 2.9 |
Port of the HTTP proxy that will receive all HTTPS requests and relay them.
If the value is not specified in the task, the value of environment variable
VMWARE_PROXY_PORT will be used instead. |
|
show_attribute
boolean
added in 2.8 |
|
Attributes related to VM guest shown in information only when this is set
true . |
show_tag
boolean
added in 2.9 |
|
Tags related to virtual machine are shown if set to
True . |
username
string
|
The username of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_USER will be used instead.Environment variable support added in Ansible 2.6.
aliases: admin, user |
|
validate_certs
boolean
|
|
Allows connection when SSL certificates are not valid. Set to
false when certificates are not trusted.If the value is not specified in the task, the value of environment variable
VMWARE_VALIDATE_CERTS will be used instead.Environment variable support added in Ansible 2.6.
If set to
yes , please make sure Python >= 2.7.9 is installed on the given machine. |
vm_type
string
added in 2.5 |
|
If set to
vm , then information are gathered for virtual machines only.If set to
template , then information are gathered for virtual machine templates only.If set to
all , then information are gathered for all virtual machines and virtual machine templates. |
Notes¶
Note
- Tested on ESXi 6.7, vSphere 5.5 and vSphere 6.5
- From 2.8 and onwards, information are returned as list of dict instead of dict.
Examples¶
- name: Gather all registered virtual machines
vmware_vm_info:
hostname: '{{ vcenter_hostname }}'
username: '{{ vcenter_username }}'
password: '{{ vcenter_password }}'
delegate_to: localhost
register: vminfo
- debug:
var: vminfo.virtual_machines
- name: Gather only registered virtual machine templates
vmware_vm_info:
hostname: '{{ vcenter_hostname }}'
username: '{{ vcenter_username }}'
password: '{{ vcenter_password }}'
vm_type: template
delegate_to: localhost
register: template_info
- debug:
var: template_info.virtual_machines
- name: Gather only registered virtual machines
vmware_vm_info:
hostname: '{{ vcenter_hostname }}'
username: '{{ vcenter_username }}'
password: '{{ vcenter_password }}'
vm_type: vm
delegate_to: localhost
register: vm_info
- debug:
var: vm_info.virtual_machines
- name: Get UUID from given VM Name
block:
- name: Get virtual machine info
vmware_vm_info:
hostname: '{{ vcenter_hostname }}'
username: '{{ vcenter_username }}'
password: '{{ vcenter_password }}'
folder: "/datacenter/vm/folder"
delegate_to: localhost
register: vm_info
- debug:
msg: "{{ item.uuid }}"
with_items:
- "{{ vm_info.virtual_machines | json_query(query) }}"
vars:
query: "[?guest_name=='DC0_H0_VM0']"
- name: Get Tags from given VM Name
block:
- name: Get virtual machine info
vmware_vm_info:
hostname: '{{ vcenter_hostname }}'
username: '{{ vcenter_username }}'
password: '{{ vcenter_password }}'
folder: "/datacenter/vm/folder"
delegate_to: localhost
register: vm_info
- debug:
msg: "{{ item.tags }}"
with_items:
- "{{ vm_info.virtual_machines | json_query(query) }}"
vars:
query: "[?guest_name=='DC0_H0_VM0']"
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
virtual_machines
list
|
success |
list of dictionary of virtual machines and their information
Sample:
[{'guest_name': 'ubuntu_t', 'cluster': None, 'esxi_hostname': '10.76.33.226', 'guest_fullname': 'Ubuntu Linux (64-bit)', 'ip_address': '', 'mac_address': ['00:50:56:87:a5:9a'], 'power_state': 'poweredOff', 'uuid': '4207072c-edd8-3bd5-64dc-903fd3a0db04', 'vm_network': {'00:50:56:87:a5:9a': {'ipv4': ['10.76.33.228'], 'ipv6': []}}, 'attributes': {'job': 'backup-prepare'}, 'tags': [{'category_id': 'urn:vmomi:InventoryServiceCategory:b316cc45-f1a9-4277-811d-56c7e7975203:GLOBAL', 'category_name': 'cat_0001', 'description': '', 'id': 'urn:vmomi:InventoryServiceTag:43737ec0-b832-4abf-abb1-fd2448ce3b26:GLOBAL', 'name': 'tag_0001'}]}]
|
Status¶
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors¶
- Joseph Callen (@jcpowermac)
- Abhijeet Kasurde (@Akasurde)
- Fedor Vompe (@sumkincpp)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.