Abiquo 5.1
Introduction
This tutorial describes how to create and deploy a basic VM with the Abiquo cloud platform. It also describes how to retrieve a single entity and a group of entities from the cloud platform.
This document introduces the API from the perspective of the Abiquo user interface (UI).
- All Abiquo platform functionality as seen in the UI is also available through the Abiquo REST API
- The UI runs as a client of the API, using the API to perform actions on the platform
- Abiquo recommends that before you start working with the API, you should use the Abiquo UI to learn about the features and functionality of the platform. Or at least do the Abiquo Quick Tutorial.
You can apply the basic general flow from this document to other Abiquo entities.
- Replace the URLs in the examples with the URL for your own environment
- We provide example responses in case you are reading this without access to the platform
- Due to release timing, some of the requests examples may be run using different versions and media types may vary slightly
- For guides to specific use cases, see the API How Tos.
- For API reference documentation, see https://wiki.abiquo.com/api/latest
Prerequisites
To follow along with this tutorial, we recommend that you use a Firefox or Chrome browser. The screenshots and instructions here are from Chrome.
You will need a working Abiquo platform with:
- Cloud infrastructure including a datacenter, rack, and hypervisor host
- A virtual datacenter with a virtual appliance inside
- An Abiquo private network in the virtual datacenter with two IP addresses added to it.
To create the prerequisite entities, you can do the following:
- If your test environment already has infrastructure, work through the Abiquo quick walkthrough of private cloud
- If your test environment does not have infrastructure, work through the Abiquo Quick Tutorial
- To add an extra IP address to a private network, follow the instructions in Create IP addresses in private networks.
Authentication
You will need to authenticate with your own credentials as appropriate in your environment. For a complete guide, see Authentication. For this tutorial you could use:
- Token authentication: with the token returned in the X-Abiquo-Token header in the format "Authentication: Token XXXXXXXX", replacing XXXXXXXX with the token
- To obtain this token, you can send a GET request with basic authentication to the login resource of your API, for example, https://abiquo.example.com/api/login
- To obtain this token, you can send a GET request with basic authentication to the login resource of your API, for example, https://abiquo.example.com/api/login
- Basic authentication: in a securely isolated test environment, you could use your user and password, in the format "-u user:password".
- To use basic authentication, you can add the insecure "-k" option to the request.
- To use basic authentication, you can add the insecure "-k" option to the request.
- OAuth authentication. See Authentication
Create an entity with the UI and obtain the entity data object
First, create a VM with the UI.
- Open your connection to Abiquo and open your browser console to the Network tab
- Check that the browser is recording actions, e.g. click the red record button
- Create a VM in the UI, which will issue a POST request to the API
- In the browser console, find the POST request
Screenshot from Chrome: the POST request to create a VM is highlighted in blue
In Chrome, to display the Method column to easily identify the POST request, right-click on the header row to display the header options list, then select "Method"
To create a VM, the Abiquo UI makes the POST request to the virtualmachines link of the virtual appliance. This link contains the IDs of the virtual datacenter and virtual appliance.
https://nardo40.bcn.abiquo.com/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines
In this case, the ID values are 2486 and 2990.
To copy a request directly from the UI, right-click on the request URL and select Copy as cURL. Note that you may have to delete UI cache details before you run the cURL.
In your browser console, select the POST request that created the VM and go to the Headers tab.
The following screenshot highlights the the API Location (in the Response headers) and Request Payload of a VM.
The Request Payload is the VM object that the UI sent to create the VM. It is very simple with just a friendly name label (which by default is the VM template name), a template link, plus the default option to enable remote access to the VM. This is one of the simplest data objects that you can use to create a VM.
Click "view source", and copy the request payload. If you format it with a JSON formatter, it should look similar to the following example.
{
"label":"yVM_Abiquo_enterprise",
"links":[
{
"title":"yVM_Abiquo_enterprise",
"rel":"virtualmachinetemplate",
"type":"application/vnd.abiquo.virtualmachinetemplate+json",
"href":"https://nardo40.bcn.abiquo.com:443/api/admin/enterprises/336/datacenterrepositories/1/virtualmachinetemplates/2"
}
],
"vdrpEnabled":true
}
The Location link shows the VM location in the API, which is the URL of the VM, as shown here.
https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19453
The last element of the URL is the ID of the VM, which has a value of 19453. We can use the above link to retrieve this VM.
To retrieve all the VMs in the virtual appliance, you can use the link to virtualmachines, without referring to any specific VM.
https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/
These URLs are the API locations of the VMs.
Create an entity using the API
We are now going to create a new VM with a different friendly-name label.
To create the new VM, use the link to virtualmachines from the previous step, and send a POST request with the modified data entity. For example, we could change "yvm_Abiquo_enterprise" to "yVM_New".
Here we have an example of an API request to create a VM:
curl --verbose -X POST 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines' \
-H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=5.0' \
-H 'Accept: application/vnd.abiquo.virtualmachine+json;version=5.0' \
-u user:password \
-d '{"label":"yVM_New","links":[{"title":"yVM_Abiquo_enterprise","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json","href":"https://nardo40.bcn.abiquo.com:443/api/admin/enterprises/336/datacenterrepositories/1/virtualmachinetemplates/2"}],"vdrpEnabled":true}'
We are working with JSON objects and we specify them with request content headers that start with "-H". The Content-Type header refers to the VM object we are sending. And the Accept header refers to the API response we will receive.
You can also use XML instead of JSON with the Abiquo API and to do this, you would use "+xml" instead of "+json" in all the headers. Abiquo recommends JSON format. There may be some slight differences between the formats, so always retrieve an object in the format you are working with and modify it to ensure the correct data structure.
We specify the virtualmachine media type and the version number.
To control compatibility always specify the version number in your requests because if you do not specify a version, the API will always return the latest one, meaning that after an upgrade to the platform your code may cease to work as intended.
If the API creates the machine successfully, the response body contains the VM object.
From the VM object, note the link with a "rel" value of "edit". Also note that in the example the VM has an "id" of 19454.
...
{
"links":[
{
"title":"ABQ_2fb11009-8157-4d61-915d-40fa45f440ac",
"rel":"edit",
"type":"application/vnd.abiquo.virtualmachine+json",
"href":"https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454"
},
...
Also note the deploy link.
...
{
"title":"virtual machine deploy",
"rel":"deploy",
"type":"application/vnd.abiquo.acceptedrequest+json",
"href":"https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/action/deploy"
},
...
Display the VM in the UI
When you've created the VM, return to the UI and you should be able to find the new VM!
Retrieve an entity using the API
To retrieve the details of the VM you just created, perform a GET request to the edit link of the VM.
curl --verbose 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454' \ -H 'Accept: application/vnd.abiquo.virtualmachine+json; version=5.0' \ -u user:password -k
The result of this query is a VM data object in JSON format. The expanding section below contains the full request. On a Linux system, to format the response JSON body inline, you could try piping it to jq (with "| jq ."))
Retrieve a group of entities with the API
To retrieve the collection of VMs in the virtual appliance, send a GET request to the virtualmachines link.
https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines
The response contains metadata about the size of the collection and the default paging links. The following example shows the collection information but we removed the VM links to reduce the size of the example.
Deploy your VM
To deploy the VM you created, send a POST request to the deploy link of the VM.
curl --verbose -X POST 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/action/deploy' \ -u user:password -k
The API will respond with an accepted request object and a link that you can use to check the progress of the deploy.
{ "message":"You can keep track of the progress in the link",
"links":[ {
"title":"status",
"rel":"status",
"type":"application/vnd.abiquo.task+json",
"href":"https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/tasks/a975de9c-8558-4487-8f43-153df2d3cb55"
}
]
}
Of course, you can also switch back to the UI and watch the VM deploy!
Conclusion
Congratulations, you have created a VM and deployed a VM with the API. And you also know how to retrieve an entity and a collection of entities, and you can apply this method to any entity, using the entity link and a GET request.
To work through how to modify and delete entities, see Get Started with the Abiquo API part 2.
Related links
Overview
Content Tools
