提升代理厂商通道至核心 API¶
https://bugs.launchpad.net/ironic/+bug/1570841
本规范建议将当前的代理厂商通道 API（查找和心跳）设为一级 API 端点，并弃用代理厂商通道接口。
问题描述¶
厂商通道的设计目的是让厂商在其特定功能被 Ironic 广泛采用并提升到核心 API 之前，先放置这些功能。
然而，在使用 IPA（目前唯一可用的树内 ramdisk）时，这两个 API 端点在部署和清理过程中都起着关键作用。因此，每个基于 IPA 的驱动程序都必须将其代理厂商通道融入其厂商通道中。
drac 驱动程序在未这样做时出现了一个错误，导致该驱动程序无法与 IPA 配合使用。
该提案还试图减少发送到未经身份验证的端点和从这些端点接收的数据量。当前的厂商通道 API 接受整个清单并返回整个节点记录，包括 IPMI 凭据。
提议的变更¶
创建用于查找和心跳的新 API 端点 - 参见 REST API 影响 以获取详细信息。
使用心跳方法扩展部署接口 - 参见 驱动程序 API 影响 以获取详细信息。
备选方案¶
继续执行我们现在所做的事情。
使查找调用依赖于驱动程序（如 passthru 以前那样）。
这看起来是不必要的复杂化（例如，我们现在必须将驱动程序传递给来自 conductor 的 IPA）。
我们可以利用这次更改将未经身份验证的端点完全从主 API 中移除。这可以通过引入一个新的 API 服务来实现，例如
ironic-agent-api，仅提供这两个端点。然后我们将建议操作员使此服务仅侦听配置网络，而不侦听可供用户访问的网络。从理论上讲，可以通过配置 WSGI 容器（Apache mod_wsgi 或类似容器）来实现相同的结果，因此可能不值得增加复杂性。
数据模型影响¶
无
状态机影响¶
无
REST API 影响¶
添加了两个新的端点。这两个端点不经过身份验证。
GET /v1/lookup?addresses=MAC1,MAC2&node_uuid=UUID查找节点详细信息，以便在 ramdisk 中进一步使用。
没有正文；必须存在以下 URL 参数中的至少一个
addresses以逗号分隔的硬件地址列表（例如 MAC），用于查找；node_uuid节点 UUID（如果已知，例如通过检查）。
如果存在
node_uuid，则忽略addresses。默认情况下，仅当节点处于以下临时状态之一时才返回节点：
deploying、deploy wait、cleaning、clean wait、inspecting、inspect wait。需要始终工作的查找的部署者可以设置一个新的选项[api]restrict_lookup为False。注意
从理论上讲，我们也不需要这里的
-ing状态。但是，在清理期间重新启动时，我们当前不会将状态重置为clean wait。支持其他-ing状态，以防第三方驱动程序具有类似的限制。响应：HTTP 200，带有包含键的 JSON 正文
config用于将配置选项从 conductor 传递到 ramdisk 的字典。对于 IPA ramdisk，当前仅使用一个heartbeat_timeoutramdisk 期望的 Ironic 心跳之间的超时时间（以秒为单位）。
node节点的部分表示形式，作为一个 JSON 对象，发送以下字段properties用于根设备提示，instance_info用于磁盘大小详细信息，uuid节点 UUID，driver_internal_info用于传递其他运行时信息。
可以随着时间的推移通过适当的 API 版本升级来暴露更多字段。
错误代码
400 - 请求错误，
404 - 未找到节点。
POST /v1/heartbeat/<UUID>记录来自 ramdisk 的心跳消息。
正文是一个带有字段的 JSON
callback_url- IPA URL 以进行回调。请注意，对于潜在的非 IPA 驱动程序，它可能具有不同的含义（例如，如果我们同意 ansible 驱动程序，这可以是 SSH “URL”）。
响应：HTTP 202，没有正文。
错误代码
400 - 请求错误，
404 - 未找到节点，
409 - 节点已锁定（应由 ramdisk 重试）。
将引入一个新的 API 版本来涵盖这两个端点。
客户端 (CLI) 影响¶
这两个端点都将在 Python API 中作为 ironic 客户端暴露
ironic.node.lookup(addresses, node_uuid=None)
ironic.node.heartbeat(node_uuid, callback_url)
但是，由于它们不打算供最终用户使用，因此它们不会在 CLI 中暴露。
“ironic” CLI¶
无
“openstack baremetal” CLI¶
无
RPC API 影响¶
创建一个新的 RPC 调用，以连接心跳 API 端点和新的部署驱动程序方法：heartbeat（异步）。
驱动程序 API 影响¶
在部署驱动程序接口中添加了一种新方法
def heartbeat(self, task, callback_url):
"""Record a heart beat for the node.
:param task: a task manager task
:param callback_url: a URL to use to call to the ramdisk
:return: None
"""
LOG.warning('Got heartbeat message from node %(node)s, but the driver '
'%(driver)s does not support heartbeating',
{'node': task.node.uuid, 'driver': task.node.driver})
将 BaseAgentVendor 中的心跳方法重构为单独的 mix-in 类，以便在 AgentDeploy 和 BaseAgentVendor 中重用。
新方法不会是抽象的，以允许驱动程序使用不同的方法（例如，没有 ramdisk 的驱动程序）。默认实现将不执行任何操作，以适应不需要心跳的部署驱动程序。
新方法将接收共享的节点锁。实现是否需要将锁升级为独占锁由实现决定。
Nova 驱动程序影响¶
无
Ramdisk 影响¶
无
安全影响¶
此更改将暴露用于通过其 MAC 地址查找节点的未经身份验证的 API。它对大多数部署没有影响，因为树内部署方法（iscsi 和 http）已经暴露了这种 API。
在完全切换到新的 API 端点后，将不再有可能在不知道身份验证的情况下通过其 MAC 地址获取整个节点。只有有限的字段可用。值得注意的是，新的 API 端点不发送电源凭据。
我们应该明确指出，任何部署实现都应谨慎处理新的
heartbeat调用中的传入数据。特别是，不应将任何敏感信息发送到由callback_url参数指定的端点。
其他最终用户影响¶
无
可扩展性影响¶
无
性能影响¶
与旧的查找通道不同，新的查找端点将不使用 RPC，从而降低消息队列和 conductor 的负载。
其他部署者影响¶
建议更新 IPA 镜像以使其使用新的 API。
在
api部分中添加了一个新的选项restrict_lookup（布尔值，默认为True） - 是否将新的查找 API 限制为仅在预期查找的状态。
开发人员影响¶
第三方驱动程序开发人员应停止在其驱动程序中使用 BaseAgentVendor 类，而应仅使用 AgentDeploy 类。
第三方驱动程序应记录它们是否需要将 restrict_lookup 选项设置为 False 才能正常运行。
实现¶
负责人¶
Dmitry Tantsur (lp: divius, irc: dtanstur)
Jim Rollenhagen (irc: jroll)
工作项¶
创建新的部署接口方法
在 AgentDeploy 中实现它们
创建新的 RPC 调用和 API 端点
切换 IPA 以使用新的端点，并在失败时回退到旧的端点
依赖项¶
无
测试¶
测试将在当前门禁测试中进行。
升级和向后兼容性¶
无论升级顺序如何，IPA 和 ironic 本身，都将保证完全的向后兼容性。
将弃用 BaseAgentVendor 类，但会保留一段时间，遵循通常的弃用策略。旧的 IPA 镜像将能够通过使用旧的通道 API 运行。
新的 IPA 镜像将首先尝试命中新的端点，并在收到 HTTP 406 Not Acceptable（表示 API 版本不受支持）时回退到旧的端点。
文档影响¶
记录如何使用新的心跳方法实现新的部署驱动程序。
记录与两个端点相关的潜在安全问题。
