Support cloning VMs into a specific VM folder

The pysphere VIVirtualMachine.clone() method supports specifying a VM
folder to place the VM in after the clone has completed.  This exposes
that functionality to playbooks.

Also documents that creating VMs could always place VMs in a specific
folder.

lib/ansible/modules/cloud/vmware/vsphere_guest.py

@@ -170,6 +170,7 @@ EXAMPLES = '''
       vcpu.hotadd: yes
       mem.hotadd:  yes
       notes: This is a test VM
+      folder: MyFolder
     vm_disk:
       disk1:
         size_gb: 10
@@ -238,6 +239,8 @@ EXAMPLES = '''
     template_src: centosTemplate
     cluster: MainCluster
     resource_pool: "/Resources"
+    vm_extra_config:
+      folder: MyFolder
 
 # Task to gather facts from a vSphere cluster only if the system is a VMWare guest
 
@@ -594,7 +597,7 @@ def vmdisk_id(vm, current_datastore_name):
     return id_list
 
 
-def deploy_template(vsphere_client, guest, resource_pool, template_src, esxi, module, cluster_name, snapshot_to_clone, power_on_after_clone):
+def deploy_template(vsphere_client, guest, resource_pool, template_src, esxi, module, cluster_name, snapshot_to_clone, power_on_after_clone, vm_extra_config):
     vmTemplate = vsphere_client.get_vm_by_name(template_src)
     vmTarget = None
 
@@ -686,6 +689,10 @@ def deploy_template(vsphere_client, guest, resource_pool, template_src, esxi, mo
                 cloneArgs["linked"] = True
                 cloneArgs["snapshot"] = snapshot_to_clone
 
+            if vm_extra_config.get("folder") is not None:
+                # if a folder is specified, clone the VM into it
+                cloneArgs["folder"] = vm_extra_config.get("folder")
+
             vmTemplate.clone(guest, **cloneArgs)
             changed = True
         else:
@@ -1521,7 +1528,8 @@ def main():
                 module=module,
                 cluster_name=cluster,
                 snapshot_to_clone=snapshot_to_clone,
-                power_on_after_clone=power_on_after_clone
+                power_on_after_clone=power_on_after_clone,
+                vm_extra_config=vm_extra_config
             )
 
         if state in ['restarted', 'reconfigured']: