文档中心

云数据库 PostgreSQL 版

管理白名单（新版）

升级白名单

本文介绍为云数据库 PostgreSQL 版实例升级到 v2 版本白名单管理功能的操作步骤。

背景信息

为使白名单管理更加高效和便捷，云数据库 PostgreSQL 版于 2024 年 4 月 25 日全面上线了新版的白名单管理功能。新版的白名单管理功能实现了白名单与实例的解耦，白名单与实例相互独立，一个白名单可以绑定到多个实例，一个实例也可以绑定多个白名单，支持批量管理，更加贴合实际业务场景。例如，可以按照应用服务器来组织白名单，增加一台应用服务器只需要调用一次 Open API，即可达到批量管理多个实例的效果。

新版白名单管理功能提供了新的 Open API 接口。新老版本的白名单 Open API 不能互通，在新版本接口发布后，老版本接口会被逐步废弃，不再支持调用。

功能	接口（v2）	接口（v1）
查看白名单列表	DescribeAllowLists	ListDBInstanceIPLists
查看白名单详情	DescribeAllowListDetail	无
创建白名单	CreateAllowList	CreateDBInstanceIPList
修改白名单	ModifyAllowList	ModifyDBInstanceIPList
绑定白名单	AssociateAllowList	无
解绑白名单	DisassociateAllowList	无
删除白名单	DeleteAllowList	DeleteDBInstanceIPList
合并生成白名单	UnifyNewAllowList	无
升级白名单版本	UpgradeAllowListVersion	无

升级说明

如果在控制台中实例的数据安全页签下看到以下提示，需要为实例升级白名单管理功能。关于升级白名单管理功能的详细信息，请参见升级白名单管理功能。

说明

您可根据业务需要决定是否升级白名单管理功能和升级时间。在升级白名单管理功能前，请参照添加 IP 白名单分组管理白名单分组。

如果您使用了 Open API ，需要在升级白名单管理功能前对业务代码做修改和适配。新老版本白名单差异请参见新老版本白名单接口使用方式差异。

如果在使用新版白名单管理功能过程中，遇到“The AllowListVersion is not valid.”的提示，可能是因为调用的接口版本与实例的白名单管理功能版本不一致导致，请参照新老版本白名单接口使用方式差异进行改造。

升级前准备

确认是否使用了旧版本的白名单接口管理实例的白名单。旧版本的白名单接口包含以下接口：

ListDBInstanceIPLists：查询实例的白名单。

ModifyDBInstanceIPList：编辑实例的白名单。

CreateDBInstanceIPList：创建的白名单。

DeleteDBInstanceIPList：删除的白名单。

如果使用了旧版本的白名单接口，需切换至新版本的白名单接口。新老版本白名单接口使用方式差异见下表。

场景	使用老版本接口	使用新版本接口
新建实例	调用 CreateDBInstance 接口创建实例。调用 CreateDBInstanceIPList 接口为实例创建白名单调用 ListDBInstanceIPLists 查看白名单是否正确。	调用 CreateDBInstance 接口创建实例。调用 CreateAllowList 和 AssociateAllowList 接口新建白名单并绑定，或者直接调用 AssociateAllowList 接口绑定一个已经存在的白名单。调用 DescribeAllowLists 接口查看绑定的白名单。
修改白名单	调用 ModifyDBInstanceIPList 接口修改白名单。	调用 ModifyAllowList 接口修改白名单。说明对白名单的修改会影响绑定了这个白名单的所有实例。
删除白名单	调用 DeleteDBInstanceIPList 接口删除实例的白名单。	调用 DisassociateAllowList 接口与白名单解除绑定。如需彻底删除白名单，需要调用 DeleteAllowList 接口实现。说明对白名单的删除会影响绑定了这个白名单的所有实例，删除前需要解除该白名单和实例的绑定。

升级白名单管理功能

可通过控制台或 Open API 完成白名单管理功能的升级。

通过控制台

此方式适用于实例数量较多的场景。

登录云数据库 PostgreSQL 版控制台。

在顶部菜单栏选择实例所属的项目和地域。

说明

如未设置实例的所属项目，本操作应选择项目为账号全部资源。

在左侧导航栏单击实例列表。

（可选）在实例列表页面，勾选需要升级白名单的实例后，单击合并生成白名单。

说明

合并生成白名单仅将选中的实例所绑定的白名单进行去重合并，生成新白名单，并不会替换当前实例正在使用的白名单。

务必确保在后续步骤中操作的实例，在合并白名单阶段已被选中，即合并的白名单中包含了实例升级前的白名单中的 IP 地址。

升级实例的白名单后，会自动为实例创建一个新版本的白名单。为了避免白名单数量过多达到 500 的上限，也为了后期维护方便，可以通过合并生成白名单功能将不同实例的多个白名单进行去重、合并，生成一个新的公共的白名单。

实例升级完白名单之后，依然可以使用合并白名单的功能。关于使用合并生成白名单功能的更多详细信息，请参见合并生成白名单。

在实例列表页面，单击目标实例名称。

在页面上方，单击数据安全页签。

单击数据安全页签下横幅消息的立即升级。

在弹出的立即升级对话框中，单击确定。

说明

单击确定后，会自动将实例之前绑定的所有 IP 白名单组中的 IP 进行去重，并合并为一个名为“实例ID的白名单”的白名单，并与实例绑定。

升级白名单管理功能的过程中，会对 IP 地址进行规范化处理，将未采用 CIDR 格式的 IP 地址统一规范为标准 CIDR 格式表示（/32）。例如，原地址为 127.0.0.1，升级后会被规范为 127.0.0.1/32。已采用了 CIDR 格式表述的 IP 地址或地址段不做处理。

