Repository: ansible-collections/community.vmware

Issue:
vmware_guest: Network parameters are missing in the documentation
##### SUMMARY

**networks** parameter is missing two sub parameters in the document section and thats impacting template deployment which need to attach different dvpg than the one actually available in the template.

- connected
- start_connected

<!--- HINT: Did you know the documentation has an "Edit on GitHub" link on every page ? -->

For ansible 2.10, there is no edit option available in the documentation page.

##### ISSUE TYPE
- Documentation Report

##### COMPONENT NAME
- networks

##### ANSIBLE VERSION
```
$ pip3 show ansible
Name: ansible
Version: 2.10.3
Summary: Radically simple IT automation
Home-page: https://ansible.com/
Author: Ansible, Inc.
Author-email: info@ansible.com
License: GPLv3+
Location: /usr/local/lib/python3.8/dist-packages
Requires: ansible-base
Required-by:
```

##### PLAYBOOK
This is an example of the play from a playbook that has already been tested and working perfectly:

```
- name: Deploy the vm '{{ inventory_hostname }}'
  vmware_guest:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    datacenter: '{{ vsphere_datacenter }}'
    cluster: '{{ vsphere_cluster }}'
    datastore: '{{ vsphere_datastore }}'
    name: '{{ inventory_hostname }}'
    template: '{{ win_temp }}'
    folder: '/{{ vsphere_datacenter }}/vm/{{ vsphere_folder }}'
    validate_certs: 'no'
    networks:
    - name: '{{ Mgmt_network }}'
      ip: "{{ Mgmt_network_ipv4 }}"
      netmask: '{{ Mgmt_network_nmv4 }}'
      gateway: '{{ Mgmt_network_gwv4 }}'
      device_type: vmxnet3
      connected: True
      start_connected: True
      type: static
      dns_servers:
        - '{{ dns_server1 }}'
        - '{{ dns_server2 }}'
    state: present
    wait_for_ip_address: yes
    customization:
      hostname: "{{ vsphere_vm_hostname }}"
      dns_suffix: '{{ ad_domain }}'
      domainadmin: '{{ ad_domain_admin }}'
      domainadminpassword: '{{ ad_domain_password }}'
      joindomain: '{{ ad_domain }}'
      timezone: '{{ timezone }}'
    wait_for_customization: yes
  delegate_to: localhost
```

Without the following two components, the deployment wont attach the nic and activate it. So other plays having dependency on the network will fail:
```
      connected: True
      start_connected: True
```


Discussion:

Resolving patch:
diff --git a/plugins/modules/vmware_guest.py b/plugins/modules/vmware_guest.py
--- a/plugins/modules/vmware_guest.py
+++ b/plugins/modules/vmware_guest.py
@@ -510,6 +510,15 @@
             - Domain name for this network interface (Windows).
             - Optional per entry.
             - Used for OS customization.
+        connected:
+            type: bool
+            description:
+            - Indicates whether the NIC is currently connected.
+            version_added: '1.5.0'
+        start_connected:
+            type: bool
+            description:
+            - Specifies whether or not to connect the device when the virtual machine starts.
   customization:
     description:
     - Parameters for OS customization when cloning from the template or the virtual machine, or apply to the existing virtual machine directly.
@@ -1224,7 +1233,7 @@ def create_nic(self, device_type, device_label, device_infos):
         nic.device.connectable = vim.vm.device.VirtualDevice.ConnectInfo()
         nic.device.connectable.startConnected = bool(device_infos.get('start_connected', True))
         nic.device.connectable.allowGuestControl = bool(device_infos.get('allow_guest_control', True))
-        nic.device.connectable.connected = True
+        nic.device.connectable.connected = bool(device_infos.get('connected', True))
         if 'mac' in device_infos and is_mac(device_infos['mac']):
             nic.device.addressType = 'manual'
             nic.device.macAddress = device_infos['mac']
@@ -1950,34 +1959,21 @@ def configure_network(self, vm_obj):
                 nic.operation = vim.vm.device.VirtualDeviceSpec.Operation.edit
 
                 nic.device = current_net_devices[key]
