Add ability to get vmware_guest_facts using vsphere schema output (#47446)

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

@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 #
 # This module is also sponsored by E.T.A.I. (www.etai.fr)
+# Copyright (C) 2018 James E. King III (@jeking3) <jking@apache.org>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
@@ -25,7 +26,7 @@ version_added: 2.3
 author:
     - Loic Blot (@nerzhul) <loic.blot@unix-experience.fr>
 notes:
-    - Tested on vSphere 5.5
+    - Tested on vSphere 5.5, 6.7
 requirements:
     - "python >= 2.6"
     - PyVmomi
@@ -79,6 +80,32 @@ options:
      default: 'no'
      type: bool
      version_added: '2.8'
+   schema:
+     description:
+     - Specify the output schema desired.
+     - The 'summary' output schema is the legacy output from the module
+     - The 'vsphere' output schema is the vSphere API class definition
+       which requires pyvmomi>6.7.1
+     choices: ['summary', 'vsphere']
+     default: 'summary'
+     type: str
+     version_added: '2.8'
+   properties:
+     description:
+     - Specify the properties to retrieve.
+     - If not specified, all properties are retrieved (deeply).
+     - Results are returned in a structure identical to the vsphere API.
+     - 'Example:'
+     - '   properties: ['
+     - '      "config.hardware.memoryMB",'
+     - '      "config.hardware.numCPU",'
+     - '      "guest.disk",'
+     - '      "overallStatus"'
+     - '   ]'
+     - Only valid when C(schema) is C(vsphere).
+     type: list
+     required: False
+     version_added: '2.8'
 extends_documentation_fragment: vmware.documentation
 '''
 
@@ -93,6 +120,19 @@ EXAMPLES = '''
     uuid: 421e4592-c069-924d-ce20-7e7533fab926
   delegate_to: localhost
   register: facts
+
+- name: Gather some facts from a guest using the vSphere API output schema
+  vmware_guest_facts:
+    hostname: "{{ vcenter_hostname }}"
+    username: "{{ vcenter_username }}"
+    password: "{{ vcenter_password }}"
+    validate_certs: no
+    datacenter: "{{ datacenter_name }}"
+    name: "{{ vm_name }}"
+    schema: "vsphere"
+    properties: ["config.hardware.memoryMB", "guest.disk", "overallStatus"]
+  delegate_to: localhost
+  register: facts
 '''
 
 RETURN = """
@@ -168,11 +208,6 @@ except ImportError:
     HAS_VCLOUD = False
 
 
-class PyVmomiHelper(PyVmomi):
-    def __init__(self, module):
-        super(PyVmomiHelper, self).__init__(module)
-
-
 class VmwareTag(VmwareRestClient):
     def __init__(self, module):
         super(VmwareTag, self).__init__(module)
@@ -189,7 +224,9 @@ def main():
         use_instance_uuid=dict(type='bool', default=False),
         folder=dict(type='str'),
         datacenter=dict(type='str', required=True),
-        tags=dict(type='bool', default=False)
+        tags=dict(type='bool', default=False),
+        schema=dict(type='str', choices=['summary', 'vsphere'], default='summary'),
+        properties=dict(type='list')
     )
     module = AnsibleModule(argument_spec=argument_spec,
                            required_one_of=[['name', 'uuid']])
@@ -199,14 +236,21 @@ def main():
         # so we should leave the input folder path unmodified
         module.params['folder'] = module.params['folder'].rstrip('/')
 
-    pyv = PyVmomiHelper(module)
+    if module.params['schema'] != 'vsphere' and module.params.get('properties'):
+        module.fail_json(msg="The option 'properties' is only valid when the schema is 'vsphere'")
+
+    pyv = PyVmomi(module)
     # Check if the VM exists before continuing
     vm = pyv.get_vm()
 
     # VM already exists
     if vm:
         try:
-            instance = pyv.gather_facts(vm)
+            if module.params['schema'] == 'summary':
+                instance = pyv.gather_facts(vm)
+            else:
+                instance = pyv.to_json(vm, module.params['properties'])
+
             if module.params.get('tags'):
                 if not HAS_VCLOUD:
                     module.fail_json(msg="Unable to find 'vCloud Suite SDK' Python library which is required."