Skip to content

Commit

Permalink
[DNM] Test consolidate argument specs and doc fragments
Browse files Browse the repository at this point in the history
  • Loading branch information
mariolenz committed Dec 11, 2024
1 parent 290bc26 commit e4af855
Show file tree
Hide file tree
Showing 3 changed files with 170 additions and 0 deletions.
29 changes: 29 additions & 0 deletions plugins/doc_fragments/additional_rest_options.py
Original file line number Diff line number Diff line change
@@ -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 option is used if the correct proxy protocol cannot be automatically determined.
type: str
choices: [ http, https ]
default: https
aliases: [protocol]
'''
69 changes: 69 additions & 0 deletions plugins/doc_fragments/base_options.py
Original file line number Diff line number Diff line change
@@ -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 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
'''
72 changes: 72 additions & 0 deletions plugins/module_utils/vmware_argument_spec.py
Original file line number Diff line number Diff line change
@@ -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'])
),
)

0 comments on commit e4af855

Please sign in to comment.