Extending VMware vcloud API with vcloud Extensibility Framework

Size: px

Start display at page:

Download "Extending VMware vcloud API with vcloud Extensibility Framework"

Jessica Russell
6 years ago
Views:

1 VMware vclud Architecture Tlkit fr Service Prviders Extending VMware vclud API with vclud Extensibility Framewrk Versin 2.9 January 2018 Jhn Dwyer

2 2018 VMware, Inc. All rights reserved. This prduct is prtected by U.S. and internatinal cpyright and intellectual prperty laws. This prduct is cvered by ne r mre patents listed at VMware is a registered trademark r trademark f VMware, Inc. in the United States and/r ther jurisdictins. All ther marks and names mentined herein may be trademarks f their respective cmpanies. VMware, Inc Hillview Ave Pal Alt, CA VMware vclud Architecture Tlkit fr Service Prviders

3 Cntents Intrductin vclud Directr API Extensin Requirements... 5 Cmmand-Line API Calls Lg in t vclud Directr API using HTTPie... 6 Extensin Example Register an Extensin Handling Extensin AMQP Messages Full Ticketing Example Adding API Links Summary VMware vclud Architecture Tlkit fr Service Prviders

4 4 VMware vclud Architecture Tlkit fr Service Prviders

5 Intrductin As mre custmers embrace develpment and peratins (DevOps), fr autmating the prcess f sftware delivery and infrastructure changes, it is imprtant t prvide users with the necessary tls t interact with yur cmplete IaaS platfrm. By prviding yur services as an extensin t the VMware vclud API, yu prvide a single pint f integratin fr yur user interface (custm r third-party) as well as yur tenant custmers autmatin tls. The VMware vclud Directr Extensin Framewrk gives service prviders the pwer t extend the standard API included with vclud Directr. Service prviders can register a URL pattern that, when called, will be ruted t custm cde t execute thrugh the Advanced Message Queuing Prtcl (AMQP). Sme example services yu might cnsider implementing using vclud API calls include the fllwing: Ability t rder and manage services Public IP space Operating system supprt Ability t pen, update, and clse truble ticket requests Ability t cnfigure: Anti-virus Backups Disaster recvery 1.1 vclud Directr API Extensin Requirements The requirements fr using vclud Directr API extensins include the fllwing: A vclud Directr user accunt with system administratr privileges. vclud Directr must be cnfigured t use AMQP: Administratin > System Settings > Extensibility. After cnfiguring the AMQP settings, verify yur AMQP cnnectin. A prgramming language f yur chice with bindings fr RabbitMQ. (RabbitMQ prvides the AMQP implementatin that is used with vclud Directr.) (Optinal) Ability t make cmmand-line API calls. In the fllwing examples, HTTPie is utilized. 5 VMware vclud Architecture Tlkit fr Service Prviders

