项目标签

蓝图 project-tags

允许 keystone 中的项目可以使用简单的字符串进行标记。这将使项目更易于分类和过滤。此规范紧随 neutron 的 [0] 资源标签实现，并将遵循 OpenStack API 工作组制定的使用标签指南 [1]。

问题描述

目前，操作员必须依赖命名约定或 keystone 中的 extras 实现来标记或分类项目。此 extras 字段定义不明确，并且没有提供标准的 API 方法来检索或过滤此数据。

用例：通过标签进行项目组织

对于包含许多项目且项目生命周期范围从几天到更长时间的大型私有云，需要能够根据项目的预期用途、使用者以及存在时间来标记和分类项目。操作员能够查询具有特定标签的所有项目，而无需使用特定的命名约定来命名项目。此外，在项目修改或删除时，可以正确清理这些标签，而无需设置外部跟踪系统。目前，对于大规模部署，使用外部系统来跟踪项目的标签比较困难，因为项目经常更改并且经常在几天内被删除。

提议的变更

• 添加一个新的表 project_tag 来映射字符串到项目，将在 project_id 和 name 之间强制唯一性。

  CREATE TABLE `project_tag` (
     `project_id`       varchar(64) NOT NULL,
     `name`             varchar(60) NOT NULL
  )
  

• 一个项目最多可以有 80 个标签，并且每个标签不能超过 255 个字符。请参阅 [2]。

• 在列出项目和显示单个项目时，将 tags 字段作为默认响应的一部分添加。

• 添加新的 API 调用来与项目标签进行基本的 CRUD 功能交互。

• 标签是 URL 安全的，应匹配以下正则表达式

  ^[^,/]*$
  

标签将遵循 API 工作组制定的以下限制 [1]

注意

• 标签区分大小写

• 标签名称中不允许使用“/”

• 为了简化指定标签列表的请求，标签名称中不允许使用逗号“，”

项目标签的模式将是

{
    "type": "array",
    "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "pattern": "^[^,/]*$"
    },
    "maxItems": 80
}

如果将标签添加到项目并且超过了最大项目数，将返回 400 Bad Request。

新的 API 调用

列出项目的全部标签

请求： GET /v3/projects/{project_id}/tags

参数

• project_id - 项目 ID。

响应

• 200 - 确定

• 404 - 不存在

响应体

{
  "tags": ["foo", "bar"]
}

检查项目是否包含任何标签

请求： HEAD /v3/projects/{project_id}/tags

参数

• project_id - 项目 ID。

响应

• 204 - 无内容

• 404 - 项目不包含标签

检查项目是否包含指定的标签

请求： GET 或 HEAD /v3/projects/{project_id}/tags/{value}

参数

• project_id - 项目 ID。

• value - 标签值。

响应

• 204 - 无内容

• 404 - 标签或项目不存在

将单个标签添加到项目

创建指定的标签并将其添加到项目列表中

请求： PUT /v3/projects/{project_id}/tags/{value}

参数

• project_id - 项目 ID。

• value - 标签值。

响应

• 201 - 已创建

• 404 - 项目不存在

响应头

• Location: http://identity:5000/v3/projects/{project_id}/tags/{value}

修改项目的标签列表

修改项目的标签。未指定的任何现有标签将被删除。

请求： PUT /v3/projects/{project_id}/tags

{
  "tags": ["foo", "bar"]
}

参数

• project_id - 项目 ID。

响应

• 200 - 确定

• 404 - 项目不存在

响应体

{
  "links": {
    "next": null,
    "previous": null,
    "self": "http://identity:5000/v3/projects"
  },
  "projects": [
    {
      "description": "Test Project",
      "domain_id": "default",
      "enabled": true,
      "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
      "links": {
        "self": "http://identity:5000/v3/projects/3d4c2c82bd5948f0bcab0cf3a7c9b48c"
      },
      "name": "demo",
      "tags": ["foo", "bar"]
    }
  ]
}

从项目删除单个标签

从项目中删除单个标签。

请求： DELETE /v3/projects/{project_id}/tags/{value}

参数

• project_id - 项目 ID。

• value - 要删除的标签

响应

• 204 - 标签已删除

• 404 - 标签或项目未找到

从项目删除所有标签

删除给定项目的整个标签列表。

请求： DELETE /v3/projects/{project_id}/tags

参数

• project_id - 项目 ID。

响应

• 204 - 标签已删除

• 404 - 项目未找到

通过标签过滤和搜索

