VirtualAppliancesResource


Copy a virtual appliance to a virtual datacenter


Copies a virtual appliance to another virtual datacenter or the same one.

The request data entity can be a single link. To create it, copy the "edit" link from the virtual appliance and change "rel"="edit" to rel="original". Some preconditions must be met:

  • The state of the virtual appliance must be NOT_ALLOCATED. This means that none of its VMs can exist in the hypervisor or have a hypervisor assigned. In other words all the VMs must be in the NOT_ALLOCATED state.
  • All of the VMs must be deployable in the target virtual datacenter. This means that either the VM template must be of the same base format or it must have a finished conversion of that format.
If there are volumes attached to any of the VMs, they will be copied to the target virtualdatacenter.
The name of the newly created virtual appliance will be the same as the original plus _ (Copy)__

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

Roles : [ROLE_VDC_MANAGE_VAPP]

Content-Type : cp-virtualappliance Accept : virtualappliance

Error Codes

  • VAPP-10 - The virtual appliance cannot be moved or copied because it contains virtual machine templates that are not compatible with the target hypervisor
  • VAPP-11 - The virtual appliance cannot be copied because it contains persistent virtual machine templates
  • VAPP-13 - The virtual appliance cannot be copied in this state. It should be NOT_DEPLOYED
  • VAPP-18 - The virtual appliance cannot be moved or copied because the target virtual datacenter is not in the same enterprise
  • VAPP-7 - The virtual appliance cannot be moved or copied because the target virtual datacenter is not in the same datacenter
  • VAPP-9 - The virtual appliance cannot be moved or copied because it contains captured virtual machines

Example

Create a virtual appliance


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

Roles : [ROLE_VDC_MANAGE_VAPP]

Content-Type : virtualappliance Accept : virtualappliance

Error Codes

  • CONSTR-LENGTH - The property 'name' length must be between 1 and 255.
  • GEN-4 - Not enough permissions to perform this action

Example

Create a virtual appliance from a virtual appliance spec


Create a virtual appliance within a virtual datacenter from a virtual appliance spec

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

Roles : [ROLE_VDC_MANAGE_VAPP]

Content-Type : virtualappliancespec Accept : virtualappliance

Example

List virtual appliances


Retrieves virtual appliances from a virtual datacenter

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

Roles : [ROLE_VDC_ENUMERATE]

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 name Order by
has String If present filter to apply in the search.
asc Boolean true If the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)
restricted Boolean If true, filter to display restricted virtual appliances

Example

Move a virtual appliance to a virtual datacenter


Moves a virtual appliance to another virtual datacenter.

The request data entity can be a single link. To create it, copy the "edit" link from the virtual appliance and change "rel"="edit" to rel="source". Some preconditions must be met:

  • The state of the virtual appliance must be NOT_ALLOCATED. This means that none of its VMs can exist in the hypervisor or have a hypervisor assigned. In other words all the VMs must be in the NOT_ALLOCATED state.
  • All of the VMs must be deployable in the target virtual datacenter. This means that either the VM template must be of the same base format or it must have a finished conversion of that format.
If there are volumes attached to any of the virtual machines, they will also be moved to the target virtualdatacenter.
The network configuration is not moved to the target virtual datacenter. Instead Abiquo will assign IPs that are available in the target virtual datacenter.
If the virtual appliance being moved is an ESX or ESXi hypervisor type and it is being moved to a virtual datacenter with a different virtualization technology all of the extra hard disks that may be on any virtual machine will be deleted. Otherwise the hard disks will be moved.

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

Roles : [ROLE_VDC_MANAGE_VAPP]

Content-Type : mv-virtualappliance Accept : virtualappliance

