community.vmware.vmware_guest_network module – Manage network adapters of specified virtual machine in given vCenter infrastructure
Note
This module is part of the community.vmware collection (version 2.10.2).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.vmware.
To use it in a playbook, specify: community.vmware.vmware_guest_network.
New in community.vmware 1.0.0
Synopsis
This module is used to add, reconfigure, remove network adapter of given virtual machine.
Parameters
Parameter |
Comments |
|---|---|
Allows the guest OS to change the MTU on a SR-IOV network adapter. This option is only compatible for SR-IOV network adapters. Choices:
|
|
Name of cluster where VM belongs to. |
|
If NIC should be connected to the network. Choices:
|
|
Datacenter the VM belongs to. Default: |
|
Type of virtual network device. Valid choices are - Default: |
|
Enable Universal Pass-through (UPT). Only compatible with the Choices:
|
|
The hostname of the ESXi host where the VM belongs to. |
|
Folder location of given VM, this is only required when there’s multiple VM’s with the same name. |
|
Force adapter creation even if an existing adapter is attached to the same network. Choices:
|
|
Return information about current guest network adapters. Choices:
|
|
Enables guest control over whether the connectable device is connected. Choices:
|
|
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. |
|
Alter the name of the network adapter. |
|
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. |
|
Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance. Required if |
|
Name of virtual machine Required if |
|
Name of network in vSphere. |
|
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
Default: |
|
Allows the guest OS to change the MTU on a SR-IOV network adapter. This option is only compatible for SR-IOV network adapters. Choices:
|
|
Indicates that virtual network adapter connects to the associated virtual machine. Choices:
|
|
Valid virtual network device types are Used to add new network adapter, reconfigure or remove the existing network adapter with this type. If |
|
If set, Universal Pass-Through (UPT or DirectPath I/O) will be enabled on the network adapter. UPT is only compatible for Vmxnet3 adapter. Choices:
|
|
Name of the distributed vSwitch. This value is required if multiple distributed portgroups exists with the same name. |
|
Label of the existing network adapter to be reconfigured or removed, e.g., “Network adapter 1”. |
|
MAC address of the existing network adapter to be reconfigured or removed. |
|
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. There are restrictions on the MAC addresses you can set. Consult the documentation of your vSphere version as to allowed MAC addresses. |
|
Name of the portgroup or distributed virtual portgroup for this interface. When specifying distributed virtual portgroup make sure given |
|
If set, specifies the PCI ID of the physical function to use as backing for a SR-IOV network adapter. This option is only compatible for SR-IOV network adapters. |
|
Indicates that virtual network adapter starts with associated virtual machine powers on. Choices:
|
|
State of the network adapter. If set to If set to If set to |
|
If set, specifies the PCI ID of the physical function to use as backing for a SR-IOV network adapter. This option is only compatible for SR-IOV network adapters. |
|
VLAN number for this interface. |
|
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. |
|
If set, specifies the PCI ID of the physical function to use as backing for a SR-IOV network adapter. This option is only compatible for SR-IOV network adapters. |
|
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. Default: |
|
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 |
|
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 |
|
If NIC should be connected to network on startup. Choices:
|
|
NIC state. When When Choices:
|
|
Name of the (dv)switch for destination network, this is only required for dvswitches. |
|
Whether to use the VMware instance UUID rather than the BIOS UUID. Choices:
|
|
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. |
|
vm uuid Required if |
|
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 Choices:
|
|
If set, specifies the PCI ID of the physical function to use as backing for a SR-IOV network adapter. This option is only compatible for SR-IOV network adapters. |
|
VLAN id associated with the network. |
|
Enable wake on LAN. Choices:
|
Notes
Note
For backwards compatibility network_data is returned when using the gather_network_info and networks parameters
All modules requires API write access and hence is not supported on a free ESXi license.
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 |
Description |
|---|---|
For backwards compatibility, metadata about the virtual machine network adapters Returned: when using gather_network_info or networks parameters Sample: |
|
metadata about the virtual machine network adapters Returned: always Sample: |