Virtual Infrastructure Distributed Virtual Switch APIs

Virtual Infrastructure Distributed Virtual Switch APIs

A DistributedVirtualSwitch managed object is a virtual network switch that is located on a vCenter Server.

A distributed virtual switch manages configuration for proxy switches (HostProxySwitch). A proxy switch is located on an ESXi host that is managed by the vCenter Server and is a member of the switch. A distributed switch also provides virtual port state management so that port state is maintained when vCenter Server operations move a virtual machine from one host to another.

A proxy switch performs network I/O to support the following network traffic and operations:

  • Network traffic between virtual machines on any hosts that are members of the distributed virtual switch.
  • Network traffic between virtual machines that uses a distributed switch and a virtual machine that uses a VMware standard switch.
  • Network traffic between a virtual machine and a remote system on a physical network connected to the ESXi host.
  • vSphere system operations to support capabilities such as VMotion or High Availability.

A DistributedVirtualSwitch is the base distributed switch implementation. It supports a VMware distributed virtual switch implementation and it supports third party distributed switch implementations. The base implementation provides the following capabilities (DVSFeatureCapability):

  • NIC teaming
  • Network I/O control
  • Network resource allocation
  • Quality of service tag support
  • User-defined resource pools
  • I/O passthrough (VMDirectPath Gen2)

A VmwareDistributedVirtualSwitch supports the following additional capabilities (DVSFeatureCapability and VMwareDVSFeatureCapability):

  • Backup, restore, and rollback for a VMware distributed virtual switch and its associated portgroups.
  • Maximum Transmission Unit (MTU) configuration.
  • Health check operations for NIC teaming and VLAN/MTU support.
  • Monitoring switch traffic using Internet Protocol Flow Information Export (IPFIX).
  • Link Layer Discovery Protocol (LLDP).
  • Virtual network segmentation using a Private VLAN (PVLAN).
  • VLAN-based SPAN (VSPAN) for virtual distributed port mirroring.
  • Link Aggregation Control Protocol (LACP) defined for uplink portgroups.

Distributed Virtual Switch Configuration

To use a distributed virtual switch, you create a switch and portgroups on a vCenter Server, and add hosts as members of the switch.

  1. Create a distributed virtual switch (Folder.CreateDVS_Task). Use a DVSConfigSpec to create a switch for a third-party implementation. Use a VMwareDVSConfigSpec to create a VMware distributed virtual switch.

  2. Create portgroups (CreateDVPortgroup_Task) for host and virtual machine network connections and for the connection between proxy switches and physical NICs. A DistributedVirtualPortgroup specifies how virtual ports (DistributedVirtualPort) will be used. When you create a distributed virtual switch, the vCenter Server automatically creates one uplink portgroup (config.uplinkPortgroup). Uplink portgroups are distributed virtual portgroups that support the connection between proxy switches and physical NICs.

    Port creation on a distributed switch is determined by the portgroup type (DVPortgroupConfigSpec.type):

    You can also specify standalone ports that are not associated with a port group and uplink ports that are created on ESXi hosts (DVSConfigSpec.numStandalonePorts).

    The DVPortgroupConfigInfo.numPorts property is the total number of ports for a distributed virtual switch. This total includes the ports generated by the static and dynamic portgroups and the standalone ports.

  3. If you have created additional uplink portgroups, use the ReconfigureDvs_Task method to add the portgroup(s) to the DVSConfigSpec.uplinkPortgroup array.

  4. Retrieve physical NIC device names from the host (HostSystem.config.network.pnic[].device).

  5. Add host member(s) to the distributed virtual switch. To configure host members:

    When you add a host to a distributed virtual switch (DistributedVirtualSwitch.config.host), the host automatically creates a proxy switch. The proxy switch is removed automatically when the host is removed from the distributed virtual switch.

  6. Connect hosts and virtual machines to the distributed virtual switch.

    Host connection Specify port or portgroup connections in the host virtual NIC spec ([HostVirtualNicSpec](../../data-structures/HostVirtualNicSpec/).[distributedVirtualPort](../../data-structures/HostVirtualNicSpec/) or [HostVirtualNicSpec](../../data-structures/HostVirtualNicSpec/).[portgroup](../../data-structures/HostVirtualNicSpec/)).
    Virtual machine connection Specify port or portgroup connections in the distributed virtual port backing ([VirtualEthernetCardDistributedVirtualPortBackingInfo](../../data-structures/VirtualEthernetCardDistributedVirtualPortBackingInfo/)) for the virtual Ethernet cards on the virtual machine ([VirtualEthernetCard](../../data-structures/VirtualEthernetCard/).[backing](../../data-structures/VirtualDevice/)).

Backup, Rollback, and Query Operations

If you are using a VmwareDistributedVirtualSwitch, you can perform backup and rollback operations on the switch and its associated distributed virtual portgroups. When you reconfigure a VMware distributed virtual switch (ReconfigureDvs_Task), the Server saves the current switch configuration before applying the configuration updates. The saved switch configuration includes portgroup configuration data. The Server uses the saved switch configuration as a checkpoint for rollback operations. You can rollback the switch or portgroup configuration to the saved configuration, or you can rollback to a backup configuration (EntityBackupConfig).

