Versions Compared

Old Version 22

changes.mady.by.user MS

Saved on

compared with

New Version 23

changes.mady.by.user MS

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Introduction

This tutorial continues on from Get started with the Abiquo API.

In this tutorial, you will :use the Abiquo API to do the following.

  1. Configure a VM by adding an IP address (NIC)

...

  2. Delete a VM

There is also a link to another section that describes how to power cycle a VM.

...


Requirements

This tutorial requires two VMs that are:

...

  1. Not deployed

  2. Have no IP addresses (NICs)

You will also need 2 free IP addresses in private networks in the virtual datacenter with the VMs.

To use a VM VMs from the last previous tutorial, in the UI undeploy it and delete its IP address. 

Tip

...

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 Abiquo API:, do these steps.

  1. Use a GET request to retrieve the entity's data object

  2. Modify the data object

  3. Use a PUT request to update the entity

Note

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 such as by deleting a disk from your VM!


...


Configure a VM to add a NIC using the UI

First add a NIC perform the action using the Abiquo UI, in order to view the API request made in that the APIUI makes.

We will To the first VM, which is not deployed, 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.

  1. Open the browser console to the Network tab and record actions

  2. Edit the VM and go to Network → Private

...

  2. Select the network and drag an IP address into the NICs panel, and Save the VM

  3. Find the PUT request and copy it, or get the