（可选）为实例绑定在升级前合并生成的白名单，并解绑、删除升级过程中自动创建的白名单以减少白名单数量。

注意

务必在给实例绑定合并生成的白名单后，再解绑原来的白名单，否则会导致业务短暂中断。

通过 Open API

此方式适用于实例数量较多的场景。

（可选）调用 UnifyNewAllowList 接口，将需要升级白名单的实例的 IP 地址进行合并。该接口为同步接口，该接口的请求参数和返回参数如下：

请求参数

参数	类型	是否必选	示例值	描述
InstanceIds	String[]	是	["postgres-4b38053d**","postgres-5efe96ae**"]	需合并生成白名单的实例的 ID。说明最多支持对 300 个实例的白名单进行合并生成。
AllowListName	String	是	测试白名单	合并生成的白名单的名称。命名规则如下：在当前地域内，白名单名称唯一。以中文、字母或下划线（_）开头。只能包含中文、字母、数字、下划线（_）和中划线（-）。长度为 1~128 个字符。
AllowListDesc	String	否	这是一段合并生成白名单的描述信息。	白名单的描述信息。长度在 200 字符以内。默认值为空字符串。

返回参数

参数
类型
示例值
描述
AllowListId
String
acl-61778b8b39a048fa969ca50bb020****
白名单的 ID。

注意

务必确保在后续步骤中操作的实例，在合并白名单阶段已被选中，即合并的白名单中包含了实例升级前的白名单中的 IP 地址。

如果实例数量比较多，建议分批次处理。假设每批处理 50 个实例，则对 50 个实例进行合并白名单、升级白名单、绑定合并生成、解绑升级生成白名单等操作后，再对下一批执行相同操作。

合并白名单时，会汇总所有实例的 IP 地址并去重。

实例升级完白名单之后，依然可以使用合并白名单的功能。

该步骤为可选。如未执行该步骤，则不可执行后续的步骤 3~6。

调用 UpgradeAllowListVersion 接口升级实例的白名单。该接口为同步接口，无返回参数。该接口的请求参数如下表所示。

参数
类型
是否必选
示例值
描述
InstanceId
String
是
postgres-e49268e4****
实例的 ID。

（可选）调用 AssociateAllowList 为实例绑定在步骤 1 中合并生成的白名单。该接口为异步接口，无返回参数。该接口的请求参数如下表所示。

参数	类型	是否必选	示例值	描述
AllowListIds	String[]	是	["acl-2b7d64502b0a4210a24c58e739de****"]	需绑定实例的白名单的 ID。说明为步骤 1 中调用UnifyNewAllowList 接口的返回参数。
InstanceIds	String[]	是	["postgres-4b38053d**","postgres-5efe96ae**"]	需绑定白名单的实例的 ID。说明支持传入多个实例 ID，将单个白名单绑定到多个实例。

（可选）调用 DescribeAllowLists 接口查询实例绑定的白名单。该接口为同步接口，该接口的请求参数和返回参数如下：

请求参数

参数	类型	是否必选	示例值	描述
RegionId	String	是	cn-beijing	地域 ID，可调用 DescribeRegions 接口查询。说明如不设定该字段，返回当前地域下的所有白名单。如设定该字段，则返回该实例的所有白名单。

返回参数

参数			类型	示例值	描述
AllowLists			Object[]	请参见返回示例。	白名单信息。
	AllowListDesc	String	这是一段白名单的描述信息。	白名单的描述信息。
	AllowListIPNum	Integer	2	白名单中 IP 地址或 IP 地址段的数量。
	AllowListId	String	acl-fe1339b0024e42ca9872e8f4af12****	白名单的 ID。
	AllowListName	String	这是一个白名单名称	白名单的名称。
	AllowListType	String	IPv4	白名单采用的网络协议类型。取值为 IPv4。
	AssociatedInstanceNum	Integer	3	白名单绑定的实例数量。

（可选）调用 DisassociateAllowList 接口，为实例解绑在升级白名单时创建的白名单。该接口为异步接口，无返回参数。该接口的请求参数如下表所示。

参数	类型	是否必选	示例值	描述
AllowListIds	String[]	是	["acl-2b7d64502b0a4210a24c58e739de****"]	需解绑实例的白名单的 ID。
InstanceIds	String[]	是	["postgres-4b38053d****"]	需解绑白名单的实例的 ID。

（可选）调用 DeleteAllowList 接口，删除升级时自动创建的白名单。该接口为同步接口，无返回参数。该接口的请求参数如下表所示。

参数	类型	是否必选	示例值	描述
AllowListId	String	是	acl-2b7d64502b0a4210a24c58e739de****	白名单的 ID。

重复步骤 2～6，对本批次中的所有实例进行操作。

API	描述
DescribeAllowLists	调用 DescribeAllowLists 接口查看指定地域下的白名单列表。
DescribeAllowListDetail	调用 DescribeAllowListDetail 接口查看白名单详情。
CreateAllowList	调用 CreateAllowList 接口创建白名单。
ModifyAllowList	调用 ModifyAllowList 接口修改白名单。
AssociateAllowList	调用 AssociateAllowList 接口绑定白名单。
DisassociateAllowList	调用 DisassociateAllowList 接口解绑白名单。
DeleteAllowList	调用 DeleteAllowList 接口删除白名单。
UpgradeAllowListVersion	调用 UpgradeAllowListVersion 接口升级白名单版本。