管理/取消管理共享服务器¶

https://blueprints.launchpad.net/manila/+spec/manage-unmanage-with-share-servers

本规范建议增强 manila 的管理/取消管理功能，以便在 DHSS=True 模式下运行的驱动程序可以

导入现有的共享和快照，将它们纳入 manila 的管理范围。
从 manila 的管理中释放共享及其快照，而不会销毁它们。

问题描述¶

当这些共享属于以 driver_handles_share_servers = True 模式运行的后端驱动程序时，云管理员无法将预先存在的共享纳入 manila 的管理 [1]。为简洁起见，我们将在本文档中将此模式称为 DHSS = True。由于 DHSS = True 是 manila 保证安全多租户隔离的模式，因此云用户最终不得不做出不幸的权衡，以 DHSS = False 模式使用他们导入的共享。

我们今天缺乏针对 DHSS=True 模式驱动程序的管理/取消管理功能，原因是以下复杂性

共享服务器设置和网络： 在 DHSS = True 模式下，manila 为每个租户的网络配置和管理共享服务器的生命周期。在创建共享服务器时，manila 必须分配网络端口（并在删除共享服务器时稍后释放它们）。但是，在 DHSS = False 模式下，共享服务器的概念不适用，后端出口位置的可访问性由管理员和驱动程序负责。
管理共享： 在 DHSS = False 中，manila 请求驱动程序在配置的后端中查找基于 API 调用中给定的出口位置的预先存在的共享。被管理的共享预计可以像从 manila 创建的任何共享一样从客户端主机访问。在 DHSS = True 模式下，任何现有的共享都将位于共享服务器中，因此要管理共享，首先必须管理其共享服务器，然后才能管理共享服务器内的共享。
管理快照： 由于目前无法在 DHSS = True 模式下在 manila 中管理共享，因此也无法管理快照。此外，目前不允许取消管理快照。
共享服务器的生命周期： 在 DHSS = True 模式下，manila 配置共享服务器及其相关网络资源，因此在适当的时候（例如，当共享服务器不再为任何共享提供服务时）也会删除它们。在 DHSS = False 中，manila 仅管理其创建的资源的生命周期，例如共享、快照、副本和访问规则。

根据之前提到的方面，很明显，要管理 DHSS = True 模式下的共享或快照，需要一个 API 来首先管理共享服务器。

用例¶

已经使用存储设备配置共享及其快照的云管理员应该能够迁移到 manila 时导入现有的共享。支持 DHSS = True 模式的 manila 驱动程序如果 Manila 中实现了这样的 API，就可以做到这一点。

类似地，manila 共享和快照可以在 DHSS = True 模式下取消管理，以迁移到另一个系统或进行维护，但这只有在它们可以被重新管理的情况下才有意义。

提议的变更¶

提出以下更改：

