centralize argument spec

changelogs/fragments/87-centralize-spec-args.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - pyvmomi doc fragments - Remove redundant 'vcenter_documentation' fragment. Add proxy protocol documentation to all modules for simplicity. Remove redundant cluster and datastore docs

plugins/module_utils/_vmware.py

@@ -32,54 +32,14 @@
     PYVMOMI_IMP_ERR = traceback.format_exc()
     HAS_PYVMOMI = False
 
-from ansible.module_utils.basic import env_fallback, missing_required_lib
+from ansible.module_utils.basic import missing_required_lib
 
 
 class ApiAccessError(Exception):
     def __init__(self, *args, **kwargs):
         super(ApiAccessError, self).__init__(*args, **kwargs)
 
 
-def vmware_argument_spec():
-    return dict(
-        hostname=dict(type='str',
-                      required=False,
-                      fallback=(env_fallback, ['VMWARE_HOST']),
-                      ),
-        username=dict(type='str',
-                      aliases=['user', 'admin'],
-                      required=False,
-                      fallback=(env_fallback, ['VMWARE_USER'])),
-        password=dict(type='str',
-                      aliases=['pass', 'pwd'],
-                      required=False,
-                      no_log=True,
-                      fallback=(env_fallback, ['VMWARE_PASSWORD'])),
-        cluster=dict(type='str',
-                     aliases=['cluster_name'],
-                     required=False),
-        datacenter=dict(type='str',
-                        aliases=['datacenter_name'],
-                        required=False),
-        port=dict(type='int',
-                  default=443,
-                  fallback=(env_fallback, ['VMWARE_PORT'])),
-        validate_certs=dict(type='bool',
-                            required=False,
-                            default=True,
-                            fallback=(env_fallback, ['VMWARE_VALIDATE_CERTS'])
-                            ),
-        proxy_host=dict(type='str',
-                        required=False,
-                        default=None,
-                        fallback=(env_fallback, ['VMWARE_PROXY_HOST'])),
-        proxy_port=dict(type='int',
-                        required=False,
-                        default=None,
-                        fallback=(env_fallback, ['VMWARE_PROXY_PORT'])),
-    )
-
-
 def connect_to_api(module, disconnect_atexit=True, return_si=False, hostname=None, username=None, password=None,
                    port=None, validate_certs=None,
                    httpProxyHost=None, httpProxyPort=None):

plugins/module_utils/_vmware_argument_spec.py

@@ -0,0 +1,72 @@
+from ansible.module_utils.basic import env_fallback
+
+
+def rest_compatible_argument_spec():
+    """
+    This returns a dictionary that can be used as the baseline for all REST module specs.
+    If your module uses the REST API, you should use this instead of the base_argument_spec.
+    If your module uses both this and the pyvmomi SDK, you should still use this spec.
+    """
+    return {
+        **base_argument_spec(),
+        **dict(
+            proxy_protocol=dict(
+                type='str',
+                default='https',
+                choices=['https', 'http'],
+                aliases=['protocol']
+            ),
+        )
+    }
+
+
+def base_argument_spec():
+    """
+    This returns a dictionary that can be used as the baseline for all vmware module specs. Any arguments
+    common to both the REST API SDK and pyvmomi SDK should be placed here.
+    If your module uses the REST API, you should use the rest_compatible_argument_spec since that
+    includes additional arguments specific to that SDK.
+    """
+    return dict(
+        hostname=dict(
+            type='str',
+            required=False,
+            fallback=(env_fallback, ['VMWARE_HOST']),
+        ),
+        username=dict(
+            type='str',
+            aliases=['user', 'admin'],
+            required=False,
+            fallback=(env_fallback, ['VMWARE_USER'])
+        ),
+        password=dict(
+            type='str',
+            aliases=['pass', 'pwd'],
+            required=False,
+            no_log=True,
+            fallback=(env_fallback, ['VMWARE_PASSWORD'])
+        ),
+        port=dict(
+            type='int',
+            default=443,
+            fallback=(env_fallback, ['VMWARE_PORT'])
+        ),
+        validate_certs=dict(
+            type='bool',
+            required=False,
+            default=True,
+            fallback=(env_fallback, ['VMWARE_VALIDATE_CERTS'])
+        ),
+        proxy_host=dict(
+            type='str',
+            required=False,
+            default=None,
+            fallback=(env_fallback, ['VMWARE_PROXY_HOST'])
+        ),
+        proxy_port=dict(
+            type='int',
+            required=False,
+            default=None,
+            fallback=(env_fallback, ['VMWARE_PROXY_PORT'])
+        ),
+    )

