Sunday, August 16, 2015

REST while using CURL for vRA

DevOps needs REST :-)

In DevOps world users are mostly using the command line and APIs to do almost all of their work. So for the following example you’re going to need curl as the usage was done keeping in mind the universal tool and just not focusing other available large number of REST client or such, and as this is inside a Lab encryption is not needed bu you will need the version that supports SSL for end-to-end encryption !  

Use of jq, ( a new parsing tool for JSON) is used here, which does everything thro' command-line, and being portable (zero install) and open source, it runs on Windows and Linux both, so all of the developers out there can use it irrespective of the platform they’re using. I saved both utilities in C:\curl, and put my .bat file and .json files there too.  You can decide the best way to do that, Token is required.

So what is Token or a Bearer Token?  Putting it simply, its an authentication token.  First thing you’ll need is to get a bearer token and parse it.  You’ll need a .json file with your authentication details; the basic format is 

{“username”:”domain\\myusername“, “password”:”mypassword“, “tenant”:”vsphere.local”}.  

Fill in your username, password, and if you’re not using the default tenant, then save it to C:\curl\hellotoken.json and you’re good to go. 

Use the following curl command to submit your request:

curl –insecure -H “Accept: application/json” -H “Content-Type: 
application/json” –data @hellotoken.json https://vra-fqdn/identity/api/tokens > identity.json

Please note I used –insecure because my vRA environment is still using self-signed SSL certs.  If you have actual SSL certs that will validate, please drop the –insecure option.  This command will drop a .json file named identity.json in the current folder (c:\curl if you’ve been following along), the file looks a little like this:


So it has an expiry, an id, and a tenant. Bearer tokens are good for 24 hours, and what's not obvious is a user can only have one at a time; if you ask for a new bearer token, that invalidates all previous bearer token/s.  These two facts means, it’s very difficult to manually get and use a bearer token. What we want to do is extract that ID in such a way that we can automatically use it in subsequent curl calls.

For this I will be using jq:

jq .id -r < identity.json > bearer.txtset /p btoken=

Let’s look into what it consists of:

jq .id -r parse out the id field from the json.  Print it to stdout in raw mode (i.e. no surrounding quotes or symbols)

< identity.json use the previously generated identity.json file as input to jq

> bearer.txt output the parsed id field to a file bearer.txt

use bearer.txt as the input file for the following command

set /p btoken= set the environment variable btoken to the input.  The /p normally means to prompt for the environment variable, but in this case since we provided a stdin pipe, the contents of bearer.txt will be used instead of prompting the user

) Close the section using bearer.txt as input. Yes I know it is required to do it here. 

To use the bearer token add the following HTTP Header to all future curl calls:

-H “Authorization: Bearer %btoken%”

Machine Request

Now you can request the catalog item you want from the vRA console and note the request ID. After the request has completed, you can use curl to look at the request with the following command:

curl –insecure -H “Accept: application/json” -H “Authorization: Bearer %btoken%” https://vra-fqdn/catalog-service/api/consumer/resources/?$filter=request/requestNumber+eq+myReqNumber > myreqOutput.json

This will create a file myreqOutput.json with details of your request.  The item you care most about is the catalog ID which you will be able to find at  Note that ID, then request the entitled catalog item with the following:

curl –insecure -H “Accept: application/json” -H “Authorization: Bearer %btoken%”https://vra-fqdn/catalog-service/api/consumer/entitledCatalogItems/?$filter=id+eq+&#8217;catalogItemId‘ > catalogItem.json

This time, note the provider binding at .content.0.catalogItem.providerBinding.bindingId.  Also note the tenant ID specified here.

Now you have the information you need to format the machineRequest.json file:

“@type”: “CatalogItemRequest”,
“catalogItemRef”: {
“id”: “catalogItemId”
“organization”: {
“tenantRef”: “vsphere.local”,
“subtenantRef”: “TenantId”
“requestedFor”: “myUserName@domain“,
“state”: “SUBMITTED”,
“requestNumber”: 0,
“requestData”: {
“entries”: [{
“key”: “provider-blueprintId”,
“value”: {
“type”: “string”,
“value”: “Provider-binding”
“key”: “provider-VirtualMachine.Network0.NetworkProfileName”,
“value”: {
“type”: “string”,
“value”: “Network Profile Name”
“key”: “provider-Variable1″,
“value”: {
“type”: “string”,
“value”: “value”

Note the key: provider-name section above; this is how you specify any custom properties for the blueprint, I provided a couple samples above but what you put here will really depend on the blueprint configuration.  Basically just add provider- to the start of any custom property (or even VM property, see provider-VirtualMachine.Network0.NetworkProfileName above) to submit it with your request… so the next step is to…

Submit a Request

The curl command to submit a request is:

curl -X POST –insecure -H “Content-Type: application/json” -H “Authorization: Bearer %btoken%” https://vra-fqdn/catalog-service/api/consumer/requests –data @machineRequest.json

And now you can see under Infrastructure --> Recent Events or under Requests that new VM getting deployed in vRA. You can also verify under vSphere client session that the VM is getting cloned and deployed.

Hope you find this useful.

Please share and care.

No comments:

Post a Comment