添加管理共享服务器 API： 通过此 API，将管理共享服务器。它们的状态转换将与管理共享时类似。换句话说，它们将以 manage_starting 状态创建，并根据成功过渡到 available 或过渡到 manage_error。预计需要提供以下参数
- 主机： 后端名称（“<node_hostname>@<backend_stanza>”）。
- 共享网络： 与共享服务器连接的 neutron 网络关联的共享网络。
- 标识符： 驱动程序管理共享服务器所需的特定于驱动程序的共享服务器标识符。
- 驱动程序选项： 可选的键值对列表，可能需要帮助驱动程序管理共享服务器。
- 网络分配先决条件： 由于预计现有共享服务器与客户端主机之间存在连接，因此共享服务器已经具有带有 MAC 和 IP 地址的接口，但 neutron 和 manila 不知道它们。在将共享服务器纳入 manila 的管理之前，云管理员必须创建与这些共享服务器接口对应的 neutron 端口，将适当的地址分配给这些端口，并将每个端口的 device_owner 设置为 manila:share。在管理共享服务器时，驱动程序将请求共享服务器 IP 地址，并在检索到后，将其与关联的 share network 提供的或配置的网络插件中存在的由 manila:share 拥有的 neutron 端口进行匹配。如果未找到所有分配，则操作将因错误而中止。在使用独立网络插件时，不需要此步骤，因为不涉及 Neutron。
- 安全服务先决条件： 在管理之前，必须将设置为与共享网络关联的安全服务配置为与要管理的共享服务器设置的任何预先存在的身份验证服务。
- 实现： 当收到管理共享服务器的请求时，将验证 API 参数，然后创建一个带有 is_imported 字段设置的共享服务器模型。通过 RPC 调用运行指定主机中指定的后端 stanza 的共享服务，并调用驱动程序方法 manage_server 以获取要管理的共享服务器的后端详细信息和网络分配。保存返回的后端详细信息，然后将检索到的网络分配传递给配置的网络插件，以验证管理员先前创建的网络分配。验证后，网络分配将保存到 manila 的 network_allocations 数据库表中。
添加取消管理共享服务器 API： 通过此 API，将取消管理共享服务器。除了要取消管理的共享服务器的 ID 之外，不需要任何参数。指定的共享服务器将从 manila 数据库中删除。我们不会删除分配，因为对于网络中任何现有的未跟踪资源，如果端口被释放，将来很可能会导致冲突。如果需要，由管理员释放端口。状态转换将与取消管理共享类似，因此它将从 available 转换为 unmanage_starting，然后根据成功转换为 deleted 或转换为 unmanage_error。
- 实现： 当收到取消管理共享服务器的请求时，将验证 API 参数，然后通过 RPC 调用负责给定共享服务器的共享服务。然后调用驱动程序以执行为继续取消管理可能需要的任何操作，最后从 manila 的 network_allocations 数据库表中删除网络分配。
将 share_server_id 参数添加到管理共享 API： 每当管理共享并传递具有 driver_handles_share_servers 设置为 True 的共享类型时，将需要参数 share_server_id，否则 API 将返回 400 BadRequest。由于它将从父共享的模型中读取，因此管理快照 API 不需要此参数。
允许在 ``DHSS = True`` 模式下取消管理共享和快照： 当前不允许取消管理在此模式下创建的共享和快照。当指定较新的微版本时，我们将更改 API 以允许它（从而不再返回错误）。API 层不需要任何行为更改。
更新管理/取消管理共享和快照的驱动程序接口，以传递共享服务器： 由于现有的实现从未期望在 DHSS = True 驱动程序模式下工作，因此驱动程序接口不包含共享服务器参数。将更新驱动程序接口以接收共享服务器模型以执行共享和快照的管理和取消管理操作。该参数是可选的，因此不会以任何方式影响现有的 DHSS = False 驱动程序实现。
防止自动删除管理的共享服务器： 与 manila 创建的共享服务器不同，我们不会尝试自动删除没有 manila 共享的管理的共享服务器，因为其中可能存在 manila 未知的现有共享。
手动删除管理的共享服务器： 由 manila 管理的共享服务器可能包含现有的共享，并且并非所有这些共享都由 manila 管理。如果管理员决定删除共享服务器，则管理员必须尝试将其与 manila 未知的任何现有共享一起删除。但是，是否允许操作成功取决于驱动程序，因为某些后端不允许在剩余共享存在的情况下删除共享服务器。如果是这样，则共享服务器将进入错误状态，管理员必须取消管理它，或者手动在后端或通过管理它们来删除剩余的共享（manila 未知）。

备选方案¶

与添加管理共享服务器 API 相比，之前讨论的方法是在 DHSS = True 模式下具有两个阶段的管理共享 API。这种方法具有以下特征

与提议的解决方案相同的复杂性和技术工作量，但由单个 API 完成。
仅对 DHSS = True 模式有意义的几个附加参数。
更复杂的错误处理，因为需要针对每个阶段（管理共享服务器或管理共享服务器内的共享）都有特定的状态和错误。
当单个 API 在两种驱动程序模式下表现不同时，用户体验会下降，因为用户在使用它时可能会感到困惑。

作为要求管理员在管理共享服务器之前创建 neutron 端口的替代方案，我们可以让 manila 在管理共享服务器时创建网络分配，这将使管理员在“批量”管理共享服务器时更容易。这种方法的缺点是

可以合理地假设我们正在管理的共享服务器已经连接到共享网络并可供主机访问。因此，也可以合理地假设共享网络中的端口应该已经存在，以防止这些共享服务器的网络分配与其他资源发生冲突。
在取消管理共享服务器时，我们不会删除网络分配，因为假设这些共享服务器可能仍然连接到共享网络，并且需要这些网络分配以防止与同一子网中的其他资源发生冲突。这种行为与在管理共享服务器时创建端口形成不对称。

如果坚持不更改 API，则无法导入现有资源以供 manila 管理。如果未实现此功能，管理员需要在其存储设备之外管理存储设备，或者接受仅使用 DHSS = False 模式的限制，而无法获得 DHSS = True 模式下的优势。

数据模型影响¶

