API 一致性清理

https://blueprints.launchpad.net/nova/+spec/api-consistency-cleanup

此蓝图提出了一些 API 的清理工作，以提高一致性和可用性。

问题描述

目前，API 中存在许多不一致之处和宽松的验证。这些不一致之处是由于 v2 API 的兼容性造成的。

由于对请求体和查询参数的验证过于宽松，API 会默默地忽略未知的和无效的输入。这会给用户留下这样的印象，即请求的未知或无效输入是有效的，并且已被 Nova 处理。但 Nova 在 API 层直接忽略所有未知或无效的输入，而不会向用户发出任何警告。

服务器的表示形式在所有返回服务器信息的 API 响应体中并不一致。GET、PUT、REBUILD /servers API 返回服务器的表示形式（包含所有服务器属性）。但 PUT 和 REBUILD /servers 响应与 GET /servers API 不匹配。

这些是 API 不一致的两个例子，可能还有更多类似的例子，这些例子在“提案”部分中描述。

用例

作为 API 消费者，我希望以更一致的方式使用 Nova API，并进行严格的验证以提高可用性。

作为开发者，我希望提供和维护更好/更干净/更一致的 API。

对于客户端代码解析 API 响应，存在维护优势。对于开发者来说，只有当我们能够在未来提高最低微版本号时，维护才能更容易。

提议的变更

为 API 添加一个新的微版本，以清理多个问题和不一致之处。

提案是将所有上述清理工作放在单个微版本中完成。

清理列表

  1. 对于查询参数和请求体中的未知参数，返回 400 错误。

    目前，服务器查询参数或许多其他 API 请求体中的未知参数会被默默忽略。这导致了许多不一致之处，一个很好的例子是 --deleted 和 --status DELETED 查询参数，用于 nova --list。

    如果您不是管理员，那么 --deleted 和 --status deleted 的行为分别对应 200 和 403。从最终用户角度来看，这两个过滤器是相同的，但由于我们的实现，我们返回不同的行为。

    • nova list --deleted：200，由于 additionalProperty=True 且为了向后兼容性，API 接受并忽略了无效的过滤器。 --deleted 是非管理员的无效过滤器

    • nova list --status DELETED：403。 --status 是非管理员的有效过滤器，因此 API 不会忽略它。

    我们对 status=DELETED 请求有明确的检查，如果请求者不是管理员，则返回 403。详细讨论 [1]

    我们可以通过将所有 API 的查询参数和请求体的 additionalProperties: False 来解决这个问题，前提是 additionalProperties 为 True。例如 [2] 和 [3]

    需要修改的 API： https://github.com/openstack/nova/search?p=1&q=additionalProperties%3A+True&unscoped_q=additionalProperties%3A+True

  2. 使所有返回完整服务器表示形式的 API 中的服务器表示形式始终一致。

    GET、PUT、REBUILD /servers API 返回完整的服务器表示形式（包含所有服务器属性）。但 PUT 和 REBUILD /servers 响应与 GET /servers API 不匹配。

    PUT 和 REBUILD 响应与 GET 响应之间的差异可能是由于历史原因，PUT 和 REBUILD 只返回响应中可以从请求中获取的字段，这些字段会修改服务器，但随着时间的推移，我们开始在响应中返回更多的字段，以使其与 GET 响应一致。 这样，只有新添加到 GET 响应中的字段也开始返回到 PUT 和 REBUILD 中，而旧字段却遗漏了。最终，这并没有保持 PUT 和 REBUILD 响应的原始意图，并且与 GET 响应不完全一致。

    许多字段仅在 GET API 中返回，而在 PUT 或 REBUILD 中不返回。响应差异是作为扩展添加的属性

    • OS-EXT-AZ:availability_zone

    • OS-EXT-SRV-ATTR:host

    • OS-EXT-SRV-ATTR:hostname

    • OS-EXT-SRV-ATTR:hypervisor_hostname

    • OS-EXT-SRV-ATTR:instance_name

    • OS-EXT-SRV-ATTR:kernel_id

    • OS-EXT-SRV-ATTR:launch_index

    • OS-EXT-SRV-ATTR:ramdisk_id

    • OS-EXT-SRV-ATTR:reservation_id

    • OS-EXT-SRV-ATTR:root_device_name

    • OS-EXT-SRV-ATTR:user_data

    • OS-EXT-STS:power_state

    • OS-EXT-STS:task_state

    • OS-EXT-STS:vm_state

    • OS-SRV-USG:launched_at

    • OS-SRV-USG:terminated_at

    • os-extended-volumes:volumes_attached

    需要修改的 API

    • PUT /servers

    • POST /servers/{server_id}/action {rebuild}

  3. 将风味 API 中 swap 字段的默认返回值从空字符串更改为 0（整数）。

    目前，在创建风味时，如果您没有设置可选的 swap 属性，则风味 API 响应中的 swap 属性值将返回一个空字符串。Bug：https://bugs.launchpad.net/nova/+bug/1815476 在 CLI 侧处理此空字符串时，它显示为空白，这令人困惑，并且与其他字段不一致，例如“OS-FLV-EXT-DATA:ephemeral”。服务器 API 响应中的风味表示形式将 swap 默认值设置为 0。提案使其一致，并在以下 API 中返回 swap 默认值 0（整数）

    • POST /flavors

    • GET /flavors/detail

    • GET /flavors/{flavor_id}

    • PUT /flavors/{flavor_id}

  4. 即使超节点上没有服务器，也要始终在 GET 超节点 API 的响应中返回 servers 字段

    目前，如果请求的超节点上没有服务器，则 servers 字段将从 API 响应中省略。这是一种不一致的响应，理想情况下，所有字段都应存在于响应中，即使值为为空。提案是在以下 API 的响应中始终返回 servers 字段。如果没有任何服务器，servers 字段将是一个空列表。

    • GET /os-hypervisors?with_servers=True

    • GET /os-hypervisors/detail?with_servers=True

    • GET /os-hypervisors/{hypervisor_id}?with_servers=True

