支持添加服务器锁定的原因¶

https://blueprints.launchpad.net/nova/+spec/add-locked-reason

目前，在锁定实例时，我们知道是谁锁定了它，但不知道“为什么”锁定它。本规范旨在解决这个问题。

问题描述¶

使用 nova lock 操作锁定服务器时，没有提供设置描述或说明锁定原因的机制。在某些情况下（例如，安全/硬件团队锁定服务器，或自动化作业锁定服务器，或管理员锁定服务器并休假），仅仅询问用户为什么锁定以及是否可以解锁是不理想的，因此通常需要此信息。

用例¶

作为云操作员，我希望知道某个用户锁定了服务器的原因，即使该用户无法联系，或者无需打开内部工单来查找。

作为用户/管理员，我希望在锁定服务器时添加一个原因，例如解锁的安全日期，以便其他管理员知道。

提议的变更¶

本规范建议将 locked_reason 作为实例的系统元数据中的一个条目进行存储。

对于 POST /servers/{server_id}/action 请求，其中 action 为 “lock”，将添加一个新的可选参数，名为 locked_reason，用户可以通过该参数指定锁定实例的原因。如果指定了原因，它将在该实例的 instance_system_metadata 中创建 locked_reason 条目，该条目将在解锁实例时删除。

计划通过在 GET servers/{server_id}、GET /servers/detail、POST /servers/{server_id}/action（其中 action 为 rebuild）和 PUT servers/{server_id} 请求的响应中添加一个新的键来暴露 locked_reason 信息。有关具体操作方法，请参阅 REST API 影响部分的详细信息。

备选方案¶

一种替代方案是不使用 POST /servers/{server_id}/action 来进行锁定机制，而仅通过 PUT servers/{server_id} 请求来完成。

另一种替代方案是将 lock 作为其自身资源，在这种情况下，我们可以添加一个新的 lock API，其形式如下：GET servers/{server_id}/lock，可以包含诸如是否锁定、locked_by、locked_reason 和时间戳等详细信息。但是，我们已经有一个 GET servers/{server_id}/os-instance-actions/{request_id} 请求 API 来获取诸如时间戳之类的详细信息。因此，仅为了检索 locked_reason 信息而添加全新的 API 没有意义。

数据模型影响¶

无。

REST API 影响¶

对于 POST /servers/{server_id}/action 的请求将会发生变化，因为它将获得一个新的可选参数，名为 locked_reason，该参数将接受锁定服务器的原因，并将其存储在数据库中的 instance_system_metadata 表中。

锁定服务器的示例 JSON 请求如下

"lock": {
   "locked_reason": "because I am mad at belmiro"
}

请求体要么是一个“null”对象（如果未指定原因），要么在对象中包含一个“locked_reason”字段（可能来自新的微版本）。

我们计划通过 GET servers/{server_id}、GET /servers/detail、POST /servers/{server_id}/action（其中 action 为 rebuild）和 PUT servers/{server_id} REST API 暴露 locked_reason 信息，这些 REST API 的响应将包含该键。

目前，响应仅包含“locked”键，该键的类型为布尔值，表示实例是否锁定（如果为 true 或 false）。现在，我们将添加“locked”键，并包含 locked_reason 键。

锁定服务器的示例 JSON 响应如下

{
    "servers": [
        {
            "OS-EXT-STS:task_state": null,
            "id": "b546af1e-3893-44ea-a660-c6b998a64ba7",
            "status": "ACTIVE",
            .
            .
            .
            "locked": true,
            "locked_reason": "foo-test",
            .
            .
            .
            "name": "surya-probes-001",
            "OS-EXT-SRV-ATTR:launch_index": 0,
            "created": "2018-06-29T15:07:29Z",
            "tenant_id": "940f47b984034c7f8f9624ab28f5643c",
            .
            .
            "host_status": "UP",
            "trusted_image_certificates": null,
            "metadata": {}
        }
    ]
}

请注意，锁定实例的管理员有责任在原因中放入用户可见的信息，因为那里没有保护措施。

解锁服务器的示例 JSON 响应如下

{
    "servers": [
        {
            "OS-EXT-STS:task_state": null,
            "id": "b546af1e-3893-44ea-a660-c6b998a64ba7",
            "status": "ACTIVE",
            .
            .
            .
            "locked": false,
            "locked_reason": null,
            .
            .
            .
            "name": "surya-probes-001",
            "OS-EXT-SRV-ATTR:launch_index": 0,
            "created": "2018-06-29T15:07:29Z",
            "tenant_id": "940f47b984034c7f8f9624ab28f5643c",
            .
            .
            "host_status": "UP",
            "trusted_image_certificates": null,
            "metadata": {}
        }
    ]
}

过滤/排序：locked 键将被添加到现有的有效排序/过滤键列表中，以便可以根据该字段过滤/排序实例。

安全影响¶

锁定实例的管理员应注意不要通过 locked_reason 暴露所有者不应知道的信息。

通知影响¶

InstancePayload 对象将被更新，以包含“locked_reason”字段，该字段可以添加到锁定实例时将发出的 InstanceActionPayload 通知中。这将需要对 payload 通知对象进行版本更新。

锁定服务器的示例通知

{
    "event_type": "instance.lock",
    "payload": {
        "$ref": "common_payloads/InstanceActionPayload.json#",
        "nova_object.data": {
            "locked": true,
            "locked_reason": "foo-test"
        }
    },
    "priority": "INFO",
    "publisher_id": "nova-api:fake-mini"
}

其他最终用户影响¶

为了能够提供原因并在请求服务器 show 时看到它，python-openstackclient 和 python-novaclient 将被更新

为 POST /servers/{server_id}/action 添加一个新的可选参数 --reason，其中 action 为 “lock”。
为了适应从新微版本中解析服务器响应中的新键，GET servers/{server_id}、GET /servers/detail、POST /servers/{server_id}/action（其中 action 为 rebuild）和 PUT servers/{server_id} REST API。

性能影响¶

无。

其他部署者影响¶

无。

开发人员影响¶

无。

升级影响¶

无。

实现¶

负责人¶

主要负责人: <tssurya>

工作项¶

处理 POST /servers/{server_id}/action，在客户端接收 lock 操作的“locked_reason”可选参数时。
通过 GET servers/{server_id}、GET /servers/detail、POST /servers/{server_id}/action（其中 action 为 rebuild）和 PUT servers/{server_id} REST API 暴露 locked_reason，在服务器端锁定/解锁和更新微版本时设置/删除原因。
支持在 locked 参数上过滤和排序服务器。

依赖项¶

无。

测试¶

用于验证功能的单元和功能测试。Tempest schema 测试用于更改 REST API 响应模式格式。

文档影响¶

更新计算 API 参考的描述，以反映 REST API 更改。

参考资料¶

历史¶

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

支持添加服务器锁定的原因