6 Cmmand-Line API Calls T simplify making API calls frm the cmmand line, HTTPie is used fr all dem examples. HTTPie is a simple client that prvides curl-like functinality. All example cde can be fund n GitHub. 2.1 Lg in t vclud Directr API using HTTPie Yu must be lgged in as a system administratr. This example uses a lcal system administratr accunt called api-user. # http --verify n --sessin=vclud-gcp-admin -a api-user@system POST 'Accept:applicatin/*+xml;versin=5.6' This example uses a self-signed certificate n a vclud Directr instance, s the verify n ptin is passed. After yu lg in, the sessin is stred in vclud-gcp-admin t reuse n future requests. The utput resulting frm executin f the example shuld lk smething like the fllwing: HTTP/ OK Cntent-Length: 1390 Cntent-Type: applicatin/vnd.vmware.vclud.sessin+xml;versin=5.6 Date: Tue, 08 Dec :49:08 GMT Date: Tue, 08 Dec :49:09 GMT Set-Ckie: vclud-tken=304715fbb28e4ad19efeb6adfe850184; Secure; Path=/ X-VMWARE-VCLOUD-REQUEST-EXECUTION-TIME: 1076 X-VMWARE-VCLOUD-REQUEST-ID: b64552a4-054a-42e4-9ae1-0ea7fabb56a4 x-vclud-authrizatin: fbb28e4ad19efeb6adfe <?xml versin="1.0" encding="utf-8"?> <ns0:sessin xmlns:ns0=" xmlns:xsi=" href=" rg="system" type="applicatin/vnd.vmware.vclud.sessin+xml" user="api-user" userid="urn:vclud:user:44fbd6f9-7a76-4bca-b b181ad09" xsi:schemalcatin=" <ns0:link href=" rel="dwn" type="applicatin/vnd.vmware.vclud.rglist+xml" /> <ns0:link href=" rel="remve" /> <ns0:link href=" rel="dwn" type="applicatin/vnd.vmware.admin.vclud+xml" /> <ns0:link href=" rel="dwn" type="applicatin/vnd.vmware.admin.vmwextensin+xml" /> <ns0:link href=" name="system" rel="dwn" type="applicatin/vnd.vmware.vclud.rg+xml" /> <ns0:link href=" rel="dwn" type="applicatin/vnd.vmware.vclud.query.querylist+xml" /> <ns0:link href=" rel="entityreslver" type="applicatin/vnd.vmware.vclud.entity+xml" /> <ns0:link href=" rel="dwn:extensibility" type="applicatin/vnd.vmware.vclud.apiextensibility+xml" /> </ns0:sessin> 6 VMware vclud Architecture Tlkit fr Service Prviders

7 T reuse the sessin, simply specify the --sessin=vclud-gcp-admin parameter n all future calls. The fllwing example lists all rganizatins in the vclud Directr instance: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET Returns: <?xml versin="1.0" encding="utf-8"?> <OrgList xmlns=" href=" type="applicatin/vnd.vmware.vclud.rglist+xml" xmlns:xsi=" xsi:schemalcatin=" <Org href=" name="system" type="applicatin/vnd.vmware.vclud.rg+xml"/> <Org href=" name="cke" type="applicatin/vnd.vmware.vclud.rg+xml"/> <Org href=" name="pepsi" type="applicatin/vnd.vmware.vclud.rg+xml"/> </OrgList> 7 VMware vclud Architecture Tlkit fr Service Prviders

