Get Started with the Abiquo API part 2
- MS (Unlicensed)
Introduction
This tutorial continues on from Get Started with the Abiquo API.
In this tutorial, you will:
- Configure a VM by adding an IP address (NIC)
- Change the state of a VM
Requirements
This tutorial requires two VMs that are:
- not deployed
- do not have any IP addresses.
To use a VM from the last tutorial, in the UI undeploy it and delete its IP address.
Working with Deployed VMs
A deployed VM must always have a NIC. If you want to add another NIC, you may need to create another network to avoid trying to add two IP addresses in the same network.
To change the configuration of a deployed VM, if the VM doesn't have network hot-reconfigure, then you will need to shut it down first.
Get and modify an entity using the API
In general, to modify an entity using the API:
- Use a GET request to retrieve the entity's data object
- Modify the data object
- Use a PUT request to update the entity
Within a data object, links can define an entity's configuration.
When you edit the VM data object, be careful not to accidentally delete links because you could change the configuration, e.g. delete a disk from your VM!
Configure a VM to add a NIC using the UI
First add a NIC using the UI, in order to view the request made in the API.
We will add a network interface card (NIC) with an IP address in a private network to the first VM we created. In this case, we will assume that the VM is not deployed.
- Open the browser console to the Network tab and record actions
- Edit the VM and go to Network → Private → select network → drag an IP address into the NICs panel, and Save
Find the PUT request and copy it, or get the NIC link and VM data object
Obtain the link to the NIC
In the VM object, you will probably find the link to the NIC near the end of the VM links section.
{
"title":"privateip",
"rel":"nic0",
"type":"application/vnd.abiquo.privateip+json",
"href":"https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/privatenetworks/53/ips/326"
},
Get an IP address to add to the VM
To find a free IP address:
From the link to the NIC in the previous step, get only the networks IPs link
https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/privatenetworks/53/ips
Use a GET request to obtain the first 3 IP addresses in this network, with the parameter "limit=3".
curl --verbose 'href":"https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/privatenetworks/53/ips?limit=3' \ -H 'Accept: application/vnd.abiquo.privateips+json; version=5.2' \ -u user:password -k | jq .To only retrieve IPs that are available for use, you can use the query parameter "free=true".
The response has 3 IP addresses: the gateway and the IP addresses we created specifically for this exercise.
In the above example, the IP that is being used on a VM has a link to the VM.
The available IP that we will use has the identifier "335".
Create a NIC link
From the IP address object in the above step, get the link with a "rel" value of "self".
{
"title": "privateip",
"rel": "self",
"type": "application/vnd.abiquo.privateip+json",
"href": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/privatenetworks/53/ips/335"
},
To prepare it for the VM, change "self" to "nicX", where "X" represents the number of the new NIC in the VM. So if there are no NICs, add "nic0" as shown here.
{
"title": "privateip",
"rel": "nic0",
"type": "application/vnd.abiquo.privateip+json",
"href": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/privatenetworks/53/ips/335"
},
Add the NIC link to the VM object
Go the end of the links section and add the NIC from the previous step.
If this is the last link, add a comma before it, and remove any comma after it.
This is an example of the modified VM object, with the nic0 link at the end of the links section.
Update the VM to add the NIC
Create a PUT request to update the whole VM, including all the links.
To easily manage the large data object, we saved it to a file called "VMnic.json", and then used the @ notation to reference the file.
curl --verbose -X PUT 'https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920' \ -H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=5.2' \ -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=5.2' \ -u user:password \ -d @VMwithNIC.json -k
Send the PUT request.
If it is successful, the response status and message will be "204 No content" for an undeployed VM.
The example request is given here.
Check your VM in the UI
In the UI, when you select the VM, and open the control panel in the Network tab, the NIC should display.
Power actions on a VM
Before you begin this section, deploy a VM using the UI or the API.
To perform a power action (except for reset) on a VM using the API:
- Perform a GET request to obtain the VM object and find the VM state link
- Create a virtualmachinestate object
Send a PUT request to the VM state link
The VM state link is a link in the VM object with the "rel" attribute set to state. The "title" attribute contains the current state. You can send a PUT request of a virtualmachine state object to the link (in the "href" attribute) to change the power state of the VM.
{
"title": "ON",
"rel": "state",
"type": "application/vnd.abiquo.virtualmachinestate+json",
"href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/state"
},
Here are some examples of virtualmachinestate objects and notes about changing VM states
Hard power off
{"state": "OFF"}When you perform a power off via API, the response will include a link where you can monitor the progress of this operation. For an example of a hard power off, see https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#change-the-state-of-a-virtual-machine
Graceful shutdown
{"state": "OFF", "gracefulShutdown": true}To perform a graceful shutdown, your VM will need to have guest extensions installed on it. After an operation completes, you can view the status of the task by going to the link in the accepted request link of the response. In this case, the graceful shutdown was successful.
Power on
{"state": "ON"}Pause
{"state": "PAUSED"}Azure power off and deallocate
Azure has two power off states - powered off and deallocated.
To power off a VM in Azure via the Abiquo API, use the graceful shutdown
To deallocate a VM in Azure via the Abiquo API, use the hard power off
The deallocated VM will have a "deallocated" attribute that is set to "true".
To reset a VM using the API, use a POST request to the reset action link. If you are using a test environment, you may wish to add the --insecure option.
Delete a VM using the API
To delete a VM (or another entity), simply perform a DELETE request to the API link.
Note that there may be restrictions on what you can delete. For example, you cannot delete a virtual datacenter that contains virtual appliances.
If we delete the VM as shown here, it will be removed from the platform (and if it exists on the hypervisor, it will be destroyed). And the IP address will return to the virtual datacenter.
curl -X DELETE https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920 \ -H 'Accept: text/json,application/json;' \ -u user:password -k
Conclusion
Congratulations, you have now completed the Abiquo API tutorials. You can now continue to experiment using the API together with the UI. And you can find more examples in the API Howtos section.
And of course don't forget to check out the Java and Python libraries. Enjoy!
Related links
Copyright © 2006-2022, Abiquo Holdings SL. All rights reserved