由于需要区分由 manila 创建的共享服务器和管理的共享服务器，我们建议在 ShareServer 表中添加一个布尔型列，名为 is_imported，默认值为 False。数据库模式升级将添加该列，并为所有现有的共享服务器赋予 False 值，而数据库模式降级将删除该列。

REST API 影响¶

引入了一些新的 API，并更改了其他一些 API。与现有的管理/取消管理 API 一样，新 API 的策略仅限管理员使用。现有策略没有更改。API 微版本将针对所列更改提升到下一个版本。

管理共享服务器:

POST /v2/{tenant-id}/share-servers/manage

请求参数

{
    "share_server": {
        "host": "host@backend",
        "share_network_id": "e76be4e9-4054-4df3-9e5c-178e68fb0949",
        "identifier": "0e73a5e1-e233-4635-b6df-db568307385f",
        "driver_options": {
            "key1": "value1",
            "key2": "value2",
            "key3": "value3"
        }
    }
}

参数 driver_options 是可选的。如果缺少或无效任何其他参数，API 将返回 400 BadRequest。

响应

Code: 202 Accepted

{
    "share_server":
        "status": "manage_starting",
        "created_at": 2018-09-17T18:05:34.000000,
        "updated_at": 2018-09-17T18:05:34.000000,
        "share_network_id": "e76be4e9-4054-4df3-9e5c-178e68fb0949",
        "share_network_name": "my_share_net",
        "host": "host@backend",
        "project_id": "0ebbe03068554da9b9d9ad11983bb08a",
        "id": "fa4e4d78-d3d9-46cf-8e61-514da5008cee",
        "is_imported": "True",
        "backend_details": {
            "key1": "value1",
            "key2": "value2",
            "key3": "value3"
        }
    }
}

取消管理共享服务器:

POST /v2/{tenant-id}/share-servers/{share_server_id}/action

请求参数

{
    "unmanage": null
}

响应

Code: 202 Accepted

如果共享服务器不存在，API 将返回 404 NotFound。
如果共享服务器状态不是 error、active、inactive、manage_error 或 unmanage_error，API 将返回 400 BadRequest。
如果共享服务器在 manila 中注册了共享，它将返回 409 Conflict。

显示共享服务器:

在微版本提升后，共享服务器视图将包含字段 is_imported，只要使用更新的微版本即可。

管理共享:

POST /v2/{tenant-id}/shares/manage

请求参数

{
    "share": {
        "protocol": "NFS",
        "name": "my_share",
        "share_type": "my_type",
        "description": null,
        "driver_options": {},
        "is_public": false,
        "service_host": "host@backend#pool",
        "export_path": "192.168.10.100/my_export",
        "share_server_id": "fa4e4d78-d3d9-46cf-8e61-514da5008cee"
    }
}

如果给定的共享类型指定了 DHSS = True 模式，则需要新的参数 share_server_id。如果未提供 share_server_id，或者在给定的共享类型指定了 DHSS = False 模式时提供了 share_server_id，API 将返回 400 BadRequest。

响应

Code: 202 Accepted

没有对响应体提出任何更改。

取消管理共享:

POST /v2/{tenant-id}/shares/{share_id}/action

请求参数

{
    "unmanage": null
}

响应

Code: 202 Accepted

当尝试取消管理在 DHSS = True 模式下创建的共享时，此 API 将不再返回 403 Forbiddden。

管理快照:

不需要 API 更改。当前 API 不会验证正在管理的快照是否与在 DHSS = True 模式下创建的共享相关联。

取消管理快照:

POST /v2/{tenant-id}/snapshots/{snapshot_id}/action

请求参数

{
    "unmanage": null
}

响应

Code: 202 Accepted

当尝试取消管理在 DHSS = True 模式下创建的共享的快照时，此 API 将不再返回 403 Forbiddden。

驱动程序影响¶

引入了一个新的驱动程序接口，用于获取共享服务器网络分配数据。此数据将用于验证管理员先前创建的网络分配。支持 DHSS = True 模式的驱动程序必须实现此接口才能支持管理共享服务器功能。

def manage_server(self, context, share_server, identifier, driver_options):
    """Return compiled back end details and network allocations.

    :param context: Current context.
    :param share_server: Share server model.
    :param identifier: A driver-specific share server identifier
    :param driver-options: Dictionary of driver options to assist managing
        the share server
    :return Dictionary with back end details to be saved in the database
        and a list containing IP addresses allocated in the back end.

    Example::

        {'server_name': 'my_old_server'},['192.168.10.10', 'fd11::2000']

    """
    raise NotImplementedError()

如果驱动程序未实现此接口，将引发异常并中止操作。