Error Codes

  • VAPP-10 - The virtual appliance cannot be moved or copied because it contains virtual machine templates that are not compatible with the target hypervisor
  • VAPP-18 - The virtual appliance cannot be moved or copied because the target virtual datacenter is not in the same enterprise
  • VAPP-7 - The virtual appliance cannot be moved or copied because the target virtual datacenter is not in the same datacenter
  • VAPP-8 - The virtual appliance cannot be moved in this state. It should be NOT_DEPLOYED
  • VAPP-9 - The virtual appliance cannot be moved or copied because it contains captured virtual machines

Example

Delete a virtual appliance


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

Roles : [ROLE_VDC_MANAGE_VAPP]

Example

Get a virtual appliance


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

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]

Parameter Type Default Value Description
expand String Use 'last_task' to include the last task of the virtual appliance

Accept : virtualappliance

Error Codes

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

Example

Update a virtual appliance


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

Roles : [ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS]

Content-Type : virtualappliance Accept : virtualappliance

Error Codes

  • CONSTR-LENGTH - The property 'name' length must be between 1 and 255.
  • GEN-4 - Not enough permissions to perform this action

Example

List tasks for a virtual appliance


Return all tasks for a virtual appliance. Displays the tasks of the virtual appliance. Tasks are a set of jobs. Any of these tasks may still be in progress.

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

Roles : [ROLE_VDC_ENUMERATE]

Accept : tasks

Get a task for a virtual appliance


Retrieve a task for a virtual appliance. Displays a specific task of the virtual appliance. Tasks are a set of jobs. Any of these tasks may still be in progress. Every task has a UUID.

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

Roles : [ROLE_VDC_ENUMERATE]

Accept : task

Deploy a virtual appliance


Deploy all the VMs in the virtual appliance with the given options. This request returns a 202 HTTP code (accepted) and a list of URIs where you can track each deploy (one for each VM in the virtual appliance).

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

Roles : [ROLE_VAPP_DEPLOY_UNDEPLOY]

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

Accept : acceptedrequest

Error Codes

  • DSTIER-8 - Cannot deploy a virtual machine 'vmNotAllocated0.9458709599095104' with any disk without enabled datastore tiers
  • NAT-RULE-12 - Cannot create NAT rule because the NAT IP is in quarantine
  • VAPP-3 - The virtual appliance is deployed
  • VLAN-107 - The IP 124.52.232.116 is reserved
  • VLAN-51 - The IP 10.10.0.1 is in quarantine
  • VM-110 - Virtual machine is using a template without a system disk file. It cannot be deployed.
  • 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

Example

Get the current and new estimate price for a virtual appliance


Returns the current estimate cost for the virtual appliance and the new estimate cost after adding the given VM. The link with a "rel" value "virtualmachine" is used to send the virtual machine to add to the new virtual appliance estimated price.

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

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_DEPLOY_UNDEPLOY]

Content-Type : links Accept : virtualapplianceprices

Error Codes

  • VDC-0 - The requested virtual datacenter does not exist

Example

Get the pricing estimate for a virtual appliance


Returns a message with the cost estimate for the virtual appliance.

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

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_DEPLOY_UNDEPLOY]

Accept : text/plain

Example

Get the pricing estimate for a virtual appliance with additonal vm


Returns a message with the estimated cost of the virtual appliance after adding the given VM. The link with a "rel" value "virtualmachine" is used to send the virtual machine to add to the new virtual appliance estimated price.

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

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_DEPLOY_UNDEPLOY]

Content-Type : links Accept : text/plain

Error Codes

  • VDC-0 - The requested virtual datacenter does not exist

Example

Create a virtual appliance spec


Create a virtual appliance spec and save its JSON representation.

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

Roles : [ROLE_MANAGE_VAPP_SPEC]

Content-Type : virtualappliancespec Accept : virtualappliancespec

Error Codes

  • LOCATION-4 - The location does not exist
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example

Create a virtual appliance spec version


Create a version of a virtual appliance spec and save its JSON representation.

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

Roles : [ROLE_MANAGE_VAPP_SPEC]

Content-Type : virtualappliancespec Accept : virtualappliancespec

Error Codes

  • SPEC-9 - Cannot create a version of a spec that belongs to another enterprise

