Capture a VM via API

Author: Sergi Castro

You can capture a virtual machine using the API and once you get started, it's not such a daunting task as it might first seem! And as always, if you get stuck, you can always open your browser console and take a look at how the Abiquo UI does it!

Before you get started, make sure you are familiar with the capture process in the UI. Also you will need to prepare a suitable environment, with a virtual datacenter and a matching network for the VM. See Import and capture virtual machines. Note that the Abiquo UI enables you to create a virtual appliance or a network address as part of the capture process but these steps are not included in this tutorial.

To work through this tutorial you can use a cloud admin account with basic authentication, but this is not recommended in a production environment, see Authentication.

To capture a VM using the API:

Retrieve the virtual appliance that the VM will be captured into
Retrieve the VM with resources from the hypervisor in Abiquo
Retrieve the network addresses from the platform and add them to the VM object
Send a POST request with the VM object to virtual machines URL of the virtual appliance

Retrieve the virtual appliance

The first step is to List virtual appliances in your virtual datacenter and locate the virtual appliance where you will add the VM.

If you don't have the link to virtual appliances, first List virtual datacenters, and look for the "href" value of the virtualappliances link

curl -X GET https://example.com/api/cloud/virtualdatacenters/2/virtualappliances \
     -H 'Accept:application/vnd.abiquo.virtualappliances+json; version=4.2' \
     -u user:password --verbose

From the virtual appliance objects, look for your virtual appliance, and find the virtualmachines link.

{
    "links": [
        {
            "rel": "first",
            "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances?limit=25&by=name&asc=true"
        },
        {
            "rel": "last",
            "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances?startwith=0&limit=25&by=name&asc=true"
        }
    ],
    "collection": [
        {
            "id": 2,
            "error": 0,
            "highDisponibility": 0,
            "name": "vapp_vdc_tioco_02",
            "publicApp": 0,
            "state": "EMPTY",
            "notAllocatedVirtualMachines": 0,
            "onVirtualMachines": 0,
            "offVirtualMachines": 0,
            "pausedVirtualMachines": 0,
            "allocatedVirtualMachines": 0,
            "configuredVirtualMachines": 0,
            "unknownVirtualMachines": 0,
            "lockedVirtualMachines": 0,
            "links": [
                {
                    "title": "vapp_vdc_tioco_02",
                    "rel": "edit",
                    "type": "application/vnd.abiquo.virtualappliance+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2"
                },
                {
                    "title": "bcdc_tioco_02",
                    "rel": "virtualdatacenter",
                    "type": "application/vnd.abiquo.virtualdatacenter+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2"
                },
                {
                    "title": "Tioco",
                    "rel": "enterprise",
                    "type": "application/vnd.abiquo.enterprise+json",
                    "href": "https://example.com:443/api/admin/enterprises/2"
                },
                {
                    "title": "virtual machines",
                    "rel": "virtualmachines",
                    "type": "application/vnd.abiquo.virtualmachines+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines"
                },
                {
                    "title": "virtual appliances state",
                    "rel": "state",
                    "type": "application/vnd.abiquo.virtualappliancestate+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/state"
                },
                {
                    "title": "undeploy",
                    "rel": "undeploy",
                    "type": "application/vnd.abiquo.acceptedrequest+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/action/undeploy"
                },
                {
                    "title": "deploy",
                    "rel": "deploy",
                    "type": "application/vnd.abiquo.acceptedrequest+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/action/deploy"
                },
                {
                    "title": "price",
                    "rel": "price",
                    "type": "text/plain",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/action/price"
                },
                {
                    "title": "layers",
                    "rel": "layers",
                    "type": "application/vnd.abiquo.layers+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/layers"
                },
                {
                    "title": "alerts",
                    "rel": "alerts",
                    "type": "application/vnd.abiquo.alerts+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/alerts"
                },
                {
                    "title": "spec",
                    "rel": "spec",
                    "type": "application/vnd.abiquo.virtualappliancespec+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/action/spec"
                },
                {
                    "title": "tasks",
                    "rel": "tasks",
                    "type": "application/vnd.abiquo.tasks+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/tasks"
                },
                {
                    "title": "scalinggroups",
                    "rel": "scalinggroups",
                    "type": "application/vnd.abiquo.scalinggroups+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/scalinggroups"
                },
                {
                    "title": "metricsmetadata",
                    "rel": "metricsmetadata",
                    "type": "application/vnd.abiquo.metricsmetadata+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/metrics"
                },
                {
                    "title": "collectd",
                    "rel": "collectd",
                    "type": "application/json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/metrics/collectd"
                }
            ]
        }
    ],
    "totalSize": 1
}

