Difference between revisions of "Heat/Open API"

Latest revision as of 05:33, 12 April 2013

Proposal Only

Please recognize that this is only a proposed DSL to be considered for development. This is NOT YET IMPLEMENTED.

See: Launchpad Blueprint for Open API/DSL

Heat Open API Overview

This is a REST API to support the proposed Heat/DSL. The API is a REST HTTP API. It supports POST, PUT, GET, DELETE on:

• /components[/:id]
• /blueprints[/:id]
• /environments[/:id]
• /deployments[/:id]
• /workflows[/:id]
• /providers[/:id]

Note: Not all verbs on all paths.

GET

• Will sometimes add the object ID and tenant ID if the underlying store does not provide them.
  • This is so that the object can be identified when parsed later.

POST & PUT

• PUT - Updates without taking any action or side effects on other resources. The only permitted side-effect is on the resource itself (for example, updating a last-modified field).
• POST - Can update and/or trigger actions (like actual server deployments) and can accept partial objects.

The Semantics are:

POST /objects (without ID)

• Creates a new object. ID is generated by Heat and returned in the Location header.
• Use it to create objects without fear of ID conflicts

POST /objects/:id

• Update an existing object. Partial updates are supported (i.e. I can POST only the name to rename the object). Could trigger actions, like running a workflow.
• Use it to modify parts of an object.

PUT /objects/:id

• Overwrites the object completely. Does not trigger side effects, but will validate data (especially id and tenant_id fields).
• Use it to store something in Heat (ex. a deployment exported from another instance of Heat)

DELETE /objects/:id

• Will trigger deletion of the object.
• May also trigger deletion of all related running instances started by Heat for the given assembly.

JSON, YAML, and XML

Objects are returned as JSON by default, but YAML (content-type: application/x-yaml) and XML are also supported

Special Cases and Considerations

All objects should have a root key with the name of the class. Ex. `{"blueprint": {"id": 1}}`. However, Heat will permit objects without the root if they are provided. Example:

       PUT /blueprints/2 {"id": 2}

Heat will fill in the id, status, tenant_id, and creation date of posted objects. For puts, these value must be supplied and must be correct (i.e. matching the tenant and id in the URL).

YAML supports references within a document. If a deployment is in YAML format and is using references, the references can be provided under a key called 'includes'. This can be used, for example, to create a new deployment passing in all the necessary components, blueprints, environments, etc... (or references to them).

Some commands can be issued with a '+command' URL. Example:

     /workflows/wf1000/+execute

All calls are supported flat off of the root or under a tenant ID. Calls off of the root require administrative privileges and will return all objects from all tenants (ex. /environments vs /T1000/environments)

All calls to GET /deployments and GET /workflows may be optionally paginated by offset and limit.

List of All Calls

Note: :tid is the tenant ID and is optional.

GET/POST [/:tid]/environments
PUT/GET/POST [/:tid]/environments/:id

GET [/:tid]/environments/:id/providers
GET [/:tid]/environments/:id/providers/:pid
GET [/:tid]/environments/:id/providers/:pid/catalog
GET [/:tid]/environments/:id/providers/:pid/catalog/:cid

GET/POST [/:tid]/blueprints
PUT/GET/POST [/:tid]/blueprints/:id

GET  [/:tid]/deployments/[?offset=OFFSET&limit=LIMIT]
POST [/:tid]/deployments
PUT/GET/POST [/:tid]/deployments/:id
POST [/:tid]/deployments/+parse
POST [/:tid]/deployments/+preview
 
GET [/:tid]/deployments/:id/status
 
GET  [/:tid]/workflows/[?offset=OFFSET&limit=LIMIT]
POST [/:tid]/workflows
PUT/GET/POST [/:tid]/workflows/:id

GET [/:tid]/workflows/:id/status

POST [/:tid]/workflows/:id/+execute

GET/POST [/:tid]/workflows/:id/tasks/:task_id

POST [/:tid]/workflows/:id/tasks/:task_id/+execute
POST [/:tid]/workflows/:id/tasks/:task_id/+resubmit

GET [/:tid]/providers
GET [/:tid]/providers/:pid
GET [/:tid]/providers/:pid/catalog
GET [/:tid]/providers/:pid/catalog/:cid

