VirtualMachinesInfrastructureResource


Delete virtual machines that are not managed on a machine


Delete from Abiquo all VMs on a machine that are not managed by Abiquo. To access these VMs, you can retrieve them again.
VMs that are not managed by the platform are VMs that were retrieved from the physical machine but not captured, or VMs that were captured and later released.

DELETE https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Example

List virtual machines deployed on a machine


Retrieve VMs deployed on a physical machine.

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
sync Boolean false If true, obtain details of all VMs running in the hypervisor, including those that are not managed by Abiquo. The request will not store new VMs, but you can capture these VMs to manage them in Abiquo using the returned entities.

Accept : virtualmachines

Example

List virtual machines flat deployed in a machine


Retrieve VMS deployed on a machine with expanded resources instead of links

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
sync Boolean false If true, obtain details of all VMs running in the hypervisor, including those that are not managed by Abiquo. The request will not store new VMs, but you can capture these VMs to manage them in Abiquo using the returned objects

Error Codes

  • MACHINE-17 - The state of the physical machine does not allow retrieval of virtual machines
  • MACHINE-31 - Cannot retrieve virtual machines. A VM with name 'virtualmachine-0' already exists in another datacenter.

Example

Get a virtual machine deployed on a machine


Retrieve a virtual machine deployed in a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Accept : virtualmachine

Example

Get a virtual machine flat deployed on a machine


Retrieve a VM deployed on a machine with expanded resources instead of links

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
sync boolean false If true, obtain details of the VM running in the hypervisor. The request will not update the VM, but you can update it using the retrieved object

Error Codes

  • NC-8 - The requested virtual machine was not found on the remote hypervisor
  • RS-0 - The remote service is not assigned to the datacenter
  • VM-125 - The MAC address of the remote IP is required, check the remote VM configuration
  • VM-126 - The identifier of the remote hard disk is required, check the remote VM configuration
  • VM-127 - The identifier of the remote volume is required, check the remote VM configuration

Example

List hard disks of a virtual machine deployed on a machine


Retrieve hard disks attached to a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/action/disk

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_PHYS_DC_RETRIEVE_DETAILS]

Accept : harddisks

List nics of a virtual machine deployed on a machine


GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/action/nics

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_PHYS_DC_RETRIEVE_DETAILS]

Accept : nics

Send email to users of a virtual machine deployed on a machine


Send an email about a VM deployed on a machine

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/action/sendmail

Roles : [ROLE_AUTHENTICATED]

Parameter Type Default Value Description
sendermail boolean false If true, the user performing this request will appear as the sender of the email
admins boolean false If true, send the email to enterprise admins of the tenant that owns the VM (users in the enterprise with USERS_DEFINE_AS_MANAGER role)
owners boolean false If true, send the email to the owners of the VM

Content-Type : mail

List volumes of a virtual machine deployed on a machine


Retrieve volumes attached to a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/action/volumes

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_PHYS_DC_RETRIEVE_DETAILS]

Accept : volumes

Example

Search for alarms on a virtual machine deployed on a machine


Retrieve alarms from a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 order ascending by specified field in 'by' parameter, otherwise order descending. By default 'true'.
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

Get console access of a virtual machine deployed on a machine


Retrieve the information required to connect to a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/config/rdpaccess

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_PHYS_DC_RETRIEVE_DETAILS]

Error Codes

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

Example

Create a metric metadata on a virtual machine deployed on a machine


Creates new metric metadata for a VM deployed on a machine

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 '562897ac-7bd8-4739-b826-b86d3794228b' is already in use.
  • VM-1 - The requested virtual machine does not exist

Example

List metric metadata on a virtual machine deployed on a machine


Retrieves the metadata of all the available, built-in, and custom metrics for a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 deployed in a machine


Push values gathered by collectd. If metric metadata does not exist, it will be created automatically by the system.

The data is expected in JSON format.

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/metrics/collectd

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : application/json

Example

Get a metric metadata on a virtual machine deployed on a machine


Retrieves the metadata of a specific metric (built-in or custom) on a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricmetadata

Error Codes

  • MONITORING-1 - Unknown metric '6d273f91-e192-4e3c-87a5-df17938aa6d4' for VirtualMachine with id '1995'
  • VM-1 - The requested virtual machine does not exist

Example

Get a metric statistics on a virtual machine deployed on a 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/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 Granularity of the aggregator 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 'b172d99b-6276-420b-a8db-7782d379dd02' 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 deployed in a machine


Push metric datapoints to a custom metric on a VM deployed on a machine. If the metric metadata does not exist, it will be created automatically by the system.

Push is not allowed for built-in metrics.

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : datapoints

Example

Update a metric metadata on a virtual machine deployed on a machine


Updates existing metric metadata for a VM deployed on a machine

PUT https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Example

Create an alarm on a virtual machine deployed on a machine


Creates a new alarm for an existing metric (built-in or custom) on a VM deployed on a machine

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 '2518168d-1359-4e7d-aed2-07593a568cea' 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-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 deployed on a machine


List the alarms associated with an existing metric on a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 deployed on a machine


DELETE https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/virtualmachines/{virtualmachine}/metrics/{metric}/alarms/{alarm}

Roles : [ROLE_USERS_MANAGE_ALARMS]

Example

Get an alarm on a virtual machine deployed on a machine


Returns an alarm on a metric on a VM deployed on a machine

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 6e198f74-4181-4a93-b13f-6a11ddfc8ca8 not found
  • VM-1 - The requested virtual machine does not exist

Example

Update an alarm on a virtual machine deployed on a machine


PUT https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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 '1b4348a0-85fc-41e1-a374-065e9900aeb0' not found for metric '894f834e-5778-4e5c-9f1e-828da4804326-capturedvm' 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