reduce redundant doc fragments and arg specs

changelogs/fragments/89-consolidate-arg-specs-and-docs.yml

@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - doc fragments - Remove redundant fragments. Update pyvmomi modules to use new consolidated docs
+  - argument specs - Remove redundant argument specs. Update pyvmomi modules to use new consolidated spec

plugins/doc_fragments/additional_rest_options.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2016, Charles Paul <[email protected]>
+# Copyright: (c) 2018, Ansible Project
+# Copyright: (c) 2019, Abhijeet Kasurde <[email protected]>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+    # This document fragment serves as a compliment to the vmware.vmware.base documentation fragment for modules
+    # that use the REST API SDK. You must include the base fragment in addition to this
+    #
+    # This vmware.vmware.additional_rest_options fragment will cover any options returned by rest_compatible_argument_spec()
+    # that are not included in vmware.vmware.base
+    DOCUMENTATION = r'''
+options:
+  proxy_protocol:
+    description:
+      - The proxy connection protocol to use.
+      - This is option is used if the correct proxy protocol cannot be automatically determined.
+    type: str
+    choices: [ http, https ]
+    default: https
+    aliases: [protocol]
+'''

plugins/doc_fragments/base_options.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2016, Charles Paul <[email protected]>
+# Copyright: (c) 2018, Ansible Project
+# Copyright: (c) 2019, Abhijeet Kasurde <[email protected]>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+    # This document fragment serves as a base for all vmware modules. If you are using the REST API SDK in your module,
+    # you should also include the vmware.vmware.additional_rest_options fragment.
+    #
+    # This vmware.vmware.base_options fragment covers the arg spec provided by the base_argument_spec() function
+    DOCUMENTATION = r'''
+notes:
+  - All modules require API write access and hence is not supported on a free ESXi license.
+  - All variables and VMware object names are case sensitive.
+  - >-
+      Modules may rely on the 'requests' python library, which does not use the system certificate store by default. You can
+      specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable.
+      Example: 'export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem'
+options:
+  hostname:
+    description:
+      - The hostname or IP address of the vSphere vCenter server.
+      - If the value is not specified in the task, the value of environment variable E(VMWARE_HOST) will be used instead.
+    type: str
+  username:
+    description:
+      - The username of the vSphere vCenter server.
+      - If the value is not specified in the task, the value of environment variable E(VMWARE_USER) will be used instead.
+    type: str
+    aliases: [ admin, user ]
+  password:
+    description:
+      - The password of the vSphere vCenter server.
+      - If the value is not specified in the task, the value of environment variable E(VMWARE_PASSWORD) will be used instead.
+    type: str
+    aliases: [ pass, pwd ]
+  validate_certs:
+    description:
+      - Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
+      - If the value is not specified in the task, the value of environment variable E(VMWARE_VALIDATE_CERTS) will be used instead.
+    type: bool
+    default: true
+  port:
+    description:
+      - The port number of the vSphere vCenter server.
+      - If the value is not specified in the task, the value of environment variable E(VMWARE_PORT) will be used instead.
+    type: int
+    default: 443
+  proxy_host:
+    description:
+      - Address of a proxy that will receive all HTTPS requests and relay them.
+      - The format is a hostname or a IP.
+      - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_HOST) will be used instead.
+    type: str
+    required: false
+  proxy_port:
+    description:
+    - Port of the HTTP proxy that will receive all HTTPS requests and relay them.
+    - If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
+    type: int
+    required: false
+'''

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

@@ -45,8 +45,9 @@
     - module: vmware.vmware.cluster_drs
     - module: community.vmware.vmware_cluster_ha
     - module: community.vmware.vmware_cluster_vsan
+
 extends_documentation_fragment:
-    - vmware.vmware.vmware.documentation
+    - vmware.vmware.base_options
 '''
 
 EXAMPLES = r'''
@@ -92,8 +93,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 +185,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']),