plugins/modules/cluster.py

@@ -92,8 +92,10 @@
 from ansible.module_utils._text import to_native
 
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
 )
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
@@ -182,7 +184,7 @@ def get_cluster_outputs(self):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_argument_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name', 'name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
                 state=dict(type='str', default='present', choices=['absent', 'present']),

plugins/modules/cluster_dpm.py

@@ -110,8 +110,10 @@
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
 )
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
@@ -208,7 +210,7 @@ def apply_dpm_configuration(self):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_argument_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
                 enable=dict(type='bool', default=True),

plugins/modules/cluster_drs.py

@@ -136,8 +136,10 @@
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
 )
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
@@ -246,7 +248,7 @@ def apply_drs_configuration(self):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_argument_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
                 enable=dict(type='bool', default=True),

plugins/modules/cluster_drs_recommendations.py

@@ -96,8 +96,10 @@
 from itertools import zip_longest
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
 )
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
@@ -177,7 +179,7 @@ def __wait_for_recommendation_task_results(self, recommendation_tasks):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_argument_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name']),
                 datacenter=dict(type='str', required=True, aliases=['datacenter_name']),
             )

plugins/modules/cluster_info.py

@@ -155,7 +155,12 @@
 except ImportError:
     pass
 from ansible.module_utils.basic import AnsibleModule
-from ansible_collections.vmware.vmware.plugins.module_utils._vmware import PyVmomi, vmware_argument_spec
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    rest_compatible_argument_spec
+)
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_rest_client import VmwareRestClient
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_facts import (
     ClusterFacts,
@@ -230,7 +235,7 @@ def _get_tags(self, cluster):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **rest_compatible_argument_spec(), **dict(
                 cluster=dict(type='str', aliases=['cluster_name', 'name']),
                 datacenter=dict(type='str', aliases=['datacenter_name']),
                 gather_tags=dict(type='bool', default=False),

plugins/modules/cluster_vcls.py

@@ -137,8 +137,10 @@
 from ansible.module_utils._text import to_native
 
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
-    PyVmomi,
-    vmware_argument_spec
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
 )
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import (
     TaskError,
@@ -246,7 +248,7 @@ def configure_vcls(self, datastores_to_add, datastores_to_remove):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_argument_spec(), **dict(
                 cluster=dict(type='str', required=True, aliases=['cluster_name']),
                 datacenter=dict(type='str', required=False, aliases=['datacenter_name']),
                 allowed_datastores=dict(type='list', elements='str'),

plugins/modules/folder_template_from_vm.py

@@ -143,7 +143,12 @@
 import traceback
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible_collections.vmware.vmware.plugins.module_utils._vmware import PyVmomi, vmware_argument_spec
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
+)
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_folder_paths import format_folder_path_as_vm_fq_path
 from ansible_collections.vmware.vmware.plugins.module_utils._vmware_tasks import RunningTaskMonitor, TaskError
 
@@ -262,7 +267,7 @@ def custom_validation(module):
 def main():
     module = AnsibleModule(
         argument_spec={
-            **vmware_argument_spec(), **dict(
+            **base_argument_spec(), **dict(
                 vm_name=dict(type='str', required=False, default=None),
                 vm_name_match=dict(type='str', required=False, choices=['first', 'last']),
                 vm_uuid=dict(type='str', required=False, default=None),

plugins/modules/license_info.py

@@ -44,7 +44,12 @@
 '''
 
 from ansible.module_utils.basic import AnsibleModule
-from ansible_collections.vmware.vmware.plugins.module_utils._vmware import PyVmomi, vmware_argument_spec
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware import (
+    PyVmomi
+)
+from ansible_collections.vmware.vmware.plugins.module_utils._vmware_argument_spec import (
+    base_argument_spec
+)
 
 
 class VcenterLicenseMgr(PyVmomi):
@@ -62,7 +67,7 @@ def list_keys(self, licenses):
 
 def main():
     module = AnsibleModule(
-        argument_spec=vmware_argument_spec(),
+        argument_spec=base_argument_spec(),
         supports_check_mode=True,
     )