• Sales: 1-800-961-2888
  • Support: 1-800-961-4454

Using the OpenCenter API


NOTE: This documentation is for the Rackspace Private Cloud Software v. 3.0 with OpenCenter. Other v. 3.0 documentation can be found on the Archived Versions page. Documentation for the newest version of Rackspace Private Cloud Software can be found in the Getting Started section.

 

 


The OpenCenter CLI implements the OpenCenter API through the command line interface. This chapter discusses the OpenCenter API for users that want to interact directly with the API.

Overview

The OpenCenter API is a RESTful API with two base URIs, a user endpoint and an admin endpoint.

About the User Endpoint

Calls sent to the user endpoint do not immediately commit changes to the database; instead, the OpenCenter solver determines the most efficient way to execute the request before committing the change. The user endpoint is located at the root of the OpenCenter server. For example, if your OpenCenter server's IP address was 192.0.2.1:8443, you would access the user endpoint at https://192.0.2.1:8443/api_uri.

For example, when you use the UI to move a node from the Unprovisioned container to a Nova infrastructure container, the OpenCenter solver determines the operations that need to be performed on the node to turn it into a Nova Controller node; among other things, the system needs to install Chef client on the node, set the node in Chef to be a Nova infrastructure node, reset the parent_id fact, and more.

About the Admin Endpoint

Calls sent to the admin endpoint are directly recorded in the database, and should be used with caution. The admin endpoint is located at /admin. In the above example, admin API calls go to https://192.0.2.1:8443/admin/api_uri.

In this case, if you were to use the admin API to simply change a node's parent_id from the Unprovisioned container to the Nova infrastructure container, the parent_id information would be changed in the OpenCenter database, but no actual work would be performed, and the node would not be correctly provisioned with a Chef client or any Nova infrastructure information.

Authentication

The OpenCenter API currently uses basic authentication and should be run over https://. Use the username and password for the server node.

Notifications and Errors

The OpenCenter API returns standard HTTP response codes. Admin API calls always return a 200 or a 404 immediately. User API calls on facts or adventures may indicate that the request is still being processed or requires more information.

Code Description
200 The request and operation worked as expected.
202 The system has accepted the request and is working on it.
403 Bad request; the system can't figure out how to process it.
404 The requested item does not exist.
409 The request is missing data and cannot be processed until you supply that data.

For example, the following API call attempts to run an adventure on a node, but the adventure requires arguments:

curl http://localhost:8443/adventures/6/execute -d '{"node": 4}' -H "content-type: application/json"

The system response on the call will be as follows:

{
  "status": 409,
  "message": "need additional input",
  "plan": [
    {
      "args": {
        "sleep_interval": {
          "message": "I cannot solve for type \"int\"",
          "required": true,
          "type": "int"
        }
      },
      "primitive": "sleep",
      "ns": {},
      "timeout": 30
    }
  ],
  "friendly": "Please supply additional info"
}

API Operations

This section documents the API operations and parameters available in the OpenCenter API.

Nodes

A node is any object that can be managed within the environment. It may be a container (such as a Nova cluster) or a server (such as a Chef server). If you are using Cloud Files, your environment will contain a Cloud Files node that includes authorization keys and any other attributes relevant to your Cloud Files account.

Verb URI Description
GET nodes/ Fetches the list of nodes in the OpenCenter cluster.
POST nodes/ Creates a new node.
POST nodes/whoami Fetches the node ID.
GET nodes/object_id Fetches information about the node.
PUT nodes/object_id Makes changes to a node.
DELETE nodes/object_id Deletes a node.
GET nodes/node_id/tasks Returns the first task available to be run on a node. If no taks is available, returns a 404.
GET nodes/node_id/tasks_blocking Returns the first available task or blocks until a task is available. This will not return until there is a new task available to run.
GET nodes/node_id/adventures Fetches a list of adventures available to run on a node.

 

Parameter Description Required?
name The name of the node. May be up to 64 characters long. Yes
task_id The ID number of a task. No
adventure_id The ID number of an adventure. No
attrs An attribute associated with the node. No
facts A fact associated with the node. No
id The ID number of the node Yes

 

In the following example, a node is assigned the name test and the ID number 15.

echo '{"name":"test","id":15}' | curl -d @- -H 'Content-Type: application/json' -X PUT http://192.0.2.1:8443/nodes/15

Facts

A fact is a property that can be inherited from a parent node. For example, if a node is placed within a Nova container, the node inherits the container's properties. These properties can include the Chef server that the container uses, the API server, and the nova configuration file information. Each node includes a fact that describes its parent, which determines what additional facts the node needs to inherit.

Verb URI Description
GET facts/ Fetches a list of facts defined within OpenCenter.
POST facts/ Creates a new fact.
GET facts/fact_id Fetches information about the fact.
PUT facts/fact_id Makes changes to a fact.
DELETE facts/fact_id Deletes a fact.

 

Parameter Description Required?
key The name of the fact. Yes
node_id The ID number of the node to which the fact applies. Yes
id The ID number of the fact. Yes
value The components of the fact, expressed in JSON. No

In the following example, a fact called fact73 is created and assigned to node 5. The value of the fact is not specified in this example, but could be a JSON string.

