Home > Blogs > vCloud Architecture Toolkit (vCAT) Blog


Re: Working with the vCloud Networking and Security API

Working with with the vCloud Networking and Security API

By: Michael Haines ( Senior Cloud Networking and Security Architect)

In vCAT 3.0 we discuss many of the vCloud Networking and Security components as well as aspects of design principals and best practices to follow. In this blog we take this one step further and show you how to get started with the very powerful and feature rich vCloud Networking and Security API. I will also show you one very important, but overlooked aspect, which is how to interpret the XML data of the Edge device for example, which can be daunting and very hard to read as it is currently enumerated and presented.

The vCloud Networking and Security REST API REST uses HTTP requests (which are often executed in an automated manner, using a script or other higher‐level language) as a way of making what are essentially remote procedure calls that create, modify, or delete the objects defined by the API. This vCloud Networking and Security REST API is defined by a collection of XML documents that represent the objects on which the API operates. The operations themselves (HTTP requests) are generic to all HTTP clients.

The vCloud Networking and Security REST work flows fall into a pattern that includes only two fundamental operations:

  1. Make an HTTP request (typically GET, PUT, POST, or DELETE). The target of this request is either a well‐known URL (such as the vCloud Networking and Security Manager) or a link obtained from the response to a previous request.
  2. Examine the response, which can be an XML document or an HTTP response code. If the response is an XML document, it may contain links or other information about the state of an object. If the response is an HTTP response code, it indicates whether the request succeeded or failed, and may be accompanied by a URL that points to a location from which additional information can be retrieved.

Lets take a look at some of the basic elements and examples of actally using the vCloud Networking and Security REST API.  In my examples that follow, I will be using a command-line tool called cURL to consume the vCloud Networking and Security REST API. There is no need for fancy document descriptions here, as we need to only hit each URL with the appropriate method and data to cause an immediate response. cURL, sometimes written as curl, is a set of C-based libraries in PHP that supports HTTP “GET”. The curl command-line can get a little messy, as there  are lots of options available for controlling exactly how you want cURL to interface with the remote server.

So, the first thing you will want to do is get a list of the vCloud Networking and Security Edge Gateway devices installed in a Datacenter:

$ curl -i -k -H “content-type: application/xml” -H “host: <vCNS-IP-Address>” -H
“Authorization: Basic YWRtaW46ZGVmYXVsdA==” -X GET https://<vCNS Manager-IP-Address>/api/3.0/edges/

NOTE: YWRtaW46ZGVmYXVsdA== is the base64 encoded string which when decoded.

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONID=ED9F79E5921E89A5EFDBB59E7F6DDA0F; Path=/; Secure; HttpOnly
Content-Type: application/xml
Transfer-Encoding: chunked
Date: Mon, 19 Nov 2012 12:12:35 GMT

<?xml version=”1.0″ encoding=”UTF-8″?>
<com.vmware.vshield.edge.dto.EdgePageDto><edgePage><pagingInfo><pageSize>256</pageSize><startIndex>0</startIndex><totalCount>1</totalCount><sortOrderAscending>true</sortOrderAscending><sortBy>objectId</sortBy></pagingInfo><edgeSummary><objectId>edge-3</objectId><type><typeName>Edge</typeName></type><name>test</name><revision>6</revision><objectTypeName>Edge</objectTypeName><extendedAttributes/><id>edge-3</id><state>undeployed</state><datacenterMoid>datacenter-2</datacenterMoid><datacenterName>testbed</datacenterName><apiVersion>3.0</apiVersion><recentJobInfo><jobId>jobdata-27</jobId><status>SUCCESS</status></recentJobInfo><numberOfConnectedVnics>1</numberOfConnectedVnics><appliancesSummary><vmVersion>5.1.0</vmVersion><applianceSize>compact</applianceSize><fqdn>vShield-edge-3</fqdn><numberOfDeployedVms>0</numberOfDeployedVms></appliancesSummary></edgeSummary></edgePage></com.vmware.vshield.edge.dto.EdgePageDto>
$

Next, how can I get the status of a particular Edge gateway:

$ curl -i -k -H “content-type: application/xml” -H “host: <vCNS-IP-Address>” -H
“Authorization: Basic YWRtaW46ZGVmYXVsdA==” -X GET https://<vCNS-IP-Address>/api/3.0/edges/<edge-identifier>/status

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONID=D88C4882CCA194760785BE546E537058; Path=/; Secure; HttpOnly
Content-Type: application/xml
Transfer-Encoding: chunked
Date: Mon, 19 Nov 2012 12:12:12 GMT

<?xml version=”1.0″ encoding=”UTF-8″?>
<edgeStatus><timestamp>1342440732007</timestamp><edgeStatus>GREY</edgeStatus><publishStatus>PERSISTED</publishStatus><version>6</version><edgeVmStatus/><featureStatuses><featureStatus><service>highAvailability</service><status>not_configured</status></featureStatus><featureStatus><service>nat</service><status>not_configured</status></featureStatus><featureStatus><service>loadBalancer</service><status>not_configured</status></featureStatus><featureStatus><service>firewall</service><status>Configured</status></featureStatus><featureStatus><service>dns</service><status>not_configured</status></featureStatus><featureStatus><service>staticRouting</service><status>not_configured</status></featureStatus><featureStatus><service>syslog</service><status>not_configured</status></featureStatus><featureStatus><service>ipsec</service><status>not_configured</status></featureStatus><featureStatus><service>dhcp</service><status>not_configured</status></featureStatus><featureStatus><service>sslvpn</service><status>not_configured</status></featureStatus></featureStatuses></vice>edgeStatus>

NOTE: The edge-identifier: It is the edge identifier generated by vCloud Networking and Security Manager to identify an Edge device uniquely within the vCloud Networking and Security Manager.

All Edge operations in vCloud Networking and Security v5.1.x follow this addressing scheme now where the Edge is addressed using its edge-id/edge-identifier.

As you can see from the above examples, the XML data that is enumerated and returned in not easy to read and interpret. Remember, this is a basic example, (as basic as it gets). So, what would happen if you had many Edge devices that was using many of the features? Yes, it would be a lot more complex. So, f you are working with the vCloud Networking and Security REST API, and thus XML you maybe asking yourself how on earth do I read the output of the XML in a more readable fashion?

In the following example I am enumerating a specific Edge device using the following command:

$ curl -i -k -H “content-type: application/xml” -H “host: <vCNS-Manager
-IP-Address>” -H “Authorization: Basic YWRtaW46ZGVmYXVsdA==” -X GET https://<vCNS-Manager-IP-Address>/api/3.0/edges/edge-5
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONID=DC63EB7BD4A641E38C62C62F5B4D53AE; Path=/; Secure;
HttpOnly
Content-Type: application/xml
Transfer-Encoding: chunked
Date: Tue, 19 Nov 2012 15:05:35 GMT

