通过 Runbook 进行自助服务¶

https://bugs.launchpad.net/ironic/+bug/2027690

随着服务步骤的增加，结合所有者/承租人概念，我们现在有机会允许项目成员通过允许他们访问策划好的步骤 Runbook 来自助完成许多维护项目。

此功能主要涉及扩展创建新的 Runbook 概念，允许创建步骤列表，并通过特性与节点关联。然后，这些 Runbook 将能够在执行手动清理或节点服务时替代步骤列表。

问题描述¶

目前，作为项目范围成员的 Ironic API 用户自助完成维护项目能力有限。Ironic 操作员面临着艰难的选择，即授予用户对节点的广泛访问权限，允许他们运行任意手动清理或服务步骤，或者完全不允许访问自助完成这些维护项目。

用例包括

作为项目成员，我可以在不授予执行节点上任意步骤的能力的情况下，通过节点服务执行 Runbook。
作为系统管理员，我希望以相同的方式在许多相似节点上存储执行操作的步骤列表。

提议的变更¶

提议的更改是创建一个新的 API 概念，即 Runbook，它可以与当前接受显式步骤列表的任何 API 流程一起使用。

这些 Runbook 随后可以用作设置节点置备状态时 clean_steps 或 service_steps [0] 的替代品。预计它们与提供 clean_steps 或 service_steps 的 API 调用具有相同的行为，包括尊重 disable_ramdisk 字段，并提供显式排序而不是自动化清理和部署中使用的基于优先级的排序。

此外，我们将确保 Runbook 的完整 CRUD 生命周期在代码中是基于角色的，以便项目可以限制谁可以创建、删除、编辑或将 Runbook 标记为公共，所有这些都是单独的策略开关。我们还将确保部署者可以单独切换通过 Runbook 或任意步骤列表进行基于步骤的流程的能力。

Runbook 仅会在具有与 Runbook 名称相等的特性的节点上运行，以确保 Runbook 已被批准用于给定的硬件，作为防止硬件损坏的额外预防措施。

备选方案¶

最初，我们考虑过将现有的部署模板重新用于通用模板概念。由于部署模板包含隐式步骤，难以对其进行推理，因此放弃了这一想法。这就是为什么我们选择将其称为 Runbook 的原因，Runbook 完全指定，而模板部分指定并集成了隐式步骤。

数据模型影响¶

创建下面描述的新表

``runbooks`` (same as ``deploy_templates`` except addition of ``owner`` and ``public``)
  - id (int, pkey)
  - uuid
  - name (string 255)
  - public (bool) - When true, template is available for use by any project.
  - owner (nullable string, usually a keystone project ID)
  - disable_ramdisk - When true, similar behavior to disable_ramdisk in manual cleaning -- do not boot IPA
  - extra json/string
  - steps list of ids pointing to ``runbook_steps``

``runbook_steps``
  - id (int, pkey)
  - runbook_id (Foreign Key to runbooks.id)
  - interface
  - step
  - args
  - order (or some other field/method to indicate how the steps were ordered coming into the API)

注意：确保对 runbooks 的所有查询仅在需要时拉取 runbook_steps。

状态机影响¶

虽然没有提议任何状态或状态转换，但用于调用其中一些状态转换的 API 需要更改为支持 Runbook。

REST API 影响¶

将添加一个新的顶级 REST API 端点，/v1/runbooks/，并提供基本的 CRUD 支持。

现有的 /v1/nodes/<node>/states/provision API 将更改为在用于服务或手动清理时接受 runbook（名称或 uuid）来替代 clean_steps。

客户端 (CLI) 影响¶

CLI 将更新以添加对新 API 端点支持。

一些将要添加的 CLI 命令示例，以及它们如何与 RBAC 交互

- baremetal runbook create X [opts] # as system-scoped manager
  - owner: null
  - public: false
- baremetal runbook create X [opts] # as project-scoped manager
  - owner: projectX
  - public: false
- baremetal runbook set X --public # as system-scoped manager
  - owner: null
  - public: true
  - Note: Owner field is nulled even if it previously set.
- baremetal runbook set X --public # as project-scoped manager
  - Forbidden! Requires system-scoped access.
- baremetal runbook unset X --public # as system-scoped manager
  - owner: null
  - public: false