8 Extensin Example This example integrates a ticketing system with vclud Directr. This can be an integratin int an pen surce prject, an existing enterprise tl, r a hmegrwn system. The gal f the integratin in this example is t allw tenants t pen generic tickets at the custmer level. This integratin is dne using custm scripts fund at Register an Extensin T create a custm extensin, yu must POST a service element. A service element describes the name, namespace, ruting key, exchange t use, and URL patterns (APIFilters) and ServiceLink elements t be used as API filters. The parameters used t create the extensin are as fllws: Name Name f the entity. Fr example: gcp-ticketing. Namespace Service namespace, which must be unique amng all registered extensin services. Service namespace names must fllw the naming cnventin used fr Java packages. This example uses the namespace lcal.gcp.ticketing. RutingKey AMQP ruting key that vclud Directr must use when ruting messages t the service. This example uses the ruting key gcp-ticketing. Exchange AMQP exchange name that vclud Directr must use when ruting messages t the service. The service must create the specified exchange n the AMQP service that vclud Directr uses. This example uses the AMQP exchange name vcdext, which is different than the ne that was cnfigured with vclud Directr. The exchange used fr extensins must be f the type Direct. APIFilters One r mre URL patterns that the vclud Directr REST service must treat as extensin requests. URL patterns can include regular expressins recgnizable by java.util.regex.pattern. Fr example: (/api/rg/.*/ticketing/*[0-9]*) This allws yu t match n: /api/rg/rg-uuid/ticketing /api/rg/rg-uuid/ticketing/ /api/rg/rg-uuid/ticketing/12345 In this case, the additin t rg is limited. If yu wanted t als allw this creatin n individual VMs, yu culd specify: (/api/rg/.*/ticketing*[0-9]*) (/api/vapp/vm-.*/ticketing*[0-9]*) The XML fr the API extensin is created in a file called ext-reg.xml ( and this will be passed t vclud t register the extensin: <?xml versin="1.0" encding="utf-8"?> <vmext:service xmlns=" xmlns:vmext=" name="gcpticketing"> 8 VMware vclud Architecture Tlkit fr Service Prviders

9 <vmext:namespace>lcal.gcp.ticketing</vmext:namespace> <vmext:enabled>true</vmext:enabled> <vmext:rutingkey>gcp-ticketing</vmext:rutingkey> <vmext:exchange>vcdext</vmext:exchange> <vmext:apifilters> <vmext:apifilter> <vmext:urlpattern>(/api/rg/.*/ticketing/*[0-9]*)</vmext:urlpattern> </vmext:apifilter> </vmext:apifilters> </vmext:service> T register, POST t /api/admin/extensin/service with: Cntent Type: applicatin/vnd.vmware.admin.service+xml 'Accept:applicatin/*+xml;versin=5.6 T d this with HTTPie, execute the fllwing cmmand: # http --verify n --sessin=vclud-gcp-admin POST 'Cntent-type: applicatin/vnd.vmware.admin.service+xml' 'Accept:applicatin/*+xml;versin=5.6' < ext-reg.xml Yu will receive the fllwing utput: <?xml versin="1.0" encding="utf-8"?> <vmext:service xmlns:vmext=" xmlns:vclud=" name="gcp-test" id="urn:vclud:externalservice:f79f562a-8d7a-44d6-9bab-82ddf40589f7" href=" type="applicatin/vnd.vmware.admin.service+xml" xmlns:xsi=" xsi:schemalcatin=" <vclud:link rel="remve" href=" 8d7a-44d6-9bab-82ddf40589f7"/> <vclud:link rel="edit" href=" 8d7a-44d6-9bab-82ddf40589f7" type="applicatin/vnd.vmware.admin.service+xml"/> <vclud:link rel="rights" href=" 8d7a-44d6-9bab-82ddf40589f7/rights" type="applicatin/vnd.vmware.admin.rights+xml"/> <vclud:link rel="dwn:servicelinks" href=" 82ddf40589f7/links" type="applicatin/vnd.vmware.vclud.query.recrds+xml"/> <vclud:link rel="bundle:uplad" href=" type="applicatin/vnd.vmware.admin.bundleupladparams+xml"/> <vclud:link rel="add" href=" 44d6-9bab-82ddf40589f7/links" type="applicatin/vnd.vmware.admin.servicelink+xml"/> <vclud:link rel="dwn:apifilters" href=" 82ddf40589f7/apifilters" type="applicatin/vnd.vmware.vclud.query.recrds+xml"/> <vclud:link rel="add" href=" 44d6-9bab-82ddf40589f7/apifilters" type="applicatin/vnd.vmware.admin.apifilter+xml"/> 9 VMware vclud Architecture Tlkit fr Service Prviders

10 <vclud:link rel="add" href=" 44d6-9bab-82ddf40589f7/apidefinitins" type="applicatin/vnd.vmware.admin.apidefinitin+xml"/> <vclud:link rel="dwn:apidefinitins" href=" 82ddf40589f7/apidefinitins" type="applicatin/vnd.vmware.vclud.query.recrds+xml"/> <vclud:link rel="add" href=" 44d6-9bab-82ddf40589f7/resurceclasses" type="applicatin/vnd.vmware.admin.resurceclass+xml"/> <vclud:link rel="dwn:resurceclasses" href=" 82ddf40589f7/resurceclasses" type="applicatin/vnd.vmware.vclud.query.recrds+xml"/> <vclud:link rel="authrizatin:check" href=" 82ddf40589f7/authrizatincheck" type="applicatin/vnd.vmware.admin.authrizatincheckparams+xml"/> <vmext:namespace>lcal.gcp.ticketing</vmext:namespace> <vmext:enabled>true</vmext:enabled> <vmext:authrizatinenabled>false</vmext:authrizatinenabled> <vmext:rutingkey>gcp-ticketing</vmext:rutingkey> <vmext:pririty>0</vmext:pririty> <vmext:exchange>vcdext</vmext:exchange> </vmext:service> T retrieve a list f all extensins yu can execute: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET T test that the extensin allws calling the ticketing methd fr an rganizatin, execute the fllwing cmmand: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET When this test cmmand is executed, the call will hang fr 10 secnds, and eventually return a 504 errr message, External service gcp-ticketing failed t respnd in the specified timeut (10 SECONDS). This verifies that the new extensin was registered successfully, hwever, nthing was cnfigured yet t handle the message that was added t the message queue. 3.2 Handling Extensin AMQP Messages When the API receives an extensin request, the vclud Directr REST service creates a message and sends it t the system AMQP service, specifying the exchange and ruting key registered by the extensin service. The extensin service retrieves the message frm a queue bund t the exchange it registered, prcesses the request, and returns a respnse t the cmmn reply exchange. T handle the AMQP messages, yu must use a language that has a client t cmmunicate with RabbitMQ. There are tutrials fr mst majr prgramming languages n the RabbitMQ site at This example uses Pythn with the Pika client. T listen fr incming messages, yu must bind t the crrect Exchange and Queue (als referred t as RutingKey). This was defined when yu registered the extensin (see Sectin 3.1, Register an Extensin). Exchange: vcdext Queue: gcp-ticketing 10 VMware vclud Architecture Tlkit fr Service Prviders

11 When new messages are received, the fllwing infrmatin is prvided: channel, methd, prperties and bdy. The prperties cntain three imprtant pieces f infrmatin that are required t respnd t the request: Headers These are the AMQP headers, nt the API headers. The key piece f infrmatin required is the replytexchange. Crrelatin_id vclud Directr sets a unique crrelatin_id in every message sent t the extensin service, and the extensin must set the same value in the crrespnding respnse. Reply_t What queue t respnd n. The bdy is made up f many parts, but, fr basic integratin, the fllwing is required: Bdy The bdy f the API request. Headers The API request headers. It is imprtant t nte the incming Accept header t respnd back with the crrect cntent type. Methd The methd used t call the API (GET, POST, PUT, DELETE). Id The unique ID assigned t the incming message. This is used t reply t the message. Fr mre infrmatin abut the bdy, see the VMware vclud API Prgramming Guide fr Service Prviders at BD00-A76E47A9C731.html Basic Example This example generically handles a request and respnds back using Pythn. The fllwing is an example f the cde used. Refer t the surce cde n GitHub t make sure yu have the mst current versin f the cde. On a server that can cnnect t the RabbitMQ instance, run the basic_receive.py prgram script ( 11 VMware vclud Architecture Tlkit fr Service Prviders

12 12 VMware vclud Architecture Tlkit fr Service Prviders

13 A call is then made against the new API ticketing endpint: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET The call and respnse is similar t the fllwing: The fllwing utput frm basic_receive.py indicates that the message has been prperly handled: 3.3 Full Ticketing Example Nw that yu have seen that the message has been successfully handled, yu can implement a full ticketing slutin. A pythn script, ticketing.py, that is meant t simulate wrking with a ticketing system, is available at T explre the API, execute pythn ticketing.py: The fllwing is a list f newly expsed functinality with examples shwing hw t make the crrespnding API extensin call: List tickets fr an rg GET: /api/rg/<org_uuid>/ticketing http --sessin=vclud-gcp-admin --pretty clrs GET --verify n Create a ticket POST: /api/rg/<org_uuid>/ticketing http --sessin=vclud-gcp-admin --pretty clrs POST --verify n < ticket_create.xml Get ticket details GET: /api/rg/<org_uuid>/ticketing/<ticket_id> 13 VMware vclud Architecture Tlkit fr Service Prviders

14 http --sessin=vclud-gcp-admin --pretty clrs GET --verify n Update a ticket PUT: /api/rg/<org_uuid>/ticketing/<ticket_id> http --sessin=vclud-gcp-admin --pretty clrs PUT --verify n < ticket_update.xml Delete a ticket DELETE: /api/rg/<org_uuid>/ticketing/<ticket_id> http --sessin=vclud-gcp-admin --pretty clrs DELETE --verify n Using these example, yu can explre hw the new API endpints are expsed and implemented. 3.4 Adding API Links While the new ticketing extensin is registered, it des nt shw up in the link list. By using the ServiceLink bject, yu can add link elements t the representatin f vclud API bjects. This can be dne by passing the ServiceLinks with the riginal service extensin registratin, r it can be added later. In this case, they are added after the extensin has been implemented. When yu view an rganizatin: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET there is n link element returned prviding the path t the newly defined service. T add the new links, yu must retrieve the UUID f the registered service: # http --sessin=vclud-gcp-admin --pretty clrs GET --verify n This prvides the list f all registered extensins. After finding the ticketing extensin, yu can get the details f the extensin yu added: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET d601a58 One f the links that is returned allws yu t add the ServiceLinks: <vclud:link rel="add" href=" type="applicatin/vnd.vmware.admin.servicelink+xml"/> POST this ServiceLink t this lcatin. T build a ServiceLink, there are fur required attributes: LinkHref The value f the href attribute f this service Link. This can be any URI, and can include the variables {baseuri} and {resurceid}. When cnstructing the href value f the link, vclud Directr replaces {baseuri} with the vclud Directr REST API base URL, and replaces {resurceid} with the UUID prtin f the id attribute value f the resurce in which the link is inserted. The value must be less than r equal t 255 characters in length. MimeType The value, specified as a MIME cntent type, f the type attribute f the link. The value must be less than r equal t 255 characters in length. Rel The value f the rel attribute f the link. This value must be less than r equal t 255 characters in length. ResurceType The bject type, specified as a MIME cntent type, f the bject in which the link appears. Must be less than r equal t 255 characters in length. 14 VMware vclud Architecture Tlkit fr Service Prviders

15 Example XML ( <?xml versin="1.0" encding="utf-8"?> <vmext:servicelink xmlns:vmext=" xmlns:vclud=" type="applicatin/vnd.vmware.admin.servicelink+xml"> <vmext:linkhref>{baseuri}rg/{resurceid}/ticketing</vmext:linkhref> <vmext:mimetype>applicatin/vnd.example.vcd.tickets+xml</vmext:mimetype> <vmext:rel>listtickets</vmext:rel> <vmext:resurcetype>applicatin/vnd.vmware.vclud.rg+xml</vmext:resurcetype > </vmext:servicelink> Add the link t the extensin: # http --verify n --sessin=vclud-gcp-admin --pretty clrs POST d601a58/links 'Cntent-type: applicatin/vnd.vmware.admin.servicelink+xml' < ext-addlink.xml After the link is added, call the rg bject t verify that it has been added: # http --verify n --sessin=vclud-gcp-admin --pretty clrs GET The Org XML that is returned nw includes the newly added ticketing link element: <Link rel="listtickets" href=" 49a8-8dab-3fdbf00a21ae/ticketing" type="applicatin/vnd.example.vcd.tickets+xml"/> 15 VMware vclud Architecture Tlkit fr Service Prviders

16 Summary Nw that yu have created an extensin, yu might be wndering hw yu cntrl access t yur new API. By default, all extensin requests must be authenticated thrugh the vclud API, but all users are implicitly granted permissin t perfrm all actins. Thrugh the use f the vclud Directr API Authrizatin Framewrk, yu can create granular ACL-based cntrl. Als cnsider adding the schema files t prvide dcumentatin abut yur new API using Create r Update an Extensin Service API Definitin. 16 VMware vclud Architecture Tlkit fr Service Prviders

Troubleshooting Citrix- Published Resources Configuration in VMware Identity Manager

Troubleshooting Citrix- Published Resources Configuration in VMware Identity Manager Trubleshting Citrix- Published Resurces Cnfiguratin in VMware Identity Manager VMware Identity Manager A U G U S T 2 0 1 7 V1 Table f Cntents Overview... 1 Supprted Versins f Cmpnents... 1 Prerequisites...