WIXLIB

VMware vSphere Automation SDK for Python Programming Guideby including the SAML token in every request that you issue to the vSphere AutomationEndpoint.Service DiscoveryYou use the Lookup Service to discover the endpoint URL for the vCenter Single Sign-Onservice on the Platform Services Controller, the location of the vCenter Server instances, andthe vSphere Automation Endpoint.Services Installed with vCenter ServervCenter Server is a central administration point for ESXi hosts. The vCenter Server group of services contains vCenter Server, vSphere Web Client, Inventory Service, vSphere Auto Deploy , vSphere ESXi Dump Collector, VMware vSphere Syslog Collector on Windows andVMware vSphere Syslog Service for the vCenter Server Appliance.vCenter Server also provides services that you can access through the vSphere AutomationEndpoint.Content Library ServiceYou can use the Content Library Service to share VM templates, vApp templates, and otherfiles across the software-defined data center. You can create, share, and subscribe tocontent libraries on the same vCenter Server instance or on a remote instance. This promotesconsistency, compliance, efficiency, and automation in deploying workloads at scale. By usingcontent libraries, you can also create OVF packages from virtual machines and virtualappliances in hosts, resource pools, and clusters. You can then use the OVF packages toprovision new virtual machines in hosts, resource pools, and clusters.Tagging ServiceThis service supports the definition of tags that you can associate with vSphere objects orvSphere Automation resources. The vSphere Automation SDKs provide the capability tomanage tags programmatically.vSphere Deployment ConfigurationsvSphere Automation client applications communicate with services on the Platform ServicesController and vCenter Server components of the virtual environment. vCenter Server can bedeployed with an embedded or external Platform Services Controller.vCenter Server with an Embedded Platform Services ControllervCenter Server and Platform Services Controller reside on the same virtual machine or physicalserver. This deployment is most suitable for small environments such as development or testbeds.VMware, Inc.12

VMware vSphere Automation SDK for Python Programming GuideYou can use the Platform Services Controller in two ways to establish secure, authenticatedsessions for your client application, by making requests to the Lookup Service and the vCenterSingle Sign-On Service.One way to use the Platform Services Controller is to request an authentication token that can beused to authenticate requests across services. The client connects to the Lookup Service andretrieves the vCenter Single Sign-On Service endpoint and the vSphere Automation API endpoint.The client then uses the vCenter Single Sign-On endpoint to authenticate with user credentialsand receive a token that securely verifies the client's credentials. This allows the client toauthenticate with a number of service endpoints without sending user credentials over thenetwork repeatedly.Alternatively, if the client connects directly to the vSphere Automation API endpoint, there is noneed for the client to interact with the vCenter Single Sign-On Service. The client sends usercredentials to the vSphere Automation API endpoint, which creates a session identifier thatpersists across requests.Figure 2-1. vCenter Server with Embedded Platform Services ControllerVM or Physical ServerPlatform Services ControllerLookupServiceSingle Sign-OnService URLvSphere AutomationEndpoint URLvCenter ServerURLOther ServicesURLsSingleSign-ONServiceSAML TokenVMware ESXivCenter ServervAPIEndpointContent LibraryServiceТaggingServiceOther ServicesVMVMware ESXiVMware, Inc.13

VMware vSphere Automation SDK for Python Programming GuidevCenter Server with an External Platform Services ControllerIn the case of an external Platform Services Controller, the vCenter Server and the PlatformServices Controller are deployed on separate virtual machines or physical servers. The PlatformServices Controller can be shared across several vCenter Server instances. For largerdeployments or to provide better availability, more than one Platform Services Controller can bedeployed. When configured as replication partners within a single vCenter Single Sign-Ondomain, Platform Services Controller instances replicate all user and system data within thecluster.A client application functions in a similar way as in a Platform Services Controller with embeddedvCenter Server deployment. The only difference is that the client application can access serviceson multiple vCenter Server instances, or services only on a particular vCenter Server instance.Figure 2-2. vCenter Server with External Platform Services ControllerVM or Physical ServerPlatform Services ControllerLookupServiceSingle Sign-OnService URLvSphere AutomationEndpoint URLvCenter ServerURLOther ServicesURLsSingleSign-ONServiceSAML TokenVM or Physical ServerVM or Physical ServervCenter ServervAPIEndpointVMware ESXiVMware, Inc.vCenter ServerContent LibraryServiceТaggingServiceOther ServicesVMware ESXivAPIEndpointVMware ESXiContent LibraryServiceТaggingServiceOther ServicesVMware ESXi14

Retrieving Service Endpoints3To access services and resources in the virtual environment, vSphere Automation API clientapplications must know the endpoints of vSphere Automation and vSphere services. Clientapplications retrieve service endpoints from the Lookup Service that runs on the PlatformServices Controller.The Lookup Service provides service registration and discovery by using a Web services API. Byusing the Lookup Service, you can retrieve endpoints of services on the Platform ServicesController and vCenter Server. The following endpoints are available from the Lookup Service.nThe vCenter Single Sign-On endpoint on the Platform Services Controller. You use thevCenter Single Sign-On service to get a SAML token and establish an authenticated sessionwith a vSphere Automation endpoint or a vCenter Server endpoint.nThe vSphere Automation Endpoint on vCenter Server. Through the vSphere AutomationEndpoint, you can make requests to vSphere Automation API services such as virtualmachine management, Content Library, and Tagging.nThe vCenter Server endpoint. In an environment with external Platform Services Controllerinstances, you can use the vCenter Server endpoint to get the node ID of a particular vCenterServer instance. By using the node ID , you can retrieve service endpoints on that vCenterServer instance.nThe vSphere API endpoint and endpoints of other vSphere services that run on vCenterServer.Workflow for Retrieving Service EndpointsThe workflow that you use to retrieve service endpoints from the Lookup Service might varydepending on the endpoints that you need and their number. Follow this general workflow forretrieving service endpoints.1Connect to the Lookup Service on the Platform Services Controller and service registrationobject so that you can query for registered services.2Create a service registration filter for the endpoints that you want to retrieve.3Use the filter to retrieve registration information for services from the Lookup Service.VMware, Inc.15

VMware vSphere Automation SDK for Python Programming Guide4Extract one or more endpoint URLs from the array of registration information that youreceive from the Lookup Service.This chapter includes the following topics:nFiltering for Predefined Service EndpointsnFilter Parameters for Predefined Service EndpointsnConnect to the Lookup Service and Retrieve the Service Registration ObjectnRetrieve Service Endpoints on vCenter Server InstancesnRetrieve a vCenter Server ID by Using the Lookup ServicenRetrieve a vSphere Automation Endpoint on a vCenter Server InstanceFiltering for Predefined Service EndpointsThe Lookup Service maintains a registration list of vSphere services. You can use the LookupService to retrieve registration information for any service by setting a registration filter that youpass to the List() function on the Lookup Service. The functions and objects that you can usewith the Lookup Service are defined in the lookup.wsdl file that is part of the SDK.Lookup Service Registration FiltersYou can query for service endpoints through a service registration object that you obtain fromthe Lookup Service. You invoke the List() function on the Lookup Service to list the endpointsthat you need by passing LookupServiceRegistrationFilter. LookupServiceRegistrationFilteridentifies the service and the endpoint type that you can retrieve.Optionally, you can include the node ID parameter in the filter to identify the vCenter Serverinstance where the endpoint is hosted. When the node ID is omitted, the List() function returnsthe set of endpoint URLs for all instances of the service that are hosted on different vCenterServer instances in the environment.For example, a LookupServiceRegistrationFilter for querying the vSphere Automation service hasthese service endpoint elements.Table 3-1. Service Registration Filter ParametersFilter iceTypeproduct "com.vmware.cis"vSphere Automationnamespace.type "cs.vapi"Identifies the vSphereAutomation service.type "com.vmware.vapi.endpoint"Specifies the endpoint path forthe service.protocol Identifies the protocol that willbe used for communicationwith the endpoint ttps.public"VMware, Inc.16

VMware vSphere Automation SDK for Python Programming GuideFor information about the filter parameter of the available predefined service endpoints, seeFilter Parameters for Predefined Service Endpoints.Filter Parameters for Predefined Service EndpointsDepending on the service endpoint that you want to retrieve, you provide different parametersto the LookupServiceRegistrationFilter that you pass to the List() function on the LookupService. To search for services on a particular vCenter Server instance, set the node ID parameterto the filter.Table 3-2. Input Data for URL Retrieval for the Lookup Service Registration FilterServiceInput DataValuevCenter Single Sign-Onproduct namespacecom.vmware.cisservice typecs.identityprotocolwsTrustendpoint typecom.vmware.cis.cs.identity.ssoproduct namespacecom.vmware.cisservice typecs.vapiprotocolvapi.json.https.publicendpoint typecom.vmware.vapi.endpointproduct namespacecom.vmware.cisservice typevcenterserverprotocolvmomiendpoint typecom.vmware.vimproduct namespacecom.vmware.vim.smsservice typesmsprotocolhttpsendpoint typecom.vmware.vim.smsproduct namespacecom.vmware.vim.smsservice typesmsprotocolhttpsendpoint typecom.vmware.vim.pbmproduct namespacecom.vmware.vim.smsservice typecs.eamvSphere Automation EndpointvCenter ServervCenter Storage MonitoringServicevCenter Storage Policy-BasedManagementvSphere ESX Agent ManagerVMware, Inc.17

VMware vSphere Automation SDK for Python Programming GuideTable 3-2. Input Data for URL Retrieval for the Lookup Service Registration Filter (continued)ServiceInput DataValueprotocolvmomiendpoint typecom.vmware.cis.cs.eam.sdkConnect to the Lookup Service and Retrieve the ServiceRegistration ObjectYou must connect to the Lookup Service to gain access to its operations. After you connect tothe Lookup Service, you must retrieve the service registration object to make registrationqueries.Python Example of Connecting to the Lookup Service and Retrieving a Service RegistrationObjectnThe example is based on the code from the lookup service helper.py sample file.Procedure1Connect to the Lookup Service.2aConfigure a connection stub for the Lookup Service endpoint, which uses SOAP bindings,by using the HTTPS protocol.bCreate a connection object to communicate with the Lookup Service.Retrieve the Service Registration Object.aCreate a managed object reference to the Service Instance.bInvoke the RetrieveServiceContent() method to retrieve the ServiceContent data object.cSave the managed object reference to the service registration object.With the service registration object, you can make registration queries.Python Example of Connecting to the Lookup Service and Retrievinga Service Registration ObjectThe example is based on the code from the lookup service helper.py sample file.Note For a complete and up-to-date version of the sample code, see the vSphere AutomationSDK Python samples at GitHub.# 1 - Create SOAP client object to communicate with the Lookup Service.my ls stub Client(url wsdl url, location ls url)# 2 - Configure service & port type for client transaction.VMware, Inc.18

VMware vSphere Automation SDK for Python Programming Guidemy ls stub.set options(service 'LsService', port 'LsPort')# 3 - Manufacture a managed object reference.managed object ref \my ls anaged object ref. type 'LookupServiceInstance'managed object ref.value 'ServiceInstance'# 4 - Retrieve the ServiceContent object.ls service content \my ls stub.service.RetrieveServiceContent(managed object ref)# 5 - Retrieve the service registration object.service registration ls service content.serviceRegistrationRetrieve Service Endpoints on vCenter Server InstancesYou can create a function that obtains the endpoint URLs of a service on all vCenter Serverinstances in the environment. You can modify that function to obtain the endpoint URL of aservice on a particular vCenter Server instance.PrerequisitesnEstablish a connection with the Lookup Service.nRetrieve a service registration object.Procedure12Create a registration filter object, which contains the following parts:nA filter criterion for service informationnA filter criterion for endpoint informationOptionDescriptionOmit the node ID parameterRetrieves the endpoint URLs of the service on all vCenter Server instances.Include the node ID parameterRetrieves the endpoint URL of the service on a particular vCenter Serverinstance.Retrieve the specified service information by using the List() function.ResultsDepending on whether you included the node ID parameter, the List() function returns one ofthe following results:nA list of endpoint URLs for a service that is hosted on all vCenter Server instances in theenvironment.nAn endpoint URL of a service that runs on a particular vCenter Server instance.VMware, Inc.19

