community.vmware.vmware_dvs_portgroup module – Create or remove a Distributed vSwitch portgroup.

Note

This module is part of the community.vmware collection (version 1.18.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_dvs_portgroup.

Synopsis

  • Create or remove a Distributed vSwitch portgroup.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6

  • PyVmomi

Parameters

Parameter

Comments

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 VMWARE_HOST will be used instead.

Environment variable support added in Ansible 2.6.

mac_learning

dictionary

added in 1.10.0 of community.vmware

Dictionary which configures MAC learning for portgroup.

allow_unicast_flooding

boolean

The flag to allow flooding of unlearned MAC for ingress traffic.

Choices:

  • no

  • yes

enabled

boolean

The flag to indicate if source MAC address learning is allowed.

Choices:

  • no

  • yes

limit

integer

The maximum number of MAC addresses that can be learned.

limit_policy

string

The default switching policy after MAC limit is exceeded.

Choices:

  • allow

  • drop

network_policy

dictionary

Dictionary which configures the different security values for portgroup.

Default: {“forged_transmits”: false, “mac_changes”: false, “promiscuous”: false}

forged_transmits

boolean

Indicates whether forged transmits are allowed.

Choices:

  • no ← (default)

  • yes

mac_changes

boolean

Indicates whether mac changes are allowed.

Choices:

  • no ← (default)

  • yes

promiscuous

boolean

Indicates whether promiscuous mode is allowed.

Choices:

  • no ← (default)

  • yes

num_ports

integer

The number of ports the portgroup should contain.

password

aliases: pass, pwd

string

The password of the vSphere vCenter or ESXi server.

If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.

Environment variable support added in Ansible 2.6.

port

integer

The port number of the vSphere vCenter or ESXi server.

If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.

Environment variable support added in Ansible 2.6.

Default: 443

port_allocation

string

added in 1.10.0 of community.vmware

Elastic port groups automatically increase or decrease the number of ports as needed.

Only valid if port_binding is set to static.

Will be elastic if not specified and port_binding is set to static.

Choices:

  • elastic

  • fixed

port_binding

string

added in 1.10.0 of community.vmware

The type of port binding determines when ports in a port group are assigned to virtual machines.

See VMware KB 1022312 https://kb.vmware.com/s/article/1022312 for more details.

Choices:

  • static

  • ephemeral

port_policy

dictionary

Dictionary which configures the advanced policy settings for the portgroup.

Default: {“block_override”: true, “ipfix_override”: false, “live_port_move”: false, “network_rp_override”: false, “port_config_reset_at_disconnect”: true, “security_override”: false, “shaping_override”: false, “traffic_filter_override”: false, “uplink_teaming_override”: false, “vendor_config_override”: false, “vlan_override”: false}

block_override

boolean

Indicates if the block policy can be changed per port.

Choices:

  • no

  • yes ← (default)

ipfix_override

boolean

Indicates if the ipfix policy can be changed per port.

Choices:

  • no ← (default)

  • yes

live_port_move

boolean

Indicates if a live port can be moved in or out of the portgroup.

Choices:

  • no ← (default)

  • yes

network_rp_override

boolean

Indicates if the network resource pool can be changed per port.

Choices:

  • no ← (default)

  • yes

port_config_reset_at_disconnect

boolean

Indicates if the configuration of a port is reset automatically after disconnect.

Choices:

  • no

  • yes ← (default)

security_override

boolean

Indicates if the security policy can be changed per port.

Choices:

  • no ← (default)

  • yes

shaping_override

boolean

Indicates if the shaping policy can be changed per port.

Choices:

  • no ← (default)

  • yes

traffic_filter_override

boolean

Indicates if the traffic filter can be changed per port.

Choices:

  • no ← (default)

  • yes

boolean

Indicates if the uplink teaming policy can be changed per port.

Choices:

  • no ← (default)

  • yes

vendor_config_override

boolean

Indicates if the vendor config can be changed per port.

Choices:

  • no ← (default)

  • yes

vlan_override

boolean

Indicates if the vlan can be changed per port.

Choices:

  • no ← (default)

  • yes

portgroup_name

string / required

The name of the portgroup that is to be created or deleted.

portgroup_type

string

See VMware KB 1022312 regarding portgroup types.

Deprecated. Will be removed 2021-12-01.

Choices:

  • earlyBinding

  • lateBinding

  • ephemeral

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 VMWARE_PROXY_HOST will be used instead.

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 VMWARE_PROXY_PORT will be used instead.

state

string / required

Determines if the portgroup should be present or not.

Choices:

  • present

  • absent

switch_name

string / required

The name of the distributed vSwitch the port group should be created on.

teaming_policy

dictionary

Dictionary which configures the different teaming values for portgroup.

Default: {“load_balance_policy”: “loadbalance_srcid”, “notify_switches”: true, “rolling_order”: false}

list / elements=string

added in 1.10.0 of community.vmware

List of active uplinks used for load balancing.

inbound_policy

boolean

Indicate whether or not the teaming policy is applied to inbound frames as well.

Choices:

  • no

  • yes

load_balance_policy

string

Network adapter teaming policy.

loadbalance_loadbased is available from version 2.6 and onwards.

Choices:

  • loadbalance_ip

  • loadbalance_srcmac

  • loadbalance_srcid ← (default)

  • loadbalance_loadbased

  • failover_explicit

notify_switches

boolean

Indicate whether or not to notify the physical switch if a link fails.

Choices:

  • no

  • yes ← (default)

rolling_order

boolean

Indicate whether or not to use a rolling policy when restoring links.

Choices:

  • no ← (default)

  • yes

list / elements=string

added in 1.10.0 of community.vmware

List of standby uplinks used for failover.

username

aliases: admin, user

string

The username of the vSphere vCenter or ESXi server.

If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.

Environment variable support added in Ansible 2.6.

validate_certs

boolean

Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.

If the value is not specified in the task, the value of environment variable VMWARE_VALIDATE_CERTS will be used instead.

Environment variable support added in Ansible 2.6.

If set to true, please make sure Python >= 2.7.9 is installed on the given machine.

Choices:

  • no

  • yes ← (default)

vlan_id

string / required

The VLAN ID that should be configured with the portgroup, use 0 for no VLAN.

If vlan_trunk is configured to be true, this can be a combination of multiple ranges and numbers, example: 1-200, 205, 400-4094.

The valid vlan_id range is from 0 to 4094. Overlapping ranges are allowed.

If vlan_private is configured to be true, the corresponding private VLAN should already be configured in the distributed vSwitch.

vlan_private

boolean

Indicates whether this is for a private VLAN or not.

Mutually exclusive with vlan_trunk parameter.

Choices:

  • no ← (default)

  • yes

vlan_trunk

boolean

Indicates whether this is a VLAN trunk or not.

Mutually exclusive with vlan_private parameter.

Choices:

  • no ← (default)

  • yes

Notes

Note

  • Tested on vSphere 7.0

  • All modules requires API write access and hence is not supported on a free ESXi license.

Examples

- name: Create vlan portgroup
  community.vmware.vmware_dvs_portgroup:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    portgroup_name: vlan-123-portrgoup
    switch_name: dvSwitch
    vlan_id: 123
    num_ports: 120
    port_binding: static
    state: present
  delegate_to: localhost

- name: Create vlan trunk portgroup
  community.vmware.vmware_dvs_portgroup:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    portgroup_name: vlan-trunk-portrgoup
    switch_name: dvSwitch
    vlan_id: 1-1000, 1005, 1100-1200
    vlan_trunk: True
    num_ports: 120
    port_binding: static
    state: present
  delegate_to: localhost

- name: Create private vlan portgroup
  vmware_dvs_portgroup:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    portgroup_name: private-vlan-portrgoup
    switch_name: dvSwitch
    vlan_id: 1001
    vlan_private: True
    num_ports: 120
    port_binding: static
    state: present
  delegate_to: localhost

- name: Create no-vlan portgroup
  community.vmware.vmware_dvs_portgroup:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    portgroup_name: no-vlan-portrgoup
    switch_name: dvSwitch
    vlan_id: 0
    num_ports: 120
    port_binding: static
    state: present
  delegate_to: localhost

- name: Create vlan portgroup with all security and port policies
  community.vmware.vmware_dvs_portgroup:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    portgroup_name: vlan-123-portrgoup
    switch_name: dvSwitch
    vlan_id: 123
    num_ports: 120
    port_binding: static
    state: present
    network_policy:
      promiscuous: true
      forged_transmits: true
      mac_changes: true
    port_policy:
      block_override: true
      ipfix_override: true
      live_port_move: true
      network_rp_override: true
      port_config_reset_at_disconnect: true
      security_override: true
      shaping_override: true
      traffic_filter_override: true
      uplink_teaming_override: true
      vendor_config_override: true
      vlan_override: true
  delegate_to: localhost

Authors

  • Joseph Callen (@jcpowermac)

  • Philippe Dellaert (@pdellaert)