-                if "wake_on_lan" in network_devices[
-                    key
-                ] and nic.device.wakeOnLanEnabled != network_devices[key].get(
-                    "wake_on_lan"
-                ):
-                    nic.device.wakeOnLanEnabled = network_devices[key].get(
-                        "wake_on_lan"
-                    )
+                if "wake_on_lan" in network_devices[key] and \
+                   nic.device.wakeOnLanEnabled != network_devices[key].get("wake_on_lan"):
+                    nic.device.wakeOnLanEnabled = network_devices[key].get("wake_on_lan")
                     nic_change_detected = True
-                if "start_connected" in network_devices[
-                    key
-                ] and nic.device.connectable.startConnected != network_devices[key].get(
-                    "start_connected"
-                ):
-                    nic.device.connectable.startConnected = network_devices[key].get(
-                        "start_connected"
-                    )
+                if "start_connected" in network_devices[key] and \
+                   nic.device.connectable.startConnected != network_devices[key].get("start_connected"):
+                    nic.device.connectable.startConnected = network_devices[key].get("start_connected")
                     nic_change_detected = True
-                if "allow_guest_control" in network_devices[
-                    key
-                ] and nic.device.connectable.allowGuestControl != network_devices[
-                    key
-                ].get(
-                    "allow_guest_control"
-                ):
-                    nic.device.connectable.allowGuestControl = network_devices[key].get(
-                        "allow_guest_control"
-                    )
+                if "connected" in network_devices[key] and \
+                   nic.device.connectable.connected != network_devices[key].get("connected"):
+                    nic.device.connectable.connected = network_devices[key].get("connected")
+                    nic_change_detected = True
+                if "allow_guest_control" in network_devices[key] and \
+                   nic.device.connectable.allowGuestControl != network_devices[key].get("allow_guest_control"):
+                    nic.device.connectable.allowGuestControl = network_devices[key].get("allow_guest_control")
                     nic_change_detected = True
 
                 if nic.device.deviceInfo.summary != network_name:
@@ -2003,9 +1999,9 @@ def configure_network(self, vm_obj):
                 nic.operation = vim.vm.device.VirtualDeviceSpec.Operation.add
                 nic_change_detected = True
 
-            if hasattr(self.cache.get_network(network_name), 'portKeys'):
+            net_obj = self.cache.get_network(network_name)
+            if hasattr(net_obj, 'portKeys'):
                 # VDS switch
-
                 pg_obj = None
                 if 'dvswitch_name' in network_devices[key]:
                     dvs_name = network_devices[key]['dvswitch_name']
@@ -2052,10 +2048,10 @@ def configure_network(self, vm_obj):
                 nic.device.backing = vim.vm.device.VirtualEthernetCard.DistributedVirtualPortBackingInfo()
                 nic.device.backing.port = dvs_port_connection
 
-            elif isinstance(self.cache.get_network(network_name), vim.OpaqueNetwork):
+            elif isinstance(net_obj, vim.OpaqueNetwork):
                 # NSX-T Logical Switch
                 nic.device.backing = vim.vm.device.VirtualEthernetCard.OpaqueNetworkBackingInfo()
-                network_id = self.cache.get_network(network_name).summary.opaqueNetworkId
+                network_id = net_obj.summary.opaqueNetworkId
                 nic.device.backing.opaqueNetworkType = 'nsx.LogicalSwitch'
                 nic.device.backing.opaqueNetworkId = network_id
                 nic.device.deviceInfo.summary = 'nsx.LogicalSwitch: %s' % network_id
@@ -2066,7 +2062,6 @@ def configure_network(self, vm_obj):
                     nic.device.backing = vim.vm.device.VirtualEthernetCard.NetworkBackingInfo()
                     nic_change_detected = True
 
-                net_obj = self.cache.get_network(network_name)
                 if nic.device.backing.network != net_obj:
                     nic.device.backing.network = net_obj
                     nic_change_detected = True
@@ -2079,7 +2074,7 @@ def configure_network(self, vm_obj):
                 # Change to fix the issue found while configuring opaque network
                 # VMs cloned from a template with opaque network will get disconnected
                 # Replacing deprecated config parameter with relocation Spec
-                if isinstance(self.cache.get_network(network_name), vim.OpaqueNetwork):
+                if isinstance(net_obj, vim.OpaqueNetwork):
                     self.relospec.deviceChange.append(nic)
                 else:
                     self.configspec.deviceChange.append(nic)


Test patch: