WIXLIB

VMware vCloud Suite SDK for .NET Programming GuidevCenter Server also provides services that you can access through the vCloud Suite Endpoint.Content Library ServiceYou can use the Content Library Service to share VM templates, vApptemplates, and other files across the software-defined data center. You cancreate, share, and subscribe to content libraries on the same vCenter Serverinstance or on a remote instance. This promotes consistency, compliance,efficiency, and automation in deploying workloads at scale. By using contentlibraries, you can also create OVF packages from virtual machines andvirtual appliances in hosts, resource pools, and clusters. You can then use theOVF packages to provision new virtual machines in hosts, resource pools,and clusters.Tagging ServiceThis service supports the definition of tags that you can associate withvSphere objects or vCloud Suite resources. The vCloud Suite SDKs providethe capability to manage tags programmatically.vSphere Deployment ConfigurationsvCloud Suite client applications communicate with services on the Platform Services Controller andvCenter Server components of the virtual environment. vCenter Server can be deployed with an embeddedor external Platform Services Controller.vCenter Server with an Embedded Platform Services ControllervCenter Server and Platform Services Controller reside on the same virtual machine or physical server. Thisdeployment is most suitable for small environments such as development or test beds.A client application must first connect to the Lookup Service on the Platform Services Controller andretrieve the vCenter Single Sign-On Service endpoint and the vCloud Suite Endpoint. The application canaccess services on the vCenter Server instance through the vCloud Suite Endpoint in an authenticatedsession or by providing as SAML token in each request.14VMware, Inc.

Chapter 2 Components of the vCloud Suite Virtualization LayerFigure 2‑1. vCenter Server with Embedded Platform Services ControllerVM or Physical ServerPlatform Services ControllerSingle Sign-OnService URLvCloud SuiteEndpoint URLvCenter ServerURLOther ServicesURLsLookupServiceSingleSign-ONServiceSAML TokenVMVMware ESXivCenter ServervCloud SuiteEndpointContent LibraryServiceТaggingServiceOther ServicesVMVMware ESXivCenter Server with an External Platform Services ControllervCenter Server and Platform Services Controller are deployed on separate virtual machines or physicalservers. The Platform Services Controller can be shared across several vCenter Server instances. For largerdeployments, more than one Platform Services Controller can exist as infrastructure data is replicated acrossall Platform Services Controller instances.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 services on multiplevCenter Server instances, or services only on a particular vCenter Server instance.VMware, Inc.15

VMware vCloud Suite SDK for .NET Programming GuideFigure 2‑2. vCenter Server with External Platform Services ControllerVM or Physical ServerPlatform Services ControllerLookupServiceSingleSign-ONServiceSAML TokenVM or Physical ServerVM or Physical ServervCenter ServervCenter ServervCloud SuiteEndpointVMVMware ESXi16Single Sign-OnService URLvCloud SuiteEndpoint URLvCenter ServerURLOther ServicesURLsContent LibraryServiceТaggingServiceOther ServicesvCloud SuiteEndpointVMVMware ESXiVMVMware ESXiContent LibraryServiceТaggingServiceOther ServicesVMVMware ESXiVMware, Inc.

Retrieving Service Endpoints3To access services and resources in the virtual environment, vCloud Suite API client applications mustretrieve endpoints of vCloud Suite and vSphere services. Client applications retrieve service endpoints fromthe Lookup Service that runs on the Platform Services Controller.The Lookup Service provides service registration and discovery by using the vSphere Web services API. Byusing the Lookup Service, you can retrieve endpoints of services on the Platform Services Controller andvCenter Server.nThe vCenter Single Sign-On endpoint on the Platform Services Controller. You use the vCenter SingleSign-On service to get a SAML token and establish an authenticated session with the vCloud SuiteEndpoint. You can also use the token in a sessionless manner by including it in every request that youissue to the vCloud Suite Endpoint. For more information, see Chapter 4, “AuthenticationMechanisms,” on page 25.nThe vCloud Suite Endpoint on vCenter Server. Through the vCloud Suite Endpoint, you can makerequests to vCloud Suite API services such as Content Library and Tagging.nThe vCenter Server endpoint. In an environment with external Platform Services Controller instances,you can use the vCenter Server endpoint to get the node ID of a particular vCenter Server instance. Byusing the node ID , you can retrieve service endpoints on that vCenter Server instance.nThe vSphere API endpoint and endpoints of other vSphere services that run on vCenter Server.Workflow for Retrieving Service EndpointsThe workflow that you use to retrieve service endpoints from the Lookup Service might vary depending onthe endpoints that you need and their number. Follow a general workflow for retrieving service endpoints.1Connect to the Lookup Service on the Platform Services Controller and service registration object sothat 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.4Extract one or more endpoint URLs from the array of registration information that you receive from theLookup Service.This chapter includes the following topics:n“Filtering for Predefined Service Endpoints,” on page 18n“Filter Parameters for Predefined Service Endpoints,” on page 18n“Connect to the Lookup Service and Retrieve the Service Registration Object,” on page 19n“Retrieve Service Endpoints on vCenter Server Instances,” on page 20VMware, Inc.17