# If the server is started with --with-simulator, the following calls are available:

POST [/:tid]/deployments/simulate
GET [/:tid]/deployments/simulate
GET [/:tid]/workflows/simulate/status  #progresses the workflow by one task
GET [/:tid]/workflows/simulate/status?complete  #completes the workflow

Full Lifecycle with API Use Case

This section details all the necessary API calls a client (such as Horizon) would need to implement the ability to select a Heat Blueprint, launch it, monitor progress, and then delete it.

CALL 1: Get list of Heat Blueprints

Request:

GET /v1/{tenant_id}/blueprints/.json HTTP/1.1
X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663
Host: heat.openstack.org

Note: Paginated collections use when we have a large number of blueprints.

Response Example:

> HTTP/1.1 200 OK
> Content-Type: application/json;charset=utf-8
> Content-Length: 1587
> Date: Mon, 08 Apr 2013 01:26:00 GMT
 
{
    "38476ACF45F6745F223452E": {
       "blueprint": {
          "id": "38476ACF45F6745F223452E",
          "version": "1.0.0",
          "name": "WordPress",
          "options": {
              "region": {
                 "default": "ORD", 
                 "required": true, 
                 "type": "string", 
                 ...
               }, ...
          },
         "services": ...,
         ...
     },
    "environment": ...,
    ...
    }, ...
}

CALL 2: Launch a deployment

Request Description:

Combine the options the user supplies into an `inputs` object. Add that to the blueprint object and POST the combined object.

Request (to Heat):

POST /{tenant_id}/deployments/.json HTTP/1.1
X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663
Host: heat.openstack.org
Content-type: application/json
 
{
   "name": "My Blog",
   "blueprint": …,
   "environment": …,
   "inputs": {
      "region": "ORD",
      ...
   }
}

Response Description:

The Location header will return asynchronously to provide the deployment ID ASAP.

display-outputs: will contain outputs to display such as the application URL. Additional information, such as the IP for a URL, can also be returned so clients can show information such as a bash script for modifying the hosts file until DNS propagates.

