DatacentersResource


Create a datacenter


You can create a datacenter with remote services that are already registered in the platform or new remote services. To use existing remote services, include links to them with rel 'remoteservice' in the datacenter entity. To create new remote services, add them as remote service entities in the remote services attribute of the datacenter entity. If an error occurs the response will contain configuration errors but the platform will still create the datacenter, even if it is missing some remote services.

POST https://example.com/api/admin/datacenters

Roles : [ROLE_PHYS_DC_MANAGE]

Content-Type : datacenter Accept : datacenter

Error Codes

  • RS-32 - More than one remote service of the same type is not allowed in a datacenter

Example

List datacenter names and ids


Retrieves a list of datacenter entities with only two attributes, the identifier and the name

GET https://example.com/api/admin/datacenters

Roles : [ROLE_PHYS_DC_ENUMERATE, ROLE_VDC_MANAGE, ROLE_USERS_MANAGE_ENTERPRISE, ROLE_PRICING_VIEW, ROLE_APPLIB_VIEW, ROLE_USERS_VIEW]

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)
idEnterprise Integer If present, filter by the identifier of an enterprise
pricing Integer If present, filter by the identifier of a pricing template
idScope Integer If present, filter by the identifier of a scope

Accept : datacenterslight

Example

List datacenters


GET https://example.com/api/admin/datacenters

Roles : [ROLE_PHYS_DC_ENUMERATE, ROLE_VDC_MANAGE, ROLE_USERS_MANAGE_ENTERPRISE, ROLE_PRICING_VIEW, ROLE_APPLIB_VIEW, ROLE_USERS_VIEW]

Parameter Type Default Value Description
idEnterprise Integer If present, filter by the identifier of an enterprise
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)
pricing Integer If present, filter by the identifier of a pricing template
idScope Integer If present, filter by the identifier of a scope

Accept : datacenters

Example

List datacenters with their remote services


GET https://example.com/api/admin/datacenters

Roles : [ROLE_PHYS_DC_ENUMERATE, ROLE_VDC_MANAGE, ROLE_USERS_MANAGE_ENTERPRISE, ROLE_PRICING_VIEW, ROLE_APPLIB_VIEW, ROLE_USERS_VIEW]

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)
idScope Integer If present, filter by the identifier of a scope
idEnterprise Integer If present, filter by the identifier of an enterprise

Accept : datacenters_rs

Example

Search for alarms on datacenters


Retrieve alarms from the datacenters, optionally the search could be recursive and includes the alarms of the entities:
  • Racks
  • Virtual machines
  • Machines
  • Virtual machines

GET https://example.com/api/admin/datacenters/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

Delete a datacenter


Deletes a datacenter and the remote services that are exclusive to the datacenter

DELETE https://example.com/api/admin/datacenters/{datacenter}

Roles : [ROLE_PHYS_DC_MANAGE]

Example

Get a datacenter


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

Roles : [ROLE_PHYS_DC_ENUMERATE, ROLE_USERS_MANAGE_ENTERPRISE, ROLE_APPLIB_ALLOW_MODIFY]

Accept : datacenter

Error Codes

  • DC-0 - The requested datacenter does not exist

Example

Update a datacenter


PUT https://example.com/api/admin/datacenters/{datacenter}

Roles : [ROLE_PHYS_DC_MANAGE]

Content-Type : datacenter Accept : datacenter

Error Codes

  • DC-3 - There is already a datacenter with that name
  • RS-32 - More than one remote service of the same type is not allowed in a datacenter
  • RS-33 - Cannot unassign the Monitor Manager because the datacenter has monitors
  • RS-35 - Cannot detach not reusable remote service

Example

Get the state of the ipmi configuration of a remote machine


Check the IPMI configuration of a remote machine given its user, password, and port. This machine does not need to be managed by Abiquo. Behind the scenes, this method uses the Discovery Manager remote service.

GET https://example.com/api/admin/datacenters/{datacenter}/action/checkmachineipmistate

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
ip String The IP of the target cloud node.
user String The hypervisor user.
password String The hypervisor password.
port Integer The hypervisor port.

Accept : machineipmistate

Get the state of a remote machine


This request is used to check the state of a remote machine given its user, password and hypervisor type. This machine does not need to be managed by Abiquo. The response entity is a MachineState. Behind the scenes, this method uses the Discovery Manager remote service.

GET https://example.com/api/admin/datacenters/{datacenter}/action/checkmachinestate

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
hypervisor String The cloud node hypervisor type.
ip String The IP of the target cloud node.
port Integer The hypervisor port.
user String The hypervisor user.
password String The hypervisor password.
managerip String The manager IP of the target cloud node.
managerport Integer The hypervisor manager port.
manageruser String The hypervisor manager user.
managerpassword String The hypervisor manager password.
agentip String The agent IP of the target cloud node.
agentport Integer The hypervisor agent port.
agentuser String The hypervisor agent user.
agentpassword String The hypervisor agent password.

Accept : machinestate

List remote machines


Retrieve a list of remote machines that you can use to create multiple physical machines. All the datastores have the ''enabled'' attribute set to "false". Before you call the method to create a physical machine, you must edit the machine entity to enable at least one datastore.

GET https://example.com/api/admin/datacenters/{datacenter}/action/discover

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
hypervisor String The cloud node hypervisor type.
ip String The IP of the target cloud node.
port Integer The hypervisor port.
user String The hypervisor user.
password String The hypervisor password.
managerip String The manager IP of the target cloud node.
managerport Integer The hypervisor manager port.
manageruser String The hypervisor manager user.
managerpassword String The hypervisor manager password.
agentip String The agent IP of the target cloud node.
agentport Integer The hypervisor agent port.
agentuser String The hypervisor agent user.
agentpassword String The hypervisor agent password.

Accept : machines

List remote managed machine locators


Retrieve a list of locators of machines that are managed by the manager with the connection info supplied

GET https://example.com/api/admin/datacenters/{datacenter}/action/discover

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Parameter Type Default Value Description
hypervisor String The cloud node hypervisor type.
ip String The IP of the target cloud node.
port Integer The hypervisor port.
user String The hypervisor user.
password String The hypervisor password.
managerip String The manager IP of the target cloud node.
managerport Integer The hypervisor manager port.
manageruser String The hypervisor manager user.
managerpassword String The hypervisor manager password.
agentip String The agent IP of the target cloud node.
agentport Integer The hypervisor agent port.
agentuser String The hypervisor agent user.
agentpassword String The hypervisor agent password.

List enterprises that are using the datacenter


GET https://example.com/api/admin/datacenters/{datacenter}/action/enterprises

Roles : [ROLE_PHYS_DC_RETRIEVE_RESOURCE_USAGE, ROLE_PHYS_DC_ENUMERATE]

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

Accept : enterprises

Example

Update used resources of a datacenter


Update the resources used from the datacenter for machines and VMs

PUT https://example.com/api/admin/datacenters/{datacenter}/action/updateusedresources

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_SERVERS]

Search alarms of a datacenter


Retrieves datacenter alarms and with the recursive option it also retrieves the alarms on the infrastructure path for following entities:
  • Racks>/li>
  • Machines
  • Virtual machines

GET https://example.com/api/admin/datacenters/{datacenter}/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

List the datastores of a datacenter


Retrieve the datastores of a datacenter and optionally obtain those that are available to add to the given datastore tier.

Shared datastores are represented as one datastore with ''shared'' links to the other datastore/s using the same physical datastore.

GET https://example.com/api/admin/datacenters/{datacenter}/datastores

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS]

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)
availabletoadd String if present, filter datastores that can be added to the specified datastore tier name

Accept : datastores

Example

List available hypervisor types in a datacenter


List the hypervisor types of the hypervisors in the datacenter

GET https://example.com/api/admin/datacenters/{datacenter}/hypervisors

Roles : [ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_VDC_MANAGE, ROLE_APPLIB_ALLOW_MODIFY]

Accept : hypervisortypes

Error Codes

  • DC-0 - The requested datacenter does not exist

Example

List limits of a datacenter


Retrieves the limits for enterprises that are allowed to use the datacenter

GET https://example.com/api/admin/datacenters/{datacenter}/action/getlimits

Roles : [ROLE_PHYS_DC_RETRIEVE_RESOURCE_USAGE]

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

Accept : limits

Example

Create a backup manager


Create a backup manager for the datacenter

POST https://example.com/api/admin/datacenters/{datacenter}/backupmanager

Roles : [ROLE_PHYS_DC_ALLOW_BACKUP_CONFIG]

Content-Type : backupmanager Accept : backupmanager

Delete a backup manager


Delete the backup manager for the datacenter

DELETE https://example.com/api/admin/datacenters/{datacenter}/backupmanager

Roles : [ROLE_PHYS_DC_ALLOW_BACKUP_CONFIG]

Get a backup manager


Get the backup manager for the datacenter

GET https://example.com/api/admin/datacenters/{datacenter}/backupmanager

Roles : [ROLE_PHYS_DC_ALLOW_BACKUP_CONFIG]

Accept : backupmanager

Update a backup manager


When you update the backup manager for a datacenter, you cannot change the type. You only need to supply the user and password attributes if you wish to change them.

PUT https://example.com/api/admin/datacenters/{datacenter}/backupmanager

Roles : [ROLE_PHYS_DC_ALLOW_BACKUP_CONFIG]

Content-Type : backupmanager Accept : backupmanager

Get backup properties in a datacenter


GET https://example.com/api/admin/datacenters/{datacenter}/backupproperties

Roles : [ROLE_PHYS_DC_ALLOW_BACKUP_CONFIG, ROLE_USERS_MANAGE_ENTERPRISE]

Update backup properties in a datacenter


PUT https://example.com/api/admin/datacenters/{datacenter}/backupproperties