VMware vCloud Suite SDK for .NET Programming Guiden“Retrieve a vCenter Server ID by Using the Lookup Service,” on page 22n“Retrieve a vCloud Suite Endpoint on a vCenter Server Instance,” on page 23Filtering for Predefined Service EndpointsThe Lookup Service maintains a registration list of all services in the virtual environment. You can use theLookup Service to retrieve registration information for every service by setting a registration filter that youpass to the List() function on the Lookup Service. The functions and objects that you can use with theLookup 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 from the LookupService. You invoke theList() function on the Lookup Service to list the endpoints that you need by passingLookupServiceRegistrationFilter . LookupServiceRegistrationFilter identifies the service and theendpoint type that you can retrieve.Optionally, you can include the node ID parameter in the filter that identifies the vCenter Server instancewhere the endpoint is hosted. When the node ID is omitted, the List() function returns the endpoint URLsof the service that are hosted on all vCenter Server instances in the environment.For example, a LookupServiceRegistrationFilter for queering the vCloud Suite service has these serviceendpoint elements.Table 3‑1. Service Registration Filter ParametersFilter iceTypeproduct "com.vmware.cis"vCloud Suite namespace.type "cs.vapi"Identifies the vCloud Suiteservice.type "com.vmware.vapi.endpoint"Specifies the endpoint path forthe service.protocol "vapi.json.https.public"Identifies the protocol that willbe used for communication withthe endpoint .LookupServiceRegistrationEndpointTypeFor information about the filter parameter of the available predefined service endpoints, see “FilterParameters for Predefined Service Endpoints,” on page 18.Filter Parameters for Predefined Service EndpointsDepending on the service endpoint that you want to retrieve, you provide different parameters to theLookupServiceRegistrationFilter that you pass to the List() function on the Lookup Service. To search forservices on a particular vCenter Server instance, set the node ID parameter to the filter.Table 3‑2. Input Data for URL Retrieval for the Lookup Service Registration Filter18ServiceInput DataValuevCenter Single Sign-Onproduct namespacecom.vmware.cisservice typecs.identityprotocolwsTrustendpoint typecom.vmware.cis.cs.identity.ssoVMware, Inc.

Chapter 3 Retrieving Service EndpointsTable 3‑2. Input Data for URL Retrieval for the Lookup Service Registration Filter (Continued)ServiceInput DataValuevCloud Suite Endpointproduct 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.eamprotocolvmomiendpoint typecom.vmware.cis.cs.eam.sdkvCenter ServervCenter Storage MonitoringServicevCenter Storage Policy-BasedManagementvSphere ESX Agent ManagerConnect to the Lookup Service and Retrieve the Service RegistrationObjectYou must connect to the Lookup Service to gain access to its operations. After you connect to the LookupService, you must retrieve the service registration object to make registration queries.Procedure12Connect to the Lookup Service.aConfigure a connection stub for the Lookup Service endpoint, which uses SOAP bindings, by usingthe HTTPS protocol.bCreate a connection object to communicate with the Lookup Service.Retrieve the Service Registration Object.aCreate a managed object reference.bRetrieve the ServiceContent managed object.cRetrieve the service registration object.With the service registration object, you can make registration queries.VMware, Inc.19

VMware vCloud Suite SDK for .NET Programming Guide.NET Example of Connecting to the Lookup Service and Retrieving a ServiceRegistration ObjectThe example is based on the code from the LsConnection.cs sample file. The source file is located in thefollowing vCloud Suite SDK for .NET ware.lookupservice;// 1 - Create a custom binding for SOAP messages.var customBinding new CustomBinding();var textMessageEncoding new oding.MessageVersion MessageVersion.Soap11;var transport new edMessageSize ncoding);customBinding.Elements.Add(transport);// 2 - Create an object that encapsulates the Lookup Service URL.var address new EndpointAddress(lsUrl);// 3 - Create a connection object to communicate with the Lookup Service.lsPort new LsPortTypeClient(customBinding, address);// 4 - Manufacture a managed object reference.var serviceInstanceRef new ManagedObjectReference();serviceInstanceRef.type "LookupServiceInstance";serviceInstanceRef.Value "ServiceInstance";// 5 - Retrieve the ServiceContent managed object.serviceContent // 6 - Retrieve the service registration object.serviceRegistration serviceContent.serviceRegistration;Retrieve Service Endpoints on vCenter Server InstancesYou can create a function that obtains the endpoint URLs of a service on all vCenter Server instances in theenvironment. You can modify that function to obtain the endpoint URL of a service on a particularvCenter Server instance.See “Connect to the Lookup Service and Retrieve the Service Registration Object,” on page 19.PrerequisitesnEstablish a connection with the Lookup Service.nRetrieve a service registration object.Procedure201Create a filter criterion for service information.2Create a filter criterion for endpoint information.VMware, Inc.

