Designate/蓝黑名单 API

概述

Gerrit补丁	[]
Launchpad蓝图	[1]

此蓝图建议提供一个仅限管理员使用的 API 调用，以动态管理黑名单域名。

黑名单域名是指 Designate 将阻止在顶级域名 (TLD) 级别使用的域名。它不会阻止它们用作较低级别的域名。例如，如果 google.com 被列入黑名单，那么这将有效地阻止有人尝试添加域名 www.google.com。但是，它不会禁止 google.com.au，因此如果需要，该域名需要单独列入黑名单。

当前，黑名单域名列表位于 .config 文件中。在对 .config 文件进行任何更改之前，必须重新启动 Designate。一种可能的解决方案是使 .config 文件可重新加载，而无需重新启动 Designate 服务。但是，只有有限数量的运维人员可以访问 .config 文件，虽然黑名单域名通常不会经常添加或更改，但当需要时，需要快速完成。提供一个 API 调用将允许支持人员获得此 API 调用的管理员权限，以便他们能够及时有效地进行更改，而无需尝试找到一两个可以更改 .config 文件的人。

为了实现此管理功能，将创建一个新的 API 调用，以及一个新的数据库表来存储黑名单域名，并且它们将不再位于 .config 文件中。

API 资源

将公开一个新的资源，blacklist 作为 Designate API 的一部分。blacklist 资源将允许授权用户创建一个新的黑名单域名。

blacklist 资源提供以下数据

id – 系统定义的 UUID，在第一次创建黑名单域名时分配 (必需)
pattern – 黑名单域名的正则表达式模式 (必需)
created_at – 创建黑名单域名的时间戳 (必需)
updated_at – 更新黑名单域名的时间戳 (可以为空)
description – UTF-8 文本字段 (可选)

API 详情：创建 / 列出 / 删除实例

动词	资源	描述
GET	/blacklist	返回黑名单域名列表
GET	/blacklist/{id}	返回特定的黑名单域名
POST	/blacklist	根据请求体中提供的参数创建一个新的黑名单域名
PUT	/blacklist/{id}	返回更新后的特定黑名单域名
DELETE	/blacklist/{id}	删除黑名单域名。请求中不期望任何消息体

获取黑名单域名 (GET)

当未指定 id 时，将返回所有黑名单域名。如果 URL 中指定了域名，则仅返回该特定的黑名单域名。

两种情况下都没有请求消息体。

响应

   {
       “blacklist”: [
           {
               “id”: "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
               “pattern”: “google\\.com$”,
               "created_at": "2012-11-02T19:56:26.000000",      
               "updated_at": null
               “description”: null
           },
           {
               “id”: "2e32e609-3a4f-45ba-bdef-e50eacd34521",
               “pattern”: “rackspace\\.com$”,
               “created_at”: “2012-11-02T19:56:26.000000",      
               “updated_at”: null
               “description”: null
             }
         ]
   }

创建一个黑名单域名 (POST)

创建黑名单域名时，调用者必须提供域名。

请求

   {
       “blacklist”: {
           “pattern”: “google\\.com$”
       }
    }

响应

   {
       “blacklist”: {
           {
              “id”: "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
              “pattern”: “google\\.com$”,
              "created_at": "2012-11-02T19:56:26.000000",      
              "updated_at": null,
              “description”: null
           }
       }
   }

更新一个黑名单域名 (PUT)

创建黑名单域名时，调用者必须提供要更改的项目。

请求

   {
       “blacklist”: {
           “description”: “This is a comment added.”
       }
    }

响应

   {
       “blacklist”: {
           {
              “id”: "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
              “pattern”: “google\\.com$”,
              "created_at": "2012-11-02T19:56:26.000000",      
              "updated_at": "2013-01-02T17:56:26.000000"
              “description”: "This is a comment added."
           }
       }
   }

删除一个黑名单域名 (DELETE)

删除黑名单域名时，用户必须在 url 中提供 id。请求体为空。返回体为空。

数据库模式

将在 Designate 数据库中创建一个新表：blacklist，它将存储黑名单域名以及其他数据。

姓名	数据类型	长度	可为空	详情
id	VARCHAR	36	假	主键，生成的UUID
pattern	VARCHAR	512	假	要列入黑名单的区域的正则表达式模式
version	INTEGER	-	假	Designate API 版本
created_at	DATETIME	-	假	创建的 UTC 时间
updated_at	DATETIME	-	真	上次更新的 UTC 时间
description	VARCHAR	160	真	UTF-8 文本字段