To perform query operations on a distributed virtual switch, use the DistributedVirtualSwitchManager methods.

Operations
POST
Distributed Virtual Switch Add DV Portgroup Task
Creates one or more *DistributedVirtualPortgroup*s and adds them to the distributed virtual switch.
POST
Distributed Virtual Switch Add Network Resource Pool
Add a network resource pool.
POST
Distributed Virtual Switch Create DV Portgroup Task
Creates a single *DistributedVirtualPortgroup* and adds it to the distributed virtual switch.
POST
Distributed Virtual Switch Destroy Task
Destroys this object, deleting its contents and removing it from its parent folder (if any).
POST
Distributed Virtual Switch Dvs Reconfigure Vm Vnic Network Resource Pool Task
reconfigure the Virtual NIC network resource pool configuration.
POST
Distributed Virtual Switch DVS Rollback Task
This method determines if the distributed virtual switch configuration has changed.
POST
Distributed Virtual Switch Enable Network Resource Management
Enable/Disable network I/O control on the vSphere Distributed Switch.
POST
Distributed Virtual Switch Fetch DV Port Keys
Return the keys of ports that meet the criteria.
POST
Distributed Virtual Switch Fetch DV Ports
Return the ports that meet the criteria.
GET
Distributed Virtual Switch Get Alarm Actions Enabled
Whether alarm actions are enabled for this entity.
GET
Distributed Virtual Switch Get Available Field
List of custom field definitions that are valid for the object's type.
GET
Distributed Virtual Switch Get Capability
Capability of the switch.
GET
Distributed Virtual Switch Get Config
Switch configuration data.
GET
Distributed Virtual Switch Get Config Issue
Current configuration issues that have been detected for this entity.
GET
Distributed Virtual Switch Get Config Status
The configStatus indicates whether or not the system has detected a configuration issue involving this entity.
GET
Distributed Virtual Switch Get Custom Value
Custom field values.
GET
Distributed Virtual Switch Get Declared Alarm State
A set of alarm states for alarms that apply to this managed entity.
GET
Distributed Virtual Switch Get Disabled Method
List of operations that are disabled, given the current runtime state of the entity.
GET
Distributed Virtual Switch Get Effective Role
Access rights the current session has to this entity.
GET
Distributed Virtual Switch Get Name
Name of this entity, unique relative to its parent.
GET
Distributed Virtual Switch Get Network Resource Pool
Network resource pool information for the switch.
GET
Distributed Virtual Switch Get Overall Status
General health of this managed entity.
GET
Distributed Virtual Switch Get Parent
Parent of this entity.
GET
Distributed Virtual Switch Get Permission
List of permissions defined for this entity.
GET
Distributed Virtual Switch Get Portgroup
Portgroups that are defined on the switch.
GET
Distributed Virtual Switch Get Recent Task
The set of recent tasks operating on this managed entity.
GET
Distributed Virtual Switch Get Runtime
Runtime information of the distributed virtual switch.
GET
Distributed Virtual Switch Get Summary
Summary of the switch.
GET
Distributed Virtual Switch Get Tag
The set of tags associated with this managed entity.
GET
Distributed Virtual Switch Get Triggered Alarm State
A set of alarm states for alarms triggered by this entity or by its descendants.
GET
Distributed Virtual Switch Get Uuid
Generated UUID of the switch.
GET
Distributed Virtual Switch Get Value
List of custom field values.
POST
Distributed Virtual Switch Lookup Dv Port Group
Returns the portgroup identified by the key within this VDS.
POST
Distributed Virtual Switch Merge Dvs Task
Merge an existing DistributedVirtualSwitch (source) to this switch (destination).
POST
Distributed Virtual Switch Move DV Port Task
Move the ports out of their current portgroup into the specified portgroup.
POST
Distributed Virtual Switch Perform Dvs Product Spec Operation Task
This method updates the *DistributedVirtualSwitch* product specifications.
POST
Distributed Virtual Switch Query Used Vlan Id In Dvs
Return the used VLAN ID (PVLAN excluded) in the switch.
POST
Distributed Virtual Switch Reconfigure DV Port Task
Reconfigure individual ports.
POST
Distributed Virtual Switch Reconfigure Dvs Task
Reconfigures a distributed virtual switch.
POST
Distributed Virtual Switch Rectify Dvs Host Task
Update the switch configuration on the host to bring them in sync with the current configuration in vCenter Server.
POST
Distributed Virtual Switch Refresh DV Port State
Refresh port states.
POST
Distributed Virtual Switch Reload
Reload the entity state.
POST
Distributed Virtual Switch Remove Network Resource Pool
Remove a network resource pool.
POST
Distributed Virtual Switch Rename Task
Renames this managed entity.
POST
Distributed Virtual Switch Set Custom Value
Assigns a value to a custom field.
POST
Distributed Virtual Switch Update Dvs Capability
Set the capability of the switch.
POST
Distributed Virtual Switch Update DVS Health Check Config Task
Update health check configuration.
POST
Distributed Virtual Switch Update Network Resource Pool
Update the network resource pool configuration.