License

This specification is licensed under the FIWARE Open Specification License (implicit patents license).

Intended Audience

This specification is intended for both software developers and Cloud Providers. For the former, this document provides a full specification of how to interoperate with Cloud Platforms that implements PMI API. For the latter, this specification indicates the interface to be provided in order to create rules with conditions and actions associated the facts received from cloud services. To use this information, the reader should first have a general understanding of the Policy Manager Generic Enabler and also be familiar with:

• RESTful web services
• RFC2616.
• JSON data serialization formats.

Conformance

This specification describes the "full" compliance level.

However, future iterations of this specification might define optionality in some parts and the compliance level (or roles/profiles) corresponding to them.

Conventions

PMI version 1.0 uses lower camel case (lowerCamelCase) syntax for naming properties and related artifacts used by the API.

Specification

Introduction

The PMI API defines:

• A rule represents the policy or rule that will be used to infers new facts or actions based on the facts notified by the Publish/Subscribe Context Broker GE. Usually, rules are compound of conditions and actions
• A condition is some type of conditional statement of the form: x > 85% [AND y > 64.5%]. Several conditions can be connected using AND logical operator.
• A fact represents the measurement of the cloud resources and will be used to infer new facts or actions. It is the base of the reasoning process.
• An action represents the triggered message inferred by the rule engine based on the execution of certain conditions defined in a rule or rules set. This message is notified to the third parties in order to launch the proper action.

Authentication

Each HTTP request against the PMI requires the inclusion of specific authentication credentials following the same architecture of the other OpenStack projects. The specific implementation of this API supports OAuth v2.0 authentication schemes and will be determined by the specific provider that implements this GE and Interface. To authenticate access to OpenStack services, you must first issue an authentication request with a payload of credentials to OpenStack Identity to get an authentication token.

Credentials are usually a combination of your user name and password, and optionally, the name or ID of the tenant from your FIWARE Lab account. Ask your cloud administrator for your user name (OS_USERNAME), password (OS_PASSWORD), and tenant (OS_PROJECT_NAME) if you do not remember it or sing up your own account in FIWARE Lab account service so that you can generate authentication tokens.

When you send PMI API requests, you include the token in the X-Auth-Token header. Please, keep in mind that a token is valid for a limited time before it expires. A token can also become invalid for other security reasons. The workflow that you have to follow is:

• Request an authentication token from the Identity Manager endpoint that your cloud administrator gave you. Send a payload of credentials in the request as shown in Authenticate. If the request succeeds, the server returns an authentication token. Please refer to FIWARE Identity Management GE for more details. First, export your tenant name to the OS_PROJECT_NAME environment variable, your user name to the OS_USERNAME environment variable, your password to the OS_PASSWORD environment variable and the url of the Identity Management to OS_AUTH_URL environment variable and then execute:

$ curl -s -X POST $OS_AUTH_URL/tokens \
-H "Content-Type: application/json" \
-d '{"auth": {"tenantName": "'"$OS_PROJECT_NAME"'", "passwordCredentials": {"username": "'"$OS_USERNAME"'", "password": "'"$OS_PASSWORD"'"}}}' \
| python -m json.tool

Note: In the FIWARE Lab environment the url of the Identity Management GEi is http://cloud.lab.fi-ware.org:5000/v2.0/

If the request succeeds, it returns the OK (200) response code followed by a response body that contains a token in the form "id":"token" and an expiration date and time in the form "expires":"datetime". This is a normal example of the response to the previous POST, we show only details about the token, the rest are not needed in this case.

{
  "access": {
    "token": {
      "issued_at": "2016-09-02T10:03:51.159419",
      "expires": "2016-09-03T10:03:51Z",
      "id": "98763040c99h740i95809z2098123704",
      "tenant": {
        "description": "Joe Foo",
        "enabled": true,
        "id": "0000000000000098758734z730478503",
        "name": "foo"
      },
      "audit_ids": [
        "HsO-r_exQ9upNUMpuf4iWg"
      ]
    },
    "serviceCatalog": [ ... ],
    "user": { ... },
    "metadata": { ... }
  }
}

