xenserver_guest - fixed validations (#2243) (#2253)

* fixed cdrom parameter

* fixed networks and custom_params parameters

* fixed disks parameter

* fixed remaining parameters

* removed plugins/modules/cloud/xenserver/xenserver_guest.py from ignore list

* comments from PR

* comments from PR

* more adjustments from the PR

(cherry picked from commit 69a9a77b65)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

plugins/module_utils/xenserver.py

@@ -20,7 +20,6 @@ except ImportError:
     XENAPI_IMP_ERR = traceback.format_exc()
 
 from ansible.module_utils.basic import env_fallback, missing_required_lib
-from ansible.module_utils.common.network import is_mac
 from ansible.module_utils.ansible_release import __version__ as ANSIBLE_VERSION
 
 

plugins/modules/cloud/xenserver/xenserver_guest.py

@@ -4,7 +4,7 @@
 # Copyright: (c) 2018, Bojan Vitnik <bvitnik@mainstream.rs>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import absolute_import, division, print_function
+from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = r'''
@@ -24,14 +24,14 @@ notes:
    Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
    Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub:
    U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py)'
-- 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are
+- 'If no scheme is specified in I(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are
    accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
-- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no)
+- 'To use C(https://) scheme for I(hostname) you have to either import host certificate to your OS certificate store or use I(validate_certs): C(no)
    which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
-- 'Network configuration inside a guest OS, by using C(networks.type), C(networks.ip), C(networks.gateway) etc. parameters, is supported on
+- 'Network configuration inside a guest OS, by using I(networks.type), I(networks.ip), I(networks.gateway) etc. parameters, is supported on
   XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try to
   detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest
-  agent only support None and Static types of network configuration, where None means DHCP configured interface, C(networks.type) and C(networks.type6)
+  agent only support None and Static types of network configuration, where None means DHCP configured interface, I(networks.type) and I(networks.type6)
   values C(none) and C(dhcp) have same effect. More info here:
   U(https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html)'
 - 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore
@@ -49,10 +49,10 @@ options:
   state:
     description:
     - Specify the state VM should be in.
-    - If C(state) is set to C(present) and VM exists, ensure the VM configuration conforms to given parameters.
+    - If I(state) is set to C(present) and VM exists, ensure the VM configuration conforms to given parameters.
-    - If C(state) is set to C(present) and VM does not exist, then VM is deployed with given parameters.
+    - If I(state) is set to C(present) and VM does not exist, then VM is deployed with given parameters.
-    - If C(state) is set to C(absent) and VM exists, then VM is removed with its associated components.
+    - If I(state) is set to C(absent) and VM exists, then VM is removed with its associated components.
-    - If C(state) is set to C(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically.
+    - If I(state) is set to C(poweredon) and VM does not exist, then VM is deployed with given parameters and powered on automatically.
     type: str
     default: present
     choices: [ present, absent, poweredon ]
@@ -60,10 +60,9 @@ options:
     description:
     - Name of the VM to work with.
     - VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
-    - In case of multiple VMs with same name, use C(uuid) to uniquely specify VM to manage.
+    - In case of multiple VMs with same name, use I(uuid) to uniquely specify VM to manage.
     - This parameter is case sensitive.
     type: str
-    required: yes
     aliases: [ name_label ]
   name_desc:
     description:
@@ -79,7 +78,7 @@ options:
     description:
     - Name of a template, an existing VM (must be shut down) or a snapshot that should be used to create VM.
     - Templates/VMs/snapshots on XenServer do not necessarily have unique names. The module will fail if multiple templates with same name are found.
-    - In case of multiple templates/VMs/snapshots with same name, use C(template_uuid) to uniquely specify source template.
+    - In case of multiple templates/VMs/snapshots with same name, use I(template_uuid) to uniquely specify source template.
     - If VM already exists, this setting will be ignored.
     - This parameter is case sensitive.
     type: str
@@ -104,56 +103,138 @@ options:
   hardware:
     description:
     - Manage VM's hardware parameters. VM needs to be shut down to reconfigure these parameters.
-    - 'Valid parameters are:'
-    - ' - C(num_cpus) (integer): Number of CPUs.'
-    - ' - C(num_cpu_cores_per_socket) (integer): Number of Cores Per Socket. C(num_cpus) has to be a multiple of C(num_cpu_cores_per_socket).'
-    - ' - C(memory_mb) (integer): Amount of memory in MB.'
     type: dict
+    suboptions:
+      num_cpus:
+        description:
+        - Number of CPUs.
+        type: int
+      num_cpu_cores_per_socket:
+        description:
+        - Number of Cores Per Socket. I(num_cpus) has to be a multiple of I(num_cpu_cores_per_socket).
+        type: int
+      memory_mb:
+        description:
+        - Amount of memory in MB.
+        type: int
   disks:
     description:
     - A list of disks to add to VM.
     - All parameters are case sensitive.
     - Removing or detaching existing disks of VM is not supported.
-    - 'Required parameters per entry:'
+    - New disks are required to have either a I(size) or one of I(size_[tb,gb,mb,kb,b]) parameters specified.
-    - ' - C(size_[tb,gb,mb,kb,b]) (integer): Disk storage size in specified unit. VM needs to be shut down to reconfigure this parameter.'
+    - VM needs to be shut down to reconfigure disk size.
-    - 'Optional parameters per entry:'
-    - ' - C(name) (string): Disk name. You can also use C(name_label) as an alias.'
-    - ' - C(name_desc) (string): Disk description.'
-    - ' - C(sr) (string): Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR.'
-    - ' - C(sr_uuid) (string): UUID of a SR to create disk on. Use if SR name is not unique.'
     type: list
     elements: dict
     aliases: [ disk ]
+    suboptions:
+      size:
+        description:
+        - 'Disk size with unit. Unit must be: C(b), C(kb), C(mb), C(gb), C(tb). VM needs to be shut down to reconfigure this parameter.'
+        - If no unit is specified, size is assumed to be in bytes.
+        type: str
+      size_b:
+        description:
+        - Disk size in bytes.
+        type: str
+      size_kb:
+        description:
+        - Disk size in kilobytes.
+        type: str
+      size_mb:
+        description:
+        - Disk size in megabytes.
+        type: str
+      size_gb:
+        description:
+        - Disk size in gigabytes.
+        type: str
+      size_tb:
+        description:
+        - Disk size in terabytes.
+        type: str
+      name:
+        description:
+        - Disk name.
+        type: str
+        aliases: [ name_label ]
+      name_desc:
+        description:
+        - Disk description.
+        type: str
+      sr:
+        description:
+        - Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR.
+        type: str
+      sr_uuid:
+        description:
+        - UUID of a SR to create disk on. Use if SR name is not unique.
+        type: str
   cdrom:
     description:
     - A CD-ROM configuration for the VM.
     - All parameters are case sensitive.
-    - 'Valid parameters are:'
-    - ' - C(type) (string): The type of CD-ROM, valid options are C(none) or C(iso). With C(none) the CD-ROM device will be present but empty.'
-    - ' - C(iso_name) (string): The file name of an ISO image from one of the XenServer ISO Libraries (implies C(type: iso)).
-          Required if C(type) is set to C(iso).'
     type: dict
+    suboptions:
+      type:
+        description:
+        - The type of CD-ROM. With C(none) the CD-ROM device will be present but empty.
+        type: str
+        choices: [ none, iso ]
+      iso_name:
+        description:
+        - 'The file name of an ISO image from one of the XenServer ISO Libraries (implies I(type): C(iso)).'
+        - Required if I(type) is set to C(iso).
+        type: str
   networks:
     description:
     - A list of networks (in the order of the NICs).
     - All parameters are case sensitive.
-    - 'Required parameters per entry:'
+    - Name is required for new NICs. Other parameters are optional in all cases.
-    - ' - C(name) (string): Name of a XenServer network to attach the network interface to. You can also use C(name_label) as an alias.'
-    - 'Optional parameters per entry (used for VM hardware):'
-    - ' - C(mac) (string): Customize MAC address of the interface.'
-    - 'Optional parameters per entry (used for OS customization):'
-    - ' - C(type) (string): Type of IPv4 assignment, valid options are C(none), C(dhcp) or C(static). Value C(none) means whatever is default for OS.
-          On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux).'
-    - ' - C(ip) (string): Static IPv4 address (implies C(type: static)). Can include prefix in format <IPv4 address>/<prefix> instead of using C(netmask).'
-    - ' - C(netmask) (string): Static IPv4 netmask required for C(ip) if prefix is not specified.'
-    - ' - C(gateway) (string): Static IPv4 gateway.'
-    - ' - C(type6) (string): Type of IPv6 assignment, valid options are C(none), C(dhcp) or C(static). Value C(none) means whatever is default for OS.
-          On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux).'
-    - ' - C(ip6) (string): Static IPv6 address (implies C(type6: static)) with prefix in format <IPv6 address>/<prefix>.'
-    - ' - C(gateway6) (string): Static IPv6 gateway.'
     type: list
     elements: dict
     aliases: [ network ]
+    suboptions:
+        name:
+          description:
+          - Name of a XenServer network to attach the network interface to.
+          type: str
+          aliases: [ name_label ]
+        mac:
+          description:
+          - Customize MAC address of the interface.
+          type: str
+        type:
+          description:
+            - Type of IPv4 assignment. Value C(none) means whatever is default for OS.
+            - On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux).
+          type: str
+          choices: [ none, dhcp, static ]
+        ip:
+          description:
+          - 'Static IPv4 address (implies I(type): C(static)). Can include prefix in format C(<IPv4 address>/<prefix>) instead of using C(netmask).'
+          type: str
+        netmask:
+          description:
+          - Static IPv4 netmask required for I(ip) if prefix is not specified.
+          type: str
+        gateway:
+          description:
+          - Static IPv4 gateway.
+          type: str
+        type6:
+          description:
+          - Type of IPv6 assignment. Value C(none) means whatever is default for OS.
+          type: str
+          choices: [ none, dhcp, static ]
+        ip6:
+          description:
+          - 'Static IPv6 address (implies I(type6): C(static)) with prefix in format C(<IPv6 address>/<prefix>).'
+          type: str
+        gateway6:
+          description:
+          - Static IPv6 gateway.
+          type: str
   home_server:
     description:
     - Name of a XenServer host that will be a Home Server for the VM.
@@ -163,18 +244,29 @@ options:
     description:
     - Define a list of custom VM params to set on VM.
     - Useful for advanced users familiar with managing VM params trough xe CLI.
-    - A custom value object takes two fields C(key) and C(value) (see example below).
+    - A custom value object takes two fields I(key) and I(value) (see example below).
     type: list
     elements: dict
+    suboptions:
+      key:
+        description:
+        - VM param name.
+        type: str
+        required: yes
+      value:
+        description:
+        - VM param value.
+        type: raw
+        required: yes
   wait_for_ip_address:
     description:
-    - Wait until XenServer detects an IP address for the VM. If C(state) is set to C(absent), this parameter is ignored.
+    - Wait until XenServer detects an IP address for the VM. If I(state) is set to C(absent), this parameter is ignored.
     - This requires XenServer Tools to be preinstalled on the VM to work properly.
     type: bool
     default: no
   state_change_timeout:
     description:
-    - 'By default, module will wait indefinitely for VM to accquire an IP address if C(wait_for_ip_address: yes).'
+    - 'By default, module will wait indefinitely for VM to accquire an IP address if I(wait_for_ip_address): C(yes).'
     - If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
     - In case of timeout, module will generate an error message.
     type: int
@@ -441,11 +533,12 @@ except ImportError:
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.common.network import is_mac
 from ansible.module_utils import six
-from ansible_collections.community.general.plugins.module_utils.xenserver import (xenserver_common_argument_spec, XAPI, XenServerObject, get_object_ref,
+from ansible_collections.community.general.plugins.module_utils.xenserver import (
-                                                                                  gather_vm_params, gather_vm_facts, set_vm_power_state,
+    xenserver_common_argument_spec, XenServerObject, get_object_ref,
-                                                                                  wait_for_vm_ip_address, is_valid_ip_addr, is_valid_ip_netmask,
+    gather_vm_params, gather_vm_facts, set_vm_power_state,
-                                                                                  is_valid_ip_prefix, ip_prefix_to_netmask, ip_netmask_to_prefix,
+    wait_for_vm_ip_address, is_valid_ip_addr, is_valid_ip_netmask,
-                                                                                  is_valid_ip6_addr, is_valid_ip6_prefix)
+    is_valid_ip_prefix, ip_prefix_to_netmask, ip_netmask_to_prefix,
+    is_valid_ip6_addr, is_valid_ip6_prefix)
 
 
 class XenServerVM(XenServerObject):

tests/sanity/ignore-2.10.txt

@@ -95,11 +95,6 @@ plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:parameter-type
 plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:undocumented-parameter
 plugins/modules/cloud/univention/udm_share.py validate-modules:parameter-list-no-elements
 plugins/modules/cloud/univention/udm_user.py validate-modules:parameter-list-no-elements
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-choices-do-not-match-spec  # missing docs on suboptions
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-required-mismatch          # missing docs on suboptions
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:missing-suboption-docs         # missing docs on suboptions
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:parameter-type-not-in-doc      # missing docs on suboptions
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:undocumented-parameter         # missing docs on suboptions
 plugins/modules/clustering/consul/consul.py validate-modules:doc-missing-type
 plugins/modules/clustering/consul/consul.py validate-modules:undocumented-parameter
 plugins/modules/clustering/consul/consul_session.py validate-modules:parameter-state-invalid-choice

tests/sanity/ignore-2.11.txt

@@ -94,11 +94,6 @@ plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:parameter-type
 plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:undocumented-parameter
 plugins/modules/cloud/univention/udm_share.py validate-modules:parameter-list-no-elements
 plugins/modules/cloud/univention/udm_user.py validate-modules:parameter-list-no-elements
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-choices-do-not-match-spec
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-required-mismatch
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:missing-suboption-docs
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:parameter-type-not-in-doc
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:undocumented-parameter
 plugins/modules/clustering/consul/consul.py validate-modules:doc-missing-type
 plugins/modules/clustering/consul/consul.py validate-modules:undocumented-parameter
 plugins/modules/clustering/consul/consul_session.py validate-modules:parameter-state-invalid-choice

tests/sanity/ignore-2.12.txt

@@ -94,11 +94,6 @@ plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:parameter-type
 plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:undocumented-parameter
 plugins/modules/cloud/univention/udm_share.py validate-modules:parameter-list-no-elements
 plugins/modules/cloud/univention/udm_user.py validate-modules:parameter-list-no-elements
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-choices-do-not-match-spec
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-required-mismatch
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:missing-suboption-docs
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:parameter-type-not-in-doc
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:undocumented-parameter
 plugins/modules/clustering/consul/consul.py validate-modules:doc-missing-type
 plugins/modules/clustering/consul/consul.py validate-modules:undocumented-parameter
 plugins/modules/clustering/consul/consul_session.py validate-modules:parameter-state-invalid-choice

tests/sanity/ignore-2.9.txt

@@ -133,10 +133,6 @@ plugins/modules/cloud/spotinst/spotinst_aws_elastigroup.py validate-modules:undo
 plugins/modules/cloud/univention/udm_dns_record.py validate-modules:parameter-type-not-in-doc
 plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:parameter-type-not-in-doc
 plugins/modules/cloud/univention/udm_dns_zone.py validate-modules:undocumented-parameter
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:doc-choices-do-not-match-spec
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:missing-suboption-docs
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:parameter-type-not-in-doc
-plugins/modules/cloud/xenserver/xenserver_guest.py validate-modules:undocumented-parameter
 plugins/modules/clustering/consul/consul.py validate-modules:doc-missing-type
 plugins/modules/clustering/consul/consul.py validate-modules:undocumented-parameter
 plugins/modules/net_tools/ldap/ldap_attr.py validate-modules:deprecation-mismatch