vsphere_guest – Create/delete/manage a guest VM through VMware vSphere — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# vsphere_guest – Create/delete/manage a guest VM through VMware vSphere

- DEPRECATED
- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Status

## DEPRECATED

Removed in Ansible:
| version: 2.9
Why: | Replaced by vmware_guest module. Also, ‘Pysphere’ is deprecated in favor of VMware’s Official Python bindings - ‘Pyvmomi’.
Alternative: | Use vmware_guest and other vmware guest related modules instead.

## Synopsis

- Create/delete/reconfigure a guest VM through VMware vSphere. This module has a dependency on pysphere >= 1.7

## Requirements

The below requirements are needed on the host that executes this module.

- python >= 2.6
- pysphere

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
cluster - |  | The name of the cluster to create the VM in. By default this is derived from the host you tell the module to build the guest on.
esxi - |  | Dictionary which includes datacenter and hostname on which the VM should be created. For standalone ESXi hosts, ha-datacenter should be used as the datacenter name
force boolean | Choices: no ← yes | Boolean. Allows you to run commands which may alter the running state of a guest. Also used to reconfigure and destroy.
from_template boolean | Choices: no ← yes | Specifies if the VM should be deployed from a template (mutually exclusive with 'state' parameter). No guest customization changes to hardware such as CPU, RAM, NICs or Disks can be applied when launching from template.
guest - / required |  | The virtual server name you wish to manage.
password - / required |  | Password of the user to connect to vcenter as.
power_on_after_clone boolean | Choices: no yes ← | Specifies if the VM should be powered on after the clone.
resource_pool - |  | The name of the resource_pool to create the VM in.
snapshot_to_clone - added in 2.0 |  | A string that when specified, will create a linked clone copy of the VM. Snapshot must already be taken in vCenter.
state - | Choices: present ← powered_off absent powered_on restarted reconfigured reboot_guest poweroff_guest | Indicate desired state of the vm. 'reconfigured' only applies changes to 'vm_cdrom', 'memory_mb', and 'num_cpus' in vm_hardware parameter. The 'memory_mb' and 'num_cpus' changes are applied to powered-on vms when hot-plugging is enabled for the guest.
template_src - |  | Name of the source template to deploy from
username - / required |  | Username to connect to vcenter as.
validate_certs boolean added in 2.1 | Choices: no yes ← | Validate SSL certs. Note, if running on python without SSLContext support (typically, python < 2.7.9) you will have to set this to `no` as pysphere does not support validating certificates on older python. Prior to 2.1, this module would always validate on python >= 2.7.9 and never validate on python <= 2.7.8.
vcenter_hostname - / required |  | The hostname of the vcenter server the module will connect to, to create the guest.
vm_disk - |  | A key, value list of disks and their sizes and which datastore to keep it in.
vm_extra_config - |  | A key, value pair of any extra values you want set or changed in the vmx file of the VM. Useful to set advanced options on the VM.
vm_hardware - |  | A key, value list of VM config settings. Must include ['memory_mb', 'num_cpus', 'osid', 'scsi'].
vm_hw_version - |  | Desired hardware version identifier (for example, "vmx-08" for vms that needs to be managed with vSphere Client). Note that changing hardware version of existing vm is not supported.
vm_nic - |  | A key, value list of nics, their types and what network to put them on. Optionaly with their MAC address.
vmware_guest_facts boolean | Choices: no yes | Gather facts from vCenter on a particular VM

## Notes

Note

- This module should run from a system that can access vSphere directly. Either by using local_action, or using delegate_to.