<?xml version=”1.0″ encoding=”UTF-8″?><pagedEdgeList><edgePage><pagingInfo><pageSize>256</pageSize><startIndex>0</startIndex><totalCount>2</totalCount><sortOrderAscending>true</sortOrderAscending><sortBy>id</sortBy></pagingInfo><edgeSummary><objectId>edge-5</objectId><type><typeName>Edge</typeName></type><name>vCNS-Edge-Tenant1</name><revision>13</revision><objectTypeName>Edge</objectTypeName><extendedAttributes/><id>edge-5</id><state>deployed</state><datacenterMoid>datacenter-2</datacenterMoid><datacenterName>Cloud Datacenter</datacenterName><apiVersion>3.0</apiVersion><recentJobInfo><jobId>jobdata-47</jobId><status>SUCCESS</status></recentJobInfo><numberOfConnectedVnics>2</numberOfConnectedVnics><appliancesSummary><vmVersion>5.1.0</vmVersion><applianceSize>compact</applianceSize><fqdn>vShield-edge-5</fqdn><numberOfDeployedVms>1</numberOfDeployedVms><activeVseHaIndex>0</activeVseHaIndex><vmMoidOfActiveVse>vm-64</vmMoidOfActiveVse><vmNameOfActiveVse>vCNS-Edge-Tenant1-0</vmNameOfActiveVse><hostMoidOfActiveVse>host-37</hostMoidOfActiveVse <hostNameOfActiveVse>10.129.139.7</hostNameOfActiveVse><resourcePoolMoidOfActiveVse>resgroup-20</resourcePoolMoidOfActiveVse><resourcePoolNameOfActiveVse>Resources</resourcePoolNameOfActiveVse><dataStoreMoidOfActiveVse>datastore-38</dataStoreMoidOfActiveVse><dataStoreNameOfActiveVse>datastore1(2)</dataStoreNameOfActiveVse><statusFromVseUpdatedOn>1351609518000</statusFromVseUpdatedOn></appliancesSummary></edgeSummary><edgeSummary><objectId>edge-6</objectId><type><typeName>Edge</typeName></type><name>vCNS-Edge-Tenant2</name><revision>13</revision><objectTypeName>Edge</objectTypeName><extendedAttributes/><id>edge-6</id><state>deployed</state><datacenterMoid>datacenter-2</datacenterMoid><datacenterName>Cloud Datacenter</datacenterName><apiVersion>3.0</apiVersion><recentJobInfo><jobId>jobdata-39</jobId><status>SUCCESS</status></recentJobInfo <numberOfConnectedVnics>2</numberOfConnectedVnics><appliancesSummary><vmVersion>5.1.0</vmVersion><applianceSize>compact</applianceSize><fqdn>vShield-edge-6</fqdn><numberOfDeployedVms>1</numberOfDeployedVms><activeVseHaIndex>0</activeVseHaIndex><vmMoidOfActiveVse>vm-63</vmMoidOfActiveVse><vmNameOfActiveVse>vCNS-Edge-Tenant2-0</vmNameOfActiveVse><hostMoidOfActiveVse>host-39</hostMoidOfActiveVse <hostNameOfActiveVse>10.129.139.8</hostNameOfActiveVse><resourcePoolMoidOfActiveVse>resgroup-22</resourcePoolMoidOfActiveVse><resourcePoolNameOfActiveVse>Resources</resourcePoolNameOfActiveVse><dataStoreMoidOfActiveVse>datastore-40</dataStoreMoidOfActiveVse><dataStoreNameOfActiveVse>datastore1(3)</dataStoreNameOfActiveVse><statusFromVseUpdatedOn>1351609519000</statusFromVseUpdatedOn></appliancesSummary></edgeSummary></edgePage></pagedEdgeList>

WOW, I hear you say! How in earth can I read and interpret this? To help make this more readable perform the following:

1.  Re-direct the output of the REST API query to a file:

$ curl -i -k -H “content-type: application/xml” -H “host: <vCNS-Manager
-IP-Address>” -H “Authorization: Basic YWRtaW46ZGVmYXVsdA==” -X GET
https://<vCNS-Manager-IP-Address>/api/3.0/edges/edge-5 > edge-xml.xml

2. Remove the Cntrl M characters if they exist. If you use vi then perform the following. Note: ^v is a CONTROL-V character and ^m is a CONTROL-M:

$ vi edge-xml.xml
$ %s/^M//g
$ Save the NEW file to edge-xml-converted.xml

3. Edit the file edge-xml-converted.xml and remove all lines before and including <?xml version=”1.0″ encoding=”UTF-8″?>

4. Now, you should be able to view the contents of the edge xml file with some legability:

$ xmllint -format edge-xml-converted.xml

<?xml version="1.0"?>
<edge>
   <id>edge-5</id>
   <version>17</version>
   <status>deployed</status>
   <datacenterMoid>datacenter-2</datacenterMoid>
   <datacenterName>Cloud Datacenter</datacenterName>
   <name>vCNS-Edge-Tenant1</name>
   <fqdn>vShield-edge-5</fqdn>
   <enableAesni>true</enableAesni>
   <enableFips>false</enableFips>
   <enableTcpLoose>false</enableTcpLoose>
   <vseLogLevel>info</vseLogLevel>
   <vnics>
     <vnic>
       <index>0</index>
       <name>External</name>
       <type>uplink</type>
       <portgroupId>dvportgroup-26</portgroupId>
       <portgroupName>vSE-External</portgroupName>
       <addressGroups>
         <addressGroup>
           <primaryAddress>10.129.139.5</primaryAddress>
           <subnetMask>255.255.255.0</subnetMask>
         </addressGroup>
       </addressGroups>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>false</enableSendRedirects>
       <isConnected>true</isConnected>
     </vnic>
     <vnic>
       <index>1</index>
       <name>Internal-Tenant-1</name>
       <type>internal</type>
       <portgroupId>dvportgroup-18</portgroupId>
       <portgroupName>Tenant-1</portgroupName>
       <addressGroups>
         <addressGroup>
           <primaryAddress>172.16.0.1</primaryAddress>
           <subnetMask>255.255.0.0</subnetMask>
         </addressGroup>
       </addressGroups>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>false</enableSendRedirects>
       <isConnected>true</isConnected>
     </vnic>
     <vnic>
       <index>2</index>
       <name>vnic2</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>3</index>
       <name>vnic3</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>4</index>
       <name>vnic4</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>5</index>
       <name>vnic5</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>6</index>
       <name>vnic6</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>7</index>
       <name>vnic7</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>8</index>
       <name>vnic8</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
     <vnic>
       <index>9</index>
       <name>vnic9</name>
       <type>internal</type>
       <addressGroups/>
       <mtu>1500</mtu>
       <enableProxyArp>false</enableProxyArp>
       <enableSendRedirects>true</enableSendRedirects>
       <isConnected>false</isConnected>
     </vnic>
   </vnics>
   <appliances>
     <applianceSize>compact</applianceSize>
     <appliance>
       <highAvailabilityIndex>0</highAvailabilityIndex>
       <vcUuid>421c8d1d-aed4-1003-8c46-282ff75f94c9</vcUuid>
       <vmId>vm-64</vmId>
       <resourcePoolId>resgroup-20</resourcePoolId>
       <resourcePoolName>Resources</resourcePoolName>
       <datastoreId>datastore-38</datastoreId>
       <datastoreName>datastore1 (2)</datastoreName>
       <hostId>host-37</hostId>
       <hostName>10.129.139.7</hostName>
       <vmFolderId>group-v3</vmFolderId>
       <vmFolderName>vm</vmFolderName>
       <vmHostname>vShield-edge-5-0</vmHostname>
       <vmName>vCNS-Edge-Tenant1-0</vmName>
       <deployed>true</deployed>
       <edgeId>edge-5</edgeId>
     </appliance>
   </appliances>
   <cliSettings>
     <remoteAccess>true</remoteAccess>
     <userName>admin</userName>
   </cliSettings>
   <features>
     <featureConfig/>
     <firewall>
       <version>3</version>
       <enabled>true</enabled>
       <defaultPolicy>
         <action>accept</action>
         <loggingEnabled>false</loggingEnabled>
       </defaultPolicy>
       <firewallRules>
         <firewallRule>
           <id>131074</id>
           <ruleTag>131074</ruleTag>
           <name>firewall</name>
           <ruleType>internal_high</ruleType>
           <source>
             <vnicGroupId>vse</vnicGroupId>
           </source>
           <action>accept</action>
           <enabled>true</enabled>
           <loggingEnabled>false</loggingEnabled>
           <description>firewall</description>
         </firewallRule>
         <firewallRule>
           <id>131073</id>
           <ruleTag>131073</ruleTag>
           <name>default rule for ingress traffic</name>
           <ruleType>default_policy</ruleType>
           <action>accept</action>
           <enabled>true</enabled>
           <loggingEnabled>false</loggingEnabled>
           <description>default rule for ingress traffic</description>
         </firewallRule>
       </firewallRules>
     </firewall>
     <dns>
       <version>0</version>
       <enabled>false</enabled>
       <cacheSize>16</cacheSize>
       <listeners>
         <ipAddress>any</ipAddress>
       </listeners>
       <logging>
         <enable>false</enable>
         <logLevel>info</logLevel>
       </logging>
     </dns>
     <sslvpnConfig>
       <version>0</version>
       <enabled>false</enabled>
       <logging>
         <enable>false</enable>
         <logLevel>info</logLevel>
       </logging>
       <advancedConfig>
         <enableCompression>false</enableCompression>
         <forceVirtualKeyboard>false</forceVirtualKeyboard>
         <randomizeVirtualkeys>false</randomizeVirtualkeys>
         <preventMultipleLogon>false</preventMultipleLogon>
         <clientNotification/>
         <enablePublicUrlAccess>false</enablePublicUrlAccess>
         <timeout>
           <forcedTimeout>0</forcedTimeout>
           <sessionIdleTimeout>10</sessionIdleTimeout>
         </timeout>
       </advancedConfig>
       <clientConfiguration>
         <autoReconnect>true</autoReconnect>
         <upgradeNotification>false</upgradeNotification>
       </clientConfiguration>
       <layoutConfiguration>
         <portalTitle>VMware</portalTitle>
         <companyName>VMware</companyName>
         <logoExtention>jpg</logoExtention>

