openstack/deb-python-pyvmomi
Code Issues Proposed changes

Fixed broken formatting in a few docs.

Browse Source
This commit is contained in:
patricklundquist
2014-12-17 00:20:23 -08:00
parent f55e14730d
commit c2adb2e7ce
4 changed files with 258 additions and 446 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/vim/Datacenter.rst
View File

@@ -74,28 +74,11 @@
vim.Datacenter
==============
The `Datacenter`_ managed object provides the interface to the common container object for hosts, virtual machines, networks, and datastores. These entities must be under a distinct datacenter in the inventory, and datacenters may not be nested under other datacenters.Every `Datacenter`_ has the following set of dedicated folders. These folders are empty until you create entities for the Datacenter.
* A folder for
* `VirtualMachine`_
* , template, and
* `VirtualApp`_
* objects.
* A folder for a
* `ComputeResource`_
* hierarchy.
* A folder for
* `Network`_
* ,
* `DistributedVirtualSwitch`_
* , and
* `DistributedVirtualPortgroup`_
* objects.
* A folder for
* `Datastore`_
* objects.
*
* For a visual representation of the organization of objects in a vCenter hierarchy, see the description of the
* `ServiceInstance`_
* object.
* A folder for `VirtualMachine`_, template, and `VirtualApp`_ objects.
* A folder for a `ComputeResource`_ hierarchy.
* A folder for `Network`_ , `DistributedVirtualSwitch`_ , and `DistributedVirtualPortgroup`_ objects.
* A folder for `Datastore`_ objects.
For a visual representation of the organization of objects in a vCenter hierarchy, see the description of the `ServiceInstance`_ object.
:extends: vim.ManagedEntity_

193
docs/vim/DistributedVirtualSwitch.rst
View File

