PublicCloudRegionsResource


Create a public cloud region


You can create a public cloud region 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 public cloud region entity. To create new remote services, add them as remote service entities in the remote services attribute of the public cloud region entity. If the public cloud region is for a generic cloud provider, such as a generic OpenStack installation, in order to retrieve the list of available regions, add the following additional headers to the request. Note that this header information will not be stored and will only be used to get the list of available regions.
Header Value
X-Abiquo-PCR-Identity The identity to use when connecting to the cloud provider to get the available regions.
X-Abiquo-PCR-Credential The identity to use when connecting to the cloud provider to get the available regions.
X-Abiquo-PCR-Endpoint The endpoint to connect to in order to get the list of available regions.
If an error occurs, the response will contain configuration errors but the public cloud region will still be created.

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

Roles : [ROLE_PCR_MANAGE]

Content-Type : publiccloudregion Accept : publiccloudregion

Error Codes

  • GEN-21 - The requested plugin is not a cloud provider plugin type
  • GEN-23 - The operation requires authentication to the provider and the X-Abiquo-PCR-Identity, X-Abiquo-PCR-Credential and X-Abiquo-PCR-Endpoint headers must be set
  • PUBLICREGION-10 - Cannot obtain the endpoint of the given provider type and region.
  • PUBLICREGION-2 - The name is required
  • PUBLICREGION-5 - The region is already used by another public cloud region
  • PUBLICREGION-6 - The name is already used by another public cloud region
  • PUBLICREGION-7 - The remote services for a public cloud region must be: Virtualization Manager, Monitor Manager, Plugin Manager, Remote Access Manager
  • REGION-0 - Missing region link
  • REGION-1 - Invalid region link
  • REGION-2 - Region not found in the provider plugin
  • RS-26 - The requested remote service does not exist
  • RS-32 - More than one remote service of the same type is not allowed in a datacenter

Example

List public cloud regions


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

Roles : [ROLE_PCR_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 based on the enterprise identifier
has String If present filter to apply in the search.
startwith int 0 The first element to be retrieved of the filtered search
limit int 25 The number of entities to retrieve
idScope Integer If present, filter based on the scope identifier
onlywithcredentials Boolean If true, only return public cloud regions for which the current enterprise has public cloud credentials

Example

Search for alarms on public cloud regions


Retrieve alarms from the public cloud regions, optionally the search could be recursive and includes the alarms of the entities:
  • Virtual machines

GET https://example.com/api/admin/publiccloudregions/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 public cloud region


DELETE https://example.com/api/admin/publiccloudregions/{publiccloudregion}

Roles : [ROLE_PCR_MANAGE]

Example

Get a public cloud region


GET https://example.com/api/admin/publiccloudregions/{publiccloudregion}

Roles : [ROLE_PCR_ENUMERATE, ROLE_USERS_MANAGE_ENTERPRISE, ROLE_APPLIB_ALLOW_MODIFY]

Error Codes

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

Example

Update a public cloud region


When updating a public cloud region, you can change the name and endpoint

PUT https://example.com/api/admin/publiccloudregions/{publiccloudregion}

Roles : [ROLE_PCR_MANAGE]

Content-Type : publiccloudregion Accept : publiccloudregion

Error Codes

  • CONSTR-LENGTH - The property 'name' length must be between 1 and 255.
  • CONSTR-REQUIRED - The property 'name' must have a value.
  • GEN-21 - The requested plugin is not a cloud provider plugin type
  • PUBLICREGION-12 - The region of a public cloud region cannot be modified
  • PUBLICREGION-13 - The provider type of a public cloud region cannot be modified
  • PUBLICREGION-6 - The name is already used by another public cloud region
  • RS-29 - Remote service type not allowed to be used in a public cloud region
  • 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

Example

Search for alarms on a public cloud region


Retrieve alarms from the public cloud region, or with the recursive option also include the alarms of the following entities on the infrastructure path:
  • Virtual machines

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

Create a metric metadata on a public cloud region


Creates a new metric metadata

POST https://example.com/api/admin/publiccloudregions/{publiccloudregion}/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 'be8fcdaf-4910-4ffe-be89-3051f721332c' is already in use.
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example

List metrics metadata on a public cloud region


Returns the metadata of all the available, built-in, and custom metrics for the given public cloud region

GET https://example.com/api/admin/publiccloudregions/{publiccloudregion}/metrics

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricsmetadata

Error Codes

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

Example

Push collectd values on a public cloud region


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

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : application/json

Example

Get a metric metadata on a public cloud region


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

GET https://example.com/api/admin/publiccloudregions/{publiccloudregion}/metrics/{metric}

Roles : [ROLE_USERS_SHOW_METRICS]

Accept : metricmetadata

Error Codes

  • MONITORING-1 - Unknown metric 'c3768030-0a01-47bd-a0e2-24b2e8267383' for PublicCloudRegion with id '6072'
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example

Get a metric statistics on a public cloud region


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/publiccloudregions/{publiccloudregion}/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 '41aa6bc3-38f3-4d8a-8b86-e70d11db8779' in namespace 'cloudregion' 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
  • PUBLICREGION-8 - The requested public cloud region does not exist

Push metric datapoints on a public cloud region


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

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : datapoints

Example

Update a metric metadata on a public cloud region


Updates an existing metric metadata

PUT https://example.com/api/admin/publiccloudregions/{publiccloudregion}/metrics/{metric}

Roles : [ROLE_USERS_PUSH_METRICS]

Content-Type : metricmetadata Accept : metricmetadata

Example

Create an alarm on a public cloud region


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

POST https://example.com/api/admin/publiccloudregions/{publiccloudregion}/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 '4a824527-6e8b-4ea0-9175-6d223df2a220' in namespace 'cloudregion' 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
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example

List alarms on a public cloud region


List the alarms associated with an existing metric

GET https://example.com/api/admin/publiccloudregions/{publiccloudregion}/metrics/{metric}/alarms

Roles : [ROLE_USERS_VIEW_ALARMS]

Accept : alarms

Error Codes

  • GEN-4 - Not enough permissions to perform this action
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example

Delete an alarm from a public cloud region


Deletes an existing alarm

DELETE https://example.com/api/admin/publiccloudregions/{publiccloudregion}/metrics/{metric}/alarms/{alarm}

Roles : [ROLE_USERS_MANAGE_ALARMS]

Example

Get an alarm on a public cloud region


Returns a concrete alarm

GET https://example.com/api/admin/publiccloudregions/{publiccloudregion}/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 f0c6dff8-43f8-4456-8032-797cdd61bb4d not found
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example

Update an alarm on a public cloud region


Updates an existing alarm

PUT https://example.com/api/admin/publiccloudregions/{publiccloudregion}/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 with uuid 514951f2-8496-4db2-81d3-9135a326000c 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
  • PUBLICREGION-8 - The requested public cloud region does not exist

Example