• Send API requests and include the token in the X-Auth-Token header. Continue to send API requests with that token until the service completes the request or the Unauthorized (401) error occurs.

• If the Unauthorized (401) error occurs, go to the first point and request another token.

The examples in this section use cURL commands. For information about cURL, see http://curl.haxx.se/. For information about the OpenStack APIs, see http://developer.openstack.org/api-ref.html.

Representation Format

The PMI API resources are represented by hypertext that allows each resource to reference other related resources. More concisely, JSON format are used for resource representation and URLs are used for referencing other resources by default. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header with values application/json or adding a .json extension to the request URI. In the following examples we can see the different options in order to represent format.

POST /d3fdddc6324c439780a6fd963a9fa148/servers/15520fa6dc914f97bd1e54f8e1444d41 HTTP/1.1
Host: servers.api.openstack.org
Content-Type: application/json
Accept: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

POST /d3fdddc6324c439780a6fd963a9fa148/servers/15520fa6dc914f97bd1e54f8e1444d41.json HTTP/1.1
Host: servers.api.openstack.org
Content-Type: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

MIME Types

The API response payloads in this specification are based on application/json. Clients issuing HTTP requests with accept types different than those will get a 406 Not Acceptable error.

Resource Identification

API consumer must indicate the resource identifier while invoking a GET, PUT, POST or DELETE operation. PMI API combines both identification and location by terms of URL. Each invocation provides the URL of the target resource along the verb and any required input data. That URL is used to identify unambiguously the resource. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

PMI API does not enforce any determined URL pattern to identify its resources. Anyway the PMI API follows the HATEOAS principle (Hypermedia As The Engine Of Application State). This means that resource representation contains the URLs of the related resources (e.g., book representation contains hyperlinks to its chapters; chapter representation contains hyperlinks to its pages...). API consumer obtains the server representation as its following point, which in turn provides hyperlinks that directly or indirectly take to other resources like scalability rules.

Some PMI API entities provide an instance identifier property (instance ID). This property is used to identify unambiguously the entity but not the REST resource used to manage it, which is identified by its URL as described above. It is common that most implementations make use of instance ID to compose the URL (e.g., the book with instance ID 1492 could be represented by resource http://.../book/1492), but such an assumption should not be taken by API consumer to obtain the resource URL from its instance ID.

Last but not least, PMI API does not take care about this instance creation. PMI API supposes that the instance, identified by its serverId, is created in the FIWARE Lab.

Links and References

Resources often lead to refer to other resources. In those cases, we have to provide an ID or an URL to a remote resource. see OpenStack Compute Developer Guide on their application to infrastructural resources.

Rules

Rules are described using JSON, and contain information about CPU and Memory usage, in first instance. The rule is compound of three parts, name, conditions and actions. In this case, the name will be "AlertCPU" and the defined condition expects all server with cpu usage greater than 98.3 and memory load greater or equal to 95.

Actions will create an HTTP POST notification to an url specified on every subscription to this rule. In this case the notification will be that server should be scaled up because CPU usage is greater than certain limit. This is the rule as is expected to:

{
    "name": "AlertCPU", 
    "condition": {
           "cpu": {
                  "value": 98.3,
                  "operand": "greater"
           },
           "mem": {
                  "value": 95,
                  "operand": "greater equal"
           }
   },
    "action": {
          "actionName": "notify-scale",
          "operation": "scaleUp"
    }
}

Rule Conditions

Rule conditions represent a boolean condition to be evaluated (e.g. x > 10). A rule condition is simply a statement that is either true or false. We can have two options:

• Simple rule conditions, which only requires one statement.
• Complex rule conditions, which requires two or more statements linked with a logical operator. The only allowed operator is AND in Policy Manger in release 5.4

A rule condition is represented by a JSON object with the following syntax:

• The entity metric representing the cloud service metric is specified by the object's property. These metrics are only cpu, mem, hdd, net.
• The entity value representing the cloud service value for the entity metric is specified by the object's value property, whose value is a floating number representing the percentaje of utilization of this metric in the cloud service.
• The logical operator used to check the entity value is specified by the object's operand property. PMI API v1.0 allows values "greater", "less", "greater equal", "less equal" for this property.

An example of a rule definition can be found in the following code:

"condition": {
    "cpu": {
           "value": 98.3,
           "operand": "greater"
    },
    "mem": {
           "value": 95,
           "operand": "greater equal"
    }
}

Actions

Actions are the messages that we send to the user of the rule when a rule is triggered. An action is represented by a JSON object with the following syntax:

• The action id is specified by the object's actionName property, whose value is a string containing the action's name. Depending of the actionName we have predefined different properties:

• If the object's actionName property has value notify-email, we have the email and body which are represented by the object's email and body properties, whose values are the string containing the email address to send the email and the message of this email. This is a possible example:

"action": {
    "actionName": "notify-email",
    "email": "foo@fighters",
    "body": "You have a problem with your instance, please check it."
}

• If the object's actionName property has value notify-scale, we have action operation. The action operation is specified by the object's operation property, whole value is a string containing the action's operation. PMI API v1.0 allows values "scaleUp", "scaleDown" for this property. This messages is sent back to the url that is specified in the subscription process described bellow. This is a possible example:

"action": {
    "actionName": "notify-scale",
    "operation": "scaleUp"
}

• Any other possible value of the object's actionName property will have the same behaviour described in the previous case.

Error Responses

Every HTTP request has a status code. 2xx codes signify the PMI API was a success. However, sometimes is not the response that be obtained. All the errors message are sent in JSON format with the following attributes:

• A message. A descriptive text of the error that was reported by the PMI API.
• A code. A integer value to identity the error type.
• A title. The error type in text format.

An example of an error message could be:

{
  "error": {
    "message": "Expecting to find valid JSON in request body - the server could not comply with the request since it is either malformed or otherwise incorrect. The client is assumed to be in error.",
    "code": 400,
    "title": "Bad Request"
  }

The possible values that we have in the attributes are described bellow. Keep in mind that we give them in the format title (code). <description>:

• Bad Request (400). The PMI API failed to parse the request as expected. One of the following errors occurred:

  • A required attribute was missing.
  • An attribute that is not allowed was specified, such as an ID on a POST request in a basic CRUD operation.
  • An attribute of an unexpected data type was specified.
  • An attribute is unexpected in the body JSON message.

• Unauthorized (401). One of the following errors occurred:

  • Authentication was not performed.
  • The specified X-Auth-Token header is not valid.

• Forbidden (403). The identity was successfully authenticated but it is not authorized to perform the requested action.

• Not Found (404). An operation failed because a referenced entity cannot be found by ID.

• Service Unavailable (503). The Policy Manager is unable to perform the operation due to it is unavailable. One of the following errors accurred:

  • Policy Manager service or some of its subcomponents (RabbitMQ, MySQL, Redis and/or Facts) are down.
  • Policy Manager cannot contact the Identity Management to authenticate the received token.

API Specification

Content-Type: application/json

{
  "contextResponses": [
            {
                "contextElement": {
                    "attributes": [
                        {
                            "value": "0.12",
                            "name": "usedMemPct",
                            "type": "string"
                        },
                        {
                            "value": "0.14",
                            "name": "cpuLoadPct",
                            "type": "string"
                        },
                        {
                            "value": "0.856240",
                            "name": "freeSpacePct",
                            "type": "string"
                        },
                        {
                            "value": "0.8122",
                            "name": "netLoadPct",
                            "type": "string"
                        }
                    ],
                    "id": "Trento:193.205.211.69",
                    "isPattern": "false",
                    "type": "host"
                },
           "statusCode": {
               "code": "200",
               "reasonPhrase": "OK"
            }
        }
    ]
}

Content-Type: application/json

{ 
    "id": 3, 
    "title": "no error." 
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "owner": "TELEFONICA I+D",
    "windowsize": <windows_size>,
    "version": "<API_version>",
    "runningfrom": "<last_launch_date>
    "doc": "http://telefonicaid.github.io/fiware-cloto/api/v1.0/"
}

Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

{
    "windowsize": <window_size>
}  

Content-Type: application/json

{
    "windowsize": <windows_size>
}

Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>
}

Content-Type: application/json

{
    "ruleId": <RULE_ID>
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "rules": [
        {
            "name": <NAME>,
            "condition": <CONDITION_DESCRIPTION>,
            "action": <ACTION_ON_SERVER>,
            "ruleId": "<RULE_ID>"
        },
        {
            "name": <NAME2>,
            "condition": <CONDITION_DESCRIPTION>,
            "action": <ACTION_ON_SERVER>,
            "ruleId": "<RULE_ID>"
        }
    ]
}

Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>
}