Example

Undeploy a virtual appliance


Perform an undeploy of all the VMs that are DEPLOYED (in the provider or hypervisor). After an undeploy, all the VMs with be NOT_ALLOCATED in Abiquo. If an undeploy is successful, all the VMs will be deleted from the hypervisor. If any of the VMs are in the ON state, Abiquo will power them off before deconfiguring them. You can also set the force undeploy parameter in the VM task entity. This force option will also delete imported VMs. This request returns a 202 HTTP code (Accepted) and a list of URIs where you can track each undeploy (one for each VM in the virtual appliance). If there are no VMs to undeploy, it returns a 204 HTTP code (No Content).

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

Roles : [ROLE_VAPP_DEPLOY_UNDEPLOY]

Content-Type : virtualmachinetask Accept : acceptedrequest

Error Codes

  • SCALING-GROUP-16 - The scaling group must be in maintenance mode in order to apply the requested operation

Example

Search for alarms on a virtual appliance


Retrieve alarms from the virtual appliance, and with the recursive options include the alarms of the following entities on the cloud path:
  • Scaling groups
  • Virtual machines

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/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'
recursive Boolean false If true, the search will be recursive. False by default.

Accept : alarms

Error Codes

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

Example

Get the state of a virtual appliance


Retrieves the state of the virtual appliance.
This state is inferred from the state of the VMs in the virtual appliance

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

Roles : [ROLE_VDC_ENUMERATE, ROLE_VAPP_CUSTOMISE_SETTINGS]

Example

Create a metric metadata on a virtual appliance


Creates a new metric metadata

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/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 '450cbcff-127d-48bf-8c1b-01a462fd8811' is already in use.
  • VAPP-0 - The requested virtual appliance does not exist

Example

List metrics metadata on a virtual appliance


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

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

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricsmetadata

Error Codes

  • VAPP-0 - The requested virtual appliance does not exist

Example

Push collectd values on a virtual appliance


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}/metrics/collectd

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : application/json

Example

Get a metric metadata on a virtual appliance


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

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

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricmetadata

Error Codes

  • MONITORING-1 - Unknown metric '37257972-5dab-4a2f-9a34-2feb0b6a22af' for VirtualAppliance with id '1315'
  • VAPP-0 - The requested virtual appliance does not exist

Example

Get a metric statistics on a virtual appliance


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}/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 '443fe782-45d3-46c0-be2a-e235bcc38268' in namespace 'virtualappliance' 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
  • VAPP-0 - The requested virtual appliance does not exist

Push metric datapoints on a virtual appliance


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}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : datapoints

Example

Update a metric metadata on a virtual appliance


Updates existing metric metadata

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

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Example

Create an alarm on a virtual appliance


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

POST https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/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 '95da1a62-e2a2-41d2-a04e-fc4e92118ea6' in namespace 'virtualappliance' 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
  • VAPP-0 - The requested virtual appliance does not exist

Example

List alarms on a virtual appliance


List the alarms associated with an existing metric

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

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarms

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • VAPP-0 - The requested virtual appliance does not exist

Example

Delete an alarm from a virtual appliance


Deletes an existing alarm

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

Roles : [ROLE_USERS_MANAGE_ALARMS]

Example

Get an alarm on a virtual appliance


Returns a concrete alarm

GET https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/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 3803930f-6625-4563-8a6e-a9e69a62efa9 not found
  • VAPP-0 - The requested virtual appliance does not exist

Example

Update an alarm on a virtual appliance


Updates an existing alarm

PUT https://example.com/api/cloud/virtualdatacenters/{virtualdatacenter}/virtualappliances/{virtualappliance}/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 '9862b638-5765-4b13-9b64-9ab83c9ef450' not found for metric '1ec1779d-0b12-421d-a53d-20c729de6ae5-1341' in namespace 'virtualappliance'
  • 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
  • VAPP-0 - The requested virtual appliance does not exist

Example