Jump to: navigation, search

Difference between revisions of "Heat/Open API"

(GET)
m (CALL 2: Launch a deployment)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== DRAFT ONLY - WORK IN PROGRESS ==
+
== Proposal Only ==
Please recognize that this is only a '''proposed''' DSL to be considered for development. This is NOT YET IMPLEMENTED.
+
Please recognize that this is only a proposed DSL to be considered for development. This is NOT YET IMPLEMENTED.
 +
 
 +
See: [https://blueprints.launchpad.net/heat/+spec/open-api-dsl Launchpad Blueprint for Open API/DSL]
  
 
== Heat Open API Overview ==
 
== Heat Open API Overview ==
Line 14: Line 16:
  
 
Note: Not all verbs on all paths.
 
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 ==
 
== POST & PUT ==
Line 39: Line 45:
  
 
== JSON, YAML, and XML ==
 
== JSON, YAML, and XML ==
Objects are returned as JSON by default, but YAML is also supported (content-type: application/x-yaml)
+
Objects are returned as JSON by default, but YAML (content-type: application/x-yaml) and XML are also supported
HTML output is also supported if the server is started with a `--with-ui` parameter.
 
 
 
XML is not yet supported.
 
  
 
== Special Cases and Considerations ==
 
== Special Cases and Considerations ==
Line 63: Line 66:
  
 
== List of All Calls ==
 
== List of All Calls ==
*:tid* is the tenant ID and is optional.
+
Note: ''':tid''' is the tenant ID and is optional.
  
    GET/POST [/:tid]/environments
+
GET/POST [/:tid]/environments
    PUT/GET/POST [/:tid]/environments/:id
+
PUT/GET/POST [/:tid]/environments/:id
 
   
 
   
    GET [/:tid]/environments/:id/providers
+
GET [/:tid]/environments/:id/providers
    GET [/:tid]/environments/:id/providers/:pid
+
GET [/:tid]/environments/:id/providers/:pid
    GET [/:tid]/environments/:id/providers/:pid/catalog
+
GET [/:tid]/environments/:id/providers/:pid/catalog
    GET [/:tid]/environments/:id/providers/:pid/catalog/:cid
+
GET [/:tid]/environments/:id/providers/:pid/catalog/:cid
 
   
 
   
    GET/POST [/:tid]/blueprints
+
GET/POST [/:tid]/blueprints
    PUT/GET/POST [/:tid]/blueprints/:id
+
PUT/GET/POST [/:tid]/blueprints/:id
 
   
 
   
    GET  [/:tid]/deployments/[?offset=OFFSET&limit=LIMIT]
+
GET  [/:tid]/deployments/[?offset=OFFSET&limit=LIMIT]
    POST [/:tid]/deployments
+
POST [/:tid]/deployments
    PUT/GET/POST [/:tid]/deployments/:id
+
PUT/GET/POST [/:tid]/deployments/:id
    POST [/:tid]/deployments/+parse
+
POST [/:tid]/deployments/+parse
    POST [/:tid]/deployments/+preview
+
POST [/:tid]/deployments/+preview
 
    
 
    
    GET [/:tid]/deployments/:id/status
+
GET [/:tid]/deployments/:id/status
 
    
 
    
    GET  [/:tid]/workflows/[?offset=OFFSET&limit=LIMIT]
+
GET  [/:tid]/workflows/[?offset=OFFSET&limit=LIMIT]
    POST [/:tid]/workflows
+
POST [/:tid]/workflows
    PUT/GET/POST [/:tid]/workflows/:id
+
PUT/GET/POST [/:tid]/workflows/:id
 
   
 
   
    GET [/:tid]/workflows/:id/status
+
GET [/:tid]/workflows/:id/status
 
   
 
   
    POST [/:tid]/workflows/:id/+execute
+
POST [/:tid]/workflows/:id/+execute
 
   
 
   
    GET/POST [/:tid]/workflows/:id/tasks/:task_id
+
GET/POST [/:tid]/workflows/:id/tasks/:task_id
 
   
 
   
    POST [/:tid]/workflows/:id/tasks/:task_id/+execute
+
POST [/:tid]/workflows/:id/tasks/:task_id/+execute
    POST [/:tid]/workflows/:id/tasks/:task_id/+resubmit
+
POST [/:tid]/workflows/:id/tasks/:task_id/+resubmit
 
   
 
   
    GET [/:tid]/providers
+
GET [/:tid]/providers
    GET [/:tid]/providers/:pid
+
GET [/:tid]/providers/:pid
    GET [/:tid]/providers/:pid/catalog
+
GET [/:tid]/providers/:pid/catalog
    GET [/:tid]/providers/:pid/catalog/:cid
+
GET [/:tid]/providers/:pid/catalog/:cid
 
 
    # If the server is started with --with-admin, the following calls are available to admin users:
 
 
   
 
   
    GET /admin/status/celery
+
# If the server is started with --with-simulator, the following calls are available:
    GET /admin/status/libraries
 
 
   
 
   
    # 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 <code>List Deployments</code> 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 <code>resume</code> and <code>abort</code>
 +
 
 +
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"
 
   
 
   
    POST [/:tid]/deployments/simulate
+
{
    GET [/:tid]/deployments/simulate
+
  "938f573645": {
    GET [/:tid]/workflows/simulate/status #progresses the workflow by one task
+
  "status": "DELETING",
    GET [/:tid]/workflows/simulate/status?complete #completes the workflow
+
  "operation": {
 +
    "status": "IN PROGRESS",
 +
    "link": "/{tenant_id}/canvases/982h3f28937h4f23847",
 +
    ...
 +
  }

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",
    ...
}