Roles : [ROLE_PHYS_DC_ALLOW_BACKUP_CONFIG]

Create a metric metadata on a datacenter


Creates metadata for a new metric on a datacenter

POST https://example.com/api/admin/datacenters/{datacenter}/metrics

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Error Codes

  • DC-0 - The requested datacenter does not exist
  • MONITORING-2 - Unable to create a new metric with null or empty name
  • MONITORING-9 - The metric name 'a954393e-7748-4c85-9a75-ab803b4ce46e' is already in use.

Example

List metrics metadata on a datacenter


Retrieves the metadata of all built-in and custom metrics on the datacenter

GET https://example.com/api/admin/datacenters/{datacenter}/metrics

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricsmetadata

Error Codes

  • DC-0 - The requested datacenter does not exist

Example

Push collectd values on a datacenter


Push values gathered by collectd. If there is no metadata for the metric, the platform will create it automatically.

The data should be in JSON format.

POST https://example.com/api/admin/datacenters/{datacenter}/metrics/collectd

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : application/json

Example

Get a metric metadata on a datacenter


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

GET https://example.com/api/admin/datacenters/{datacenter}/metrics/{metric}

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricmetadata

Error Codes

  • DC-0 - The requested datacenter does not exist
  • MONITORING-1 - Unknown metric '04ce2e23-3420-41d0-ba80-21572666208b' for Datacenter with id '4104'

Example

Get a metric statistics on a datacenter


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

  • DC-0 - The requested datacenter does not exist
  • MONITORING-1 - Metadata for metric '789015e9-34ac-4563-9860-bc61cf0f2637' in namespace 'datacenter' 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 datacenter


Push metric datapoints to a custom metric. If there is no metadata for the metric, the platform will create it automatically.

Push is not allowed for built-in metrics.

POST https://example.com/api/admin/datacenters/{datacenter}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : datapoints

Example

Update a metric metadata on a datacenter


Updates existing metadata for a metric on a datacenter

PUT https://example.com/api/admin/datacenters/{datacenter}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Example

Create an alarm on a datacenter


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

POST https://example.com/api/admin/datacenters/{datacenter}/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

  • DC-0 - The requested datacenter does not exist
  • GEN-4 - Not enough permissions to perform this action
  • MONITORING-1 - Metadata for metric '31353756-a9f6-4bef-be48-12f05d6b5d06' in namespace 'datacenter' 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 datacenter


List the alarms associated with an existing metric

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

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarms

Error Codes

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

Example

Delete an alarm from a datacenter


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

Roles : [ROLE_USERS_MANAGE_ALARMS]

Example

Get an alarm on a datacenter


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

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarm

Error Codes

  • DC-0 - The requested datacenter does not exist
  • GEN-4 - Not enough permissions to perform this action
  • MONITORING-13 - Alarm with uuid 306fd07d-6653-492a-8bd4-652b047ebb7c not found

Example

Update an alarm on a datacenter


PUT https://example.com/api/admin/datacenters/{datacenter}/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

  • DC-0 - The requested datacenter does not exist
  • GEN-4 - Not enough permissions to perform this action
  • MONITORING-13 - Alarm 'de5c5285-2836-4443-8aed-9e7ade70c313' not found for metric 'bc7a9eca-a9dc-4c3f-b4f7-9a48d42d07b5-4129' in namespace 'datacenter'
  • 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

Create a network service type


To create a network service type, the only required field is the 'name' attribute, which must be unique

POST https://example.com/api/admin/datacenters/{datacenter}/networkservicetypes

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_NETWORK]

Content-Type : networkservicetype Accept : networkservicetype

Error Codes

  • DC-0 - The requested datacenter does not exist
  • NST-0 - The name of the network service type must be supplied
  • NST-1 - The name of the network service type already exists

Example

List network service types


GET https://example.com/api/admin/datacenters/{datacenter}/networkservicetypes

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_NETWORK, ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_MANAGE]

Error Codes

  • LOCATION-4 - The location does not exist

Example

Delete a network service type


The default network service type of each datacenter cannot be deleted

DELETE https://example.com/api/admin/datacenters/{datacenter}/networkservicetypes/{networkservicetype}

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_NETWORK]

Example

Get a network service type


GET https://example.com/api/admin/datacenters/{datacenter}/networkservicetypes/{networkservicetype}

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_NETWORK, ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_PHYS_DC_MANAGE]

Error Codes

  • LOCATION-4 - The location does not exist
  • NST-2 - The requested network service type does not exist

Example

Update a network service type


When you update a network service type, you can only change the name attribute

PUT https://example.com/api/admin/datacenters/{datacenter}/networkservicetypes/{networkservicetype}

Roles : [ROLE_PHYS_DC_ALLOW_MODIFY_NETWORK]

Content-Type : networkservicetype Accept : networkservicetype

Error Codes

  • NST-0 - The name of the network service type must be supplied
  • NST-1 - The name of the network service type already exists

Example