VMware vSphere Automation Python SDK: client samples README

  VMware vSphere Automation Python SDK: client README

Additionally, some of the samples demonstrate the combined use of the vSphere Automation and vSphere APIs. To support this combined use, the vSphere Automation Python SDK samples require the vSphere Management SDK packages (pyVmomi) to be installed on the client. The examples have been developed to work with python 2.7, 3.3, 3.4 and 3.5.

• Python SDK and 3rd party Library Dependencies
• Feature Samples
• vAPI Samples for Managing vSphere Infrastructure and Virtual Machines
• Content Library and Tagging Samples
• Connection Workflow Samples
• Running the Samples

Python SDK and 3rd party Dependencies

Please see the instructions for installing the SDK and 3rd party libraries.

Feature Samples

The vSphere Automation Python SDK samples are located in the client sample directory: samples

The following table shows the sample sub-directories and their contents.

vAPI Samples for Managing vSphere Infrastructure and Virtual Machines

The directory vsphere.samples.vcenter contains samples for the vSphere infrastructure and virtual machine APIs. You have two options to run samples inside this package:

1. Run the whole sample suite which contains all vCenter samples using main.py in vsphere.samples.vcenter.setup package. Please see the README in the setup package for detailed steps.
2. Run an individual sample in an existing environment. You can either pass the environment parameters through command line arguments or specify them in setup.py in the setup package.
   For example, to run the create_default_vm sample in the vsphere.samples.vcenter.vm.create package:
   • $ cd /path/to/VMware-vSphere-Automation-SDK-Python-<version>/client/bin
   • Run the sample with the testbed settings specified in setup.py in a Linux machine:
     $ ./run_sample.sh ../samples/src/vsphere/samples/vcenter/vm/create/create_default_vm.py -v
   • Or specify the credentials using command line parameters:
     $ ./run_sample.sh ../samples/src/vsphere/samples/vcenter/vm/create/create_default_vm.py -s <server> -u <username> -p <password> -v

Sample Program Structure for the Content Library and Tagging Samples

The Content Library and Tagging samples use a framework to facilitate different aspects of using the samples. Some of the framework capabilities are:

• Command line argument parsing.
• Specifying mandatory and optional arguments for a sample.
• Sample setup, execution and post-execution cleanup.
• Information about samples.

• _options() - Called by samples_base during parse_args phase. This occurs during initialization.
• _setup() - Called by samples_base during before phase. This occurs after authentication and vAPI and vSphere service initialization.
• _execute() - Called by samples_base during run phase. At this point all the connections and services are initialized.
• _cleanup() - Called by samples_base during after phase. This occurs before disconnecting the services.

Samples configuration

[connection]
server=vCenter server IP
username=username
password=password

Connection Workflow Samples:

To work with the VMWare-supported deployment configurations of Platform Services Controllers (Single Sign-On) and vCenter Servers, applications need to dynamically discover service URLs to make service requests. Before making service requests, applications need to authenticate. They can authenticate using a username and password or with a token obtained from the Single Sign-On service.
vApi connection workflow sample performs the following basic steps to connect to the vAPI service endpoint (on a management node).

• Step 1: Retrieve the vAPI service endpoint URL from the lookup service.
• Step 2: Connect to the vAPI service endpoint.
• Step 3: Use the username/password to login to the vAPI service endpoint.
• Step 4: Create a vAPI session.
• Step 5: Validate some of the vAPI services.
• Step 6: Delete the vAPI session.

• src/vsphere/samples/common/lookup_service_helper provides methods for discovering management nodes and service endpoint URLs on management nodes from lookup service.
• src/vsphere/samples/common/platform_service_controller uses lookup_service_helper to discover the Single Sign-On URL (on any of the Platform Service Controller node) and then retrieves the SAML token from the Single Sign-On server by authenticating the given user.
• src/vsphere/samples/common/service_manager login to the vAPI and vim service endpoints (on a management node).

Running the Connection Workflow Samples:

The following parameters are needed for running the samples:

• lswsdlurl -lookup service WSDL file URL. See Using WSDL
• lssoapurl - Platform Service controller's/node's (any, since data is replicated) lookupservice soap URL. Ex: https://psc/lookupservice/sdk
• mgmtinstancename - Instance name of the vCenter Server management node. When only one node is registered, it is selected by default; otherwise, omit the parameter to get a list of available nodes.
• username - username for authentication with the SSO server
• password - password for the SSO user
• skipverification - Do not verify server certificate

Working with lookup service WSDL

1. In sample.cfg, set 'lswsdlurl' to the lokkupservice WSDL file location. Use a local file URL specification: e.g. lswsdlurl=file:///path/to/the/VMware-vSphere-Automation-SDK-Python-6.5.0/client/wsdl/lookupservice.wsdl
   (Note: You can also specify the lookup service WSDL path to the sample as a command line option)
2. In lookupservice.wsdl, set 'import location' to the local lookup WSDL file. Use a local file URL specification.

   <import location="file:///path/to/the/VMware-vSphere-Automation-SDK-Python-6.5.0/client/wsdl/lookup.wsdl" namespace="urn:lookup" />
      <service name="LsService">
         <port binding="interface:LsBinding" name="LsPort">
             <soap:address location="http://localhost:8080/lookupservice/sdk" />
         </port>
      </service>
   

Running the samples from the command line

You can run the samples from command line using the scripts supplied in VMware-vSphere-Automation-SDK-Python-<version>/client/bin directory:

1. You must set the PYTHON_HOME environment variable to the base directory for the python 2.7
2. You must install all the dependencies required by the samples on client. See Sample Dependencies

Examples:

$cd /path/to/VMware-vSphere-Automation-SDK-Python-<version>/client/bin
$run_sample.sh ../samples/src/vsphere/samples/workflow/connection_workflow.py \
    -vapiurl https://203.0.113.0/api \
    -stsurl https://203.0.113.0:443/sts/STSService/vsphere.local \
    -username administrator@vsphere.local \
    -password AdminPassword

$ ./run_sample.sh  ../samples/src/vsphere/samples/workflow/vapi_connection_workflow.py -h
usage: vapi_connection_workflow.py [-h] [-w LSWSDLURL] [-s LSSOAPURL]
                                   [-m MGMTINSTANCENAME] [-u USERNAME]
                                   [-p PASSWORD] [-v]

Demonstrates vAPI connection and service initialization call flow using the
username and password.
Step 1: Retrieve the vAPI service endpoint URL from lookup service.
Step 2: Connect to the vAPI service endpoint.
Step 3: Use the username/password to login to the vAPI service endpoint.
Step 4: Create a vAPI session.
Step 5: Validate some of the vAPI services.
Step 6: Delete the vAPI session.

optional arguments:
  -h, --help            show this help message and exit
  -w LSWSDLURL, --lswsdlurl LSWSDLURL
                        Lookup service WSDL URL
  -s LSSOAPURL, --lssoapurl LSSOAPURL
                        Lookup service SOAP URL
  -m MGMTINSTANCENAME, --mgmtinstancename MGMTINSTANCENAME
                        Instance name of the vCenter Server management node.
                        When only one node is registered, it is selected by
                        default; otherwise, omit the parameter to get a list
                        of available nodes.
  -u USERNAME, --username USERNAME
                        SSO user name
  -p PASSWORD, --password PASSWORD
                        SSO user password
  -v, --skipverification
                        Do not verify server certificate

Note: In the above example mgmtinstancename is optional and can be omitted if there's a single vCenter Server management node in the deployment. When there is more than one management node, the user MUST specify the management node instance name against which the sample needs to run, else the sample throws MultipleManagementNodeException. Example of a multiple management node exception:

raise MultipleManagementNodeException(MultipleManagementNodeException.format(result))
vsphere.samples.common.lookup_service_helper.MultipleManagementNodeException: Multiple Management Node Found on server
Node name: vcenter-1.example.com uuid: de2afd86-790e-11e4-9c20-0200087f55c6
Node name: vcenter-2.example.com uuid: 545da868-7910-11e4-81e1-020008e89d83

ValueError: abc is not a valid management node instance name
Available management nodes:
Node name: vcenter-2.example.com uuid: 545da868-7910-11e4-81e1-020008e89d83
Node name: vcenter-1.example.com uuid: de2afd86-790e-11e4-9c20-0200087f55c6