## Examples

    ---
    # Create a new VM on an ESX server
    # Returns changed = False when the VM already exists
    # Returns changed = True and a adds ansible_facts from the new VM
    # State will set the power status of a guest upon creation. Use powered_on to create and boot.
    # Options ['state', 'vm_extra_config', 'vm_disk', 'vm_nic', 'vm_hardware', 'esxi'] are required together
    # Note: vm_floppy support added in 2.0

    - vsphere_guest:
        vcenter_hostname: vcenter.mydomain.local
        username: myuser
        password: mypass
        guest: newvm001
        state: powered_on
        vm_extra_config:
          vcpu.hotadd: yes
          mem.hotadd:  yes
          notes: This is a test VM
          folder: MyFolder
        vm_disk:
          disk1:
            size_gb: 10
            type: thin
            datastore: storage001
            # VMs can be put into folders. The value given here is either the full path
            # to the folder (e.g. production/customerA/lamp) or just the last component
            # of the path (e.g. lamp):
            folder: production/customerA/lamp
        vm_nic:
          nic1:
            type: vmxnet3
            network: VM Network
            network_type: standard
          nic2:
            type: vmxnet3
            network: dvSwitch Network
            network_type: dvs
        vm_hardware:
          memory_mb: 2048
          num_cpus: 2
          osid: centos64Guest
          scsi: paravirtual
          vm_cdrom:
            type: "iso"
            iso_path: "DatastoreName/cd-image.iso"
          vm_floppy:
            type: "image"
            image_path: "DatastoreName/floppy-image.flp"
        esxi:
          datacenter: MyDatacenter
          hostname: esx001.mydomain.local
      delegate_to: localhost

    # Reconfigure the CPU and Memory on the newly created VM
    # Will return the changes made

    - vsphere_guest:
        vcenter_hostname: vcenter.mydomain.local
        username: myuser
        password: mypass
        guest: newvm001
        state: reconfigured
        vm_extra_config:
          vcpu.hotadd: yes
          mem.hotadd:  yes
          notes: This is a test VM
        vm_disk:
          disk1:
            size_gb: 10
            type: thin
            datastore: storage001
        vm_nic:
          nic1:
            type: vmxnet3
            network: VM Network
            network_type: standard
        vm_hardware:
          memory_mb: 4096
          num_cpus: 4
          osid: centos64Guest
          scsi: paravirtual
        esxi:
          datacenter: MyDatacenter
          hostname: esx001.mydomain.local
      delegate_to: localhost

    # Deploy a guest from a template
    - vsphere_guest:
        vcenter_hostname: vcenter.mydomain.local
        username: myuser
        password: mypass
        guest: newvm001
        from_template: yes
        template_src: centosTemplate
        cluster: MainCluster
        resource_pool: "/Resources"
        vm_extra_config:
          folder: MyFolder
      delegate_to: localhost

    # Task to gather facts from a vSphere cluster only if the system is a VMware guest
    - vsphere_guest:
        vcenter_hostname: vcenter.mydomain.local
        username: myuser
        password: mypass
        guest: newvm001
        vmware_guest_facts: yes
      delegate_to: localhost

    ---
    # Typical output of a vsphere_facts run on a guest
    # If vmware tools is not installed, ipaddresses with return None

    - hw_eth0:
      - addresstype: "assigned"
        label: "Network adapter 1"
        macaddress: "00:22:33:33:44:55"
        macaddress_dash: "00-22-33-33-44-55"
        ipaddresses: ['192.0.2.100', '2001:DB8:56ff:feac:4d8a']
        summary: "VM Network"
      hw_guest_full_name: "newvm001"
      hw_guest_id: "rhel6_64Guest"
      hw_memtotal_mb: 2048
      hw_name: "centos64Guest"
      hw_power_status: "POWERED ON"
      hw_processor_count: 2
      hw_product_uuid: "ef50bac8-2845-40ff-81d9-675315501dac"

    # hw_power_status will be one of the following values:
    #   - POWERED ON
    #   - POWERED OFF
    #   - SUSPENDED
    #   - POWERING ON
    #   - POWERING OFF
    #   - SUSPENDING
    #   - RESETTING
    #   - BLOCKED ON MSG
    #   - REVERTING TO SNAPSHOT
    #   - UNKNOWN
    # as seen in the VMPowerState-Class of PySphere: http://git.io/vlwOq

    ---
    # Remove a vm from vSphere
    # The VM must be powered_off or you need to use force to force a shutdown
    - vsphere_guest:
        vcenter_hostname: vcenter.mydomain.local
        username: myuser
        password: mypass
        guest: newvm001
        state: absent
        force: yes
      delegate_to: localhost

## Status

- This module will be removed in version 2.9. [deprecated]
- For more information see DEPRECATED.

### Authors

- Richard Hoop (@rhoop) <wrhoop@gmail.com>

Hint

If you notice any issues in this documentation you can edit this document to improve it.