We would like to support pluggable underlying implementations (workflows, celery canvases, distributed state engines, etc…). To support client tools in a generic way, the API will return [RFC5988](http://tools.ietf.org/html/rfc5988) Link headers where appropriate.

Response Example:

> HTTP/1.1 200 OK
> Content-Type: application/json;charset=utf-8
> Content-Length: 1587
> Date: Mon, 08 Apr 2013 01:26:00 GMT
> Location: /{tenant_id}/deployments/3554aaa
> Link: \</{tenant_id}/workflows/982h3f28937h4f23847\>; rel="workflow"; title="Deploy xxx"
 
{
  "id": "3554aaa",
  "status": "PLANNING",
  "display-outputs": {
     "Admin URL": {
       "type": "url",
       "value": "http://blog.openstack.com/admin",
       "ipv4": "4.4.4.4",
       "ipv6": "f000::08",
       "order": 1
     },
     "Username": {
       "type": "string",
       "value": "wp_user",
       "order": 2
     }
  }, ...
}

CALL 3: Get Deployment

This is used to get the status as a deployment is launched and also to retieve data about an existing deployment.

Request (to Heat):

GET /{tenant_id}/deployments/3554aaa.json HTTP/1.1
X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663
Host: heat.openstack.org

Response Description:

Response Fields:

• status: will reflect the overall deployment status.
• operation: will contain information about the ongoing operation (independent of the subsystem running it). The following fields will always be provided:
• operation.type: deploy, add node, delete, etc…
• operation.estimated-duration: total seconds expected from start to finish
• operation.elapsed: total seconds elapsed since start (this is not a valid time estimate. It is a completion estimate calculated based on task estimated durations and task completion status)
• operation.tasks: total number of tasks to complete
• operation.complete: total number of tasks already completed
• operation.link: a link to the operation - this would be implementation specific

Note: see List Deployments for example of error condition

• resources: hash of resources. For each resource:
• resource.provider: nova, databases, load-balancers, etc… the service used to create it.
• resource.dns-name: the name of the resource
• resource.status: the status of the resource (ex. BUILD, CONFIGURE, ACTIVE, etc…)
• resource.service: the blueprint service the resource is in
• resource.instance: contains information like id, flavor, image, region, etc.

Response Example:

> HTTP/1.1 200 OK
> Content-Type: application/json;charset=utf-8
> Content-Length: 1587
> Date: Mon, 08 Apr 2013 01:26:00 GMT
  
{
  "id": "3554aaa",
  "status": "LAUNCHED",
  "operation": {
    "type": "deploy",
    "status": "IN PROGRESS",
    "estimated-duration": 2400,
    "elapsed": 1702,
    "tasks": 175,
    "complete": 100,
    "link": "/{tenant_id}/transactions/982h3f28937h4f23847"
  },
  "resources": {
    "0": {
      "type": "compute",
      "status": "CONFIGURE",
      "provider": "nova",
      "service": "web",
      "dns-name": "web01.domain.com",
      "instance": {
        "id": 29857645,
        "region": "ORD",
        "flavor": 4,
        "image": 119
      }
    },
    "1": {...},
    "2": {…},
    "3": {…},
    "4": {…},
    ...
    },
    "display-outputs": {
      "Admin URL": {
        "type": "url",
        "value": "http://blog.openstack.org/admin",
        "ipv4": "4.4.4.4",
        "ipv6": "f000::08",
        "order": 1
    },
    "Username": {
      "type": "string",
      "value": "wp_user",
      "order": 2
    }
  }
}

CALL 4: List Deployments

Request (to Heat):

GET /{tenant_id}/deployments/.json HTTP/1.1
X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663
Host: heat.openstack.org

Response Description:

Response Fields:

• key: is the ID.
• name: the name of the deployment
• status: the status as a string
• operation: will contain information about the ongoing operation (independent of the pluggable subsystem running it).

In the case of an error condition:

• operation.status: ERROR. Note this differs from deployment status.
• operation.error-message: the short, one-line description of the error
• operation.error-help: detailed error information
• operation.retryable: can this error be retried?
• operation.retry-link: the URL to call to retry

Note: same for resume and abort

Response Example:

> HTTP/1.1 200 OK
> Content-Type: application/json;charset=utf-8
> Content-Length: 1587
> Date: Mon, 08 Apr 2013 01:26:00 GMT
 
"938f573645": {
  "status": "DEPLOYING",
  "operation": {
    "type": "deploy",
    "status": "IN PROGRESS",
    "estimated-duration": 2400,
    "elapsed": 1702,
    "tasks": 175,
    "complete": 100,
    "link": "/{tenant_id}/transactions/982h3f28937h4f23847"
  },
},
…
},
  "87747464ds": {
    "name": "My Blog",
    "status": "DELETING",
    "operation": {
      "type": "deploy",
      "status": "ERROR",
      "error-message": "You reached your maximum number of Cloud Databases",
      "error-help": "Please refer to the [knowledge center](http://kc-link.com) to fix this",
      "retriable": true,  //can be retried
      "retry-link": "/{tenant_id}/transactions/982h3f28937h4f23847/+retry",
      "resumable": true,
      "resume-link": "/{tenant_id}/transactions/982h3f28937h4f23847/+resume",
      "estimated-duration": 2400,
      "elapsed": 1702,
      "tasks": 175,
      "complete": 100,
      "link": "/{tenant_id}/transactions/982h3f28937h4f23847"
    },
    "blueprint": {
      "meta-data": ...
    },
    …
  },
  …
}

CALL 5: Delete Deployment

Request (to Heat):

DELETE /{tenant_id}/deployments/938f573645.json HTTP/1.1
X-Auth-Token: 0d6f2078-55f9-4a7c-97c5-7acb57b1c663
Host: heat.openstack.org

Response Description:

> HTTP/1.1 202 OK
> Content-Type: application/json;charset=utf-8
> Content-Length: 1587
> Date: Mon, 08 Apr 2013 01:26:00 GMT
> Link: \</{tenant_id}/canvases/982h3f28937h4f23847\>; rel="celery canvas"; title="Delete xxx"

{
  "938f573645": {
  "status": "DELETING",
  "operation": {
    "status": "IN PROGRESS",
    "link": "/{tenant_id}/canvases/982h3f28937h4f23847",
    ...
}