幂等 PUT 资源类¶

https://blueprints.launchpad.net/nova/+spec/placement-put-resource-class

Placement API 中创建或更新自定义资源类当前的方法存在两个缺陷，可以通过弃用现有的 POST /resource_classes 并将 PUT /resource_classes/{name} 更改为幂等创建或验证来解决。

问题描述¶

Placement API 的 1.2 微版本添加了对以通常的 POST 创建、PUT 更新方式管理自定义资源类的支持。然而，事实证明，最常见的交互是希望在资源类不存在时创建它。当前流程如下：

GET /resource_classes/CUSTOM_FOOBAR

如果响应是 404，则

POST /resource_classes

{"name": "CUSTOM_FOOBAR"}

如果响应成功，则已创建。如果响应是 409，则资源类已存在，并且在发出 GET 之后，其他进程创建了它。也可以在不发出 GET 的情况下执行 POST，并将 409 作为一种形式的成功接受，但这在 HTTP API 中不是一种正常的交互方式。

与此同时，PUT 更新的形式如下：

PUT /resource_classes/CUSTOM_FOOBAR

{"name": "CUSTOM_NEWBAR"}

这实际上是我们不想允许的事情。我们不希望对资源类的现有引用被重命名，因为这些更新不会反映在 Placement 服务之外的任何地方。

用例¶

作为管理自定义资源类的系统的开发者，我希望以简单、高效和正确的方式管理它们。

提议的变更¶

由于单个自定义资源类的含义仅存在于 URL 中，我们可以调整 PUT /resources_class/{name} 以成为单个资源类的幂等创建者和验证器。要创建新的自定义资源类：

PUT /resource_class/CUSTOM_FOOBAR
<empty body>

Status: 201 Created

如果它可能已经存在，那也没关系

PUT /resource_class/CUSTOM_FOOBAR
<empty body>

Status: 204 No Content

不需要 GET 或 POST，PUT 不需要 body，并且之前 PUT 请求的不可取重命名行为（如上文问题描述中所述）将被删除。

此功能将在新的微版本中实现，该版本将为 PUT 方法提供新的处理程序代码。将保留当前接受带有 name 属性的 body 的 POST 方法，因为这允许新的微版本继续接受旧样式的创建请求，这有利于稳定性。

如果，在未来某个时候，我们意识到需要向资源类添加其他字段，例如 description，那么我们应该再次更新微版本，以允许带有包含这些新字段的 body 的 PUT，但不包括资源类名称。这将允许我们继续使用所需的幂等行为进行 PUT 请求，并仍然防止重命名混淆（如上所述）。在我们需要这些附加字段之前，在 PUT 请求上包含 body 是多余的，因此我们不妨不允许它。

备选方案¶

我们可以什么都不做，但这会使我们面临潜在的危险重命名行为。

数据模型影响¶

无。

REST API 影响¶

主要更改是添加一个微版本，该版本调整了 PUT /resource_classes/{name} 的处理方式，使其不再接受 body，并创建或验证由 {name} 标识的自定义资源类的存在。

PUT /resource_classes/CUSTOM_FOOBAR
<empty body>

成功的响应不包含 body，并且具有以下状态代码之一：

201 Created：如果自定义资源类是新创建的
204 No Content：如果自定义资源类已经存在

可能的错误响应代码是：

400 Bad Request：如果提议的资源类格式无效

安全影响¶

上述重命名问题是一个数据完整性问题，此更改解决了该问题。该问题的表面积很小，因为当前 Placement API 仅供管理员使用。

通知影响¶

无。

其他最终用户影响¶

无。

性能影响¶

通过当前的调度程序报告客户端，存在很小的性能影响，因为我们现在在处理自定义资源类时执行最多一个而不是两个请求。

其他部署者影响¶

由于此更改是在微版本上进行的，较旧版本的调度程序报告客户端将继续对较新版本的 Placement API 正常工作。

开发人员影响¶

无。

实现¶

负责人¶

主要负责人: cdent
其他贡献者: 无

工作项¶

在新微版本中为 PUT /resource_classes/{name} 创建新的处理程序代码。
添加练习新微版本的 gabbi 测试。
更新微版本历史记录。
更新 placement-api-ref。
更新调度程序报告客户端以使用新的接口。

依赖项¶

无

测试¶

新的 gabbi 和现有的调度程序功能测试以及 tempest 测试将行使此更改。

文档影响¶

需要更新 placement-api-ref 以反映此更改，但该更改不会影响安装或配置，因此这些文档应该没问题。

参考资料¶

自定义资源类规范

历史¶

修订版¶
发布名称	描述
Pike	引入

幂等的 PUT 资源类