Chapter 3 Retrieving Service Endpoints34Create the registration filter object.OptionDescriptionOmit 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.Depending on whether you included the node ID parameter, the List() function returns different results.nA list of endpoint URLs for a service that are is hosted on all vCenter Server instances in theenvironment.nAn endpoint URL of a service that runs on a particular vCenter Server.What 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 “Filter Parametersfor Predefined Service Endpoints,” on page 18.To retrieve a service endpoint on a particular vCenter Server instance, you must retrieve the node ID of thatinstance and pass it to the function. For information about how to retrieve the ID of a vCenter Serverinstance, see “Retrieve a vCenter Server ID by Using the Lookup Service,” on page 22.NET Example of Retrieving a Service Endpoint on a vCenter Server InstanceThis example provides a common pattern for filtering Lookup Service registration data. This example isbased on the code in the LsConnection.cs sample file. The file is located in the followingvCloud Suite SDK for .NET directory: pservice;public LookupServiceRegistrationInfo[] LookupSingleServiceUrl(string prod,string sType,string proto,string eType,string nodeId){// 1 - Create a filter criterion for service info.var filterServiceType new ceType.product prod;filterServiceType.type sType;// 2 - Create a filter criterion for endpoint info.var filterEndpointType new ointType.protocol proto;filterEndpointType.type eType;// 3 - Create the registration filter object.var filterCriteria new erviceType filterServiceType;filterCriteria.endpointType filterEndpointType;filterCriteria.nodeId nodeId;VMware, Inc.21

VMware vCloud Suite SDK for .NET Programming Guide// 4 - Retrieve specified service info with the List() method.return lsPort.List(serviceRegistration, filterCriteria);}Retrieve 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 on thatvCenter Server instance. You specify the node ID in the service registration filter that you pass to the List()function on the Lookup Service.Managed services are registered with the instance name of the vCenter Server instance where they run. Theinstance name maps to a unique vCenter Server ID. The instance name of a vCenter Server system isspecified during installation and might be an FQDN or an IP address.NOTE Use the URL that you retrieve from the Lookup Service to access a service. Avoid using the instancename to construct the URL of the service.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.Use the node ID of the vCenter Server instance to filter subsequent endpoint requests. You can use the nodeID in a function that retrieves the endpoint URL of a service on a vCenter Server instance. For informationabout implementing such a function, see “Retrieve Service Endpoints on vCenter Server Instances,” onpage 20.NET Example of Retrieving a vCenter Server ID by Using the Lookup ServiceThis example provides a common pattern for filtering Lookup Service registration data. This example isbased on the code in the LsConnection.cs sample file. The file is located in the followingvCloud Suite SDK for .NET directory: ples/common/using System;using System.Linq;using vmware.vapi.util.security;public String getMgmtNodeId(String nodeInstanceName){// 1 - List the vCenter Server instances.var services ,"vmomi","com.vmware.vim");// 2 - Find the matching node name and save the ID.foreach (var service in services){foreach (var serviceAttribute in service.serviceAttributes{if er.instanceName",22VMware, Inc.

Chapter 3 Retrieving Service ) tringComparison.CurrentCultureIgnoreCase)){return service.nodeId;}}}}Retrieve a vCloud Suite Endpoint on a vCenter Server InstanceThrough the vCloud Suite Endpoint, you can access other vCloud Suite services that run on vCenter Server,such as Content Library and Tagging. To use a vCloud Suite service, you must retrieve the vCloud SuiteEndpoint.PrerequisitesnEstablish a connection with the Lookup Service.nRetrieve a service registration object.nDetermine the node ID of the vCenter Server instance where the vCloud Suite service runs.nImplement a function that retrieves the endpoint URL of a service on a vCenter Server instance.Procedure1Invoke the function for retrieving the endpoint URL of a service on a vCenter Server instance bypassing filter strings that are specific to the vCloud Suite endpoint.2Save the URL from the resulting single-element list.NET Example of Retrieving a vCloud Suite Endpoint on a vCenter ServerInstanceThis example provides a common pattern for filtering Lookup Service registration data. This example isbased on the code in the LsConnection.cs sample file. The file is located in the followingvCloud Suite SDK for .NET directory: ples/common/targetNodeId getMgmtNodeId(target node fqdn)var serviceInfo Lookup

Components of the vCloud Suite Virtualization Layer 2 At the core of vCloud Suite is vSphere, which provides the virtualization layer of the software-defined data center. You can use vSphere deployment options for vCenter Server and ESXi hosts to build virtual environments of different scales. This chapter includes the following topics: