I will do a write up on Intercloud Fabric (ICF) in the near future however as I was playing with the API I thought I would detail those first.
The ICF API works very much in the same way as the UCS Director API currently works (not surprising as the base code has the same origins).
I won’t go into the detail of why APIs are important or useful (covered in other blogs on this site) and I will jump straight into the detail. I would recommend that you review my post on accessing the UCS Director API.
While you could get the ICF solution up and running in your own environments it is not always practical or the quickest way to get exposure to the APIs. What the guys over at DevNet have done is create a sandbox environment to safely have a play.
All you need to do to get access is follow the instructions.
The documented topology is as follows;
However I find it is overly complex therefore my interpretation to make things a bit easier is as follows. The 1st topology shows how you access ICF and some of its key interactions with infrastructure and the 2nd highlights a logical topology.
More details on the labs can be found here (Intercloud Fabric Learning Lab). It will take about 30 minutes and the objective is;
- Understand the various North Bound REST API’s of Intercloud Fabric for Business and do the basic operations on the virtual machines of the cloud.
- This learning lab only talks about the USER Api’s of the ICFB. The Admin level API’s like Creation of IcfClouds, Creation of Templates, Creation of Catalogs are not covered as part of this lab
- The User API’s covered in this lab are around the operations of deploying a VM in Cloud, Migrating the VM’s from Enterprise to Cloud, Migrating the VM’s from Cloud to Enterprise, and managing the life-cycle of the VM’s in the cloud.
The 1st step is to obtain the key that you will use to access the API. This can be done following the instructions on the UCSD blog post or use a API to obtain it. The API used to achieve this is ‘getRESTKey’;
/app/api/rest?formatType=json&opName=getRESTKey&user=username&password=password
As an example the full call for the ICF sandbox would be;
https://sandboxicf.cisco.com/app/api/rest?formatType=json&opName=getRESTKey&user=robedwa&password=letmein
The expected response would be something like this (and no that’s not my real key!!);
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=F57F94A4A475BC7A0D58475381AF3DC2; Path=/app/; Secure
Content-Type: application/json;charset=ISO-8859-1
Transfer-Encoding: chunked
Date: Thu, 24 Sep 2015 13:10:52 GMT
Connection: close
"6B75494C86E1CDA4AA390A98023912"
The 2nd Step is to test against an API to confirm all the authentication works as expected (i.e. you get a response back). The easiest API is ‘userAPIGetMyLoginProfile’;
/app/api/rest?formatType=json&opName=userAPIGetMyLoginProfile
This should pull back the details about the user that you are logged on with;
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: max-age=0,must-revalidate
Expires: -1
Content-Type: application/json;charset=UTF-8
Content-Length: 240
Date: Thu, 24 Sep 2015 13:12:45 GMT
Connection: close
{ "serviceResult":
{
"userId":"robedwa",
"firstName":"Rob",
"lastName":"Edwards",
"email":"robedwa@cisco.com",
"groupName":"Cisco",
"groupId":2,"role":"Regular"
},
"serviceError":null,
"serviceName":"InfraMgr",
"opName":"userAPIGetMyLoginProfile" }
Now we know we have access to the Sandbox API what can we do that would be useful?
A full description of them all can be found here.
As of version 2.2.1 the following key categories exist (I know lots of work is going on in the background to increase the API functionality so this list will grow over time);
- Admin Operations for Networks
- Admin Operations for Users
- Catalog Operations
- Cloud Operations
- Network Operations
- Service Request Operations
- User Operations
- VDC Operations
- VM Operations
Something Useful
Initially the most useful things to do would be;
- Alter the state of a VM
- Deploy a new VM
- Migrate a VM
In this post I will only show powering a VM off. I will show other examples another day.
Alter the state of VM
A useful operational function is to power VM’s on and off, this can be done via the API. The 1st thing you need to do is identify the ‘vmid’ of the VM you want to manipulate, this can be done by using the ‘Intercloud:userAPIGetAllVms’ call (you could always use the GUI but that kind of defeats the object). This will pull back all the VMs that you have access to.
{
"serviceResult": {
"rows": [
{
"Cloud": "prov2",
"VM_ID": 173,
"VM_Label": "",
"Instance_ID": "sandbox-vm-95",
"Provider_IP": "N/A",
"Enterprise_IP": "10.10.20.172 ",
"Domain_Name": "cisco.com",
"Image_Id": "",
"Power_State": "ON",
"vDC": "CiscoCloudVDC",
"Category": "App Category 0",
"Tunnel_Status": "up",
"OS": "RHEL 6.2 (64bit)",
"Description": " "
},
{
"Cloud": "prov2",
"VM_ID": 207,
"VM_Label": "",
"Instance_ID": "EILPC7ICF",
"Provider_IP": "N/A",
"Enterprise_IP": "10.10.20.189 ",
"Domain_Name": "cisco.com",
"Image_Id": "",
"Power_State": "ON",
"vDC": "CiscoCloudVDC",
"Category": "App Category 0",
"Tunnel_Status": "up",
"OS": "RHEL 6.2 (64bit)",
"Description": " "
}
],
"columnMetaData": null,
"reportParams": {}
},
"serviceError": null,
"serviceName": "InfraMgr",
"opName": "Intercloud:userAPIGetAllVms"
}
The VM that we will power off is ‘sandbox-vm-95’ which has a ‘vmid’ of ‘173’. Now that we know this we call make a call to power-off using ‘Intercloud:userAPIVmPowerOff’;
/app/api/rest?formatType=json&opName=Intercloud:userAPIVmPowerOff&opData={param0='173'}
Which gives us a result as follows (if it works anyway);
{
"serviceResult": 0,
"serviceError": null,
"serviceName": "InfraMgr",
"opName": "Intercloud:userAPIVmPowerOff"
}
You know it has worked becuase the “serviceError” value is null.
To check if the power status has changed you could either use the same call as before to list all the VMs or use ‘Intercloud:userAPIGetVMSummary’;
/app/api/rest?formatType=json&opName=Intercloud:userAPIGetVMSummary&opData={param0='173'}
{
"serviceResult": {
"rows": [
{
"Provider_Account": "prov2",
"VM_ID": 173,
"IcfCloud": "CSCOCloudService",
"VM_Label": "",
"Instance_ID": "sandbox-vm-95",
"Provider_IP": "N/A",
"Enterprise_IP": "",
"DNS1": "",
"DNS2": "",
"Domain_Name": "",
"Image_Id": "",
"Power_State": "OFF",
"vDC": "CiscoCloudVDC",
"Category": "App Category 1",
"Tunnel_Status": "failed",
"OS": "RHEL 6.2 (64bit)",
"Description": " "
}
],
"columnMetaData": null,
"reportParams": {}
},
"serviceError": null,
"serviceName": "InfraMgr",
"opName": "Intercloud:userAPIGetVMSummary"
}
I hope you have had fun with your first steps into ICF API. I will write more blog entries with more detailed example in the coming months.