<logoUri>/3.0/edges/edge-1/sslvpn/config/layout/images/portallogo</logoUri>
         <logoBackgroundColor>FFFFFF</logoBackgroundColor>
         <titleColor>996600</titleColor>
         <topFrameColor>000000</topFrameColor>
         <menuBarColor>999999</menuBarColor>
         <rowAlternativeColor>FFFFFF</rowAlternativeColor>
         <bodyColor>FFFFFF</bodyColor>
         <rowColor>F5F5F5</rowColor>
       </layoutConfiguration>
       <authenticationConfiguration>
         <passwordAuthentication>
           <authenticationTimeout>1</authenticationTimeout>
           <primaryAuthServers/>
           <secondaryAuthServer/>
         </passwordAuthentication>
       </authenticationConfiguration>
     </sslvpnConfig>
     <staticRouting>
       <version>7</version>
       <enabled>true</enabled>
       <defaultRoute>
         <vnic>0</vnic>
         <gatewayAddress>10.129.139.253</gatewayAddress>
         <mtu>1600</mtu>
       </defaultRoute>
       <staticRoutes/>
     </staticRouting>
     <highAvailability>
       <version>2</version>
       <enabled>false</enabled>
       <vnic>any</vnic>
       <declareDeadTime>6</declareDeadTime>
       <logging>
         <enable>false</enable>
         <logLevel>info</logLevel>
       </logging>
     </highAvailability>
     <syslog>
       <version>0</version>
       <enabled>true</enabled>
     </syslog>
     <featureConfig/>
     <loadBalancer>
       <version>0</version>
       <enabled>false</enabled>
       <accelerationEnabled>false</accelerationEnabled>
     </loadBalancer>
     <ipsec>
       <version>0</version>
       <enabled>false</enabled>
       <logging>
         <enable>false</enable>
         <logLevel>info</logLevel>
       </logging>
       <sites/>
       <global>
         <caCertificates/>
         <crlCertificates/>
       </global>
     </ipsec>
     <dhcp>
       <version>0</version>
       <enabled>false</enabled>
       <staticBindings/>
       <ipPools/>
       <logging>
         <enable>false</enable>
         <logLevel>info</logLevel>
       </logging>
     </dhcp>
     <nat>
       <version>4</version>
       <enabled>true</enabled>
       <natRules/>
     </nat>
     <featureConfig/>
   </features>
   <autoConfiguration>
     <enabled>true</enabled>
     <rulePriority>high</rulePriority>
   </autoConfiguration>
</edge>

There is a great deal more to using the vCloud Networking and Security REST API, but I hope this has given you a little insight into how you can use it more effectively.