Tuskar Plan REST API 规范¶
蓝图: https://blueprints.launchpad.net/tuskar/+spec/tripleo-juno-tuskar-plan-rest-api
在 Juno 版本中，Tuskar API 正在向大型应用规划服务模型发展。其初始用途是通过利用 TripleO Heat 模板并融入更大的 TripleO 工作流来部署 OpenStack on OpenStack。
与 Icehouse 版本相比，Tuskar 将不再调用 Heat 来创建和更新堆栈。相反，它将用于定义和操作描述云的 Heat 模板。Tuskar 将是云规划的来源，而 Heat 将是实时云状态的来源。
Tuskar 采用以下概念
部署计划 - Tuskar 正在规划的应用（例如，overcloud）的描述。部署计划跟踪部署中将存在哪些角色以及它们的配置值。在 TripleO 术语中，每个 overcloud 都有自己的部署计划，描述将运行哪些服务以及该特定 overcloud 的这些服务的配置。为简洁起见，在本文档的其他地方将其简单地称为“计划”。
角色 - 可以添加到计划的功能单元。角色是定义将在已部署 Heat 堆栈中的单个服务器上运行的内容。例如，“all-in-one” 角色可能包含运行 overcloud 所需的所有服务，而“compute” 角色可能仅提供 nova-compute 服务。
换句话说，Tuskar 负责将用户选择的角色及其配置组装到 Heat 环境中，并使构建的 Heat 模板和文件可供调用者（TripleO 中的 Tuskar UI，但更普遍地，任何 REST API 的使用者）发送到 Heat。
Tuskar 将与安装的 TripleO Heat 模板一起发布，以作为其角色（取决于此版本中进行的转换 [4]）。目前假设这些模板作为 Tuskar 的 TripleO 安装的一部分安装。将发布另一份规范，涵盖用户上传和操作自己的自定义角色的 API 调用。
本规范描述了 Tuskar 中客户端将交互的 REST API，包括 URL、HTTP 方法、请求和响应数据，以及以下工作流程
在 Tuskar 中创建一个空计划。
查看可用角色的列表。
将角色添加到计划。
从 Tuskar 请求描述整个计划所需的所有配置值的描述。
将用户输入配置值与计划一起保存在 Tuskar 中。
从 Tuskar 请求计划的 Heat 模板，其中包括部署配置应用到 Heat 所需的所有文件。
列出角色调用对于此工作流程至关重要，因此在本规范中进行了描述。否则，本规范不涵盖有关创建、更新或删除角色的 API 调用。假设 Tuskar 在 TripleO 中的安装过程将采取必要的步骤将 TripleO Heat 模板安装到 Tuskar 中。将来的规范将涵盖与角色相关的 API 调用。
问题描述¶
Tuskar 中的 REST API 旨在满足以下需求
灵活选择 overcloud 的功能和部署策略。
存储库，用于发现可以添加到云中的角色。
帮助用户避免手动操作 Heat 模板以创建所需的云设置。
存储云的配置，而无需立即使更改生效（此领域的未来需求可能包括提供更结构化的更改审查和推广生命周期）。
提议的变更¶
总体概念
这些 API 调用将在
/v2/路径下添加，但是 v1 API 将不会维护（模型正在更改为不联系 Heat，并且现有的数据库正在被删除 [3]）。所有调用都有可能在服务器端发生严重错误时引发 500 错误，但为简洁起见，这已从每个调用的可能响应代码列表中省略。
所有调用都有可能在用户身份验证失败时引发 401 错误，并且已从每个调用的文档中类似地省略。
检索单个计划
URL: /plans/<plan-uuid>/
方法: GET
描述: 返回特定计划的详细信息，包括其分配的角色列表和配置信息。
注意事项
配置值是从 Tuskar 的存储文件中读取的，而不是从 Heat 本身读取的。Heat 是实时堆栈的来源，而 Tuskar 是计划的来源。
请求数据: 无
响应代码
200 - 如果找到该计划
404 - 如果没有具有给定 UUID 的计划
响应数据
包含以下内容的 JSON 文档
给定计划的 Tuskar UUID。
创建计划的名称。
创建计划的描述。
上次进行更改的时间戳。
分配给计划的角色列表（由名称和版本标识）。对于本次冲刺，将不会预取超出名称和版本的任何其他角色信息，但将来可以添加，同时保持向后兼容性。
可以为计划配置的参数列表，包括参数名称、标签、描述、隐藏标志以及（如果已设置）当前值。
响应示例
{
"uuid" : "dd4ef003-c855-40ba-b5a6-3fe4176a069e",
"name" : "dev-cloud",
"description" : "Development testing cloud",
"last_modified" : "2014-05-28T21:11:09Z",
"roles" : [
{
"uuid" : "55713e6a-79f5-42e1-aa32-f871b3a0cb64",
"name" : "compute",
"version" : "1",
"links" : {
"href" : "http://server/v2/roles/55713e6a-79f5-42e1-aa32-f871b3a0cb64/",
"rel" : "bookmark"
}
},
{
"uuid" : "2ca53130-b9a4-4fa5-86b8-0177e8507803",
"name" : "controller",
"version" : "1",
"links" : {
"href" : "http://server/v2/roles/2ca53130-b9a4-4fa5-86b8-0177e8507803/",
"rel" : "bookmark"
}
}
],
"parameters" : [
{"name" : "database_host",
"label" : "Database Host",
"description" : "Hostname of the database server",
"hidden" : "false",
"value" : "10.11.12.13"
}
],
"links" : [
{
"href" : "http://server/v2/plans/dd4ef003-c855-40ba-b5a6-3fe4176a069e/",
"rel" : "self"
}
]
}
检索计划的模板文件
URL: /plans/<plan-uuid>/templates/
方法: GET
描述: 返回要发送到 Heat 以创建或更新计划的应用程序的文件集。
注意事项
Tuskar 服务将整个环境构建成一个适合发送到 Heat 的单个文件。从此调用返回该文件的内容。
请求数据: 无
响应代码
200 - 如果找到计划的模板
404 - 如果不存在具有给定 ID 的计划
响应数据: <Heat 模板>
列出计划
URL: /plans/
方法: GET
描述: 返回存储在 Tuskar 中的所有计划的列表。将来，当添加多租户时，这将限定为特定的租户。
注意事项
计划的详细信息，包括其角色和配置值，在此调用中不会返回。需要对特定计划进行后续调用。将来，可能需要添加一个标志来在此调用期间预取此信息。
请求数据: 无（未来的增强功能将需要租户 ID 并可能支持预取标志以获取更详细的数据）
响应代码
200 - 即使列表为空，也可以检索该列表
响应数据
包含有关每个计划的有限信息的 JSON 文档。当没有计划存在时，将返回一个空列表。
响应示例
[
{
"uuid" : "3e61b4b2-259b-4b91-8344-49d7d6d292b6",
"name" : "dev-cloud",
"description" : "Development testing cloud",
"links" : {
"href" : "http://server/v2/plans/3e61b4b2-259b-4b91-8344-49d7d6d292b6/",
"rel" : "bookmark"
}
},
{
"uuid" : "135c7391-6c64-4f66-8fba-aa634a86a941",
"name" : "qe-cloud",
"description" : "QE testing cloud",
"links" : {
"href" : "http://server/v2/plans/135c7391-6c64-4f66-8fba-aa634a86a941/",
"rel" : "bookmark"
}
}
]
创建一个新计划
URL: /plans/
方法: POST
描述: 在 Tuskar 的存储中为计划创建一个条目。详细信息不在本规范的范围内，但想法是所有必要的 Heat 环境基础设施文件和目录都将在 Tuskar 的存储解决方案中创建和存储 [3]。
注意事项
与 Icehouse 不同，Tuskar 在此调用中不会向 Heat 进行任何调用。此调用是创建可以在 Tuskar 中操作、配置、保存和检索为适合发送到 Heat 的格式的新（空）计划。
这是一个同步调用，在 Tuskar 为新创建的计划创建必要的文件后完成。
目前，此调用不支持更大的批量操作，该操作将在单个调用中添加角色或设置配置值。从 REST 的角度来看，这是可以接受的，但从可用性的角度来看，我们可能希望在将来添加此支持。
请求数据
包含以下内容的 JSON 文档
名称 - 要创建的计划的名称。必须在同一租户中的所有计划中是唯一的。
描述 - 要创建的计划的描述。
请求示例
{
"name" : "dev-cloud",
"description" : "Development testing cloud"
}
响应代码
201 - 如果创建成功
409 - 如果存在具有给定名称的计划（在考虑多租户时，对于特定租户）
响应数据
描述创建的计划的 JSON 文档。详细信息与对单个计划进行 GET 操作相同（参见 Retrieve a Single Plan）。
删除现有计划
URL: /plans/<plan-uuid>/
方法: DELETE
描述: 从 Tuskar 的存储中删除计划的 Heat 模板和配置值。
请求数据: 无
响应代码
200 - 如果从 Tuskar 的存储中删除计划条目成功
404 - 如果没有具有给定 UUID 的计划
响应数据: 无
将角色添加到计划
URL: /plans/<plan-uuid>/roles/
方法: POST
描述: 将指定的角色添加到给定的计划。
注意事项
这将导致参数合并发生，并将条目添加到计划的配置参数中以获取新角色。
此调用将更新
last_modified时间戳，以指示已进行更改，需要进行更新才能使 Heat 生效。
请求数据
JSON 文档，包含要添加的角色的 uuid。
请求示例
{
"uuid" : "role_uuid"
}
响应代码
201 - 如果添加成功
404 - 如果没有具有给定 UUID 的计划
409 - 如果计划已经指定角色
响应数据
与从 Retrieve a Single Plan 相同的文档描述该计划。新添加的配置参数将出现在结果中。
从计划中删除角色
URL: /plans/<plan-uuid>/roles/<role-uuid>/
方法: DELETE
描述: 从给定的计划中删除由 role_uuid 标识的角色。
注意事项
这将导致参数合并发生，并且从计划的配置参数中删除条目。
此调用将更新
last_modified时间戳，以指示已进行更改，需要进行更新才能使 Heat 生效。
请求数据: 无
响应代码
200 - 如果删除成功
404 - 如果没有具有给定 UUID 的计划，或者它没有指定的角色和版本组合
响应数据
与从 Retrieve a Single Plan 相同的文档描述该云。配置参数将更新以反映删除的角色。
更改计划的配置值
URL: /plans/<plan-uuid>/
方法: PATCH
描述: 设置一个或多个配置参数的值。
注意事项
此调用将更新
last_modified时间戳，以指示已进行更改，需要进行更新才能使 Heat 生效。
请求数据: 包含要为计划设置的参数键和值的 JSON 文档。
请求示例
[
{
"name" : "database_host",
"value" : "10.11.12.13"
},
{
"name" : "database_password",
"value" : "secret"
}
]
响应代码
200 - 如果更新成功
400 - 如果一个或多个新值验证失败
404 - 如果没有具有给定 UUID 的计划
响应数据
与从 Retrieve a Single Plan 相同的文档描述该计划。
检索可能的角色
URL: /roles/
方法: GET
描述: 返回 Tuskar 中所有可用角色的列表。
注意事项
对于特定角色的每个版本，将有一个条目。
请求数据: 无
响应代码
200 - 包含可用角色
响应数据: 角色列表，其中每个角色包含
名称
版本
描述
响应示例
[
{
"uuid" : "3d46e510-6a63-4ed1-abd0-9306a451f8b4",
"name" : "compute",
"version" : "1",
"description" : "Nova Compute"
},
{
"uuid" : "71d6c754-c89c-4293-9d7b-c4dcc57229f0",
"name" : "compute",
"version" : "2",
"description" : "Nova Compute"
},
{
"uuid" : "651c26f6-63e2-4e76-9b60-614b51249677",
"name" : "controller",
"version" : "1",
"description" : "Controller Services"
}
]
替代方案¶
目前没有为 REST API 提出的替代架构。
安全影响¶
这些更改不应产生额外的安全影响。
其他最终用户影响¶
无
性能影响¶
潜在的性能问题围绕着 Tuskar 存储云文件的方式 [3]。
其他部署者影响¶
无
开发人员影响¶
合并后，Tuskar CLI 将有一段时间与新的调用不一致。Tuskar UI 也需要更新以适应流程的更改。
实现¶
负责人¶
- 主要负责人
jdob
工作项¶
实现计划 CRUD API
实现角色检索 API
编写 REST API 文档
依赖项¶
这些 API 更改取决于 Tuskar 后端的所有实现，包括存储的更改和模板合并。
此外，将角色（提供程序资源）组装到 Heat 环境中取决于 TripleO Heat 模板的转换 [4]。
测试¶
应将 Tempest 测试作为 API 创建的一部分添加。
文档影响¶
REST API 文档需要相应更新。