要按标签搜索项目，客户端应将 GET 请求发送到集合 URL，并包含定义查询的查询字符串参数。这些参数可以与其他参数结合使用，例如执行标签之外的其他过滤的参数。推荐的查询字符串参数用于过滤标签是

标签查询	描述
tags	包含所有指定标签的项目
tags-any	包含至少一个指定标签的项目
not-tags	不包含所有指定标签的项目
not-tags-any	不包含任何一个指定标签的项目

要请求具有单个标签的项目列表，tags 参数应设置为所需的标签名称。示例将返回所有带有“foo”标签的项目

GET /v3/projects?tags=foo

要请求具有两个或多个标签的项目列表，tags 参数应设置为用逗号分隔的标签列表。在这种情况下，必须存在所有给定的标签，项目才能包含在查询结果中。示例将返回所有同时具有“foo”和“bar”标签的项目

GET /v3/projects?tags=foo,bar

要请求具有给定列表中的至少一个标签的项目列表，tags-any 参数应设置为用逗号分隔的标签列表。在这种情况下，只要存在给定的标签中的一个，该项目将包含在查询结果中。示例返回具有“foo”或“bar”标签的项目

GET /v3/projects?tags-any=foo,bar

要请求不具有标签列表的项目列表，not-tags 参数应设置为用逗号分隔的标签列表。在这种情况下，必须不存在所有给定的标签，项目才能包含在查询结果中。示例返回不具有“foo”或“bar”标签的项目

GET /v3/projects?not-tags=foo,bar

要请求不具有列表中的至少一个标签的项目列表，not-tags-any 参数应设置为用逗号分隔的标签列表。在这种情况下，只要不存在给定的标签中的一个，该项目将包含在查询结果中。示例返回不具有“foo”标签或不具有“bar”标签的项目

GET /v3/projects?not-tags-any=foo,bar

可以将 tags、tags-any、not-tags 和 not-tags-any 参数组合起来构建更复杂的查询。示例返回具有“foo”和“bar”标签以及“red”和“blue”标签中的至少一个的项目。

GET /v3/projects?tags=foo,bar&tags-any=red,blue

备选方案

1. 将标签存储在 keystone 外部。

   • 优点：不需要更改 keystone。

   • 缺点：需要外部工具或解决方法。如果使用外部系统，则需要另一个工具来维护和跟踪。资源更新（例如删除项目）将需要外部系统中相应标签数据的更新。对于具有许多临时项目且经常被清除的大规模部署，这既笨拙又难以维护。

2. 将标签存储在 extra 列中。

   • 优点：不需要额外的 SQL 表修改。

   • 缺点：extra 列当前存储一些辅助数据，例如用户的电子邮件地址。允许 API 修改此数据可能会导致冲突。没有标准的 API 方法来操作此数据，并且数据未被索引。

3. 使用命名方案来对项目进行分类。

   • 优点：不需要更改 keystone。

   • 缺点：如果项目需要多个“标签”在其名称中，这可能会导致项目名称变得非常大，并且难以识别/不美观。对于具有许多项目的大型云，这是不现实的。

安全影响

通常，只有项目管理员才能创建/编辑项目的标签。这是为了防止未授权用户查看或更改任何现有标签，这些标签可能表示管理功能。

标签的策略规则将遵循 /v3/projects 的规则。

通知影响

任何添加的 API 调用都应发出适当的通知。

其他最终用户影响

具有适当角色(s) 的操作员可以使用新的 API 来操作 keystone 资源标签。

性能影响

现有 API 的性能不会受到影响。如果操作员允许将大量标签与项目关联，则可能会对数据库性能产生影响。

其他部署者影响

无。

开发人员影响

无。

实现

负责人

主要负责人

• Gage Hugo - gagehugo@gmail.com (IRC gagehugo)

其他贡献者

• Samuel Pilla - sp516w@att.com (IRC spilla)

• Tin Lam - tinlam@gmail.com (IRC lamt)

工作项

1. 实现新的 API 调用

2. 添加相关的测试

3. 更新所有适当的文档/api-ref

4. 更新 keystone-client/openstack-cli

依赖项

无。

文档影响

更新 api-ref 文档以显示 API 的用法。

参考资料

[0]

https://docs.openstack.org/newton/networking-guide/ops-resource-tags.html

[1] (1,2)

https://specs.openstack.org/openstack/api-wg/guidelines/tags.html

[2]

https://specs.openstack.org/openstack/nova-specs/specs/kilo/approved/tag-instances.html#rest-api-impact