diff --git a/plugins/doc_fragments/additional_rest_options.py b/plugins/doc_fragments/additional_rest_options.py new file mode 100644 index 000000000..263fb011c --- /dev/null +++ b/plugins/doc_fragments/additional_rest_options.py @@ -0,0 +1,29 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2016, Charles Paul +# Copyright: (c) 2018, Ansible Project +# Copyright: (c) 2019, Abhijeet Kasurde +# 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 option is used if the correct proxy protocol cannot be automatically determined. + type: str + choices: [ http, https ] + default: https + aliases: [protocol] +''' diff --git a/plugins/doc_fragments/base_options.py b/plugins/doc_fragments/base_options.py new file mode 100644 index 000000000..dac029963 --- /dev/null +++ b/plugins/doc_fragments/base_options.py @@ -0,0 +1,69 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2016, Charles Paul +# Copyright: (c) 2018, Ansible Project +# Copyright: (c) 2019, Abhijeet Kasurde +# 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 are 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: + - The 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: + - The 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 +''' diff --git a/plugins/module_utils/vmware_argument_spec.py b/plugins/module_utils/vmware_argument_spec.py new file mode 100644 index 000000000..fd0dcf8ea --- /dev/null +++ b/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 SDK, you should use this instead of the base_argument_spec. + If your module uses both the REST API SDK 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']) + ), + )