备选方案

我们可以保持 API 不变，并以当前的方式使用它们，或者我们可以选择上述列表中的一些问题一次性解决。

以下清理工作已从该提案中过滤掉

  1. 删除请求和响应字段中的扩展 (OS-) 前缀。

  2. 修复不一致/不正确的响应代码

数据模型影响

无

REST API 影响

此提案是为了修复 API 中的多个问题。我将以与上述相同的顺序列出每个问题对 REST API 的影响。

  1. 对于查询参数和请求体中的未知参数，返回 400 错误。

    允许未知请求和查询参数并忽略的 API 将更改为返回 400。以下是具有 additionalProperties: True 的 API，并将修改为 additionalProperties: False：https://github.com/openstack/nova/search?p=1&q=additionalProperties%3A+True&unscoped_q=additionalProperties%3A+True

  2. 使所有 API 中的服务器表示形式始终一致

    PUT /servers/{server_id} 和 POST /servers/{server_id}/action {rebuild} API 响应将被修改，以添加所有丢失的字段，这些字段由 GET /servers/{server_id} 返回。

    注意：新字段将以与 GET /servers API 响应中相同的名称添加（即带有 OS- 前缀）。

  3. 将风味 API 中 swap 字段的默认返回值从空字符串更改为 0（整数）。

    以下 API 响应将被更改为返回 swap 默认值 0（整数）

    • POST /flavors

    • GET /flavors/detail

    • GET /flavors/{flavor_id}

    • PUT /flavors/{flavor_id}

  4. 即使超节点上没有服务器，也要始终在 GET 超节点 API 的响应中返回 servers 字段

    以下 API 响应将被更改为始终在响应体中返回 servers 字段。如果没有任何服务器，servers 字段将是一个空列表

    • GET /os-hypervisors?with_servers=True

    • GET /os-hypervisors/detail?with_servers=True

    • GET /os-hypervisors/{hypervisor_id}?with_servers=True

安全影响

无

通知影响

无

其他最终用户影响

python novaclient 和 openstack-client 将被更新。

性能影响

无

其他部署者影响

无

开发人员影响

无

升级影响

无

实现

负责人

主要负责人

Ghanshyam Mann

工作项

  • Nova API 的单个微版本更改

  • 添加更改的测试

  • python 客户端 (python-novaclient 和 python-openstackclient) 更改

依赖项

无

测试

  • 添加相关的单元测试。

  • 添加相关的功能测试。

  • Tempest 中的响应更改模式测试

文档影响

修改 api-ref 以反映 API 更改。

参考资料

历史

修订：header-rows: 1

发布名称

描述

Train

引入