Content-Type: application/json

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>,
    "ruleId": "<RULE_ID>"
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "servers": [
        {
            "serverId": "<serverId>",
            "rules": [
                {
                    "condition": <CONDITION_DESCRIPTION>,
                    "action": <ACTION_ON_SERVER>,
                    "ruleId": "<RULE_ID>"      
                },
                {
                    "condition": <CONDITION_DESCRIPTION>,
                    "action": <ACTION_ON_SERVER>,
                    "ruleId": "<RULE_ID>"      
                }
            ]
        },
        {
            "serverId": "<serverId>",
            "rules": [
                {
                    "condition": <CONDITION_DESCRIPTION>,
                    "action": <ACTION_ON_SERVER>,
                    "ruleId": "<RULE_ID>"      
                },
                {
                    "condition": <CONDITION_DESCRIPTION>,
                    "action": <ACTION_ON_SERVER>,
                    "ruleId": "<RULE_ID>"      
                }
            ]
        }
    ]
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "serverId": "<serverId>",
    "rules": [
        {
            "name": <NAME>,
            "condition": <CONDITION_DESCRIPTION>,
            "action": <ACTION_ON_SERVER>,
            "ruleId": "<RULE_ID>"      
        },
        {
            "name": <NAME>,
            "condition": <CONDITION_DESCRIPTION>,
            "action": <ACTION_ON_SERVER>,
            "ruleId": "<RULE_ID>"      
        }
    ]
}

Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>
}

Content-Type: application/json

{
    "serverId": <serverId>,
    "ruleId": <RULE_ID>
}

Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>
}

Content-Type: application/json

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "name": <NAME>,
    "condition": <CONDITION_DESCRIPTION>,
    "action": <ACTION_ON_SERVER>,
    "ruleId": "<RULE_ID>"      
}

Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

{
    "ruleId": <RULE_ID>,
    "url": <URL_TO_NOTIFY>,
}

Content-Type: application/json

{
    "subscriptionId": <SUBSCRIPTION_ID>
}

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

X-Auth-Token: 1da5e7629654321e3c123456b89b1cct

Content-Type: application/json

{
    "subscriptionId": <SUBSCRIPTION_ID>,
    "url": <URL_TO_NOTIFY>,
    "serverId": <SERVER_ID>,
    "ruleId": "<RULE_ID>"      
}

References

• Apiary project
• Github source
• FIWARE Open Specification License (implicit patents license)
• Policy Manager Generic Enabler
• RFC2616
• JSON data serialization formats
• FIWARE Lab account service
• FIWARE Identity Management GE
• http://cloud.lab.fi-ware.org:5000/v2.0/
• http://curl.haxx.se/
• OpenStack Compute Developer Guide