跳转到： 导航, 搜索

Heat/Open API

仅提案

请注意，这只是一个建议的 DSL，供开发考虑。目前尚未实现。

参见：Launchpad Blueprint for Open API/DSL

Heat Open API 概述

这是一个 REST API，用于支持建议的 Heat/DSL。该 API 是一个 REST HTTP API。它支持 POST、PUT、GET、DELETE 在

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


注意：并非所有路径都支持所有动词。

GET

  • 有时会添加对象 ID 和租户 ID，如果底层存储不提供它们的话。
    • 这样做是为了在稍后解析时可以识别对象。

POST & PUT

  • PUT - 在不采取任何操作或对其他资源产生副作用的情况下更新。唯一允许的副作用是资源本身（例如，更新最后修改字段）。
  • POST - 可以更新和/或触发操作（如实际的服务器部署），并且可以接受部分对象。


语义如下

POST /objects (没有 ID)

  • 创建一个新对象。ID 由 Heat 生成，并在 Location 标头中返回。
  • 用于创建对象，无需担心 ID 冲突

POST /objects/:id

  • 更新现有对象。支持部分更新（即，我可以只 POST 名称来重命名对象）。可以触发操作，例如运行工作流。
  • 用于修改对象的某些部分。

PUT /objects/:id

  • 完全覆盖对象。不触发副作用，但会验证数据（尤其是 id 和 tenant_id 字段）。
  • 用于将某些内容存储在 Heat 中（例如，从 Heat 的另一个实例导出的部署）。

DELETE /objects/:id

  • 将触发对象的删除。
  • 也可能触发删除 Heat 为给定组装启动的所有相关正在运行的实例。

JSON, YAML 和 XML

对象默认以 JSON 格式返回，但 YAML (content-type: application/x-yaml) 和 XML 也受支持

特殊情况和注意事项

所有对象都应该有一个根键，其名称为类名。例如 `{"blueprint": {"id": 1}}`。但是，如果提供对象，Heat 将允许没有根键的对象。例如

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

Heat 将填充已发布对象的 id、状态、tenant_id 和创建日期。对于 PUT，必须提供这些值，并且必须正确（即，与 URL 中的租户和 id 匹配）。

YAML 支持文档内的引用。如果部署采用 YAML 格式并使用引用，则可以在名为 'includes' 的键下提供引用。例如，这可用于传入所有必要的组件、蓝图、环境等创建新部署（或对其引用）。

某些命令可以使用 '+command' URL 发出。例如

     /workflows/wf1000/+execute

所有调用都支持从根目录或租户 ID 下进行。从根目录发出的调用需要管理权限，并将返回所有租户的所有对象（例如，/environments 与 /T1000/environments）。

所有对 GET /deployments 和 GET /workflows 的调用都可以选择性地通过 offset 和 limit 进行分页。

所有调用的列表

注意：:tid 是租户 ID，是可选的。

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


完整生命周期与 API 用例

本节详细介绍了客户端（例如 Horizon）实现选择 Heat Blueprint、启动它、监视进度然后删除它的所有必要的 API 调用。


CALL 1: 获取 Heat Blueprints 列表

请求

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

注意：当蓝图数量很大时，使用分页集合。

响应示例

> 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: 启动部署

请求描述

将用户提供的选项组合到 `inputs` 对象中。将该对象添加到蓝图对象并 POST 组合对象。

请求（到 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",
      ...
   }
}

响应描述

Location 标头将异步返回，以便尽快提供部署 ID。

display-outputs：将包含要显示的输出，例如应用程序 URL。还可以返回其他信息，例如 URL 的 IP，以便客户端可以显示有关修改 hosts 文件直到 DNS 传播的信息，例如 bash 脚本。

我们希望支持可插拔的底层实现（工作流、celery 画布、分布式状态引擎等）。为了以通用方式支持客户端工具，API 将在适当的情况下返回 [RFC5988](http://tools.ietf.org/html/rfc5988) Link 标头。

响应示例

> 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: 获取部署

用于在部署启动时获取状态，以及检索有关现有部署的数据。

请求（到 Heat）

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

响应描述

响应字段

  • status：将反映整体部署状态。
  • operation：将包含有关正在进行的操作的信息（独立于运行它的子系统）。将始终提供以下字段
  • operation.type：deploy、add node、delete 等…
  • operation.estimated-duration：从开始到完成的预计总秒数
  • operation.elapsed：自开始以来经过的总秒数（这不是一个有效的时间估计。它是基于任务估计持续时间和任务完成状态计算的完成估计）
  • operation.tasks：要完成的总任务数
  • operation.complete：已完成的总任务数
  • operation.link：指向操作的链接 - 这将是特定于实现的


注意：请参阅 List Deployments 以获取错误条件的示例

  • resources：资源的哈希值。对于每个资源
  • resource.provider：nova、databases、load-balancers 等…用于创建它的服务。
  • resource.dns-name：资源的名称
  • resource.status：资源的状态（例如，BUILD、CONFIGURE、ACTIVE 等…）
  • resource.service：资源所在的蓝图服务
  • resource.instance：包含诸如 id、flavor、image、region 等的信息。


响应示例

> 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: 列出部署

请求（到 Heat）

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

响应描述

响应字段

  • key：是 ID。
  • name：部署的名称
  • status：状态作为字符串
  • operation：将包含有关正在进行的操作的信息（独立于可插拔的子系统运行它）。

在发生错误的情况下

  • operation.status：ERROR。请注意，这与部署状态不同。
  • operation.error-message：简短的一行错误描述
  • operation.error-help：详细的错误信息
  • operation.retryable：是否可以重试此错误？
  • operation.retry-link：要调用的 URL 以重试


注意：同样适用于 resume 和 abort

响应示例

> 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: 删除部署

请求（到 Heat）

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

响应描述

> 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",
    ...
}
从 "https://wiki.openstack.org/w/index.php?title=Heat/Open_API&oldid=20440" 检索