echo '{"key": "fact73", "node_id" :5}' | curl -d @- -H 'Content-Type:application/json' -X POST http://192.0.2.1:8443/facts/

Attributes

Attributes are properties that are specific to a single node and are not inherited. These attributes are distinct and unique to the node, such as RAM or disk space.

Verb URI Description
GET attrs/ Fetches a list of attributes defined within OpenCenter.
POST attrs/ Creates a new attribute.
GET attrs/attribute_id Fetches information about an attribute.
PUT attrs/attribute_id Makes an attribute.
DELETE attrs/attribute_id Deletes an attribute.

 

Parameter Description Required?
key The name of the attribute. Yes
node_id The ID number of the node to which the attribute applies. Yes
id The ID number of the attribute. Yes
value The components of the attribute, expressed in JSON. No

In the following example, an attribute called called attr5 is created and assigned to node 8.

echo '{"key": "attr5", "node_id": 8, "id": "1234"}' | curl -v -d @- -H 'Content-Type: application/json' -X POST http://192.0.2.1:8443/attr/

Primitives

A primitive acts on a node and manipulates the node facts. Primitives are extensible via Python.

Verb URI Description
GET primitives/ Fetches a list of primitives defined within OpenCenter.
POST primitives/ Creates a new primitive.
GET primitives/primitive_id Fetches information about a primitive.
PUT primitives/primitive_id Updates a primitive.
DELETE primitives/primitive_id Deletes a primitive.

 

Parameter Description Required?
name The name of the primitive. Can be up to 32 characters long. Yes
consequences The results of the primitive, expressed in JSON. No
args The arguments that the primitive passes, expressed in JSON. No
weight The priority assigned to the primitive. No
ID The ID number of the primitive. Yes
constraints The constraints applied to the primitive, expressed in JSON. No

Tasks

A task is an action directed at a specific node, assigned by the OpenCenter server to the OpenCenter agent that is installed on the node. A task may use one or more primitives to accomplish the action. Tasks are extensible via Python.

Verb URI Description
GET tasks Fetches a list of all tasks that have been run, are currently running, and are scheduled to run.
POST tasks Creates a new task.
GET tasks/task_id/logs Fetches a log showing when all tasks with the specified ID were performed.
GET tasks/task_id/logs/transaction  
GET tasks/task_id Fetches information about a specific task.
PUT tasks/task_id Updates a task.
DELETE tasks/task_id Deletes a task.

 

Parameter Description Required?
completed Indicates whether a task has finished. No
expires Indicates when the task will expire. No
submitted Indicates if the task has been submitted. No
ID The ID number of the task. Yes
parent_id The ID of an object's parent. No
state The current status of the task. No
node_id The ID number of the node on which the task is performed. No
result The result of the task, in JSON format. No
action The action that the task performs. No
payload JSON expression of the results of the completed task. No

In the following example, task 3 performed on node 15.

echo '{"id":"3","node_id":15}' | curl -d @- -H 'Content-Type: application/json' -X PUT http://192.0.2.1/tasks/3

Adventures

An adventure is a solution composed of multiple actions that run in sequence, created to manage common changes. For example, OpenCenter includes an adventure that installs Chef server. There are also adventures for rebooting a server, upgrading installation packages, and identifying out-of-date security patches.

 

Verb URI Description
GET adventures/ Fetches a list of adventures defined within OpenCenter.
POST adventures/ Creates a new adventure.
GET adventures/adventure_id Fetches information about an adventure.
PUT adventures/adventure_id Updates an adventure.
DELETE adventures/adventure_id Deletes an adventure.
POST adventures/adventure_id/execute Launches an adventure.

 

Parameter Description Required?
dsl Domain Specific Language for defining the adventure, expressed in JSON. Yes
args The arguments that the adventure passes, expressed in JSON. No
id The ID number of the adventure. Yes
name The name of the adventure, up to 30 characters long. Yes
criteria The criteria that must be met for the adventure to be executed. No

 

In the following example, adventure 8 is executed on node 6.

echo '{"node":6}' |curl -d @- -v -H 'Content-Type: application/json' http://192.0.2.1/adventures/8/execute

Filters

Filters are used to organize nodes by type.

Verb URI Description
GET filters/ Fetches a list of filters defined within OpenCenter.
POST filters/ Creates a new filter.
GET filters/filter_id Fetches information about a filter.
PUT filters/filter_id Updates a filter.
DELETE filters/filter_id Deletes a filter.

 

Parameter Description Required?
name The name of the filter. No
expr An expression of what the filter includes or excludes. No
filter_type The type of filter. No
parent_id Used when defining subfilters. When a filter is defined with a parent_id, it becomes a subfilter of the parent filter. No
full_expr A detailed expression of what the filter includes or excludes. No
id The ID number of the filter. Yes

Filters of the interface type select objects that offer a service. For example, a chef-server interface is a filter expression that shows what kinds of facts a Chef server has:

id: 1 
name: chef-server 
type: interface 
expr: (facts.chef_server_uri != None) and (facts.chef_server_pem != None)

A node that has the facts defined in the expression field is a Chef server. In future releases, additional interfaces will be defined to allow more detailed sorting of nodes within an OpenCenter environment.







© 2011-2013 Rackspace US, Inc.

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License


See license specifics and DISCLAIMER