VMware vSphere Automation SDK for Python Programming GuideWhat to do nextCall the function that you implemented to retrieve service endpoints. You can pass different filterparameters depending on the service endpoints that you need. For more information, see FilterParameters for Predefined Service Endpoints.To retrieve a service endpoint on a particular vCenter Server instance, you must retrieve thenode ID of that instance and pass it to the function. For information about how to retrieve the IDof a vCenter Server instance, see Retrieve a vCenter Server ID by Using the Lookup Service.Python Example of Retrieving a Service Endpoint on a vCenterServer InstanceThis example provides a common pattern for filtering Lookup Service registration data. Thisexample is based on the code in the lookup service helper.py sample file.Note For a complete and up-to-date version of the sample code, see the vSphere AutomationSDK Python samples at GitHub.def lookup service infos(prod, svc type, proto, ep type, node id) :# 1 - Create a filter criterion for service info.filter service type \my ls ServiceType')filter service type.product prodfilter service type.type svc type# 2 - Create a filter criterion for endpoint info.filter endpoint type \my ls EndpointType')filter endpoint type.protocol protofilter endpoint type.type ep type# 3 - Create the registration filter object.filter criteria \my ls Filter')filter criteria.serviceType filter service typefilter criteria.endpointType filter endpoint typefilter criteria.nodeId node id# 4 - Retrieve specified service info with the List() method.service infos my ls stub.service.List(service registration,filter criteria)return service infosRetrieve a vCenter Server ID by Using the Lookup ServiceYou use the node ID of a vCenter Server instance to retrieve the endpoint URL of a service onthat vCenter Server instance. You specify the node ID in the service registration filter that youpass to the List() function on the Lookup Service.VMware, Inc.20

VMware vSphere Automation SDK for Python Programming GuideManaged services are registered with the instance name of the vCenter Server instance wherethey run. The instance name maps to a unique vCenter Server ID. The instance name of a vCenterServer system is specified during installation and might be an FQDN or an IP address.PrerequisitesnEstablish a connection with the Lookup Service.nRetrieve a service registration object.Procedure1List the vCenter Server instances.2Find the matching node name of the vCenter Server instance and save the ID.ResultsUse the node ID of the vCenter Server instance to filter subsequent endpoint requests. You canuse the node ID in a function that retrieves the endpoint URL of a service on a vCenter Serverinstance. For information about implementing such a function, see Retrieve Service Endpoints onvCenter Server Instances.Python Example of Retrieving a vCenter Server ID by Using theLookup ServiceThis example provides a common pattern for filtering Lookup Service registration data. Thisexample is based on the code in the lookup service helper.py sample file.Note For a complete and up-to-date version of the sample code, see the vSphere AutomationSDK Python samples at GitHub.def get mgmt node id(node instance name) :# 1 - List the vCenter Server instances.mgmt node infos lookup service infos(prod 'com.vmware.cis',svc type 'vcenterserver',proto 'vmomi', ep type 'com.vmware.vim',node id '*')# 2 - Find the matching node name and save the ID.for node in mgmt node infos :for attribute in node.serviceAttributes :if attribute.key 'com.vmware.vim.vcenter.instanceName' :if attribute.value node instance name :return node.nodeIdVMware, Inc.21

VMware vSphere Automation SDK for Python Programming GuideRetrieve a vSphere Automation Endpoint on a vCenterServer InstanceThrough the vSphere Automation Endpoint, you can access other vSphere Automation servicesthat run on vCenter Server, such as Content Library and Tagging. To use a vSphere Automationservice, you must retrieve the vSphere Automation Endpoint.PrerequisitesnEstablish a connection with the Lookup Service.nRetrieve a service registration object.nDetermine the node ID of the vCenter Server instance where the vSphere Automation serviceruns.nImplement a function that retrieves the endpoint URL of a service on a vCenter Serverinstance.Procedure1Invoke the function for retrieving the endpoint URL of a service on a vCenter Server instanceby passing filter strings that are specific to the vSphere Automation endpoint.2Save the URL from the resulting single-element list.Python Example of Retrieving

Python Example of Creating a Basic Virtual Machine 67 Configuring a Virtual Machine 68 Name and Placement 69 Boot Options 70 Operating System 71 CPU and Memory 72 Networks 74 Performing Virtual Machine Power Operations 76 Python Example of Powering On a Virtual Machine 77 VMware vSphere Automation SDK for Python Programming Guide VMware, Inc. 5