# VMware vSphere Automation Python SDK: client samples 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. The following sections provide information about using the samples.. 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.
Directory | Description
--- | ---
vsphere.samples.common | Samples common classes and abstractions; This package does NOT contain any sample
vsphere.samples.vim.helpers | Samples and utilities for accessing and manipulating VC objects using pyVmomi
vsphere.samples.lookupservice | Service discovery sample using lookup service APIs
vsphere.samples.vcenter | vAPI samples for managing vSphere infrastructure and virtual machines
vsphere.samples.workflow | Various vAPI work flow samples
vsphere.samples.inventory | Samples for inventory APIs for retrieving information about vCenter datastore and network objects.
## 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: 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. 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. Each sample extends the class `samples_base`. This class uses `service_manager_factory` to create and manage the vAPI service endpoint and vSphere service port. Every sample implements the following methods from the class `samples_base`: `_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 You can specify server, username and password in the configuration file (sample.cfg). If you use a configuration file, you can run samples without specifying these options on the command line. When you run a sample, you can override the configuration file values by specifying command line options.
    [connection]
    server=vCenter server IP
    username=username
    password=password
2. The sample.cfg file can be found under `VMware-vSphere-Automation-SDK-Python-<version>/client/samples/src` ## 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. The call sequence shown above is implemented in the samples framework through the following modules: `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 You can also specify these parameters in the configuration file (sample.cfg). If you use a configuration file, you can run samples without specifying these options on the command line. ### Working with lookup service WSDL The vSphere Automation SDK for Python samples use the vSphere Automation Lookup Service to obtain the URLs for other vSphere Automation services (SSO, vAPI, VIM, SPBM, etc.). The SDK contains the Lookup Service WSDL files. The samples use the python SUDS client for accessing the lookup service. The Lookup Service WSDL files are located in the following SDK directory: `VMware-vSphere-Automation-SDK-Python-<version>/client/wsdl`. You must specify the WSDL file location in the `client/samples/src/sample.cfg` file and in the lookupservice.wsdl file (located in the WSDL directory). 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) 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: Before running the samples: You must set the `PYTHON_HOME` environment variable to the base directory for the python 2.7 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
Use the -h option to print information about a sample. The following example shows the help for the vAPI connection workflow sample.
    $ ./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
Example exception when an invalid management instance name is specified by the user:
    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
Copyright © 2015, 2016 VMware, Inc. All rights not expressly granted herein are reserved. | Last updated: 20 Oct 2016 | VMware vSphere Automation SDK for Python