...

  1. 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 (with a rel attribute with a value of nic1 near the end of the VM links section.

Code Block
      {
         "title":"privateip",
         "rel":"nic0nic1",
         "type":"application/vnd.abiquo.privateip+json",
         "href":"https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/privatenetworks/539/ips/32611"
      },


...


Get an IP address to add to the VM

To find a free IP address:

  1. From the link to the NIC in the previous step, get only the networks IPs link

    Code Block
    https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips

  2. Use a GET request to obtain the first 3 IP addresses in this network,

...

  1. and add the query parameter

...

  1. limit

...

  1. with a value of 3  

    Code Block
    curl --verbose '

...

  1. https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips?limit=3' \
     -H 'Accept: application/vnd.abiquo.privateips+json; version=

...

  1. 6.

...

  1. 1' \
	 -u user:password -k | jq .

    (tick) To

...

  1. retrieve IPs that are available for use only,

...

  1. use the query parameter

...

  1. free

...

  1. with a value of true

  2. The response has 3 IP addresses: the gateway and the IP addresses we created specifically for this exercise.

    Code Block
    √

...

  1. ~ % curl --verbose -k 'https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips?limit=3' \

...

  1. -H 'Accept: application/vnd.abiquo.privateips+json; version=

...

  1. 6.

...

  1. 1' \

...

  1. 
     -u user:password

...

  1. | jq .
     
> GET /api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips?limit=3 HTTP/1.1
> Host:

...

  1. mjsabiquo.

...

  1. lab.abiquo.com
> Authorization: Basic

...

  1. XXXXXX
> User-Agent: curl/7.

...

  1. 88.1
> Accept: application/vnd.abiquo.privateips+json; version=

...

  1. 6.

...

  1. 1
> 
< HTTP/1.1 200 200
< Date:

...

  1. Wed,

...

  1. 07

...

  1. Jun

...

  1. 2023

...

  1. 13:

...

  1. 54:

...

  1. 46 GMT
< Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips
< Set-Cookie: ABQSESSIONID=

...

  1. 5848743475559326145; Max-Age=1800; Expires=

...

  1. Wed,

...

  1. 07-

...

  1. Jun-

...

  1. 2023

...

  1. 14:

...

  1. 24:

...

  1. 46 GMT; Path=/; Secure; HttpOnly; SameSite=strict
< X-Abiquo-TracerContext:

...

  1. c2b1df27-

...

  1. 14c5-

...

  1. 4e28-

...

  1. 917d-

...

  1. f793d7dc3a71
< X-Abiquo-Token:

...

  1. XXXXXX
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
< Content-Type: application/vnd.abiquo.privateips+json; version=

...

  1. 6.

...

  1. 1
< Transfer-Encoding: chunked
< 

{
  "totalSize":

...

  1. 4,
  "links": [
    {
      "rel": "first",
      "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips?limit=3&by=ip&asc=true"
    },
    {
      "rel": "next",
      "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips?startwith=3&limit=3&by=ip&asc=true"
    },
    {
      "rel": "last",
      "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips?startwith=

...

  1. 1&limit=3&by=ip&asc=true"
    }
  ],
  "collection": [
    {
      "id":

...

  1. 8,
      "ip": "192.168.0.1",
      "mac": "00:50:56:

...

  1. 2F:

...

  1. D8:

...

  1. F3",
      "name": "

...

  1. 0050562FD8F3_

...

  1. captured",
      "networkName": "default_private_network",
      "ipv6": false,
      "quarantine": false,
      "available": true,
      "links": [
        {
          "title": "default_private_network",
          "rel": "privatenetwork",
          "type": "application/vnd.abiquo.vlan+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9"
        },
        {
          "title": "privateip",
          "rel": "self",
          "type": "application/vnd.abiquo.privateip+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips/

...

  1. 8"
        },
        {
          "title": "

...

  1. vdcbcdc",
          "rel": "virtualdatacenter",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12"
        }
      ]
    },
    {
      "id":

...

  1. 11,
      "ip": "192.168.0.2",
      "mac": "00:50:56:

...

  1. 1A:

...

  1. 2E:

...

  1. 18",
      "name": "

...

  1. 0050561A2E18_

...

  1. captured",
      "networkName": "default_private_network",
      "ipv6": false,
      "usedBy": "

...

  1. 1979e77f-

...

  1. 32b1-

...

  1. 430d-

...

  1. 9b92-

...

  1. 9f6347dbd416",
      "quarantine": false,
      "available": true,
      "links": [
        {
          "title": "default_private_network",
          "rel": "privatenetwork",
          "type": "application/vnd.abiquo.vlan+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9"
        },
        {
          "title": "privateip",
          "rel": "self",
          "type": "application/vnd.abiquo.privateip+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips/

...

  1. 11"
        },
        {
          "title": "

...

  1. vdcbcdc",
          "rel": "virtualdatacenter",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12"
        },
        {
          "title": "

...

  1. vapbcdc",
          "rel": "virtualappliance",
          "type": "application/vnd.abiquo.virtualappliance+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/virtualappliances/

...

  1. 4"
        },
        {
          "title": "

...

  1. vmapihowto",
          "rel": "virtualmachine",
          "type": "application/vnd.abiquo.virtualmachine+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/virtualappliances/

...

  1. 4/virtualmachines/

...

  1. 304"
        }
      ]
    },
    {
      "id":

...

  1. 12,
      "ip": "192.168.0.3",
      "mac": "00:50:56:

...

  1. 18:

...

  1. 63:

...

  1. 13",
      "name": "

...

  1. 005056186313_host",
      "networkName": "default_private_network",
      "ipv6": false,
      "quarantine": false,
      "available": true,
      "links": [
        {
          "title": "default_private_network",
          "rel": "privatenetwork",
          "type": "application/vnd.abiquo.vlan+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9"
        },
        {
          "title": "privateip",
          "rel": "self",
          "type": "application/vnd.abiquo.privateip+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12/privatenetworks/

...

  1. 9/ips/

...

  1. 12"
        },
        {
          "title": "

...

  1. vdcbcdc",
          "rel": "virtualdatacenter",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "href": "https://

...

  1. mjsabiquo.

...

  1. lab.abiquo.com:443/api/cloud/virtualdatacenters/

...

  1. 12"
        }
      ]
    }
  ]
}

...


In the above example, the NIC for 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"address of 192.168.0.2 is the one that we just added to the VM called vmapihowto and it has a link to the VM.
The available IP address of 192.168.0.3 is the one we will use, and it has an ID of 12.
From the IP address object in the above step, get the link with a "rel" attribute that has a value of "self".
 Code Block
        {
          "title": "privateip",
          "rel": "self",
          "type": "application/vnd.abiquo.privateip+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/privatenetworks/539/ips/33512"
        }, 
To prepare it for the VM, change "self" to "nicX", where "X" the rel attribute from a value of self to nicX, where X represents the number of the new NIC in the VM. So if there are no NICs, add "nic0" nic1 as shown here.
 Code Block
        {
          "title": "privateip",
          "rel": "nic0nic1",
          "type": "application/vnd.abiquo.privateip+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/privatenetworks/539/ips/33512"
        },
...
Add the NIC link to the VM object
Go the end of the links section and add the NIC from the previous step.
(warning) 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. 
...
Get the VM object that you created using the API in the first part of this tutorial.
(tick) To get the VM entity again, you can send a GET request to the cloud/virtualmachines link. 
In this case, we are using a vmname query parameter to filter on the number 2 in the VM name to only retrieve the VM from the first part of the tutorial.
 Code Block
√ ~ % curl --verbose 'https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualmachines?vmname=2' \
     -H 'Accept: application/vnd.abiquo.virtualmachines+json; version=6.1' \
     -u user:password -k | jq .
This request returns a collection of VMs, so you will need to select the individual VM from the collection.
In the VM object, go the end of the links section and add the NIC link from the previous step.
(warning) If this is the last link, remember to add a comma before it, and remove any comma after it.
This is an example of a modified VM object, with the nic1 link at the end of a shortened links section. We shortened the links section to make the example more readable 
 Code Block
    {
      "id": 305,
      "uuid": "eb613c22-ffa1-4498-827a-ccaf37385c2e",
      "fqdn": "box.localdomain",
      "typedescription": "application/vnd.abiquo.resourcetags+jsonA virtual machine",
      "hrefcoresPerSocket": 1,
 "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tags"     "idState": 1,
      "idType": }0,
      { "type": "MANAGED",
      "relhighDisponibility": 0,
   "tags-update"   "monitored": false,
      "typemonitoringLevel": "application/vnd.abiquo.tags+jsonDEFAULT",
      "hrefprotected": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tags"false,
      "variables": {},
      { "backuppolicies": [],
      "rellastSynchronize": "tags-format"1686046081000,
      "generateGuestInitialPassword": false,
      "typenatrules": "application/vnd.abiquo.tagformatrestrictions+json"[],
      "hrefvdrpEnabled": true,
"https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tags"      "vdrpPort": 0,
       },"password": "6t51rgZ9",
      { "deallocated": false,
      "relname": "tags-createvmapihowto2",
      "typeram": "application/vnd.abiquo.tags+json"48,
      "cpu": 1,
      "hrefstate": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tags/action/create"NOT_ALLOCATED",
    },     {"creationTimestamp": 1686042455000,
      "relbirthTimestamp": "tags-delete"1686045726000,
      "typelinks": "application/vnd.abiquo.tagkeys+json",
  [
        {
    "href": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tags/action/delete"       }"title": "Abiquo",
    {       "rel": "tags-editenterprise",
          "type": "application/vnd.abiquo.tagsenterprise+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloudadmin/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tags/action/editenterprises/1"
        },
        {
          "title": "vmapihowto2",
          "rel": "tags-syncedit",
          "type": "application/vnd.abiquo.virtualmachine+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/virtualappliances/1104/virtualmachines/1920/tags/action/sync"305"
        },
        ...
                {
          "title": "VMware vCenter Cluster",
          "rel": "hypervisortype",
          "type": "application/vnd.abiquo.hypervisortype+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/config/hypervisortypes/VMXVCENTER_04CLUSTER"
        },
        {
          "title": "yVM_mj",",
          "rel": "virtualmachinetemplate",
          "type": "application/vnd.abiquo.virtualmachinetemplate+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/72/virtualmachinetemplates/520145"
        },
        {
          "title": "Others",
          "rel": "category",
          "type": "application/vnd.abiquo.category+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/config/categories/1"
        },
        {
          "title": "privateip",
          "rel": "nic0nic1",
          "type": "application/vnd.abiquo.privateip+json",
          "href": "https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/privatenetworks/539/ips/335"12"
        } 
   }   ],
      "usageStatistics": []
    }      
...

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 you can save it to a JSON file called  "VMnic.json", and then used the @ use the @ notation to reference the file in the PUT request.
In our example, we called the file  vmapihowto2.json.
 Code Block
curl --verbose -X PUT 'https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/virtualappliances/1104/virtualmachines/1920305' \
   -H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=56.21' \
   -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=56.21' \
   -u user:password \
   -d @VMwithNIC@vmapihowto2.json -k 
Send the PUT request.
If it is successfulthe platform updates the VM successfully, the response status and message will be "204  No content" for an undeployed VM.
The An example of the request is given here.
 Code Block
 √ Abiquoapi_tutorials % curl --verbose -X PUT 'https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/virtualappliances/1104/virtualmachines/1920305' \
   -H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=56.21' \
   -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=56.21' \
   -u user:password \
   -d @VMwithNIC@vmapihowto2.json -k
    
> PUT /api/cloud/virtualdatacenters/4212/virtualappliances/1104/virtualmachines/1920305 HTTP/1.1
> Host: linatestmjsabiquo.bcnlab.abiquo.com
> Authorization: Basic XXXXXXXXXXXXX
> User-Agent: curl/7.6488.1
> Content-Type: application/vnd.abiquo.virtualmachine+json; version=56.21
> Accept: application/vnd.abiquo.acceptedrequest+json; version=56.21
> Content-Length: 1189912498
> Expect:
100-continue
> 
< HTTP/1.1 100 Continue 
< HTTP/1.1 204 204
< Date: FriWed, 1607 AprJun 20212023 1915:1906:1758 GMT
< Server: ApacheServer: Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips
< Set-Cookie: ABQSESSIONID=86083038209363036877288756894413749700; Max-Age=1800; Expires=FriWed, 1607-AprJun-20212023 1915:4936:1758 GMT; Path=/; Secure; HttpOnly; SameSite=strict
< X-Abiquo-TracerContext: 93272692e54d1e2f-df606b6a-4efa4338-a478ba9e-a4fcfd3a859b4c770f4e9813
< X-Abiquo-Token: a2e19816735381c1d074441cbd002aa06429084b01dc4d254adc14535eae44c5c3f4ad90e8e51aabe5134b3d3b841586306916bfe4fdcb486f331e2501f490c0XXXXXX
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
< 


...
Check your VM in the UI
In the UI, when you select the VM, and open the control VM details panel in to the Network NICs tab, the NIC should display.
Image Removed
...
Change the power states of a VM
To prepare a VM to change power states, deploy a VM using the UI or the API.
(tick) To deploy the VM you were using in the previous step, send a POST request to the deploy link.
Then see Administer and troubleshoot VMs in the "Manage VM power states using the API" section
...
 Code Block
curl -X DELETE https://linatestmjsabiquo.bcnlab.abiquo.com:443/api/cloud/virtualdatacenters/4212/virtualappliances/1104/virtualmachines/1920305 \
	-H 'Accept: text/json,application/json;' \
	-u user:password -k
...
And of course don't forget to check out the Java and Python libraries. Enjoy!

Related links