VirtualMachinesResource


Capture a virtual machine


This method requires a VM that has already been imported (also called retrieved) into Abiquo from the host.
It captures the VM into a virtual appliance so that it can be managed by Abiquo.
It requires a link to the imported VM, which means a link from infrastructure (api/datacenters/x/rask/x/machines/x/virtualmachines/*).

Note about resources:

  • External volumes are not supported for capture
  • Disks need the correct size in the correct sequence
  • NICs need a link of a vlan (any type of VLAN) and an ip value in this VLAN. If you are working with a network that is not a private network, the VLAN tags assigned to the VM in the platform must match the ones used in the hypervisor.

Note: It might be useful to use this get virtualmachineflat call {@link VirtualMachineInfrastructureResource#getInfrastructureVirtualMachine(Integer, Integer, Integer, Integer, IRESTBuilder)} to retrieve all the information from the remote VM, then complete the result dto in order to use it as the content of this request.

See also the tutorial on Capture a VM via API

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines

Roles : [ROLE_VDC_MANAGE_VAPP]

Content-Type : virtualmachineflat Accept : virtualmachineflat

Error Codes

  • COSTCODE-0 - The requested cost code does not exist
  • GEN-4 - Not enough permissions to perform this action
  • NETDEVICE-5 - The entity is associated with a device that is not configured in the current virtual datacenter
  • VM-100 - The requested IP is not available
  • VM-101 - The network service type of the VLAN does not match the network service type of the selected network interface in the hypervisor
  • VM-102 - Remote ip 10.60.1.1 and vlan tag 3 error: The selected remote IP is using a tag that is incompatible with the selected VLAN network
  • VM-103 - Remote ip 10.60.1.1 and vlan tag 3 error: The selected remote IP is using a tag that is already used by a different VLAN than the selected one
  • VM-104 - Cannot assign the VLAN tag to the selected VLAN because it is out of rack range
  • VM-105 - The selected rack will not allow new VLAN tags
  • VM-115 - Cannot select an IPv6 strict network to capture a virtual machine
  • VM-122 - A disk in sequence position 0 is required to capture the remote virtual machine
  • VM-123 - Cannot capture a virtual machine with persistent disks
  • VM-132 - There are disks in a datastore with no tier or not allowed to be used in the destination enterprise
  • VM-145 - Cannot capture a virtual machine without NICs
  • VM-153 - Cannot capture the virtual machine because the disk with UUID fc52d325-239d-467c-bafc-73e58c58acbd is already used by another virtual machine
  • VM-77 - To capture a virtual machine, the virtualmachine link from the infrastructure context is required
  • VM-78 - Malformed virtual machine link from infrastructure to capture
  • VM-79 - The virtual datacenter is not compatible with the hypervisor from which you are capturing the virtual machine
  • VM-80 - Disk sequences cannot be repeated
  • VM-82 - The disk sequence does not match the data retrieved from the hypervisor
  • VM-83 - The disk size does not match the data retrieved from the hypervisor
  • VM-84 - The size and the sequence are required properties of the disk
  • VM-85 - Some disks on the remote virtual machine cannot be captured
  • VM-86 - Every NIC defined requires a VLAN link
  • VM-87 - Malformed VLAN link
  • VM-88 - The VLAN link contains an invalid virtual datacenter
  • VM-89 - The VLAN link contains an invalid enterprise
  • VM-90 - The VLAN link contains an invalid datacenter
  • VM-91 - IP sequence cannot be repeated
  • VM-92 - The selected IP is already attached to another virtual machine
  • VM-93 - Malformed IP address
  • VM-95 - The IP from the remote virtual machine does not match the NIC defined by the user with the same MAC address
  • VM-96 - The MAC address, the IP address and the sequence are required properties of the NIC
  • VM-97 - There are some NICs on the remote machine that cannot be captured
  • VM-98 - The public IP was not purchased for this virtual datacenter
  • VM-99 - The requested IP is in quarantine

Example

Create a virtual machine


To create a VM, you will need the link of the virtual appliance where the VM will be created and a virtual machine data transfer object.

The simplest virtual machine data transfer object is a link to the VM template in the datacenter repository (Apps library), in the VM format as shown in the following minimal example.

 {
 "links" : [ {
     "rel" : "virtualmachinetemplate",
     "href" : "http://example.com/api/admin/enterprises/1/datacenterrepositories/1/virtualmachinetemplates/4"
   } ]
 }
 
When creating a VM, you can set more values in the data transfer object, which is the VirtualMachine Media Type. In this example we will give the VM a higher specification than the template default (2 CPUs instead of 1, and 128 MB of RAM instead of 64). And we will enable remote access and set a custom password.
 {
 "cpu" : 2,
 "ram" : 128,
 "vdrpEnabled" : true,
 "password" : "myvmpass",
 "links" : [ {
     "rel" : "virtualmachinetemplate",
     "href" : "http://example.com/api/admin/enterprises/1/datacenterrepositories/1/virtualmachinetemplates/4"
   } ]
 }
 

With the link of the VM template in the entity, you can instantiate the VM at the URL of the virtualmachines link from the virtual appliance.
In the Abiquo API, the VM has a "uuid" attribute, a "name" attribute and a "label". The "label" is the user friendly name that is displayed on the VM icon in the UI and by default it is the name of the template from the Apps library, with numbering of templates used more than once. The "name" attribute is the name of the VM in the hypervisor.
In general, you can add links to VM resources to your virtual machine data object, for example, to create a VM with a hardware profile, add the link to the hardware profile.

  • Create with hardware profile:
      {
      "links" :
      [
       {
          "rel" : "virtualmachinetemplate",
          "href" : "http://example.com/api/admin/enterprises/1/datacenterrepositories/1/virtualmachinetemplates/4"
       },
       {
           "href": "http://localhost:9009/api/cloud/locations/3439/hardwareprofiles/206",
           "rel": "hardwareprofile"
       }
     ]}
     
  • Create with NIC:
      {
      "links" :
      [
       {
          "rel" : "virtualmachinetemplate",
          "href" : "http://example.com/api/admin/enterprises/1/datacenterrepositories/1/virtualmachinetemplates/4"
       },
       {
         "href": "http://localhost:9009/api/cloud/virtualdatacenters/2396/privatenetworks/1203/ips/14398",
         "type": "application/vnd.abiquo.privateip+json",
         "rel": "nic0"
       }
     ]}
     
  • Create with firewall policies:
      {
      "links" :
      [
       {
          "rel" : "virtualmachinetemplate",
          "href" : "http://example.com/api/admin/enterprises/1/datacenterrepositories/1/virtualmachinetemplates/4"
       },
       {
          "href": "http://localhost:9009/api/cloud/locations/3438/devices/976/firewalls/445",
          "rel": "firewall"
       }
     ]}
     
  • Create a virtual machine for Amazon: This example shows how to create a virtual machine for AWS. Before you create a VM, import the AMI template details into the Apps library. Hardware profiles are imported when the user adds cloud provider credentials and automatically enabled for the enterprise.
      {
      "label":"amzn-ami-hvm-2016.09.1.20170119-x86_64-gp2",
      "links":[
        {
          "title":"amzn-ami-hvm-2016.09.1.20170119-x86_64-gp2",
          "rel":"virtualmachinetemplate",
          "type":"application/vnd.abiquo.virtualmachinetemplate+json",
          "href":"https://example.com/api/admin/enterprises/1/datacenterrepositories/3/virtualmachinetemplates/170"
        },
        {
          "title":"t2.nano",
          "rel":"hardwareprofile",
          "type":"application/vnd.abiquo.hardwareprofile+json",
          "href":"https://example.com/api/cloud/locations/3/hardwareprofiles/79"
        }
     ]}
     

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines

Roles : [ROLE_VDC_MANAGE_VAPP]

Content-Type : virtualmachine Accept : virtualmachine

Error Codes

  • ENTERPRISE-10 - The enterprise does not have permission to use the requested datacenter
  • FIREWALLPOLICY-5 - The requested firewall policy does not exist
  • GEN-15 - Not enough privileges to perform this operation
  • GEN-4 - Not enough permissions to perform this action
  • HD-5 - Invalid link to the hard disk to attach
  • LNK-0 - Invalid link. Check documentation
  • NETDEVICE-5 - The entity is associated with a device that is not configured in the current virtual datacenter
  • PERSISTENT-7 - Another virtual machine is already using the persistent virtual machine template.
  • PROFILE-3 - Invalid link to the hardware profile; cannot get profile values
  • PROFILE-6 - Inactive hardware profile. Select another one.
  • PROFILE-7 - CPU/RAM/CoresPerSocket values do not match hardware profile
  • VIMAGE-0 - The requested virtual machine template does not exist
  • VIMAGE-29 - The virtual machine template belongs to another enterprise and is not a shared template.
  • VIMAGE-47 - A HardDisk or Volume is assigned a sequence position already in use in the virtual machine template
  • VM-111 - Virtual machine cannot be created from a virtual machine template without a disk file
  • VM-113 - Virtual machine cannot be created from a virtual machine template that is not in the DONE state; check the state and pending tasks
  • VM-146 - CPU value outside the maximum and minimum values defined in the virtual machine template
  • VM-147 - RAM value outside the maximum and minimum values defined in the virtual machine template
  • VM-158 - The virtual machine must use one of the hardware profiles that are recommended for this template
  • VM-16 - The virtual machine template supplied is not available in the virtual appliance's datacenter
  • VM-168 - CPU must be specified.
  • VM-169 - RAM must be specified.
  • VM-171 - Cannot attach IPs in VLANs from different availability zones
  • VM-24 - The resource is already used by another virtual machine
  • VM-51 - Cannot create a virtual machine because the persistent virtual machine template is not ready
  • VM-61 - The disk link(s) supplied are missing the type attribute or it is invalid
  • VM-62 - Invalid input. Repeated disk attachment value is not allowed.
  • VM-63 - Invalid input. Repeated disk href value is not allowed.
  • VM-73 - VRDP passwords should be up to 8 characters
  • VM-74 - Invalid character in password. VRDP password characters should be in range [a..z][A..Z][0..9]

Example

List virtual machines flat in a virtual appliance


Retrieve all VMs that belong to this virtual appliance with the standard virtual machine data transfer object and embedded objects instead of links for disks, volumes, NICs, and action plans.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE]

Parameter Type Default Value Description
startwith Integer 0 The first element to be retrieved of the filtered search
by String name Order by
has String If present filter to apply in the search.
limit Integer 25 The number of entities to retrieve
asc Boolean true If the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)

Error Codes

  • CONSTR-MIN - Parameter 'limit' must be greater than or equal to 0 but value '-1' was found

Example

List virtual machines in a virtual appliance


Retrieve all VMs that belong to this virtual appliance with the standard virtual machine data transfer object. A similar method is also available at the virtual datacenters level.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE]

Parameter Type Default Value Description
startwith Integer 0 The first element to be retrieved of the filtered search
by String name Order by
has String If present filter to apply in the search.
limit Integer 25 The number of entities to retrieve
asc Boolean true If the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)
key String related with metadata information, allows to filter content in this field

Accept : virtualmachines

Error Codes

  • CONSTR-MIN - Parameter 'limit' must be greater than or equal to 0 but value '-1' was found
  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist

Example

Delete a virtual machine or release a captured virtual machine


A VM can be deleted if its state is DEPLOYED, NOT_ALLOCATED or UNKNOWN.
  • If the VM exists in the hypervisor, it will be removed from the hypervisor as well.
  • If the VM is deployed, the delete operation will return a 202 and a link to a task.
  • If the VM is not deployed, a successful request will return a status code of 204 no content.
  • If the VM is in the unknown state, there may have been a lost connection with the hypervisor, so the administrator should also check the hypervisor.

DELETE https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}

Roles : [ROLE_VDC_MANAGE_VAPP]

Parameter Type Default Value Description
release boolean false Logical delete of a captured virtual machine
Returns a captured VM into the imported state, which means that the VM won't be managed by Abiquo and it is ready to be captured again.
  • Note 1: This feature is also useful as "undo capture" if the VM was been captured into an incorrect virtual appliance or with incorrect networks.
  • Note 2: Warning: this request only differs from the delete action in the release query parameter, so if you forget that or give it the value false, the VM will be deleted instead of released.
force boolean false If true, perform a logical delete. Remove without calling the hypervisor or public cloud region. This doesn't require public cloud credentials

Example

Get a virtual machine


Retrieve the VM from the cloud virtual datacenters and virtual appliances path.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE]

Accept : virtualmachine

Error Codes

  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist
  • VM-1 - The requested virtual machine does not exist

Example

Get a virtual machine flat


Retrieve the VM from the cloud virtual datacenters and virtual appliances path with the standard virtual machine data transfer object and embedded objects instead of links for disks, volumes, NICs and action plans.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE]

Example

Update a virtual machine


Modify a VM that is deployed or undeployed.

If the VM is deployed, a successful request will return a status code of 202 and an accepted request with links to follow the tasks that will modify the VM. If the VM is not deployed, then a successful request will simply update the database and return a status code of 204.
If the VM is deployed and your environment does not support hot-add or hot-reconfigure, you will need to power off the VM before making changes.
For more information and examples of modifying a VM, please see API Tutorials, in particular for the process of adding a NIC or a hard disk to a VM.
To add a startup script, see Manage virtual machine metadata via API.

Disk boot order is defined by the disks and volumes link ''rel'' attribute: disk0 is the disk or volume to boot, disk1 is the next disk, and so on.

NIC order is defined by the link ''rel'' attribute: nic0 is the primary network adapter, nic1 is the next one, and so on.

Update a virtual machine to add or remove backup configuration Modify a VM as usual to add or remove the desired backup configuration under the backupPolicies attribute.
 {
   "cpu": 1,
   "ram": 1024,
   ....
   "backupPolicies":[
     {
       "links": [
         {
           "rel": "policy",
           "href": "https://example.com/api/datacenter/x/backuppolicies/x"
         }
       ],
       "configurations": [
         {
           "type": "COMPLETE",
           "subtype": "DAILY",
           "value": "13:30:00 +0200"
         },
         {
           "type": "SNAPSHOT",
           "subtype": "WEEKLY",
           "value": "15:00:02 +0100",
           "days": ["WEDNESDAY", "SUNDAY"],
           "sources": [
             {
               "links": [
                 {
                   "rel": "disk",
                   "href": "https://example.com/api/cloud/virtualdatacenter/x/disks/x"
                 }
               ]
             }
           ]
         }
       ]
     },
     {
       "links": [
         {
           "rel": "policy",
           "href": "https://example.com/api/datacenter/x/backuppolicies/x"
         }
       ],
       "configurations": [
         {
           "type": "OPTIONS",
           "subtype": "REPLICATION",
           "value": "true"
         }
       ]
     }
   ],
   ...
 }
 

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}

Roles : [ROLE_VAPP_CUSTOMISE_SETTINGS]

Parameter Type Default Value Description
force Boolean false If true, acknowledge breaking the soft limit

Content-Type : virtualmachine Accept : acceptedrequest

Error Codes

  • ALLOC-1 - Cannot make the requested changes to the virtual machine because there are not enough free resources on the host machine. Please contact the Administrator.
  • CONSTR-DIVISIBLE - The property 'cpu' is not divisible by the configured cores per socket 7.
  • CONSTR-LENGTH - The property 'fqdn' length must be between 3 and 255.
  • DSTIER-6 - Cannot modify the datastore tier from a deployed disk
  • FIREWALLPOLICY-5 - The requested firewall policy does not exist
  • GEN-15 - Not enough privileges to perform this operation
  • GEN-17 - The plugin type was not found
  • GEN-18 - The requested operation is not supported by the hypervisor plugin
  • GEN-24 - The requested disk controller is not supported by the hypervisor plugin
  • GEN-4 - Not enough permissions to perform this action
  • HD-1 - The requested hard disk does not exist: Hard Disk id 899909
  • HD-13 - The hard disk cannot be resized because the virtual machine is not deployed
  • HD-15 - Only the IDE disk controller type is supported for the ISO disk format type
  • HD-16 - The hard disk cannot be resized because it is using the ISO disk format type
  • HD-19 - Allocation is not supported in the target hypervisor type
  • HD-20 - Cannot change disk allocation in an already deployed disk
  • HD-5 - Invalid link to the hard disk to attach
  • HD-6 - Invalid virtual datacenter in the link to the volume to attach
  • LAYER-1 - Cannot create a new layer by reconfiguring the virtual machine. Use the define layer feature
  • LAYER-6 - Cannot move a deployed virtual machine from one layer to another
  • LAYER-7 - Cannot remove association between a layer and one virtual machine. Use the delete layer feature
  • LAYER-8 - Cannot associate the virtual machine with this layer because the virtual machine is already allocated to a hypervisor that is incompatible with the layer
  • NAT-IP-7 - Invalid NAT IP link
  • NAT-IP-8 - Cannot use a NAT IP not assigned to the virtualDatacenter
  • NAT-RULE-11 - Cannot create NAT rule using a private IP that is not attached to the virtual machine
  • NAT-RULE-12 - Cannot create NAT rule because the NAT IP is in quarantine
  • NAT-RULE-13 - Unsupported NAT protocol
  • NAT-RULE-14 - Cannot specify multiple SNAT rules for the same private IP
  • NAT-RULE-15 - Cannot specify ports or protocol in SNAT rules
  • NAT-RULE-3 - Original port already in use for the specified NAT IP
  • NAT-RULE-7 - Cannot delete an IP with associated NAT rules
  • NETDEVICE-5 - The entity is associated with a device that is not configured in the current virtual datacenter
  • PL-CPROV-16 - Cannot move the virtualmachine between private and standard domain, when it is deployed.
  • PL-VM-30 - Cannot perform this action because cores per socket is not available for this hypervisor
  • PROFILE-3 - Invalid link to the hardware profile; cannot get profile values
  • PROFILE-6 - Inactive hardware profile. Select another one.
  • PROFILE-7 - CPU/RAM/CoresPerSocket values do not match hardware profile
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation
  • VLAN-107 - The IP 169.45.75.212 is reserved
  • VLAN-23 - Invalid link to private IP address to create NIC
  • VLAN-51 - The IP 44.44.44.26 is in quarantine
  • VLAN-52 - Invalid input. Repeated NIC attachment value is not allowed
  • VLAN-68 - The IP 44.44.44.25 is not available
  • VM-116 - The provider of the given virtual machine does not have support for virtual machine metrics. The monitoring flag cannot be modified.
  • VM-121 - The virtual machine requires at least one IP while it is running
  • VM-129 - The primary disk (sequence 0) must be bootable.
  • VM-133 - Hypervisor does not support changing the virtual machine CPU in the current state
  • VM-137 - Hypervisor does not support changing the virtual machine remote access in the current state
  • VM-138 - Virtual machine template is not configured to support changing the CPU in the current state
  • VM-139 - Virtual machine template is not configured to support changing the RAM in the current state
  • VM-142 - Virtual machine template is not configured to support changing the remote access in the current state
  • VM-143 - It is not possible to decrease the CPU of the virtual machine in its current state. Power it off first
  • VM-144 - It is not possible to decrease the RAM of the virtual machine in its current state. Power it off first
  • VM-146 - CPU value outside the maximum and minimum values defined in the virtual machine template
  • VM-147 - RAM value outside the maximum and minimum values defined in the virtual machine template
  • VM-156 - Cannot reconfigure the virtual machine until synchronization is completed. Please wait until lastSynchronize is updated.
  • VM-158 - The virtual machine must use one of the hardware profiles that are recommended for this template
  • VM-159 - Invalid FQDN provided
  • VM-161 - Generating an initial guest password requires guest customizations in the virtual machine template and support by the plugin
  • VM-162 - Cannot modify the option to generate an initial guest password while the VM is deployed
  • VM-165 - Windows hostname cannot exceed 15 characters in length
  • VM-168 - CPU must be specified.
  • VM-169 - RAM must be specified.
  • VM-171 - Cannot attach IPs in VLANs from different availability zones
  • VM-57 - The hypervisor where the virtual machine is deployed is not running properly. Contact your System Administrator
  • VM-60 - Cannot change the layer of a virtual machine that has been assigned to a hypervisor
  • VM-61 - The disk link(s) supplied are missing the type attribute or it is invalid
  • VM-62 - Invalid input. Repeated disk attachment value is not allowed.
  • VM-63 - Invalid input. Repeated disk href value is not allowed.
  • VM-69 - Current target hypervisor does not have the required physical NICs to allocate the requested IPs
  • VM-71 - At least one primary (sequence 0) disk must be defined.
  • VOL-22 - Invalid link to the volume to attach
  • VOL-23 - Invalid virtual datacenter in the link to the volume to attach
  • VOL-3 - The volume does not exist: Volume id 899909
  • VOL-46 - The volume cannot be resized or removed from the virtual machine if it has snapshots

Example

List tasks for a virtual machine


Displays the tasks on the VM. Tasks are a set of jobs (operations on hypervisors). Any of these tasks may still be in progress.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_STATEFUL]

Accept : tasks

Example

Get a task on a virtual machine


Display a specific task on the VM. Tasks are a set of jobs (operations on hypervisors). Any of these tasks may still be in progress. Every task has a UUID.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_STATEFUL]

Accept : task

Error Codes

  • TASK-1 - The requested task does not exist
  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist

Example

Get an extended task on a virtual machine


Displays a specific task on the VM. Tasks are a set of jobs (operations on hypervisors). Any of these tasks may still be in progress. Every task has a UUID.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_STATEFUL]

Accept : taskextended

Example

Acknowledge a failed task on a virtual machine


Set the state to ACK_ERROR if the Task is in state FINISHED_UNSUCCESSFULLY or ABORTED. Also set the job state to ACK_WARNING, no matter the state of the task.

{@link TaskState#ACK_ERROR} {@link TaskState#FINISHED_UNSUCCESSFULLY} {@link TaskState#ABORTED} {@link JobState#ACK_WARNING}

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}/action/ack

Roles : [ROLE_WORKFLOW_OVERRIDE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_STATEFUL]

Example

Cancel a task on a virtual machine


Set the task state to CANCELLED, the VM to NOT_ALLOCATED and set an optional message in task data with the key ''message''.

{@link TaskState#CANCELLED} {@link VirtualMachineState#NOT_ALLOCATED}

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}/action/cancel

Roles : [ROLE_WORKFLOW_OVERRIDE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_STATEFUL]

Content-Type : text/plain

Example

Cancel a task on a virtual machine without message


Sets the task state to CANCELLED and the virtual machine to NOT_ALLOCATED

{@link TaskState#CANCELLED} {@link VirtualMachineState#NOT_ALLOCATED}.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}/action/cancel

Roles : [ROLE_WORKFLOW_OVERRIDE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_STATEFUL]

Example

Continue a task on a virtual machine


Set the task to PENDING and set an optional message in Task Data with the key ''message''.

{@link TaskState#PENDING} {@link Task#getData()}

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}/action/continue

Roles : [ROLE_WORKFLOW_OVERRIDE]

Content-Type : text/plain

Continue a task on a virtual machine without message


Set the task to PENDING

{@link TaskState#PENDING}

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/tasks/{id}/action/continue

Roles : [ROLE_WORKFLOW_OVERRIDE]

Example

Clone a virtual machine


This method was created to clone a VM for horizontal autoscaling. The original VM can be undeployed or deployed.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/clone

Roles : [ROLE_VAPP_DEPLOY_UNDEPLOY]

Content-Type : virtualmachinecloneoptions Accept : virtualmachine

Error Codes

  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation
  • VM-1 - The requested virtual machine does not exist
  • VM-2 - The virtual machine is already locked by another operation

Example

Deploy a virtual machine


Deploys the VM by launching it into the hypervisor or public cloud provider. This call returns a 202 HTTP code (accepted) and a URI where you can keep track of the deploy.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/deploy

Roles : [ROLE_VAPP_DEPLOY_UNDEPLOY]

Parameter Type Default Value Description
force boolean false If true, acknowledge soft limit surpassed

Accept : acceptedrequest

Error Codes

  • GEN-18 - The requested operation is not supported by the hypervisor plugin
  • HD-18 - The hard disk cannot be resized because the virtual machine is not deployed. It looks like the virtual machine was deployed, then the disk resized and now it is attempting to redeploy. Please set the HD required size to the original (specified in the template)
  • NAT-RULE-12 - Cannot create NAT rule because the NAT IP is in quarantine
  • VM-110 - Virtual machine is using a template without a system disk file. It cannot be deployed.
  • VM-120 - The virtual machine is protected and cannot be used
  • VM-154 - The virtual machine does not have an active hardware profile link so it cannot be deployed
  • VM-158 - The virtual machine must use one of the hardware profiles that are recommended for this template
  • VM-7 - The allowed state for deploying virtual machines is NOT_ALLOCATED

Example

Instance a virtual machine


Create an instance of a VM (clone the disks to create a template) with the given name. In a private cloud datacenter, you can supply links to the disks that you wish to include in the instance.
This call returns a 202 HTTP code (accepted) and a URI where you can keep track of the instance task.
Send the final name for the instance in a virtual machine instance DTO, as shown in the example below.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/instance

Roles : [ROLE_VAPP_CREATE_INSTANCE]

Content-Type : virtualmachineinstance Accept : acceptedrequest

Error Codes

  • CONSTR-InstanceName - Missing instance name
  • CONSTR-SNAPSHOT-LENGTH-NAME-MAX - The length of the NAME parameter must be less than 255 characters
  • DISK-1 - Missing disk link
  • GEN-17 - The plugin type was not found
  • GEN-18 - The requested operation is not supported by the hypervisor plugin
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation
  • VM-128 - Invalid ISO disk format in the instance.
  • VM-27 - The allowed power state for creating an instance of a virtual machine is OFF
  • VM-64 - Cannot create an instance of a virtual machine that is not managed by the platform. Please capture the virtual machine then try again

Example

Move a virtual machine to another virtual datacenter


Move the virtual machine to a virtual appliance in another virtual datacenter.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/move

Roles : [ROLE_MANAGE_MOVE_VM]

Parameter Type Default Value Description
force Boolean false If true, acknowledge soft limit surpassed

Content-Type : movevm Accept : acceptedrequest

Error Codes

  • MOVE-VM-0 - Not allowed to move a virtual machine that belongs to a scaling group
  • MOVE-VM-1 - Target virtual appliance link is required
  • MOVE-VM-10 - Not allowed to move a virtual machine to a different device
  • MOVE-VM-11 - To move a virtual machine within the same virtual datacenter, use the virtual appliance move endpoint
  • MOVE-VM-12 - Not allowed to move a virtual machine with NAT rules
  • MOVE-VM-3 - Unknown link rel, only expecting ''virtualappliance'', ''network_configuration'', ''firewall'', ''loadbalancer'' and ''nicX''
  • MOVE-VM-4 - Can move virtual machines that are deployed only
  • MOVE-VM-5 - Not allowed to move a virtual machine with volumes
  • MOVE-VM-6 - Not allowed to move a virtual machine running in a public cloud region
  • MOVE-VM-7 - Not allowed to move a virtual machine to a different datacenter
  • MOVE-VM-8 - Not allowed to move a virtual machine to a different hypervisor type
  • MOVE-VM-9 - Not allowed to move a virtual machine to another enterprise

Example

Publish virtual machine notification


Notifies an event of the desired severity for a virtual machine. The event is published with the action type 'TRACE_NOTIFICATION'.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/notify

Roles : [ROLE_VAPP_CUSTOMISE_SETTINGS]

Content-Type : eventnotification

Example

Protect a virtual machine


An administrator (or user with the correct privilege) can protect a VM from all Abiquo operations, so no user can perform operations on this VM while it is still protected.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/protect

Roles : [ROLE_VM_PROTECT_ACTION]

Content-Type : text/plain

Example

Relocate virtual machine


An administrator with the Relocate VM into a compatible host privilege can use this method to relocate the VM (vMotion) for hypervisor plugins that support this action. Before you relocate the VM with this method, first obtain compatible hosts with the appropriate method.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/relocate

Roles : [ROLE_VM_RELOCATE]

Get compatible hosts for virtual machine relocation


An administrator with the Relocate VM into a compatible host privilege can use this method to obtain compatible hosts (relocate candidates) and then use the relocate VM method (vMotion) for hypervisor plugins that support this action. The links returned include two types of "rel":
  • currentmachine: where the VM is currently deployed
  • targetmachine: (multiple links with same rel) candidate for the VM to be relocated to. These machines are on the same rack and have enough resources when considering loadlevel rules.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/relocatecandidates

Roles : [ROLE_VM_RELOCATE]

Accept : links

Example

Reset a virtual machine


Power cycles a VM that is in the ON state.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/reset

Roles : [ROLE_VAPP_PERFORM_ACTIONS]

Accept : acceptedrequest

Error Codes

  • GEN-18 - The requested operation is not supported by the hypervisor plugin
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation
  • VM-11 - The virtual machine is not in any hypervisor. Therefore the change of state cannot be applied
  • VM-26 - The allowed power state for resetting a virtual machine is ON

Example

Undeploy a virtual machine


Perform an undeploy. A successful undeploy will put the VM in Abiquo into the NOT_ALLOCATED state. If the undeploy is successful, the VM will be deleted from the hypervisor. If the VM is in the ON state, Abiquo will perform a power off before the deconfigure.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/undeploy

Roles : [ROLE_VAPP_DEPLOY_UNDEPLOY]

Parameter Type Default Value Description
force boolean false If true, perform a logical delete. Remove without calling the hypervisor or public cloud region. This doesn't require public cloud credentials

Content-Type : virtualmachinetask Accept : acceptedrequest

Error Codes

  • GEN-18 - The requested operation is not supported by the hypervisor plugin
  • PUBLIC-10 - The enterprise does not have credentials for this provider
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation
  • VM-109 - You are trying to undeploy a virtual machine using a template that is not stored in the Apps Library. If you undeploy it, the virtual machine template cannot be recovered. To proceed with the undeploy, please call this functionality again with the 'forceUndeploy=true' option
  • VM-148 - You are trying to undeploy a virtual machine with one or more disks that are not stored in the Apps Library, only on the hypervisor datastore. If you undeploy, you won't be able to recover those disks. To proceed with the undeploy, please call this functionality again with the 'forceUndeploy=true' option.

Example

Unprotect a virtual machine


When the work has been finished for a protected VM, the administrator can release it from the protected state or "unprotect" it.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/unprotect

Roles : [ROLE_VM_PROTECT_ACTION]

Example

Move a virtual machine to another virtual appliance


The new virtual appliance is provided with rel ''virtualappliance'' in the request body

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/action/vappmove

Roles : [ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VM_RESTRICT]

Content-Type : links

Example

Search for alarms on a virtual machine


Retrieve alarms from the virtual machine

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/alarms

Roles : [ROLE_USERS_VIEW_ALARMS]

Parameter Type Default Value Description
startwith Integer 0 First element to retrieve, By default 0.
by String alarm Field to order by. Possible values: 'alarm', 'entity_type', 'metric', 'time_range', 'datapoints_limit', 'statistic', 'formula', 'threshold', 'description'. Uses 'alarm' as default.
limit Integer 25 Number of alarms to return. By default 25.
asc Boolean true If true, sort in ascending order of the field specified with the 'by' parameter, otherwise, sort in descending order.
alarm String Filter alarms by name, accepts wildcards. Empty by default.
metric String Filter alarm by metric name, accepts wildcards. Empty by default.
state String Filter by alarm state. Possible values: 'all', 'active' or 'inactive'

Accept : alarms

Error Codes

  • GEN-4 - Not enough permissions to perform this action

Example

Get remote access details for a virtual machine


GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/config/rdpaccess

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP]

Error Codes

  • VM-164 - To get the remote console the virtual machine must be in state ON

Example

Disable fetch of metrics for a virtual machine


Stop retrieving native metrics from the virtualization technology. For UI functionality, see VM monitoring and metrics.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/disablemonitoring

Roles : [ROLE_USERS_ENABLE_DISABLE_VM_METRICS]

Example

Enable fetch of metrics for a virtual machine


Enable the retrieve of available builtin metrics from the virtualization technology for a VM. For UI functionality, see VM monitoring and metrics.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/enablemonitoring

Roles : [ROLE_USERS_ENABLE_DISABLE_VM_METRICS]

Example

Update monitoring level for a virtual machine


For supported providers, enable the monitoring level for retrieve of available builtin metrics from the virtualization technology for a VM. For UI functionality, see VM monitoring and metrics

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/enablemonitoringlevel

Roles : [ROLE_USERS_ENABLE_DISABLE_VM_METRICS]

Content-Type : monitoringlevel

Example

List load balancers of a virtual machine


Retrieve all load balancers associated with a VM.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/loadbalancers

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE, ROLE_MANAGE_LOADBALANCERS, ROLE_ASSIGN_LOADBALANCERS]

Parameter Type Default Value Description
startwith Integer 0 The first element to be retrieved of the filtered search
by String name Parameter for ordering. Valid values {@link com.abiquo.server.core.cloud.LoadBalancer.ORDER_BY}
has String If present filter to apply in the search.
limit Integer 25 The number of entities to retrieve
asc Boolean true If the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)

Accept : loadbalancers

Error Codes

  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist
  • VM-1 - The requested virtual machine does not exist

Example

Change the state of a virtual machine


The power states that you can change a VM to are as follows:
  • OFF
  • PAUSED
  • ON

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/state

Roles : [ROLE_VAPP_PERFORM_ACTIONS]

Content-Type : virtualmachinestate Accept : acceptedrequest

Error Codes

  • GEN-18 - The requested operation is not supported by the hypervisor plugin
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation
  • VLAN-107 - The IP 223.116.22.4 is reserved
  • VLAN-51 - The IP 10.10.0.1 is in quarantine
  • VLAN-68 - The IP 10.10.0.1 is not available
  • VM-11 - The virtual machine is not in any hypervisor. Therefore the change of state cannot be applied
  • VM-4 - The virtual machine cannot change to the required state
  • VM-57 - The hypervisor where the virtual machine is deployed is not running properly. Contact your System Administrator

Example

Get the state of a virtual machine


GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/state

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE]

Example

Start a manual backup of a virtual machine


Request a manual backup of a virtual machine.

Return 202 - Accepted if Abiquo and the plugin are configured to execute a task. Otherwise 2.04 - No content

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/backup/action/request

Roles : [ROLE_VAPP_MANAGE_BACKUP]

Content-Type : ondemandbackup Accept : acceptedrequest

Error Codes

  • PUBLIC-5 - The requested operation is not supported in a public cloud region
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation

Example

Start a backup restore of a virtual machine


Request a restore from a backup of a virtual machine.

Return 202 - Accepted if abiquo and the plugin are configured to execute a task. Otherwise 2.04 - No content

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/backup/action/restore

Roles : [ROLE_VAPP_MANAGE_BACKUP]

Content-Type : restore Accept : acceptedrequest

Error Codes

  • PUBLIC-5 - The requested operation is not supported in a public cloud region
  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation

Example

List backup and restore results of a virtual machine


Retrieve the backup and restore results of a virtual machine.

The default order is by date and descendant.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/backup/results

Roles : [ROLE_VAPP_MANAGE_BACKUP]

Parameter Type Default Value Description
startwith Integer 0 The first element to be retrieved of the filtered search
limit Integer 25 The number of entities to retrieve
by String creationdate Order by
has String If present filter to apply in the search.
asc Boolean false If the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)

Accept : backupresults

Example

Configure a runlist of a chef enabled virtual machine


Configures the runlist for the virtual machine.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/config/runlist

Roles : [ROLE_VAPP_PERFORM_ACTIONS]

Content-Type : runlistelements Accept : runlistelements

Error Codes

  • CHEF-4 - The given runlist element does not exist on the Chef Server
  • CHEF-9 - The virtual machine cannot use Chef. Please check that the template is Chef enabled and the Enterprise can use Chef

Example

List current runlist extended of a chef enabled virtual machine


Get the extended runlist for the virtual machine.

The extended runlist contains all the roles and recipes available on the Chef server of the user's enterprise. It is the complete list, with a 'selected' flag indicating if the role/recipe is part of the runlist of the virtual machine.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/config/runlist

Roles : [ROLE_VAPP_CUSTOMISE_SETTINGS]

Accept : runlistelements

Error Codes

  • CHEF-9 - The virtual machine cannot use Chef. Please check that the template is Chef enabled and the Enterprise can use Chef

Example

List current runlist of a chef enabled virtual machine


Retrieve bootstrap configuration of a VM, which is the Chef runlist. . The runlist can contain roles and recipes that will be applied to the virtual machine during bootstrap in the defined order.

Note: to add a configuration to VM for use with cloud-init, use VM metadata.
For more information see the API tutorial on Manage virtual machine metadata via API.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/config/runlist

Roles : [ROLE_VAPP_CUSTOMISE_SETTINGS]

Accept : application/json

Get firewalls attached to a virtual machine


Retrieve the firewalls attached to a virtual machine as a collection of links.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/firewalls

Roles : [ROLE_VDC_ENUMERATE, ROLE_ASSIGN_FIREWALLS, ROLE_MANAGE_FIREWALLS]

Accept : links

Example

Update firewalls attached to a virtual machine


Change the firewalls attached to a virtual machine from the given collection of links.

If virtual machine state if NOT_ALLOCATED a task is not generated (204).

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/firewalls

Roles : [ROLE_ASSIGN_FIREWALLS, ROLE_MANAGE_FIREWALLS]

Content-Type : links Accept : acceptedrequest

Error Codes

  • FIREWALLPOLICY-5 - The requested firewall policy does not exist
  • VDC-9 - The provided virtual datacenter link is invalid
  • VM-121 - The virtual machine requires at least one IP while it is running
  • VM-13 - Virtual machine configuration actions can only be performed when the virtual machine is NOT_ALLOCATED or OFF

Example

Delete virtual machine metadata


Delete metedata information of a VM, which deletes startup-script, monitoring-metrics, and customized metadata.

DELETE https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metadata

Roles : [ROLE_VAPP_MANAGE_BACKUP, ROLE_VAPP_CUSTOMISE_SETTINGS]

Get virtual machine metadata


Retrieve the Abiquo metadata of a VM. A metadata object has the "metadata" root key.
  • The "startup-script" attribute contains a cloud-init configuration or a command that you could execute with Docker run.
  • The "monitoring-metrics" attribute contains VM metrics data with the names of the metrics the platform retrieves for this VM
  • The "chef" attribute contains attributes for VM Chef.
  • Users can create other attributes as required
For more information, see Manage virtual machine metadata via API

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metadata

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_MANAGE_BACKUP, ROLE_VAPP_CUSTOMISE_SETTINGS]

Accept : metadata

Example

Update virtual machine metadata


Modify virtual machine metadata information. This request will replace ALL existing metadata.
  • The startup-script attribute can contain a cloud-init configuration or a command that you could execute with Docker run, as entered on the VM dialog
  • The monitoring-metrics attribute contains VM metrics data with the names of the metrics that the platform will retrieve for this VM
  • The "chef" attribute contains attributes for VM Chef, as entered on the Chef tab of the VM dialog in the UI
  • Users can create other attributes as required
For more information, see Manage virtual machine metadata via API

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metadata

Roles : [ROLE_VAPP_MANAGE_BACKUP, ROLE_VAPP_CUSTOMISE_SETTINGS]

Content-Type : metadata Accept : metadata

Example

Create a metric metadata on a virtual machine


Creates a new metric metadata

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Error Codes

  • MONITORING-2 - Unable to create a new metric with null or empty name
  • MONITORING-9 - The metric name 'c5ae475b-e1f3-4097-9fae-a43e81c2a777' is already in use.
  • VM-1 - The requested virtual machine does not exist

Example

List metrics metadata on a virtual machine


Returns the metadata of all the available, built-in, and custom metrics for the given virtual machine

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricsmetadata

Error Codes

  • VM-1 - The requested virtual machine does not exist

Example

Push collectd values on a virtual machine


Push values gathered by collectd. The metric metadata may not exist, in this case metadata will be created automatically by the system.

The pushed data is expected as JSON format.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/collectd

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : application/json

Example

Get a metric metadata on a virtual machine


Returns the metadata of a specific metric (built-in or custom)

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricmetadata

Error Codes

  • MONITORING-1 - Unknown metric 'b0212ba4-662b-4611-9935-3be63eda4a93' for VirtualMachine with id '2068'
  • VM-1 - The requested virtual machine does not exist

Example

Get metric statistics on a virtual machine


By default, this query retrieves the available datapoints for the last hour using the 'Average' aggregator with a granularity of 60 seconds. All the defaults can be overridden.

Metric dimensions to filter by can be specified with query parameters in two ways:

  • Comma separated values: ?key1=value1,value2&key2=value3
  • Duplicated key parameters: ?key1=value1&key1=value2&key2=value3

Unknown metric dimensions are filtered and ignored.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_SHOW_METRICS]

Parameter Type Default Value Description
startrelative String Relative start time following the ISO 8601 duration (cannot contain years or months)
startabsolute Long Absolute start time, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
endabsolute Long Absolute end time, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
granularity Integer Aggregator granularity in seconds. A minimum of 60 seconds.
statistic Enum : average, maximum, minimum, sum, count, dev Aggregator to apply to the datapoints in the given time range

Accept : metric

Error Codes

  • MONITORING-1 - Metadata for metric 'c4c6527d-7041-4b77-b883-e93b6ffe153b' in namespace 'virtualmachine' not found
  • MONITORING-3 - End time must be later than start time
  • MONITORING-38 - The relative start time must be shorter than configured in 'abiquo.monitoring.max.statistic.period.days' property
  • MONITORING-39 - Absolute or relative queries are allowed but not both
  • MONITORING-4 - The supplied relative time contains years or months
  • MONITORING-6 - The supplied relative start time is invalid
  • MONITORING-8 - The minimum granularity is 60 seconds
  • VM-1 - The requested virtual machine does not exist

Push metric datapoints on a virtual machine


Push metric datapoints to a custom metric. The metric metadata may not exist, in this case metadata will be created automatically by the system.

Push is not allowed for built-in metrics.

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : datapoints

Example

Update a metric metadata on a virtual machine


Updates existing metric metadata

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Example

Create an alarm on a virtual machine


Creates a new alarm for an existing metric (built-in or custom)

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}/alarms

Roles : [ROLE_USERS_MANAGE_ALARMS]

Parameter Type Default Value Description
allowunknowndimensions boolean false If true the given dimensions are not validated against the available dimensions in the metric metadata. False by default.

Content-Type : alarm Accept : alarm

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • MONITORING-1 - Metadata for metric '19477b08-0d91-4a27-bc54-11c45e74b289' in namespace 'virtualmachine' not found
  • MONITORING-16 - The alarm name is required
  • MONITORING-17 - The alarm formula is required
  • MONITORING-18 - The alarm statistic is required
  • MONITORING-21 - The supplied formula does not exist
  • MONITORING-22 - The supplied statistic does not exist
  • MONITORING-37 - Unable to create alarm for virtual machine '5273' due it is cloned in a scaling group
  • MONITORING-40 - The alarm time range must be >= 1
  • MONITORING-41 - The datapoints limit must be >= 1
  • MONITORING-47 - Unable to create alarm with unknown metric dimensions
  • VM-1 - The requested virtual machine does not exist

Example

List alarms on a virtual machine


List the alarms associated with an existing metric

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}/alarms

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarms

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • VM-1 - The requested virtual machine does not exist

Example

Delete an alarm from a virtual machine


Deletes an existing alarm

DELETE https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}/alarms/{alarm}

Roles : [ROLE_USERS_MANAGE_ALARMS]

Example

Get an alarm on a virtual machine


Returns a concrete alarm

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}/alarms/{alarm}

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarm

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • MONITORING-13 - Alarm with uuid 8dace419-d146-48ab-b8f7-5774fd5040e5 not found
  • VM-1 - The requested virtual machine does not exist

Example

Update an alarm on a virtual machine


Updates an existing alarm

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/metrics/{metric}/alarms/{alarm}

Roles : [ROLE_USERS_MANAGE_ALARMS]

Parameter Type Default Value Description
allowunknowndimensions boolean false If true the given dimensions are not validated against the available dimensions in the metric metadata. False by default.

Content-Type : alarm Accept : alarm

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • MONITORING-13 - Alarm '6f88161b-24b7-48dd-87be-28438be094b3' not found for metric '685d6dc1-dfdf-473b-a781-923665ef8bca-allocatedVM' in namespace 'virtualmachine'
  • MONITORING-16 - The alarm name is required
  • MONITORING-17 - The alarm formula is required
  • MONITORING-18 - The alarm statistic is required
  • MONITORING-21 - The supplied formula does not exist
  • MONITORING-22 - The supplied statistic does not exist
  • MONITORING-40 - The alarm time range must be >= 1
  • MONITORING-41 - The datapoints limit must be >= 1
  • MONITORING-47 - Unable to create alarm with unknown metric dimensions
  • VM-1 - The requested virtual machine does not exist

Example

List virtual machine network configurations


Returns all the posible network configurations that a machine can have.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/network/configurations

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK]

Get virtual machine network configuration


Get the details of a network configuration that can be assigned to the virtual machine. Network configurations provide the default gateway address, DNS suffix, static routes, etc, that can be applied to a virtual machine.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/network/configurations/{configuration}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_CUSTOMISE_SETTINGS]

List nics of the virtual machine


Show details of the NICs attached to the virtual machine.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/network/nics

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_ASSIGN_VOLUME, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_CREATE_STATEFUL]

Accept : nics

Error Codes

  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist
  • VM-1 - The requested virtual machine does not exist

Example

List hard disks attached to a virtual machine


List the hard disks attached to the VM. Hard disks are created on the hypervisor's datastore, and are attached to the VM as additional hard disks.
Data stored on these external hard disks will NOT be persistent. The hard disks will be destroyed when the VM is undeployed. If persistent storage is needed, use external volumes instead.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/storage/disks

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_ASSIGN_NETWORK, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_CREATE_STATEFUL, ROLE_VAPP_ASSIGN_VOLUME]

Accept : harddisks

Error Codes

  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist
  • VM-1 - The requested virtual machine does not exist

Example

Get a hard disk attached to a virtual machine


Get the details of a hard disk attached to the virtual machine.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/storage/disks/{disk}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_ASSIGN_NETWORK]

Accept : harddisk

Error Codes

  • HD-1 - The requested hard disk does not exist

Example

List volumes attached to the virtual machine


List the volumes attached to the virtual machine. Volumes are external block devices that can be attached to the virtual machines using the iSCSI protocol.
Data stored in these external volumes will be persistent (even when the virtual machine is undeployed) until the volume is deleted from the target storage device.
Includes the volume of a persistent virtual machine template if apply.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/storage/volumes

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_VOLUME, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_ASSIGN_NETWORK, ROLE_MANAGE_HARD_DISKS, ROLE_VAPP_CREATE_INSTANCE, ROLE_VAPP_CREATE_STATEFUL]

Accept : volumes

Error Codes

  • VAPP-0 - The requested virtual appliance does not exist
  • VDC-0 - The requested virtual datacenter does not exist
  • VM-1 - The requested virtual machine does not exist

Example

Get a volume attached to a virtual machine


Get the details of a volume attached to the virtual machine.

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/virtualmachines/{virtualmachine}/storage/volumes/{volume}

Roles : [ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_ASSIGN_VOLUME, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_ASSIGN_NETWORK]

Accept : volume

Error Codes

  • VOL-21 - The volume is not attached to the virtual machine
  • VOL-3 - The volume does not exist

Example