From efcdd01cd3c0dda53b03ea4f118dfdcfbb8a8ce8 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Wed, 25 Oct 2023 18:10:21 +0200 Subject: [PATCH] Implement semantic markup (2) (#1879) Implement semantic markup (2) SUMMARY Depends-On: #1878 Implementing semantic markup part 2. ISSUE TYPE Docs Pull Request COMPONENT NAME plugins/connection/vmware_tools.py plugins/inventory/vmware_host_inventory.py plugins/inventory/vmware_vm_inventory.py ADDITIONAL INFORMATION #1771 Reviewed-by: Felix Fontein --- ...vmware.vmware_host_inventory_inventory.rst | 787 -------------- ...mmunity.vmware.vmware_tools_connection.rst | 326 ------ ...y.vmware.vmware_vm_inventory_inventory.rst | 985 ------------------ plugins/connection/vmware_tools.py | 16 +- plugins/inventory/vmware_host_inventory.py | 15 +- plugins/inventory/vmware_vm_inventory.py | 18 +- tools/antsibull-docs-wrapper.sh | 2 +- tools/create_documentation_tasks.yml | 2 +- 8 files changed, 25 insertions(+), 2126 deletions(-) delete mode 100644 docs/community.vmware.vmware_host_inventory_inventory.rst delete mode 100644 docs/community.vmware.vmware_tools_connection.rst delete mode 100644 docs/community.vmware.vmware_vm_inventory_inventory.rst diff --git a/docs/community.vmware.vmware_host_inventory_inventory.rst b/docs/community.vmware.vmware_host_inventory_inventory.rst deleted file mode 100644 index 5152b819d..000000000 --- a/docs/community.vmware.vmware_host_inventory_inventory.rst +++ /dev/null @@ -1,787 +0,0 @@ -.. _community.vmware.vmware_host_inventory_inventory: - - -************************************** -community.vmware.vmware_host_inventory -************************************** - -**VMware ESXi hostsystem inventory source** - - - -.. contents:: - :local: - :depth: 1 - - -Synopsis --------- -- Get VMware ESXi hostsystem as inventory hosts from VMware environment. -- Uses any file which ends with vmware.yml, vmware.yaml, vmware_host_inventory.yml, or vmware_host_inventory.yaml as a YAML configuration file. - - - -Requirements ------------- -The below requirements are needed on the local Ansible controller node that executes this inventory. - -- vSphere Automation SDK - For tag feature - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- cache - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
ini entries: -

[inventory]
cache = no

-
-
env:ANSIBLE_INVENTORY_CACHE
- 		-
Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
-
-
- cache_connection - -
- string -
- 		- -
ini entries: -

[defaults]
fact_caching_connection = VALUE

-

[inventory]
cache_connection = VALUE

-
-
env:ANSIBLE_CACHE_PLUGIN_CONNECTION
-
env:ANSIBLE_INVENTORY_CACHE_CONNECTION
- 		-
Cache connection data or path, read cache plugin documentation for specifics.
-
-
- cache_plugin - -
- string -
- 		- Default:
"memory"
- 		-
ini entries: -

[defaults]
fact_caching = memory

-

[inventory]
cache_plugin = memory

-
-
env:ANSIBLE_CACHE_PLUGIN
-
env:ANSIBLE_INVENTORY_CACHE_PLUGIN
- 		-
Cache plugin to use for the inventory's source data.
-
-
- cache_prefix - -
- - -
- 		- Default:
"ansible_inventory_"
- 		-
ini entries: -

[default]
fact_caching_prefix = ansible_inventory_

-

[defaults]
fact_caching_prefix = ansible_inventory_

-

[inventory]
cache_prefix = ansible_inventory_

-
-
env:ANSIBLE_CACHE_PLUGIN_PREFIX
-
env:ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
- 		-
Prefix to use for cache plugin files/tables
-
-
- cache_timeout - -
- integer -
- 		- Default:
3600
- 		-
ini entries: -

[defaults]
fact_caching_timeout = 3600

-

[inventory]
cache_timeout = 3600

-
-
env:ANSIBLE_CACHE_PLUGIN_TIMEOUT
-
env:ANSIBLE_INVENTORY_CACHE_TIMEOUT
- 		-
Cache duration in seconds
-
-
- compose - -
- dictionary -
- 		- Default:
{}
- 		- -
Create vars from jinja2 expressions.
-
-
- filters - -
- list - / elements=string -
- 		- Default:
[]
- 		- -
This option allows client-side filtering hosts with jinja templating.
-
When server-side filtering is introduced, it should be preferred over this.
-
-
- groups - -
- dictionary -
- 		- Default:
{}
- 		- -
Add hosts to group based on Jinja2 conditionals.
-
-
- hostname - -
- - - / required -
- 		- -
env:VMWARE_HOST
-
env:VMWARE_SERVER
- 		-
Name of vCenter or ESXi server.
-
-
- hostnames - -
- list - / elements=string -
- 		- Default:
["name"]
- 		- -
A list of templates in order of precedence to compose inventory_hostname.
-
Ignores template if resulted in an empty string or None value.
-
You can use property specified in properties as variables in the template.
-
-
- keyed_groups - -
- list - / elements=dictionary -
- 		- Default:
[{"key": "summary.runtime.powerState", "separator": ""}]
- 		- -
Add hosts to group based on the values of a variable.
-
-
- default_value - -
- string -
-
added in 2.12
- 		- - -
The default value when the host variable's value is an empty string.
-
This option is mutually exclusive with trailing_separator.
-
-
- key - -
- string -
- 		- - -
The key from input dictionary used to generate groups
-
-
- parent_group - -
- string -
- 		- - -
parent group for keyed group
-
-
- prefix - -
- string -
- 		- Default:
""
- 		- -
A keyed group name will start with this prefix
-
-
- separator - -
- string -
- 		- Default:
"_"
- 		- -
separator used to build the keyed group name
-
-
- trailing_separator - -
- boolean -
-
added in 2.12
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		- -
Set this option to False to omit the separator after the host variable when the value is an empty string.
-
This option is mutually exclusive with default_value.
-
-
- leading_separator - -
- boolean -
-
added in 2.11
- 		- Default:
"yes"
- 		- -
Use in conjunction with keyed_groups.
-
By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
-
This is because the default prefix is "" and the default separator is "_".
-
Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
-
If the group name is derived from a mapping the separator is still used to concatenate the items.
-
To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
-
-
- password - -
- - - / required -
- 		- -
env:VMWARE_PASSWORD
- 		-
Password of vSphere user.
-
Accepts vault encrypted variable.
-
Accepts Jinja to template the value
-
-
- port - -
- integer -
- 		- Default:
443
- 		-
env:VMWARE_PORT
- 		-
Port number used to connect to vCenter or ESXi Server.
-
-
- properties - -
- list - / elements=string -
- 		- Default:
["name", "customValue", "summary.runtime.powerState"]
- 		- -
Specify the list of VMware schema properties associated with the ESXi hostsystem.
-
These properties will be populated in hostvars of the given ESXi hostsystem.
-
Each value in the list can be a path to a specific property in hostsystem object or a path to a collection of hostsystem objects.
-
summary.runtime.powerState are required if keyed_groups is set to default.
-
Please make sure that all the properties that are used in other parameters are included in this options.
-
In addition to ESXi hostsystem's properties, the following are special values
-
Use customValue to populate ESXi hostsystem's custom attributes. customValue is only supported by vCenter and not by ESXi.
-
Use all to populate all the properties of the virtual machine. The value all is time consuming operation, do not use unless required absolutely.
-
-
- proxy_host - -
- string -
- 		- -
env:VMWARE_PROXY_HOST
- 		-
Address of a proxy that will receive all HTTPS requests and relay them.
-
The format is a hostname or a IP.
-
This feature depends on a version of pyvmomi>=v6.7.1.2018.12.
-
-
- proxy_port - -
- integer -
- 		- -
env:VMWARE_PROXY_PORT
- 		-
Port of the HTTP proxy that will receive all HTTPS requests and relay them.
-
-
- resources - -
- list - / elements=dictionary -
- 		- Default:
[]
- 		- -
A list of resources to limit search scope.
-
Each resource item is represented by exactly one 'vim_type_snake_case:list of resource names pair and optional nested resources
-
Key name is based on snake case of a vim type name; e.g host_system correspond to vim.HostSystem
-
-
- strict - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
If yes make invalid entries a fatal error, otherwise skip and continue.
-
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
-
-
- use_extra_vars - -
- boolean -
-
added in 2.11
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
ini entries: -

[inventory_plugins]
use_extra_vars = no

-
-
env:ANSIBLE_INVENTORY_USE_EXTRA_VARS
- 		-
Merge extra vars into the available variables for composition (highest precedence).
-
-
- username - -
- - - / required -
- 		- -
env:VMWARE_USER
-
env:VMWARE_USERNAME
- 		-
Name of vSphere user.
-
Accepts vault encrypted variable.
-
Accepts Jinja to template the value
-
-
- validate_certs - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		-
env:VMWARE_VALIDATE_CERTS
- 		-
Allows connection when SSL certificates are not valid.
-
Set to false when certificates are not trusted.
-
-
- with_nested_properties - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		- -
This option transform flatten properties name to nested dictionary.
-
-
- with_path - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
Include ESXi hostsystem's path.
-
Set this option to a string value to replace root name from 'Datacenters'.
-
-
- with_sanitized_property_name - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
This option allows property name sanitization to create safe property names for use in Ansible.
-
Also, transforms property name to snake case.
-
-
- with_tags - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
Include tags and associated hosts.
-
Requires 'vSphere Automation SDK' library to be installed on the given controller machine.
-
Please refer following URLs for installation steps
- -
-
- - - - -Examples --------- - -.. code-block:: yaml - - # Sample configuration file for VMware Host dynamic inventory - plugin: community.vmware.vmware_host_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - with_tags: true - - # Sample configuration file for VMware Guest dynamic inventory using Jinja to template the username and password. - plugin: community.vmware.vmware_host_inventory - strict: false - hostname: 10.65.223.31 - username: '{{ (lookup("file","~/.config/vmware.yaml") | from_yaml).username }}' - password: '{{ (lookup("file","~/.config/vmware.yaml") | from_yaml).password }}' - validate_certs: false - with_tags: true - - # Using compose - plugin: community.vmware.vmware_host_inventory - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - name - - summary - - config.lockdownMode - compose: - ansible_user: "'root'" - ansible_connection: "'ssh'" - - - - -Status ------- - - -Authors -~~~~~~~ - -- Abhijeet Kasurde (@Akasurde) - - -.. hint:: - Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/docs/community.vmware.vmware_tools_connection.rst b/docs/community.vmware.vmware_tools_connection.rst deleted file mode 100644 index 80e6cd333..000000000 --- a/docs/community.vmware.vmware_tools_connection.rst +++ /dev/null @@ -1,326 +0,0 @@ -.. _community.vmware.vmware_tools_connection: - - -***************************** -community.vmware.vmware_tools -***************************** - -**Execute tasks inside a VM via VMware Tools** - - - -.. contents:: - :local: - :depth: 1 - - -Synopsis --------- -- Use VMware tools to run tasks in, or put/fetch files to guest operating systems running in VMware infrastructure. -- In case of Windows VMs, set ``ansible_shell_type`` to ``powershell``. -- Does not work with 'become'. - - - -Requirements ------------- -The below requirements are needed on the local Ansible controller node that executes this connection. - -- requests (Python library) - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- exec_command_sleep_interval - -
- float -
- 		- Default:
0.5
- 		-
var: ansible_vmware_tools_exec_command_sleep_interval
- 		-
Time in seconds to sleep between execution of command.
-
-
- executable - -
- - -
- 		- Default:
"/bin/sh"
- 		-
ini entries: -

[defaults]
executable = /bin/sh

-
-
env:ANSIBLE_EXECUTABLE
-
var: ansible_executable
-
var: ansible_vmware_tools_executable
- 		-
shell to use for execution inside container
-
-
- file_chunk_size - -
- integer -
- 		- Default:
128
- 		-
var: ansible_vmware_tools_file_chunk_size
- 		-
File chunk size.
-
(Applicable when writing a file to disk, example: using the fetch module.)
-
-
- validate_certs - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		-
env:VMWARE_VALIDATE_CERTS
-
var: ansible_vmware_validate_certs
- 		-
Verify SSL for the connection.
-
Note: This will validate certs for both vmware_host and the ESXi host running the VM.
-
-
- vm_password - -
- - - / required -
- 		- -
var: ansible_password
-
var: ansible_vmware_tools_password
- 		-
Password for the user in guest operating system.
-
-
- vm_path - -
- - -
- 		- -
var: ansible_vmware_guest_path
- 		-
Mutually exclusive with vm_uuid
-
VM path absolute to the connection.
-
vCenter Example: Datacenter/vm/Discovered virtual machine/testVM.
-
ESXi Host Example: ha-datacenter/vm/testVM.
-
Must include VM name, appended to 'folder' as would be passed to community.vmware.vmware_guest.
-
Needs to include vm between the Datacenter and the rest of the VM path.
-
Datacenter default value for ESXi server is ha-datacenter.
-
Folder vm is not visible in the vSphere Web Client but necessary for VMware API to work.
-
-
- vm_user - -
- - - / required -
- 		- -
var: ansible_user
-
var: ansible_vmware_tools_user
- 		-
VM username.
-
ansible_vmware_tools_user is used for connecting to the VM.
-
ansible_user is used by Ansible on the VM.
-
-
- vm_uuid - -
- - -
- 		- -
var: ansible_vmware_guest_uuid
- 		-
Mutually exclusive with vm_path
-
VM UUID to the connection.
-
UUID of the virtual machine from property config.uuid of vmware_vm_inventory plugin
-
-
- vmware_host - -
- - - / required -
- 		- -
env:VI_SERVER
-
env:VMWARE_HOST
-
var: ansible_host
-
var: ansible_vmware_host
- 		-
FQDN or IP Address for the connection (vCenter or ESXi Host).
-
-
- vmware_password - -
- - - / required -
- 		- -
env:VI_PASSWORD
-
env:VMWARE_PASSWORD
-
var: ansible_vmware_password
- 		-
Password for the connection.
-
-
- vmware_port - -
- - -
- 		- Default:
443
- 		-
env:VI_PORTNUMBER
-
env:VMWARE_PORT
-
var: ansible_port
-
var: ansible_vmware_port
- 		-
Port for the connection.
-
-
- vmware_user - -
- - - / required -
- 		- -
env:VI_USERNAME
-
env:VMWARE_USER
-
var: ansible_vmware_user
- 		-
Username for the connection.
-
Requires the following permissions on the VM: - VirtualMachine.GuestOperations.Execute - VirtualMachine.GuestOperations.Modify - VirtualMachine.GuestOperations.Query
-
-
- - - - - - - - -Status ------- - - -Authors -~~~~~~~ - -- Deric Crago (@dericcrago) - - -.. hint:: - Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/docs/community.vmware.vmware_vm_inventory_inventory.rst b/docs/community.vmware.vmware_vm_inventory_inventory.rst deleted file mode 100644 index a7959f4e9..000000000 --- a/docs/community.vmware.vmware_vm_inventory_inventory.rst +++ /dev/null @@ -1,985 +0,0 @@ -.. _community.vmware.vmware_vm_inventory_inventory: - - -************************************ -community.vmware.vmware_vm_inventory -************************************ - -**VMware Guest inventory source** - - - -.. contents:: - :local: - :depth: 1 - - -Synopsis --------- -- Get virtual machines as inventory hosts from VMware environment. -- Uses any file which ends with vmware.yml, vmware.yaml, vmware_vm_inventory.yml, or vmware_vm_inventory.yaml as a YAML configuration file. - - - -Requirements ------------- -The below requirements are needed on the local Ansible controller node that executes this inventory. - -- requests >= 2.3 -- vSphere Automation SDK - For tag feature - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- cache - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
ini entries: -

[inventory]
cache = no

-
-
env:ANSIBLE_INVENTORY_CACHE
- 		-
Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
-
-
- cache_connection - -
- string -
- 		- -
ini entries: -

[defaults]
fact_caching_connection = VALUE

-

[inventory]
cache_connection = VALUE

-
-
env:ANSIBLE_CACHE_PLUGIN_CONNECTION
-
env:ANSIBLE_INVENTORY_CACHE_CONNECTION
- 		-
Cache connection data or path, read cache plugin documentation for specifics.
-
-
- cache_plugin - -
- string -
- 		- Default:
"memory"
- 		-
ini entries: -

[defaults]
fact_caching = memory

-

[inventory]
cache_plugin = memory

-
-
env:ANSIBLE_CACHE_PLUGIN
-
env:ANSIBLE_INVENTORY_CACHE_PLUGIN
- 		-
Cache plugin to use for the inventory's source data.
-
-
- cache_prefix - -
- - -
- 		- Default:
"ansible_inventory_"
- 		-
ini entries: -

[default]
fact_caching_prefix = ansible_inventory_

-

[defaults]
fact_caching_prefix = ansible_inventory_

-

[inventory]
cache_prefix = ansible_inventory_

-
-
env:ANSIBLE_CACHE_PLUGIN_PREFIX
-
env:ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
- 		-
Prefix to use for cache plugin files/tables
-
-
- cache_timeout - -
- integer -
- 		- Default:
3600
- 		-
ini entries: -

[defaults]
fact_caching_timeout = 3600

-

[inventory]
cache_timeout = 3600

-
-
env:ANSIBLE_CACHE_PLUGIN_TIMEOUT
-
env:ANSIBLE_INVENTORY_CACHE_TIMEOUT
- 		-
Cache duration in seconds
-
-
- compose - -
- dictionary -
- 		- Default:
{}
- 		- -
Create vars from jinja2 expressions.
-
-
- filters - -
- list - / elements=string -
- 		- Default:
[]
- 		- -
This option allows client-side filtering hosts with jinja templating.
-
When server-side filtering is introduced, it should be preferred over this.
-
-
- groups - -
- dictionary -
- 		- Default:
{}
- 		- -
Add hosts to group based on Jinja2 conditionals.
-
-
- hostname - -
- - - / required -
- 		- -
env:VMWARE_HOST
-
env:VMWARE_SERVER
- 		-
Name of vCenter or ESXi server.
-
-
- hostnames - -
- list - / elements=string -
- 		- Default:
["config.name + \"_\" + config.uuid"]
- 		- -
A list of templates in order of precedence to compose inventory_hostname.
-
Ignores template if resulted in an empty string or None value.
-
You can use property specified in properties as variables in the template.
-
-
- keyed_groups - -
- list - / elements=dictionary -
- 		- Default:
[{"key": "config.guestId", "separator": ""}, {"key": "summary.runtime.powerState", "separator": ""}]
- 		- -
Add hosts to group based on the values of a variable.
-
-
- default_value - -
- string -
-
added in 2.12
- 		- - -
The default value when the host variable's value is an empty string.
-
This option is mutually exclusive with trailing_separator.
-
-
- key - -
- string -
- 		- - -
The key from input dictionary used to generate groups
-
-
- parent_group - -
- string -
- 		- - -
parent group for keyed group
-
-
- prefix - -
- string -
- 		- Default:
""
- 		- -
A keyed group name will start with this prefix
-
-
- separator - -
- string -
- 		- Default:
"_"
- 		- -
separator used to build the keyed group name
-
-
- trailing_separator - -
- boolean -
-
added in 2.12
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		- -
Set this option to False to omit the separator after the host variable when the value is an empty string.
-
This option is mutually exclusive with default_value.
-
-
- leading_separator - -
- boolean -
-
added in 2.11
- 		- Default:
"yes"
- 		- -
Use in conjunction with keyed_groups.
-
By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
-
This is because the default prefix is "" and the default separator is "_".
-
Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
-
If the group name is derived from a mapping the separator is still used to concatenate the items.
-
To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
-
-
- password - -
- - - / required -
- 		- -
env:VMWARE_PASSWORD
- 		-
Password of vSphere user.
-
Accepts vault encrypted variable.
-
Accepts Jinja to template the value
-
-
- port - -
- integer -
- 		- Default:
443
- 		-
env:VMWARE_PORT
- 		-
Port number used to connect to vCenter or ESXi Server.
-
-
- properties - -
- list - / elements=string -
- 		- Default:
["name", "config.cpuHotAddEnabled", "config.cpuHotRemoveEnabled", "config.instanceUuid", "config.hardware.numCPU", "config.template", "config.name", "config.uuid", "guest.hostName", "guest.ipAddress", "guest.guestId", "guest.guestState", "runtime.maxMemoryUsage", "customValue", "summary.runtime.powerState", "config.guestId"]
- 		- -
Specify the list of VMware schema properties associated with the VM.
-
These properties will be populated in hostvars of the given VM.
-
Each value in the list can be a path to a specific property in VM object or a path to a collection of VM objects.
-
config.name, config.uuid are required properties if hostnames is set to default.
-
config.guestId, summary.runtime.powerState are required if keyed_groups is set to default.
-
Please make sure that all the properties that are used in other parameters are included in this options.
-
In addition to VM properties, the following are special values
-
Use customValue to populate virtual machine's custom attributes. customValue is only supported by vCenter and not by ESXi.
-
Use all to populate all the properties of the virtual machine. The value all is time consuming operation, do not use unless required absolutely.
- -
-
- proxy_host - -
- string -
- 		- -
env:VMWARE_PROXY_HOST
- 		-
Address of a proxy that will receive all HTTPS requests and relay them.
-
The format is a hostname or a IP.
-
This feature depends on a version of pyvmomi>=v6.7.1.2018.12.
-
-
- proxy_port - -
- integer -
- 		- -
env:VMWARE_PROXY_PORT
- 		-
Port of the HTTP proxy that will receive all HTTPS requests and relay them.
-
-
- resources - -
- list - / elements=dictionary -
- 		- Default:
[]
- 		- -
A list of resources to limit search scope.
-
Each resource item is represented by exactly one 'vim_type_snake_case:list of resource names pair and optional nested resources
-
Key name is based on snake case of a vim type name; e.g host_system correspond to vim.HostSystem
- -
-
- strict - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
If yes make invalid entries a fatal error, otherwise skip and continue.
-
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
-
-
- use_extra_vars - -
- boolean -
-
added in 2.11
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
ini entries: -

[inventory_plugins]
use_extra_vars = no

-
-
env:ANSIBLE_INVENTORY_USE_EXTRA_VARS
- 		-
Merge extra vars into the available variables for composition (highest precedence).
-
-
- username - -
- - - / required -
- 		- -
env:VMWARE_USER
-
env:VMWARE_USERNAME
- 		-
Name of vSphere user.
-
Accepts vault encrypted variable.
-
Accepts Jinja to template the value
-
-
- validate_certs - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		-
env:VMWARE_VALIDATE_CERTS
- 		-
Allows connection when SSL certificates are not valid.
-
Set to false when certificates are not trusted.
-
-
- with_nested_properties - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		- -
This option transform flatten properties name to nested dictionary.
-
From 1.10.0 and onwards, default value is set to true.
-
-
- with_path - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
Include virtual machines path.
-
Set this option to a string value to replace root name from 'Datacenters'.
-
-
- with_sanitized_property_name - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
This option allows property name sanitization to create safe property names for use in Ansible.
-
Also, transforms property name to snake case.
-
-
- with_tags - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
Include tags and associated virtual machines.
-
Requires 'vSphere Automation SDK' library to be installed on the given controller machine.
-
Please refer following URLs for installation steps
- -
-
- - - - -Examples --------- - -.. code-block:: yaml - - # Sample configuration file for VMware Guest dynamic inventory - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - with_tags: true - - # Sample configuration file for VMware Guest dynamic inventory using Jinja to template the username and password. - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: '{{ (lookup("file","~/.config/vmware.yaml") | from_yaml).username }}' - password: '{{ (lookup("file","~/.config/vmware.yaml") | from_yaml).password }}' - validate_certs: false - with_tags: true - - # Gather minimum set of properties for VMware guest - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - 'name' - - 'guest.ipAddress' - - 'config.name' - - 'config.uuid' - - # Create Groups based upon VMware Tools status - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - 'name' - - 'config.name' - - 'guest.toolsStatus' - - 'guest.toolsRunningStatus' - hostnames: - - config.name - keyed_groups: - - key: guest.toolsStatus - separator: '' - - key: guest.toolsRunningStatus - separator: '' - - # Filter VMs based upon condition - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - 'runtime.powerState' - - 'config.name' - filters: - - runtime.powerState == "poweredOn" - hostnames: - - config.name - - # Filter VM's based on OR conditions - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - 'name' - - 'config.name' - - 'guest.ipAddress' - - 'guest.toolsStatus' - - 'guest.toolsRunningStatus' - - 'config.guestFullName' - - 'config.guestId' - hostnames: - - 'config.name' - filters: - - config.guestId == "rhel7_64Guest" or config.name == "rhel_20_04_empty" - - # Filter VM's based on regex conditions - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - 'config.name' - - 'config.guestId' - - 'guest.ipAddress' - - 'summary.runtime.powerState' - filters: - - guest.ipAddress is defined and (guest.ipAddress is match('192.168.*') or guest.ipAddress is match('192.169.*')) - - # Using compose and groups - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - properties: - - 'name' - - 'config.name' - - 'guest.ipAddress' - compose: - # This will populate the IP address of virtual machine if available - # and will be used while communicating to the given virtual machine - ansible_host: 'guest.ipAddress' - composed_var: 'config.name' - # This will populate a host variable with a string value - ansible_user: "'admin'" - ansible_connection: "'ssh'" - groups: - VMs: true - hostnames: - - config.name - - # Use Datacenter, Cluster and Folder value to list VMs - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.200.241 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - with_tags: true - resources: - - datacenter: - - Asia-Datacenter1 - - Asia-Datacenter2 - resources: - - compute_resource: - - Asia-Cluster1 - resources: - - host_system: - - Asia-ESXI4 - - folder: - - dev - - prod - - # Use Category and it's relation with Tag - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.201.128 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - hostnames: - - 'config.name' - properties: - - 'config.name' - - 'config.guestId' - - 'guest.ipAddress' - - 'summary.runtime.powerState' - with_tags: true - keyed_groups: - - key: tag_category.OS - prefix: "vmware_tag_os_category_" - separator: "" - with_nested_properties: true - filters: - - "tag_category.OS is defined and 'Linux' in tag_category.OS" - - # customizing hostnames based on VM's FQDN. The second hostnames template acts as a fallback mechanism. - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - hostnames: - - 'config.name+"."+guest.ipStack.0.dnsConfig.domainName' - - 'config.name' - properties: - - 'config.name' - - 'config.guestId' - - 'guest.hostName' - - 'guest.ipAddress' - - 'guest.guestFamily' - - 'guest.ipStack' - - # Select a specific IP address for use by ansible when multiple NICs are present on the VM - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.223.31 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - compose: - # Set the IP address used by ansible to one that starts by 10.42. or 10.43. - ansible_host: >- - guest.net - | selectattr('ipAddress') - | map(attribute='ipAddress') - | flatten - | select('match', '^10.42.*|^10.43.*') - | list - | first - properties: - - guest.net - - # Group hosts using Jinja2 conditionals - plugin: community.vmware.vmware_vm_inventory - strict: false - hostname: 10.65.13.37 - username: administrator@vsphere.local - password: Esxi@123$% - validate_certs: false - hostnames: - - config.name - properties: - - 'name' - - 'config.name' - - 'config.datastoreUrl' - groups: - slow_storage: "'Nas01' in config.datastoreUrl[0].name" - fast_storage: "'SSD' in config.datastoreUrl[0].name" - - - - -Status ------- - - -Authors -~~~~~~~ - -- Abhijeet Kasurde (@Akasurde) - - -.. hint:: - Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/plugins/connection/vmware_tools.py b/plugins/connection/vmware_tools.py index 533ededb1..a542a64a1 100644 --- a/plugins/connection/vmware_tools.py +++ b/plugins/connection/vmware_tools.py @@ -14,7 +14,7 @@ description: - Use VMware tools to run tasks in, or put/fetch files to guest operating systems running in VMware infrastructure. - In case of Windows VMs, set C(ansible_shell_type) to C(powershell). - - Does not work with 'become'. + - Does not work with C(become). requirements: - requests (Python library) options: @@ -64,7 +64,7 @@ validate_certs: description: - Verify SSL for the connection. - - "Note: This will validate certs for both C(vmware_host) and the ESXi host running the VM." + - "Note: This will validate certs for both O(vmware_host) and the ESXi host running the VM." env: - name: VMWARE_VALIDATE_CERTS vars: @@ -73,10 +73,10 @@ type: bool vm_path: description: - - Mutually exclusive with vm_uuid + - Mutually exclusive with O(vm_uuid) - VM path absolute to the connection. - - "vCenter Example: C(Datacenter/vm/Discovered virtual machine/testVM)." - - "ESXi Host Example: C(ha-datacenter/vm/testVM)." + - "vCenter Example: V(Datacenter/vm/Discovered virtual machine/testVM)." + - "ESXi Host Example: V(ha-datacenter/vm/testVM)." - Must include VM name, appended to 'folder' as would be passed to M(community.vmware.vmware_guest). - Needs to include I(vm) between the Datacenter and the rest of the VM path. - Datacenter default value for ESXi server is C(ha-datacenter). @@ -86,9 +86,9 @@ required: false vm_uuid: description: - - Mutually exclusive with vm_path + - Mutually exclusive with O(vm_path) - VM UUID to the connection. - - UUID of the virtual machine from property config.uuid of vmware_vm_inventory plugin + - UUID of the virtual machine from property config.uuid of P(community.vmware.vmware_vm_inventory#lookup) plugin vars: - name: ansible_vmware_guest_uuid required: false @@ -118,7 +118,7 @@ file_chunk_size: description: - File chunk size. - - "(Applicable when writing a file to disk, example: using the C(fetch) module.)" + - "(Applicable when writing a file to disk, example: using the M(ansible.builtin.fetch) module.)" vars: - name: ansible_vmware_tools_file_chunk_size default: 128 diff --git a/plugins/inventory/vmware_host_inventory.py b/plugins/inventory/vmware_host_inventory.py index 7fc56464b..e6847573f 100644 --- a/plugins/inventory/vmware_host_inventory.py +++ b/plugins/inventory/vmware_host_inventory.py @@ -54,7 +54,7 @@ validate_certs: description: - Allows connection when SSL certificates are not valid. - - Set to C(false) when certificates are not trusted. + - Set to V(false) when certificates are not trusted. default: true type: bool env: @@ -71,7 +71,7 @@ description: - A list of templates in order of precedence to compose inventory_hostname. - Ignores template if resulted in an empty string or None value. - - You can use property specified in I(properties) as variables in the template. + - You can use property specified in O(properties) as variables in the template. type: list elements: string default: ['name'] @@ -80,12 +80,12 @@ - Specify the list of VMware schema properties associated with the ESXi hostsystem. - These properties will be populated in hostvars of the given ESXi hostsystem. - Each value in the list can be a path to a specific property in hostsystem object or a path to a collection of hostsystem objects. - - C(summary.runtime.powerState) are required if C(keyed_groups) is set to default. + - V(summary.runtime.powerState) are required if O(keyed_groups) is set to default. - Please make sure that all the properties that are used in other parameters are included in this options. - In addition to ESXi hostsystem's properties, the following are special values - - Use C(customValue) to populate ESXi hostsystem's custom attributes. C(customValue) is only supported by vCenter and not by ESXi. - - Use C(all) to populate all the properties of the virtual machine. - The value C(all) is time consuming operation, do not use unless required absolutely. + - Use V(customValue) to populate ESXi hostsystem's custom attributes. V(customValue) is only supported by vCenter and not by ESXi. + - Use V(all) to populate all the properties of the virtual machine. + The value V(all) is time consuming operation, do not use unless required absolutely. type: list elements: string default: [ 'name', 'customValue', 'summary.runtime.powerState' ] @@ -112,7 +112,7 @@ description: - A list of resources to limit search scope. - Each resource item is represented by exactly one C('vim_type_snake_case):C(list of resource names) pair and optional nested I(resources) - - Key name is based on snake case of a vim type name; e.g C(host_system) correspond to C(vim.HostSystem) + - Key name is based on snake case of a vim type name; e.g V(host_system) correspond to C(vim.HostSystem) required: false type: list elements: dict @@ -133,7 +133,6 @@ description: - Address of a proxy that will receive all HTTPS requests and relay them. - The format is a hostname or a IP. - - This feature depends on a version of pyvmomi>=v6.7.1.2018.12. type: str required: false env: diff --git a/plugins/inventory/vmware_vm_inventory.py b/plugins/inventory/vmware_vm_inventory.py index 9697b47ba..7962fd7b1 100644 --- a/plugins/inventory/vmware_vm_inventory.py +++ b/plugins/inventory/vmware_vm_inventory.py @@ -54,7 +54,7 @@ validate_certs: description: - Allows connection when SSL certificates are not valid. - - Set to C(false) when certificates are not trusted. + - Set to V(false) when certificates are not trusted. default: true type: bool env: @@ -71,7 +71,7 @@ description: - A list of templates in order of precedence to compose inventory_hostname. - Ignores template if resulted in an empty string or None value. - - You can use property specified in I(properties) as variables in the template. + - You can use property specified in O(properties) as variables in the template. type: list elements: string default: ['config.name + "_" + config.uuid'] @@ -80,13 +80,13 @@ - Specify the list of VMware schema properties associated with the VM. - These properties will be populated in hostvars of the given VM. - Each value in the list can be a path to a specific property in VM object or a path to a collection of VM objects. - - C(config.name), C(config.uuid) are required properties if C(hostnames) is set to default. - - C(config.guestId), C(summary.runtime.powerState) are required if C(keyed_groups) is set to default. + - V(config.name), V(config.uuid) are required properties if O(hostnames) is set to default. + - V(config.guestId), V(summary.runtime.powerState) are required if O(keyed_groups) is set to default. - Please make sure that all the properties that are used in other parameters are included in this options. - In addition to VM properties, the following are special values - - Use C(customValue) to populate virtual machine's custom attributes. C(customValue) is only supported by vCenter and not by ESXi. - - Use C(all) to populate all the properties of the virtual machine. - The value C(all) is time consuming operation, do not use unless required absolutely. + - Use V(customValue) to populate virtual machine's custom attributes. V(customValue) is only supported by vCenter and not by ESXi. + - Use V(all) to populate all the properties of the virtual machine. + The value V(all) is time consuming operation, do not use unless required absolutely. - Please refer more VMware guest attributes which can be used as properties U(https://docs.ansible.com/ansible/latest/collections/community/vmware/docsite/vmware_scenarios/vmware_inventory_vm_attributes.html) type: list @@ -100,7 +100,6 @@ with_nested_properties: description: - This option transform flatten properties name to nested dictionary. - - From 1.10.0 and onwards, default value is set to C(true). type: bool default: true keyed_groups: @@ -122,7 +121,7 @@ description: - A list of resources to limit search scope. - Each resource item is represented by exactly one C('vim_type_snake_case):C(list of resource names) pair and optional nested I(resources) - - Key name is based on snake case of a vim type name; e.g C(host_system) correspond to C(vim.HostSystem) + - Key name is based on snake case of a vim type name; e.g V(host_system) correspond to C(vim.HostSystem) - See L(VIM Types,https://pubs.vmware.com/vi-sdk/visdk250/ReferenceGuide/index-mo_types.html) required: false type: list @@ -144,7 +143,6 @@ description: - Address of a proxy that will receive all HTTPS requests and relay them. - The format is a hostname or a IP. - - This feature depends on a version of pyvmomi>=v6.7.1.2018.12. type: str required: false env: diff --git a/tools/antsibull-docs-wrapper.sh b/tools/antsibull-docs-wrapper.sh index 97b68869d..9a105be6a 100755 --- a/tools/antsibull-docs-wrapper.sh +++ b/tools/antsibull-docs-wrapper.sh @@ -3,5 +3,5 @@ TMPDIR=$(mktemp -d) export ANSIBLE_COLLECTIONS_PATH="$TMPDIR" ansible-galaxy collection install "$1" -antsibull-docs collection-plugins community.vmware --dest-dir docs/ --use-current --output-format simplified-rst --fqcn-plugin-names +antsibull-docs collection-plugins community.vmware --dest-dir "$1/docs/" --use-current --output-format simplified-rst --fqcn-plugin-names rm -rf "$TMPDIR" diff --git a/tools/create_documentation_tasks.yml b/tools/create_documentation_tasks.yml index e5b302f0e..22b4c9b39 100644 --- a/tools/create_documentation_tasks.yml +++ b/tools/create_documentation_tasks.yml @@ -10,4 +10,4 @@ ansible.builtin.shell: tox -e add_docs - name: Update documentation with antsibull-docs - ansible.builtin.shell: "{{ playbook_dir }}/antsibull-docs-wrapper.sh" + ansible.builtin.shell: "{{ playbook_dir }}/antsibull-docs-wrapper.sh {{ playbook_dir }}/.."