- baremetal runbook set X --owner projectX # as system-scoped manager
  - owner: projectX
  - public: false
  - Note: Will return an error if ``runbook.public`` is true.
- baremetal node service N --runbook X
- baremetal node clean N --runbook X
- baremetal node service N --runbook X --service-steps {} # NOT PERMITTED
- baremetal node clean N --runbook X --clean-steps {} # NOT PERMITTED

RPC API 影响¶

RPC API 将修改为在必要时支持 Runbook 替代步骤。它们将被正确地版本化以确保平滑升级。

驱动程序 API 影响¶

无

Nova 驱动程序影响¶

无

Ramdisk 影响¶

无

安全影响¶

操作员警告说，即使使用此功能，用户也可能利用单独看起来无害的步骤或访问权限，但组合起来时可能具有恶意性。

部署者应确保他们已审查所有可能的威胁模型，并在授予不太信任的个人额外的访问权限时，包括限制不安全的节点操作，例如替换 deploy_ramdisk 以确保 Runbook（和其他基于步骤的流程）按预期运行。

实施者需要避免的事情以确保安全实施

默认情况下，不要允许项目范围的 API 用户更改 runbooks.public。
默认情况下，不要允许项目范围的 API 用户更改 runbooks.owner。
任何会隐式地将 Runbook 标记为非公共的内容。
确保我们使用节点特性检查节点是否能够运行给定的 Runbook，方法与我们对部署模板执行相同的方式。

RBAC 影响¶

此功能与 RBAC 交互的两种主要方式，除了 Runbook 的 CRUD 之外。

首先，runbooks.owner 和 runbooks.public 字段与确定 Runbook 是限定于项目还是限定于系统有关。如果 owner 为非空且 public 为 false，则 Runbook 限定于该字段中设置的项目，并且只能在由该项目拥有或租赁的节点上使用。如果 owner 为空且 public 为 false，则 Runbook 只能由系统范围的用户使用或访问。如果 owner 为空且 public 为 true，则系统范围的成员可以修改 Runbook，并且项目范围的成员可以在兼容的节点上使用它。此外，owner 字段仅在 public 为 false 或设置为 false 时才可设置，并且将 public 设置为 true 将使 owner 字段为空。

其次，节点更改置备状态 [0] API 将添加一个 runbook 字段，并且当指定 runbook 而不是 clean_steps 时，策略将不同。默认策略是允许使用 Runbook 的节点所有者或承租人范围的成员进行手动清理和维护，但在指定 clean_steps 时禁止这样做。不允许同时使用 clean_steps 和 runbook。

完成此实施后预期的访问权限

System
- Admin
- Manager
- Member
--> Can CRUD system-scoped templates (template.owner=null)
--> Can CRUD project-scoped templates (template.owner=PROJECT)
--> Can unset template.owner, changing a template to system-scope
--> Can mark system-scoped templates as public (template.public=True)
- Reader
--> Can list all templates

Project
- Admin
- Manager
--> Can CRUD project-scoped templates (template.owner=PROJECT)
--> Cannot set a template to public (template.public=True).
- Member
--> Can execute public templates or templates owned by their project.
- Reader
--> Can list public templates and templates owned by their project.

其他最终用户影响¶

无

可扩展性影响¶

无

性能影响¶

无

其他部署者影响¶

无

开发人员影响¶

无

实现¶

负责人¶

主要负责人: JayF <jay@jvf.cc>
其他贡献者: TheJulia <juliaashleykreger@gmail.com>

工作项¶

创建 Runbook - 对象层 - 数据库层 - API 层
添加策略检查测试以用于 /v1/runbooks
确保存在针对新 API 端点的 tempest API 测试
更新 API-Ref
更新手动清理和节点服务文档

依赖项¶

所有依赖项均已解决。

测试¶

将添加单元测试来测试新功能。将添加集成测试来测试新的 API 端点和 CLI 命令。

升级和向后兼容性¶

更改是向后兼容的。现有的 API 端点将继续像以前一样工作，我们将通过微版本检查来控制所有 API 更改。

文档影响¶

需要记录新功能。这包括对新 API 端点和 CLI 命令的文档，以及记录上述详细的安全注意事项。

通过 Runbook 进行自助服务