To create the VM in the platform, we will send a POST request to this link.

                {
                    "title": "virtual machines",
                    "rel": "virtualmachines",
                    "type": "application/vnd.abiquo.virtualmachines+json",
                    "href": "https://example.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines"
                },

Now let's create the VM data object that we will send with the post request.

Retrieve the VM with resources from the hypervisor

For this step, we will need to know how to locate and identify the VM in infrastructure. One easy way to do this is to open the UI console at the Network tab, and select the machine that the VM is running on. To obtain data about the infrastructure, the UI will be making GET requests to links like the following one.

To retrieve all the VMs that are running on this machine but are not registered in Abiquo, use the query parameter "sync" with a value of true.

Then search for your VM in the response and obtain the "virtualmachine" link

So our VM with the name starting with "ABQ_14c4aa8c" is number 265 in infrastructure, and its link is as follows.

Now retrieve the "virtualmachineflat" data object. This is a VM with all resources inline, including the network interface cards (NICs). Here we use the sync parameter with a value of true to obtain the latest information from the hypervisor.

This is our base virtualmachine flat object and as you can see there is no IP address for the NIC, so we will add that next.

Retrieve network details and IP addresses

In this tutorial we are going to work with an external network. This is the most flexible network type, because you can use public or private addresses and each external network is only available to the enterprise tenant that it belongs to. If you want to use a public network, you will need to purchase a public IP address for your virtual datacenter before you can add it to the VM.

External networks belong to a single enterprise, so you can open the browser console to the Networks tab and go to the Users view in the UI to find your enterprise ID number. When you select the enterprise, you should see a request to a link like the following one.

Now use the enterprises link to get the enterprise data object.

From the enterprise, get the link to the enterprise limits.

Then perform a GET request to retrieve the limits. There is one limit for each datacenter or public cloud region that your enterrpise is allowed to use. This is because in the API, to allow an enterprise to use a datacenter, you create a datacenter limit for the enterprise.

So in this example, the enteprise is allowed to use a private cloud datacenter, called "BCDC" and a public cloud region, called "aws".

Identify the limit for the datacenter you accessed in the previous steps, for example, here is the link identifying the datacenter within the limit. This limit has an ID with a value of "5".

For this limit, select the link to its external networks.

Then perform a get request to retrieve the external networks.

From the external networks object, find the link to IPs.

And perform a GET request to retrieve the IPs.

Select the IP address that you would like to add to the VM.

Create the virtualmachineflat data object

Now go back and get the virtualmachineflat object that you retrieved from the hypervisor. Find the edit link (the "rel" value will be edit and copy it to create two links. Change the "rel" value of the first link to "virtualmachine" and the second one to "imported".

In the NICs section of the VM, add links to the VLAN. For example, for the external IP address, obtain the link with a "rel" value of "externalnetwork".

And change the value of the "rel" attribute to "vlan"

And note the IP address you would like to add

Edit the VM NIC(s) and add the link(s) to the "nics" - "collection" - "links" section for each NIC and the IP to the main section of each NIC after the tag value (don't forget the comma).

Finally your data object should be similar to the one in the following example.

Capture the virtual machine

To capture the VM machine, send a POST request to the virtualmachines URL of the virtual appliance that will hold the captured VM. Use the virtualmachineflat data transfer object that you created in the previous step as the data object.

The virtualmachineflat object that you should send in the requestpayload.json file should be similar to the following example.

If the request is successful, a 201 code should be returned, as well as the virtualmachineflat data object that was created.

Now Abiquo should display your VM as a managed VM and you should be able to find it in the virtual datacenter.