community.vmware.vmware_guest_network – Manage network adapters of specified virtual machine in given vCenter infrastructure
community.vmware.vmware_guest_network – Manage network adapters of specified virtual machine in given vCenter infrastructure
Note
This plugin is part of the community.vmware collection (version 1.7.0).
To install it use: ansible-galaxy collection install community.vmware
.
To use it in a playbook, specify: community.vmware.vmware_guest_network
.
New in version 1.0.0: of community.vmware
Synopsis
- This module is used to add, reconfigure, remove network adapter of given virtual machine.
Requirements
The below requirements are needed on the host that executes this module.
- python >= 2.7
- PyVmomi
Parameters
Parameter | Choices/Defaults | Comments | |
---|---|---|---|
cluster string |
Name of cluster where VM belongs to. | ||
connected boolean |
|
If NIC should be connected to the network. | |
datacenter string |
Default: "ha-datacenter" |
Datacenter the VM belongs to. | |
device_type string |
Default: "vmxnet3" |
Type of virtual network device. Valid choices are - | |
directpath_io boolean |
|
Enable Universal Pass-through (UPT). Only compatible with the | |
esxi_hostname string |
The hostname of the ESXi host where the VM belongs to. | ||
folder string |
Folder location of given VM, this is only required when there's multiple VM's with the same name. | ||
force boolean |
|
Force adapter creation even if an existing adapter is attached to the same network. | |
gather_network_info boolean |
|
Return information about current guest network adapters.
| |
guest_control boolean |
|
Enables guest control over whether the connectable device is connected. | |
hostname string |
The hostname or IP address of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. | ||
label string |
Alter the name of the network adapter. | ||
mac_address string |
MAC address of the NIC that should be altered, if a MAC address is not supplied a new nic will be created. Required when state=absent. | ||
moid string |
Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance. Required if | ||
name string |
Name of virtual machine Required if | ||
network_name string |
Name of network in vSphere. | ||
networks list / elements=dictionary |
This method will be deprecated, use loops in your playbook for multiple interfaces instead. A list of network adapters.
If there are multiple network adapters with the same
| ||
connected boolean |
|
Indicates that virtual network adapter connects to the associated virtual machine. | |
device_type string |
Valid virtual network device types are Used to add new network adapter, reconfigure or remove the existing network adapter with this type. If | ||
directpath_io boolean |
|
If set, Universal Pass-Through (UPT or DirectPath I/O) will be enabled on the network adapter. UPT is only compatible for Vmxnet3 adapter. | |
dvswitch_name string |
Name of the distributed vSwitch. This value is required if multiple distributed portgroups exists with the same name. | ||
label string |
Label of the existing network adapter to be reconfigured or removed, e.g., "Network adapter 1". | ||
mac string |
MAC address of the existing network adapter to be reconfigured or removed. | ||
manual_mac string |
Manual specified MAC address of the network adapter when creating, or reconfiguring. If not specified when creating new network adapter, mac address will be generated automatically. When reconfigure MAC address, VM should be in powered off state. | ||
name string |
Name of the portgroup or distributed virtual portgroup for this interface. When specifying distributed virtual portgroup make sure given | ||
start_connected boolean |
|
Indicates that virtual network adapter starts with associated virtual machine powers on. | |
state string |
State of the network adapter. If set to If set to If set to | ||
vlan integer |
VLAN number for this interface. | ||
password string |
The password of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6.
| ||
port integer |
Default: 443 |
The port number of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. | |
proxy_host string |
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 This feature depends on a version of pyvmomi greater than v6.7.1.2018.12 | ||
proxy_port integer |
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 | ||
start_connected boolean |
|
If NIC should be connected to network on startup. | |
state string |
|
NIC state. When When | |
switch string |
Name of the (dv)switch for destination network, this is only required for dvswitches. | ||
use_instance_uuid boolean |
|
Whether to use the VMware instance UUID rather than the BIOS UUID. | |
username string |
The username of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6.
| ||
uuid string |
vm uuid Required if | ||
validate_certs boolean |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. If set to | |
vlan_id integer |
VLAN id associated with the network. | ||
wake_onlan boolean |
|
Enable wake on LAN. |
Notes
Note
- Tested on vSphere 6.0, 6.5 and 6.7
- For backwards compatibility network_data is returned when using the gather_network_info and networks parameters
Examples
- name: change network for 00:50:56:11:22:33 on vm01.domain.fake
community.vmware.vmware_guest_network:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
name: vm01.domain.fake
mac_address: 00:50:56:11:22:33
network_name: admin-network
state: present
- name: add a nic on network with vlan id 2001 for 422d000d-2000-ffff-0000-b00000000000
community.vmware.vmware_guest_network:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
uuid: 422d000d-2000-ffff-0000-b00000000000
vlan_id: 2001
- name: remove nic with mac 00:50:56:11:22:33 from vm01.domain.fake
community.vmware.vmware_guest_network:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
mac_address: 00:50:56:11:22:33
name: vm01.domain.fake
state: absent
- name: add multiple nics to vm01.domain.fake
community.vmware.vmware_guest_network:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
name: vm01.domain.fake
state: present
vlan_id: "{{ item.vlan_id | default(omit) }}"
network_name: "{{ item.network_name | default(omit) }}"
connected: "{{ item.connected | default(omit) }}"
loop:
- vlan_id: 2000
connected: false
- network_name: guest-net
connected: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
network_data dictionary |
when using gather_network_info or networks parameters |
For backwards compatibility, metadata about the virtual machine network adapters
Sample: {'network_data': {'0': {'allow_guest_ctl': True, 'connected': True, 'device_type': 'vmxnet3', 'label': 'Network adapter 2', 'mac_addr': '00:50:56:AA:AA:AA', 'mac_address': '00:50:56:AA:AA:AA', 'name': 'admin-net', 'network_name': 'admin-net', 'start_connected': True, 'switch': 'vSwitch0', 'unit_number': 8, 'vlan_id': 10, 'wake_onlan': False}, '1': {'allow_guest_ctl': True, 'connected': True, 'device_type': 'vmxnet3', 'label': 'Network adapter 1', 'mac_addr': '00:50:56:BB:BB:BB', 'mac_address': '00:50:56:BB:BB:BB', 'name': 'guest-net', 'network_name': 'guest-net', 'start_connected': True, 'switch': 'vSwitch0', 'unit_number': 7, 'vlan_id': 10, 'wake_onlan': True}}} |
network_info list / elements=string |
always |
metadata about the virtual machine network adapters
Sample: {'network_info': [{'allow_guest_ctl': True, 'connected': True, 'device_type': 'vmxnet3', 'label': 'Network adapter 2', 'mac_address': '00:50:56:AA:AA:AA', 'network_name': 'admin-net', 'start_connected': True, 'switch': 'vSwitch0', 'unit_number': 8, 'vlan_id': 10, 'wake_onlan': False}, {'allow_guest_ctl': True, 'connected': True, 'device_type': 'vmxnet3', 'label': 'Network adapter 1', 'mac_address': '00:50:56:BB:BB:BB', 'network_name': 'guest-net', 'start_connected': True, 'switch': 'vSwitch0', 'unit_number': 7, 'vlan_id': 10, 'wake_onlan': True}]} |
Authors
- Diane Wang (@Tomorrow9) <[email protected]>
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/community/vmware/vmware_guest_network_module.html