Introduction
This tutorial continues on from Get Started with the Abiquo API!
Modify an entity through the API
Because the VM entity is a special case, we are going to look at two types of modifications: configuring a VM and changing the state of a VM.
But for most entities you can simply retrieve a data object with a GET request, modify the data object, and then perform a PUT request.
Links do more than just take you to related objects–they also define the configuration of a VM.
When you edit the data object, take care not to accidentally remove any links because you could accidentally remove a disk or a NIC or perform some other unintended action!
To add a NIC to the VM, we are going to first perform the steps using the UI, in order to obtain information about the data object.
Configure the VM to add a NIC through the UI
Now 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 at the Network tab and record actions
- Edit the VM, go to Network → Private → select network → drag and drop an IP, and Save the VM
- Examine the PUT request and look for the link to the NIC and expand it. It will probably be at the end of the links section.
Deployed VMs
If your VM is deployed, then it will already have a NIC. To work with a deployed VM, you may need to create another private network, because by default, you may not be able to add two NICs in the same private 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.
At the top of the Request Payload section, click "view source". Copy the source, format it, and select the link to the NIC and copy it. After formatting, it will look something like this.
{
"title":"privateip",
"rel":"nic0",
"type":"application/vnd.abiquo.privateip+json",
"href":"https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips/16"
},
We will use this type of NIC link in the next step.
Add a NIC to the VM through the API
Now we are going to add a NIC to the second VM. To do this, we need to identify the second private IP that we created for this tutorial.
So we perform a GET request to retrieve all the IP addresses on the same network used above.
We will use the part of the URL that refers to the IPs of the private network, which just means removing the identifier of the IP from the IP link.
https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips
You could perform a curl request from the command line, for example.
curl --verbose 'https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips' \
-H 'Accept: application/vnd.abiquo.privateips+json; version=4.6' \
-u admin:xabiquo -k | jq .
In our response body, there are 3 IP addresses: the gateway and two 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.
Hint: to only retrieve IPs that are available for use, you can use the request parameter "free=true", as follows.
https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips?free=true
The available IP that we will use has the identifier "17".
And the link we need from this IP object is the link with a "rel" value of "self".
{
"href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips/17",
"type": "application/vnd.abiquo.privateip+json",
"rel": "self",
"title": "privateip"
},
To add it to the VM, we just need to change "self" to "nicX", where "X" represents the number of the new NIC in the VM. So if there are no NICs on the machine, we will add "nic0" as shown here.
{
"href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips/17",
"type": "application/vnd.abiquo.privateip+json",
"rel": "nic0",
"title": "privateip"
},
Remember that when you add this NIC to the end of the links section, you must add a comma first, after the previous item. And as this will be the last link, remember to remove the comma after it.
So here is an example of the request body that would be used to update our second VM, with the nic0 link at the end of the links section.
Send a PUT request to update the whole VM, including all the links. As the VM object is quite large, instead of adding it to the -d option between single quotation marks, you can save it to a file, for example, "VMnic.json", and then use the @ notation to reference the file in the cURL.
curl --verbose -X PUT 'https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8' \
-H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.6' \
-H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=4.6' \
-u admin:xabiquo \
-d @VMnic.json -k
The full text of the response object is shown in the expanding section below.
If the request is successful, the response status and message will be "204 No content".
In the UI, when you select the VM, and open the control panel in the Network tab, the NIC should display.
This expanding section contains the full request with the VM object embedded in it.
Power actions on a VM
Before you begin this section, deploy a VM through the user interface.
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.
curl -X PUT 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/state' \ -k --verbose \ -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=5.0' \ -H 'Content-Type: application/vnd.abiquo.virtualmachinestate+json; version=5.0' \ -d '{"state": "OFF", "gracefulShutdown": true}' \ -u user:password | jq .{ "taskId": "d62be542-f34c-4fed-b9f8-6443f2db4cc1", "userId": "10", "type": "SHUTDOWN", "ownerId": "19454", "state": "FINISHED_SUCCESSFULLY", "creationTimestamp": 1596040226, "timestamp": 1596040226, "jobs": { "links": [], "collection": [ { "id": "d62be542-f34c-4fed-b9f8-6443f2db4cc1.2cd94a0c-179d-4506-a71d-fabaf29a4d43", "parentTaskId": "d62be542-f34c-4fed-b9f8-6443f2db4cc1", "type": "SHUTDOWN", "description": "Shutdown task's shutdown on virtual machine with id 19454", "state": "DONE", "rollbackState": "UNKNOWN", "creationTimestamp": 1596040226, "timestamp": 1596040226, "links": [] } ] }, "links": [ { "rel": "self", "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/tasks/d62be542-f34c-4fed-b9f8-6443f2db4cc1" }, { "rel": "parent", "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/tasks" }, { "rel": "result", "type": "application/vnd.abiquo.virtualmachine+json", "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454" }, { "title": "user", "rel": "user", "type": "application/vnd.abiquo.user+json", "href": "https://nardo40.bcn.abiquo.com:443/api/admin/enterprises/336/users/10" }, { "title": "ABQ_2fb11009-8157-4d61-915d-40fa45f440ac", "rel": "virtualmachine", "type": "application/vnd.abiquo.virtualmachine+json", "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454" } ] }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.
cURL:
curl -X POST 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/action/reset' \ -k --verbose \ -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=5.0' \ -u user:password | jq .
Success status code: 202
Request payload:
--none--
Response payload:
{
"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/edec6cf1-8874-451d-a4c0-57f4c24da371"
}
]
}
Delete an entity through the API
To delete an entity, simply perform a DELETE request to the API link. But remember 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 using the following query, it will be removed from the platform (and if it exists on the hypervisor, it will be destroyed). The NIC we added will be detached and released back into the virtual datacenter.
curl -X DELETE https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8 \
-H 'Accept: text/json,application/json;' \
-u user:password
Related links: