Blueprint-ec2-error-codes

• Launchpad 条目: NovaSpec:ec2-error-codes
• 创建时间: 2012年11月19日
• 贡献者:

总结

本提案旨在以统一的方式管理外来 API 支持代码中的错误响应，特别是针对 EC2。

原理

简介

EC2 API 具有定义良好的错误码，程序可以使用这些错误码来采取纠正措施。如果没有正确的 EC2 错误码，使用 EC2 API 将非常困难。

Amazon 提供了文档：错误码

EC2 错误响应包含 3 个重要信息

• HTTP 状态码

 The documentation just distinguish the Client Error 4** or Server Errors 5**.

• 客户端错误：客户端操作不当，例如无效的格式错误的属性，尝试在由于资源实际状态而无法执行操作时执行操作。
• 服务器错误：服务器无法执行请求，因为服务器自身的问题，例如资源不足或数据库连接问题。
• 错误码（文本）

  Usable by scripts/programs to do the right corrective action.
  The same EC2 Error Code can be client or server, distinguishable by the HTTP Status Code.

• 消息部分

  Human readable text. It can be translated to the end user's native language.

当前 OpenStack 中的 EC2 错误码

• nova/api/ec2/cloud.py 在 38 个地方使用带有 EC2APIError 错误码的异常。
• nova/api/ec2/faults.py 将 HTTP 状态码 (5**) 渲染为 EC2 错误码
• nova/api/ec2/init.py 将异常类名渲染为错误码 14 次，并在不同的日志级别记录它们。
• nova/api/ec2/init.py 3 次显示“Unauthorized”（未授权）

在所有其他情况下，您将收到 "UnknownError":"An unknown error has occurred. Please try your request again."（未知错误：发生未知错误。请重试您的请求。）响应。

您会经常看到 UnknownError。想象一下，如果您是远程客户，无法查看日志文件，会发生这种情况。

为什么创建本文档 ?

• 数百个错误的 EC2 错误码可能会被报告为错误。
• 为了避免不必要的不同解决方案和关于实现的无谓提问。

设计

• 在将异常转换为错误响应时，使异常具有自描述性
• 考虑 EC2 SOAP 传输和其他 API
• 避免泄露机密信息

实现

1. 使用异常类名而不是 UnknownError
2. 根据代码变更部分修改 Executor
3. 用 EC2 异常替换 EC2APIErrors，或将参数添加到 OS 异常
4. 为现有异常添加属性并创建新的 EC2 异常
5. 修改单元测试，以不允许在 EC2 错误响应中出现非 EC2 错误码
6. 修改单元测试以验证正确的 EC2 错误码
7. 修复 Server (faults.py) EC2 错误码

代码变更

• EC2 API 实现可以使用异常类名作为 EC2 错误码，如果它没有其他想法

   Rationality:

• 有助于跟踪没有正确编码的异常
• 作为一种临时解决方案，最终用户可以使用它
• 所有异常都可能包含外来 API 数据，将其翻译到 API 实现端似乎非常困难。

  The attributes for foreign API should be prefixed by the API name like 'ec2_'
      EC2 case:

• ec2_error_code - 错误码，如果指定了它，则必须用作 EC2 错误码
• ec2_status - HTTP 状态码
• ec2_message - EC2 错误响应的消息
• ec2_loglevel - 如果无法确定，则为正确的日志级别

  Rationality:

• 避免混淆
• HTTP 状态码在 EC2 和 OS API 规范中可能不同

  Note:

• HTTP 状态码很可能不需要与 OS 的“code”属性不同
• 日志记录策略可以与 OS API 相同
• 最终消息可以与 OS API 消息相同
• 如果缺少 'ec2_status'，EC2 错误响应应使用与 OS 错误相同的 'code'
• 如果缺少 'ec2_message'，EC2 错误响应应使用与 OS 错误相同的 'message'
• 特定于 API 的异常应以 API 名称为后缀，例如 EC2。在 EC2 的情况下，必须从错误码中删除最后的“EC2”。

       Rationality:

• 有助于为正确的 API 选择正确的异常

       Note:

• EC2 标记的异常类，您可以定义没有前缀的属性
• EC2 错误码可以包含“.”，但不包含“_”。在基于异常名称创建错误码时，必须将“_”转换为“.”。

        Rationality:

• 避免需要指定与异常名称类似的 ec2_error_code

安全性和内部服务器错误考虑

服务器错误 (5**) 消息部分不一定设计给最终用户。例如：“使用用户=root，密码=S3cr3t 无法连接到 DB”

当您需要发送与未知内部错误相关的错误响应时，必须将原始消息替换为通用消息，并且必须以关键或错误级别记录原始异常。

异常的消息被认为是最终用户可见的

• 异常具有“code”属性，并且它是 4**，或者
• 异常具有“ec2_status”或“ec2_message”属性

否则，消息部分必须经过清理。

异常类名不被认为是机密数据，但是您应该使用 'InternalError' 作为服务器错误码，除非 EC2 API 规范另有说明。

附加说明

• 可能的未来 EC2 SOAP API 必须用以下内容为前缀：
  • 'Client.' - 当 HTTP 状态码为 4** 时
  • 'Server.' - 当 HTTP 状态码为 5** 时
• 由于 EC2 没有指定确切的 HTTP 状态码，您可以使用与 EC2 规范作者相同的方法，或者根据 HTTP RFC（例如 rfc2616）做出决定。
• 可能存在 EC2 需要 *.NotFound 错误响应，但 OS API 使用空列表的情况

测试/演示计划

单元测试和 tempest。

---