Difference between revisions of "Heat/Open API"

Revision as of 05:32, 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",
    ...
}

Difference between revisions of "Heat/Open API"

Revision as of 05:32, 12 April 2013

Contents

Proposal Only

Heat Open API Overview

GET

POST & PUT

POST /objects (without ID)

POST /objects/:id

PUT /objects/:id

DELETE /objects/:id

JSON, YAML, and XML

Special Cases and Considerations

List of All Calls

Full Lifecycle with API Use Case

CALL 1: Get list of Heat Blueprints

CALL 2: Launch a deployment

CALL 3: Get Deployment

CALL 4: List Deployments

CALL 5: Delete Deployment