@@ -123,17 +123,20 @@
vim.DistributedVirtualSwitch
============================
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:
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`_ ):
* 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`_ ):
* 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.
@@ -141,139 +144,36 @@ vim.DistributedVirtualSwitch
* 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 ConfigurationTo use a distributed virtual switch, you create a switch and portgroups on a vCenter Server, and add hosts as members of the switch.
* 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.
* 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`_
* ):
*
*
* If a portgroup is early binding (static), then
* `DVPortgroupConfigSpec`_
* .
* `numPorts`_
* determines the number of ports that get created when the portgroup is created. This number can be increased if
* `DVPortgroupConfigSpec`_
* .
* `autoExpand`_
* is
* true
* .
* If a portgroup is ephemeral (dynamic), then
* `numPorts`_
* is ignored and ports are created as needed.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.
* If you have created additional uplink portgroups, use the
* `ReconfigureDvs_Task`_
* method to add the portgroup(s) to the
* `DVSConfigSpec`_
* .
* `uplinkPortgroup`_
* array.
* Retrieve physical NIC device names from the host (
* `HostSystem`_
* .
* `config`_
* .
* `network`_
* .
* `pnic`_
* [].
* `device`_
* ).
* Add host member(s) to the distributed virtual switch. To configure host members:
*
*
* Specify hosts (
* `DVSConfigSpec`_
* .
* `host`_
* []).
* For each host, specify one or more physical NIC device names to identify the pNIC(s) for the host proxy connection to the network (
* `DistributedVirtualSwitchHostMemberConfigSpec`_
* .
* `backing`_
* .
* `pnicSpec`_
* [].
* `pnicDevice`_
* )
* Use the
* `DistributedVirtualSwitch`_
* .
* `ReconfigureDvs_Task`_
* method to update the switch configuration.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.
* Connect hosts and virtual machines to the distributed virtual switch.
*
*
*
* Host connection
*
* Specify port or portgroup connections in the host virtual NIC spec (
* `HostVirtualNicSpec`_
* .
* `distributedVirtualPort`_
* or
* `HostVirtualNicSpec`_
* .
* `portgroup`_
* ).
*
*
*
* Virtual machine connection
*
* Specify port or portgroup connections in the distributed virtual port backing (
* `VirtualEthernetCardDistributedVirtualPortBackingInfo`_
* ) for the virtual Ethernet cards on the virtual machine (
* `VirtualEthernetCard`_
* .
* `backing`_
* ).
*
*
* Backup, Rollback, and Query OperationsIf 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 backup the switch and portgroup configuration, use the
* `DistributedVirtualSwitchManager`_
* .
* `DVSManagerExportEntity_Task`_
* method. The export method produces a
* `EntityBackupConfig`_
* object. The backup configuration contains the switch and/or portgroups specified in the
* SelectionSet
* parameter. To backup the complete configuration you must select the distributed virtual switch and all of its portgroups.
* To rollback the switch configuration, use the
* `DVSRollback_Task`_
* method to determine if the switch configuration has changed. If it has changed, use the
* `ReconfigureDvs_Task`_
* method to complete the rollback operation.
* To rollback the portgroup configuration, use the
* `DistributedVirtualPortgroup`_
* .
* `DVPortgroupRollback_Task`_
* method to determine if the portgroup configuration has changed. If it has changed, use the
* `ReconfigureDVPortgroup_Task`_
* method to complete the rollback operation.To perform query operations on a distributed virtual switch, use the `DistributedVirtualSwitchManager`_ methods.
* 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`_ ):
* If a portgroup is early binding (static), then `DVPortgroupConfigSpec.numPorts`_ determines the number of ports that get created when the portgroup is created. This number can be increased if `DVPortgroupConfigSpec.autoExpand`_ is true.
* If a portgroup is ephemeral (dynamic), then `numPorts`_ is ignored and ports are created as needed.
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:
* Specify hosts (`DVSConfigSpec.host[]`_).
* For each host, specify one or more physical NIC device names to identify the pNIC(s) for the host proxy connection to the network (
* `DistributedVirtualSwitchHostMemberConfigSpec.backing.pnicSpec[].`pnicDevice`_ )
* Use the `DistributedVirtualSwitch.ReconfigureDvs_Task`_ method to update the switch configuration.
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.distributedVirtualPort`_ or `HostVirtualNicSpec.portgroup`_ ).
* Virtual machine connection Specify port or portgroup connections in the distributed virtual port backing ( `VirtualEthernetCardDistributedVirtualPortBackingInfo`_ ) for the virtual Ethernet cards on the virtual machine ( `VirtualEthernetCard.backing`_ ).
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 backup the switch and portgroup configuration, use the `DistributedVirtualSwitchManager.DVSManagerExportEntity_Task`_ method. The export method produces a `EntityBackupConfig`_ object. The backup configuration contains the switch and/or portgroups specified in the SelectionSet parameter. To backup the complete configuration you must select the distributed virtual switch and all of its portgroups.
* To rollback the switch configuration, use the `DVSRollback_Task`_ method to determine if the switch configuration has changed. If it has changed, use the `ReconfigureDvs_Task`_ method to complete the rollback operation.
* To rollback the portgroup configuration, use the `DistributedVirtualPortgroup.DVPortgroupRollback_Task`_ method to determine if the portgroup configuration has changed. If it has changed, use the `ReconfigureDVPortgroup_Task`_ method to complete the rollback operation.
To perform query operations on a distributed virtual switch, use the `DistributedVirtualSwitchManager`_ methods.
:extends: vim.ManagedEntity_
@@ -499,25 +399,14 @@ PerformDvsProductSpecOperation(operation, productSpec):
MergeDvs(dvs):
Merge an existing DistributedVirtualSwitch (source) to this switch (destination). The host members and the connected entity of the source switch will be transferred to the destination switch. This operation disconnects the entities from the source switch, tears down its host proxy switches, creates new proxies for the destination switch, and reconnects the entities to the destination switch.In summary, this operation does the following:
* Adds the
* config
* .
* `maxPorts`_
* of the source switch to the
* maxPorts
* of the destination switch.
* The host members of the source switch leave the source switch and join the destination switch with the same Physical NIC and VirtualSwitch (if applicable). A set of new uplink ports, compliant with the
* `uplinkPortPolicy`_
* , is created as the hosts join the destination switch.
Merge an existing DistributedVirtualSwitch (source) to this switch (destination). The host members and the connected entity of the source switch will be transferred to the destination switch. This operation disconnects the entities from the source switch, tears down its host proxy switches, creates new proxies for the destination switch, and reconnects the entities to the destination switch. In summary, this operation does the following:
* Adds the config `maxPorts`_ of the source switch to the maxPorts of the destination switch.
* The host members of the source switch leave the source switch and join the destination switch with the same Physical NIC and VirtualSwitch (if applicable). A set of new uplink ports, compliant with the `uplinkPortPolicy`_, is created as the hosts join the destination switch.
* The portgroups on the source switch are copied over to destination switch, by calculating the effective default port config and creating a portgroup of the same name in the destination switch. If the name already exists, the copied portgroup uses names following a "Copy of switch-portgroup-name" scheme to avoid conflict. The same number of ports are created inside each copied portgroup.
* The standalone distributed virtual ports are not copied, unless there is a virtual machine or host virtual NIC connecting to it. In that case, the operation calculates the effective port config and creates a port in the destination switch with the same name. Name conflict is resolved using numbers like "original-port-name(1)". The uplink ports are not copied over.
* The virtual machine and host virtual NICs are disconnected from the source switch and reconnected with the destination switch, to the copied standalone port or portgroup.
* If you are using a
* `VmwareDistributedVirtualSwitch`_
* - Unless the PVLAN map contains exactly the same entries between the source and destination VMware distributed virtual switches, the method raises a fault if
* `pvlanId`_
* is set in any port, portgroup, or switch that will be copied.
* If you are using a `VmwareDistributedVirtualSwitch`_
* - Unless the PVLAN map contains exactly the same entries between the source and destination VMware distributed virtual switches, the method raises a fault if `pvlanId`_ is set in any port, portgroup, or switch that will be copied.
Privilege:

76
docs/vim/Folder.rst
View File

@@ -113,70 +113,26 @@ vim.Folder
==========
The `Folder`_ managed object is a container for storing and organizing inventory objects. Folders can contain folders and other objects. The `childType`_ property identifies a folder's type and determines the types of folders and objects the folder can contain.
* A folder can contain a child folder of the same type as the parent folder.
* All
* `Datacenter`_
* objects contain dedicated folders for:
*
*
* `VirtualMachine`_
* , templates, and
* `VirtualApp`_
* objects.
*
* `ComputeResource`_
* hierarchies.
*
* `Network`_
* ,
* `DistributedVirtualSwitch`_
* , and
* `DistributedVirtualPortgroup`_
* objects.
*
* `Datastore`_
* objects.
*
* A folder can contain child objects of type
* `childType`_
* . Virtual machine and network entity folders can also contain additional object types.
* All `Datacenter`_ objects contain dedicated folders for:
* `VirtualMachine`_, templates, and `VirtualApp`_ objects.
* `ComputeResource`_ hierarchies.
* `Network`_, `DistributedVirtualSwitch`_, and `DistributedVirtualPortgroup`_ objects.
* `Datastore`_ objects.
* A folder can contain child objects of type `childType`_. Virtual machine and network entity folders can also contain additional object types.
* The root folder is a data center folder.
* See
* `ServiceInstance`_
* for a representation of the organization of the inventory.
* The
* `Folder`_
* managed object also acts as a factory object, meaning it creates new entities in a folder. The object provides methods to create child folders and objects, methods to add existing objects to folders, and methods to remove objects from folders and to delete folders.
*
* `Folder`_
* inherits the
* `Destroy_Task`_
* method.
* `Destroy_Task`_
* is a recursive operation that removes all child objects and folders. When you call
* `Destroy_Task`_
* to destroy a folder, the system uses the specified folder as a root and traverses its descendant hierarchy, calling
* `Destroy_Task`_
* on each object.
* `Destroy_Task`_
* is a single operation that treats each recursive call as a single transaction, committing each call to remove an object individually. If
* `Destroy_Task`_
* fails on an object, the method terminates at that point with an exception, leaving some or all of the objects still in the inventory.
* Notes on the folder destroy method:
*
* Calling
* `Destroy_Task`_
* on a virtual machine folder recursively calls
* `Destroy_Task`_
* on all the child virtual machines and vApps, which are then removed from disk. Use
* `UnregisterAndDestroy_Task`_
* to unregister virtual machines or vApps recursively without removing them from the disk.
* For virtual machine folders, the
* `Destroy_Task`_
* method requires the VirtualMachine.Delete privilege on the folder as well as all virtual machines to be destroyed. It also requires the VirtualApp.Delete privilege on all VirtualApp objects to be destroyed.
See `ServiceInstance`_ for a representation of the organization of the inventory.
The Folder`_ managed object also acts as a factory object, meaning it creates new entities in a folder. The object provides methods to create child folders and objects, methods to add existing objects to folders, and methods to remove objects from folders and to delete folders.
`Folder`_ inherits the `Destroy_Task`_ method. `Destroy_Task`_ is a recursive operation that removes all child objects and folders. When you call `Destroy_Task`_ to destroy a folder, the system uses the specified folder as a root and traverses its descendant hierarchy, calling `Destroy_Task`_ on each object. `Destroy_Task`_ is a single operation that treats each recursive call as a single transaction, committing each call to remove an object individually. If `Destroy_Task`_ fails on an object, the method terminates at that point with an exception, leaving some or all of the objects still in the inventory.
Notes on the folder destroy method:
* Calling `Destroy_Task`_ on a virtual machine folder recursively calls `Destroy_Task`_ on all the child virtual machines and vApps, which are then removed from disk. Use `UnregisterAndDestroy_Task`_ to unregister virtual machines or vApps recursively without removing them from the disk.
* For virtual machine folders, the `Destroy_Task`_ method requires the VirtualMachine.Delete privilege on the folder as well as all virtual machines to be destroyed. It also requires the VirtualApp.Delete privilege on all VirtualApp objects to be destroyed.
* Destroying a host folder or datacenter folder unregisters all child hosts and virtual machines from vCenter. The hosts are simply removed from the inventory, along with their virtual machines. The virtual machines are not removed from disk nor are their runtime states changed.
* You can remove network and datastore folders only if they are empty.
* You cannot destroy, rename, or move the virtual machine, compute resource, network entity, and datastore child folders of a Datacenter.
*
:extends: vim.ManagedEntity_

26
docs/vim/event/EventManager.rst
View File

@@ -167,20 +167,9 @@ QueryEvents(filter):
PostEvent(eventToPost, taskInfo):
Posts the specified event, optionally associating it with a task.The event being posted should have the following info in it:
* The ManagedEntity on which the event is being posted should be set in the appropriate
* `EntityEventArgument`_
* field of the base
* `Event`_
* class. It is OK to not set any entity, in which case the event is treated as an event about the system.
* Some Event fields (
* `key`_
* ,
* `chainId`_
* ,
* `createdTime`_
* ) are mandatory because of the nature of the structure, but any caller-supplied values will be overwritten by the system.
*
Posts the specified event, optionally associating it with a task. The event being posted should have the following info in it:
* The ManagedEntity on which the event is being posted should be set in the appropriate `EntityEventArgument`_ field of the base `Event`_ class. It is OK to not set any entity, in which case the event is treated as an event about the system.
* Some Event fields (`key`_, `chainId`_, `createdTime`_) are mandatory because of the nature of the structure, but any caller-supplied values will be overwritten by the system.
* If the event being posted is to be associated with an existing Task, the appropriate TaskInfo needs to be passed in. This task can either be one returned from a vSphere API operation or an extension task created by calling TaskManager#createTask.
since: `VI API 2.5`_
@@ -212,12 +201,7 @@ PostEvent(eventToPost, taskInfo):
`vmodl.fault.InvalidArgument`_:
if
* an invalid reference to a managed object is passed in to one of the
* `EntityEventArgument`_
* fields
* an invalid severity value is passed in an
* `EventEx`_
* .
*
* an invalid reference to a managed object is passed in to one of the `EntityEventArgument`_ fields
* an invalid severity value is passed in an `EventEx`_.