How to add a NIC to a VM via API

Owned by MS (Unlicensed)
Jan 17, 2023
43 min read

Introduction

This page describes how to add an existing external NIC to an existing VM. It also describes how to detach a NIC from a VM.

You will need the following resources

  • External network in a datacenter with available IP addresses

  • Private network in a datacenter with IP addresses

  • A VDC

  • A VM. If deployed on a hypervisor without hot-reconfigure, power off the VM

Your user role must include the following privileges.

  • ROLE_VDC_ENUMERATE

  • VDC_MANAGE_NETWORK 

  • ROLE_VDC_MANAGE_VAPP

  • ROLE_VAPP_CUSTOMISE_SETTINGS

Your user must be in the enterprise that owns the virtual datacenter and virtual resources.

Wiki pages describing network UI functionality

Summary diagram

The steps in this diagram link to the API reference guide resources and data entities sections.

 

Detailed steps

  1. Get VMs from the cloud and separate the VM entity

  2. Sample response. Success status code: 200
    Note that this request returns a collection of VMs, and you will need to get the VM from within the collection. You can also use the VM's edit link to obtain the VM only. 

    { "totalSize": 1, "links": [ { "rel": "first", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualmachines?vmname=yvm (1)&limit=25&by=name&asc=true" }, { "rel": "last", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualmachines?vmname=yvm (1)&startwith=0&limit=25&by=name&asc=true" } ], "collection": [ { "id": 575, "uuid": "e8606328-d09c-4f30-9635-e83113731637", "fqdn": "box.localdomain", "description": "A virtual machine", "coresPerSocket": 1, "idState": 1, "idType": 0, "type": "MANAGED", "highDisponibility": 0, "metadata": { "monitoring-metrics": [ { "name": "Uptime" }, { "name": "Memory-swap2" }, { "name": "Memory-swap" }, { "name": "CPU-Mz" }, { "name": "abq-ram_usage" }, { "name": "CPU" }, { "name": "Memory-host" }, { "name": "abq-cpu_usage" }, { "name": "Disk-latency" }, { "name": "Memory-physical" }, { "name": "CPU-time" }, { "name": "Memory" }, { "name": "Memory-vmmemctl" } ] }, "monitored": true, "monitoringLevel": "DEFAULT", "protected": false, "variables": {}, "backuppolicies": [], "lastSynchronize": 1632243438000, "generateGuestInitialPassword": false, "natrules": [], "vdrpEnabled": true, "vdrpPort": 0, "password": "7XLpC9ZU", "deallocated": false, "name": "yVM (1)", "ram": 48, "cpu": 1, "state": "NOT_ALLOCATED", "creationTimestamp": 1629396447000, "iconUrl": "https://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png", "links": [ { "title": "Empresa QA", "rel": "enterprise", "type": "application/vnd.abiquo.enterprise+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/admin/enterprises/2" }, { "title": "yVM (1)", "rel": "edit", "type": "application/vnd.abiquo.virtualmachine+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575" }, { "rel": "asynctasks", "type": "application/vnd.abiquo.asynctasks+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/asynctasks" }, { "title": "send mail", "rel": "sendmail", "type": "application/vnd.abiquo.mail+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/admin/publiccloudregions/1/enterprises/2/virtualmachines/575/action/sendmail" }, { "title": "CloudAdmin CloudAdmin", "rel": "user", "type": "application/vnd.abiquo.user+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/admin/enterprises/2/users/9" }, { "title": "vdc-torras-cluster", "rel": "virtualdatacenter", "type": "application/vnd.abiquo.virtualdatacenter+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50" }, { "title": "VappMJ", "rel": "virtualappliance", "type": "application/vnd.abiquo.virtualappliance+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70" }, { "title": "metadata", "rel": "metadata", "type": "application/vnd.abiquo.metadata+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/metadata" }, { "title": "vlan network configurations", "rel": "configurations", "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/network/configurations" }, { "title": "192.168.0.0/24", "rel": "network_configuration", "type": "application/vnd.abiquo.virtualmachinenetworkconfiguration+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/network/configurations/104" }, { "title": "nics", "rel": "nics", "type": "application/vnd.abiquo.nics+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/network/nics" }, { "title": "disks", "rel": "harddisks", "type": "application/vnd.abiquo.harddisks+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/storage/disks" }, { "title": "NOT_ALLOCATED", "rel": "state", "type": "application/vnd.abiquo.virtualmachinestate+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/state" }, { "title": "virtual machine undeploy", "rel": "undeploy", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/undeploy" }, { "title": "virtual machine deploy", "rel": "deploy", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/deploy" }, { "title": "virtual machine reset", "rel": "reset", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/reset" }, { "title": "virtual machine snapshot", "rel": "instance", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/instance" }, { "title": "remote access", "rel": "rdpaccess", "type": "application/vnd.abiquo.virtualmachineconsole+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/config/rdpaccess" }, { "title": "tasks", "rel": "tasks", "type": "application/vnd.abiquo.tasks+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tasks" }, { "title": "firewalls", "rel": "firewalls", "type": "application/vnd.abiquo.links+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/firewalls" }, { "title": "load balancers", "rel": "loadbalancers", "type": "application/vnd.abiquo.loadbalancers+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/loadbalancers" }, { "title": "request on demand backup", "rel": "requestbackup", "type": "application/vnd.abiquo.ondemandbackup+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/backup/action/request" }, { "title": "request a restore of a backup", "rel": "requestrestore", "type": "application/vnd.abiquo.restore+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/backup/action/restore" }, { "title": "move VM to a virtual appliance", "rel": "vappmove", "type": "application/vnd.abiquo.links+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/vappmove" }, { "title": "move VM to another virtual datacenter", "rel": "move", "type": "application/vnd.abiquo.movevm+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/move" }, { "title": "increase hardware profile", "rel": "increasehardwareprofile", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/increasehardwareprofile" }, { "title": "decrease hardware profile", "rel": "decreasehardwareprofile", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/decreasehardwareprofile" }, { "title": "volumes", "rel": "volumes", "type": "application/vnd.abiquo.volumes+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/storage/volumes" }, { "title": "HP_CPU1-RAM48-CPS1-CostCodenone-ABQ334998d5", "rel": "hardwareprofile", "type": "application/vnd.abiquo.hardwareprofile+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/locations/1/hardwareprofiles/786" }, { "diskAllocation": "THIN", "diskControllerType": "IDE", "diskLabel": "Hard disk 1", "length": "64", "title": "560b56eb-934d-4407-a8fc-9049553ee1f7", "rel": "disk0", "type": "application/vnd.abiquo.harddisk+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/disks/950" }, { "title": "Default Tier", "rel": "datastoretier0", "type": "application/vnd.abiquo.datastoretier+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/locations/1/datastoretiers/1" }, { "title": "192.168.0.3", "rel": "nic0", "type": "application/vnd.abiquo.privateip+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/privatenetworks/104/ips/951" }, { "title": "protect", "rel": "protect", "type": "text/plain", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/protect" }, { "title": "unprotect", "rel": "unprotect", "type": "text/plain", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/unprotect" }, { "title": "metricsmetadata", "rel": "metricsmetadata", "type": "application/vnd.abiquo.metricsmetadata+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/metrics" }, { "title": "disablemonitoring", "rel": "disablemonitoring", "type": "", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/disablemonitoring" }, { "title": "collectd", "rel": "collectd", "type": "application/json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/metrics/collectd" }, { "title": "alarmssearch", "rel": "alarmssearch", "type": "application/vnd.abiquo.alarms+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/alarms" }, { "title": "clone", "rel": "clone", "type": "application/vnd.abiquo.virtualmachinecloneoptions+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/action/clone" }, { "rel": "tags", "type": "application/vnd.abiquo.resourcetags+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags" }, { "rel": "tags-update", "type": "application/vnd.abiquo.tags+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags" }, { "rel": "tags-format", "type": "application/vnd.abiquo.tagformatrestrictions+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags" }, { "rel": "tags-create", "type": "application/vnd.abiquo.tags+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags/action/create" }, { "rel": "tags-delete", "type": "application/vnd.abiquo.tagkeys+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags/action/delete" }, { "rel": "tags-edit", "type": "application/vnd.abiquo.tags+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags/action/edit" }, { "rel": "tags-sync", "type": "", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575/tags/action/sync" }, { "title": "VMware vCenter Cluster", "rel": "hypervisortype", "type": "application/vnd.abiquo.hypervisortype+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/config/hypervisortypes/VCENTER_CLUSTER" }, { "title": "yVM", "rel": "virtualmachinetemplate", "type": "application/vnd.abiquo.virtualmachinetemplate+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/admin/enterprises/2/datacenterrepositories/1/virtualmachinetemplates/68" }, { "title": "Others", "rel": "category", "type": "application/vnd.abiquo.category+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/config/categories/1" } ], "usageStatistics": [ { "statName": "CPU_USAGE", "average": 0.051741756058800076, "maximum": 0.5, "minimum": 0, "virtualMachineUuid": "e8606328-d09c-4f30-9635-e83113731637", "virtualMachineName": "yVM (1)", "links": [] }, { "statName": "RAM_USAGE", "average": 9.545787048075159, "maximum": 18.99, "minimum": 0, "virtualMachineUuid": "e8606328-d09c-4f30-9635-e83113731637", "virtualMachineName": "yVM (1)", "links": [] } ] } ] }

     

  3. Keep the VM entity to update it.You will need the virtualmachine, nics, nicX, and virtualdatacenter links 

    1. virtualmachine

      { "title": "yVM (1)", "rel": "edit", "type": "application/vnd.abiquo.virtualmachine+json", "href": "https://abiquoapi.bcn.abiquo.com:443/api/cloud/virtualdatacenters/50/virtualappliances/70/virtualmachines/575" },

    2. nics

    3. nicX links for all NICs that are already attached to the VM. In this case, there is one NIC in position 0. Add the new NIC in the next position.

    4. virtualdatacenter

       

  4. Get the virtual datacenter of the VM

    1. Reference: https://wiki.abiquo.com/api/latest/VirtualDatacentersResource.html#get-a-virtual-datacenter

    2. cURL

    3. Sample response. Success status code: 200

    4. From the virtual datacenter save the link with a rel value of "externalips"

  5. Get the available external IPs from the virtual datacenter

    1. Reference: https://wiki.abiquo.com/api/latest/VirtualDatacentersResource.html#list-external-ips-of-a-virtual-datacenter

    2. cURL

      By default, this query returns only the IP addresses that are not in use. 

    3. Recommended query parameters

      1. limit: to return a smaller number of IP addresses

      2. has: use this parameter to filter by the the network name, for example, "has=net4", although this will also return "net411".

    4. Sample response. Success status code: 200

      In this case, we will use address 2 in the network.

    5. For the selected IP address, you will need the "self" link

       

  6. Create NIC link and add to the VM entity

    1. Change the rel value of the "self" link to "nicX" as the next disk in the sequence. As our VM has only one NIC, which is "nic0", we will set this one to "nic1". Add a comma at the end of the link!

      Don't forget to add the comma at the end of the link! 

    2. Add the link to the VM entity from above

  7. Update the VM

    1. Reference: https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#update-a-virtual-machine

    2. cURL

    3. Request data for this request will be in the local file named "virtualMachineNIC.json".

    4. Sample response:

      1. If the VM is not deployed, a successful request will update the VM entity and return a status code of 204 

      2. If the VM is deployed, the request will return a status code of 202 - Accepted request and an acceptedrequest object that contains a link that can be used to check the progress of the task.

Check that the NIC is attached

After you add the NIC, you can get the VM and check that the NIC is attached. The NIC link you added should be included in the VM object. The platform also stores extra data with the network link.


Detach a NIC from a VM

To detach a NIC from a VM, simply remove the nicX link of the NIC from the VM object and perform a PUT request to update the VM.

Copyright © 2006-2024, Abiquo Holdings SL. All rights reserved