MachinesResource


Create a machine


Creates a machine.

The best way to create a machine is to call the Retrieve remote machine information {@link DatacenterResource#listRemoteMachines(Integer, String, String, Integer, String, String, String, Integer, String, String, String, Integer, String, String, IRESTBuilder)} to get the machine entity. Modify it to enable network interfaces and datastores, then supply the machine entity with this request.

What to modify from the listRemoteMachine:

To enable at least one network interface:
Add a rel link to a network service type at the top of the networkinterface section. For example, to add the defaut network service type of "Service network" add: {link rel="networkservicetype" type="application/vnd.abiquo.networkservicetype+xml" href=" http://10.60.13.4:80/api/admin/datacenters/1/networkservicetypes/1"/ }

To enable at least one datastore:
All of the datastores are returned with the enabled attribute set to false. Edit the machine to set enabled to true for at least one datastore before creating the machine

Add the credentials if necessary.

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Content-Type : machine Accept : machine

Error Codes

  • DC-0 - The requested datacenter does not exist
  • GEN-17 - The plugin type was not found
  • GEN-19 - The supplied connection is not valid for the hypervisor plugin
  • HYPERVISOR-2 - Invalid hypervisor service IP. A hypervisor with that service IP already exists
  • HYPERVISOR-3 - Invalid hypervisor endpoint information. A hypervisor with that connection already exists
  • MACHINE-10 - The IQN of the target physical machine is not set
  • MACHINE-18 - Invalid link to network service type
  • MACHINE-19 - Duplicate network service type for network interfaces
  • MACHINE-21 - At least one network interface must have a network service type assigned
  • MACHINE-25 - Duplicate network interface name
  • NST-2 - The requested network service type does not exist
  • RS-2 - The remote service does not exist

Example

List machines


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

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_USERS_MANAGE_RESERVED_MACHINES, ROLE_VM_RELOCATE]

Parameter Type Default Value Description
filter String Name based filter

Accept : machines

Example

List machines as links


Retrieves all machines from a rack but each machine is a collection of links, not the full machine entity

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

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_USERS_MANAGE_RESERVED_MACHINES, ROLE_VM_RELOCATE]

Parameter Type Default Value Description
filter String Name based filter

Example

List machines that can be reserved


Retrieve a list of machines that can be reserved (bookable machines).

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS, ROLE_USERS_MANAGE_RESERVED_MACHINES]

Parameter Type Default Value Description
enterprise Integer If present, filter by enterprise identifier

Accept : machines

Example

Delete a machine


When you delete a machine with VMs deployed on it, the VMs will become unallocated in the platform, but they will not be changed in the provider. If you add the same machine again, the VMs may be synchronized with the import VMs feature.

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Example

Get a machine


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

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_USERS_MANAGE_RESERVED_MACHINES, ROLE_VM_RELOCATE]

Accept : machine

Error Codes

  • MACHINE-0 - The requested machine does not exist

Example

List hypervisor metrics


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

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_USERS_MANAGE_RESERVED_MACHINES, ROLE_VM_RELOCATE]

Accept : metrics

Update a machine


This request allows you to update a physical machine, for example, to change datastores.
Add the credentials to the machine entity because they are not returned by the get operation

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Content-Type : machine Accept : machine

Error Codes

  • DATASTORE-7 - The datastore is not assigned to that machine
  • DATASTORE-8 - Missing datastore link
  • DATASTORE-9 - Invalid datastore link
  • DC-0 - The requested datacenter does not exist
  • GEN-1 - Identifier cannot be 0
  • HYPERVISOR-3 - Invalid hypervisor endpoint information. A hypervisor with that connection already exists
  • MACHINE-1 - The machine is not assigned to the datacenter or rack
  • MACHINE-5 - The requested state change is not valid

Example

Get the state of a machine chassis using ipmi


Checks the state of the machine chassis using the IPMI configuration

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Accept : machineipmistate

Get the state of a machine


Checks the machine state in the plugin

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
sync boolean false If true, update the database with the value returned by the plugin

Accept : machinestate

Error Codes

  • DC-0 - The requested datacenter does not exist
  • MACHINE-1 - The machine is not assigned to the datacenter or rack

Example

Refresh the nics of a machine


Refresh the NICs of the physical machine. The refresh will save the NICs in the database without changing the network service types.

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Accept : machine

Reenable a machine after high availability


Manually enable a physical machine again after HA processes disabled it.

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

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Accept : machine

Send email to machine users


Send an email in the context of a machine

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

Roles : [ROLE_AUTHENTICATED]

Parameter Type Default Value Description
sendermail boolean false If true, the user performing this request will appear as sender of the email
admins boolean false If true, send the email to managers of the enterprises that are using the machien, which by default are enterprise admins
owners boolean false If true, send the email to the owners of VMs deployed on the machine

Content-Type : mail

Example

Search for alarms on a machine


Retrieve alarms from the machine and with the recursive option also retrieve the alarms for the following entities on the infrastructure path:
  • Virtual machines

GET https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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. The default value is false

Accept : alarms

Create a metric metadata on a machine


Creates a new metric metadata

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

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Error Codes

  • MACHINE-0 - The requested machine does not exist
  • MONITORING-2 - Unable to create a new metric with null or empty name
  • MONITORING-9 - The metric name '1a180c4a-8ff5-43b4-959e-2b739d5dae13' is already in use.

Example

List metrics metadata on a machine


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

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

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricsmetadata

Error Codes

  • MACHINE-0 - The requested machine does not exist

Example

Push collectd values on a 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/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/metrics/collectd

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : application/json

Example

Get a metric metadata on a machine


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

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

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricmetadata

Error Codes

  • MACHINE-0 - The requested machine does not exist
  • MONITORING-1 - Unknown metric '7bf9729e-adeb-443f-9f1e-7ecbd2ab0804' for Machine with id '2196'

Example

Get a metric statistics 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}/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

  • MACHINE-0 - The requested machine does not exist
  • MONITORING-1 - Metadata for metric '57709e9a-8dae-4fc5-bd94-1ab0e639c405' in namespace 'physicalmachine' 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

Push metric datapoints on a 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/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : datapoints

Example

Update a metric metadata on a machine


Updates existing metric metadata

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

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Example

Create an alarm on a machine


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

POST https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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
  • MACHINE-0 - The requested machine does not exist
  • MONITORING-1 - Metadata for metric 'c98c299a-458a-43e3-b40d-06f0d88fe083' in namespace 'physicalmachine' 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

Example

List alarms on a machine


List the alarms associated with an existing metric

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

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarms

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • MACHINE-0 - The requested machine does not exist

Example

Delete an alarm from a machine


Deletes an existing alarm

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

Roles : [ROLE_USERS_MANAGE_ALARMS]

Example

Get an alarm on a machine


Returns a concrete alarm

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

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarm

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • MACHINE-0 - The requested machine does not exist
  • MONITORING-13 - Alarm with uuid d5131b30-d68a-4d23-aea6-d8456b9a5f40 not found

Example

Update an alarm on a machine


Updates an existing alarm

PUT https://example.com/api/admin/datacenters/{datacenter}/racks/{rack}/machines/{machine}/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
  • MACHINE-0 - The requested machine does not exist
  • MONITORING-13 - Alarm with uuid cafc022f-b1db-4c0c-ba7f-fe3ec0399cfc 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

Example