Difference between revisions of "Heat/Open API"
Ziad Sawalha (talk | contribs) m (→CALL 2: Launch a deployment) |
Ziad Sawalha (talk | contribs) m (→CALL 2: Launch a deployment) |
||
Line 199: | Line 199: | ||
"status": "PLANNING", | "status": "PLANNING", | ||
"display-outputs": { | "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 | |
− | + | } | |
}, ... | }, ... | ||
} | } |
Latest revision as of 05:33, 12 April 2013
Contents
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", ... }