Ready for pull request

library/cloud/vsphere_guest

@@ -20,6 +20,196 @@ try:
 except ImportError:
     pass
 
+DOCUMENTATION = '''
+---
+module: vsphere_guest
+short_description: Create/delete/manage a guest VM through VMware vSphere.
+description:
+     - Create/delete/reconfigure a guest VM through VMware vSphere. This module has a dependency on pysphere >= 1.7
+version_added: "1.5"
+options:
+  vcenter_hostname:
+    description:
+      - The hostname of the vcenter server the module will connect to, to create the guest.
+    required: true
+    default: null
+    aliases: []
+  guest:
+    description:
+      - The virtual server name you wish to manage.
+    required: true
+  user:
+    description:
+      - Username to connect to vcenter as.
+    required: true
+    default: null
+  password:
+    description:
+      - Password of the user to connect to vcenter as.
+    required: true
+    default: null
+  resource_pool:
+    description:
+      - The name of the resource_pool to create the VM in.
+    required: false
+    default: None
+  cluster:
+    description:
+      - 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.
+    required: false
+    default: None
+  esxi:
+    description:
+      - Dictionary which includes datacenter and hostname on which the VM should be created.
+    required: false
+    default: null
+  state:
+    description:
+     - Indicate desired state of the vm.
+    default: present
+    choices: ['present', 'powered_on', 'absent', 'powered_on', 'restarted', 'reconfigured']
+  vm_disk:
+    description:
+      - A key, value list of disks and their sizes and which datastore to keep it in.
+    required: false
+    default: null
+  vm_hardware:
+    description:
+      - A key, value list of VM config settings. Must include ['memory_mb', 'num_cpus', 'osid', 'scsi'].
+    required: false
+    default: null
+  vm_nic:
+    description:
+      - A key, value list of nics, their types and what network to put them on.
+    required: false
+    default: null
+  vm_extra_config:
+    description:
+      - 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.
+    required: false
+    default: null
+  vmware_guest_facts:
+    description:
+      - Gather facts from vCenter on a particular VM
+    required: false
+    default: null
+  force:
+    description:
+      - Boolean. Allows you to run commands which may alter the running state of a guest. Also used to reconfigure and destroy.
+    default: "no"
+    choices: [ "yes", "no" ]
+
+notes:
+  - This module should run from a system that can access vSphere directly.
+    Either by using local_action, or using delegate_to.
+requirements: [ pysphere ]
+'''
+
+
+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
+
+- 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
+    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: 2048
+      num_cpus: 2
+      osid: centos64Guest
+      scsi: paravirtual
+    esxi:
+      datacenter: MyDatacenter
+      hostname: esx001.mydomain.local
+
+# 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
+
+# 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
+
+
+# Typical output of a vsphere_facts run on a guest
+
+- hw_eth0:
+  - addresstype: "assigned"
+    label: "Network adapter 1"
+    macaddress: "00:22:33:33:44:55"
+    macaddress_dash: "00-22-33-33-44-55"
+    summary: "VM Network"
+  hw_guest_full_name: "newvm001"
+  hw_guest_id: "rhel6_64Guest"
+  hw_memtotal_mb: 2048
+  hw_name: "centos64Guest"
+  hw_processor_count: 2
+  hw_product_uuid: "ef50bac8-2845-40ff-81d9-675315501dac"
+
+# Remove a vm from vSphere
+# The VM must be powered_off of 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
+'''
 
 def add_scsi_controller(module, s, config, devices, type="paravirtual", bus_num=0, disk_ctrl_key=1):
     # add a scsi controller