驱动程序接口 manage_existing、unmanage、manage_existing_snapshot 和 unmanage_snapshot 将更新为接收共享服务器模型参数。实现这些接口的所有驱动程序都将更新其方法定义以避免问题。具体来说

def manage_existing(self, share, driver_options, share_server=None):
    """Brings an existing share under Manila management.

    If the provided share is not valid, then raise a
    ManageInvalidShare exception, specifying a reason for the failure.

    If the provided share is not in a state that can be managed, such as
    being replicated on the backend, the driver *MUST* raise
    ManageInvalidShare exception with an appropriate message.

    The share has a share_type, and the driver can inspect that and
    compare against the properties of the referenced backend share.
    If they are incompatible, raise a
    ManageExistingShareTypeMismatch, specifying a reason for the failure.

    :param share: Share model
    :param driver_options: Driver-specific options provided by admin.
    :param share_server: Share server model or None.
    :return: share_update dictionary with required key 'size',
             which should contain size of the share.
    """
    raise NotImplementedError()

def unmanage(self, share, share_server=None):
    """Removes the specified share from Manila management.

    Does not delete the underlying backend share.

    For most drivers, this will not need to do anything.  However, some
    drivers might use this call as an opportunity to clean up any
    Manila-specific configuration that they have associated with the
    backend share.

    If provided share cannot be unmanaged, then raise an
    UnmanageInvalidShare exception, specifying a reason for the failure.
    """

def manage_existing_snapshot(self, snapshot, driver_options,
                             share_server=None):
    """Brings an existing snapshot under Manila management.

    If provided snapshot is not valid, then raise a
    ManageInvalidShareSnapshot exception, specifying a reason for
    the failure.

    :param snapshot: ShareSnapshotInstance model with ShareSnapshot data.

    Example::
        {
        'id': <instance id>,
        'snapshot_id': < snapshot id>,
        'provider_location': <location>,
        ...
        }

    :param driver_options: Optional driver-specific options provided
        by admin.

    Example::

        {
        'key': 'value',
        ...
        }

    :param share_server: Share server model or None.
    :return: model_update dictionary with required key 'size',
        which should contain size of the share snapshot, and key
        'export_locations' containing a list of export locations, if
        snapshots can be mounted.
    """
    raise NotImplementedError()

def unmanage_snapshot(self, snapshot, share_server=None):
    """Removes the specified snapshot from Manila management.

    Does not delete the underlying backend share snapshot.

    For most drivers, this will not need to do anything.  However, some
    drivers might use this call as an opportunity to clean up any
    Manila-specific configuration that they have associated with the
    backend share snapshot.

    If provided share snapshot cannot be unmanaged, then raise an
    UnmanageInvalidShareSnapshot exception, specifying a reason for
    the failure.
    """

安全影响¶

作为仅限管理员的 API，管理共享服务器及其内部共享所需的所有信息都通过默认策略限制为管理员。

通知影响¶

由于提出的新 API 是仅限管理员的 API，因此不需要用户消息通知。

其他最终用户影响¶

将向 python-manilaclient 添加新命令

manila share-server-manage <host> <share_network_id> <identifier> [--driver_options key1=value1 [key2=value2] ...]

manila share-server-unmanage <share_server_id>

将更新一个命令

manila manage [--name <name>] [--description <description>]
              [--share_type <share-type>]
              [--share_server_id <share-server-id>]
              [--driver_options [<key=value> [<key=value> ...]]]
              [--public]
              <service_host> <protocol> <export_path>

对于 manila-ui，将添加一个新的按钮“管理共享服务器”和一个上下文选项“取消管理共享服务器”，该按钮和选项仅在给定共享服务器没有关联 manila 共享时才会显示。

性能影响¶

预计没有显著的性能影响。

其他部署者影响¶

无。

开发人员影响¶

此规范提出的工作受到 [2] 的影响。管理共享服务器的 share_network_id 参数需要替换为 share_network_subnet_id。

实现¶

负责人¶

主要负责人: ganso

工作项¶

实现 manila 的主要补丁，包括
- 数据库模式迁移
- 管理共享服务器 API
- 取消管理共享服务器 API
- 更新管理共享、取消管理共享、管理快照和取消管理快照 API
- 添加 manage_server 驱动程序接口
- 更新现有的受影响的驱动程序接口
- 共享管理器调整，以防止自动删除管理的共享服务器
- 网络插件的调整
在第一方驱动程序中的实现
manila-tempest-plugin 中的功能测试
Python-manilaclient 更新
文档更新
Manila-UI 更新