Documentation Home
MySQL 外壳 8.0  / 第 6 章 MySQL AdminAPI  /  6.9 标记元数据

6.9 标记元数据

从 8.0.21 版本开始,可以使用可配置的标记框架来允许使用附加信息标记 InnoDB Cluster、InnoDB ClusterSet 或 InnoDB ReplicaSet 的元数据。标签使得将自定义键值对关联到集群、副本集或实例成为可能。标记已保留供 MySQL Router 使用,使兼容的 MySQL Router 能够支持对应用程序隐藏实例。为此保留了以下标签:

  • _hidden指示 MySQL Router:从客户端应用程序的可能目的地列表中排除实例。

  • _disconnect_existing_sessions_when_hidden:指示路由器断开与标记为隐藏的实例的现有连接。

有关详细信息,请参阅 从路由中删除实例

此外,标签框架是用户可配置的。自定义标签可以包含任何 ASCII 字符并提供一个 namespace,它用作可以与 Clusters、ReplicaSets 或其特定实例相关联的字典键值对。标记值可以是任何 JSON 值。此配置使您能够在元数据之上添加自己的属性。

显示标签

Cluster.options() 操作显示有关分配给各个集群实例以及集群本身的标签的信息。例如,分配给的 InnoDB Cluster myCluster可以显示:

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": false
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

该集群有一个名为 的全局标签location ,其值为US East,并且实例 ic-1已被标记。

在集群实例上设置标签

您可以在实例级别设置标签,例如,这使您能够将实例标记为不可用,以便应用程序和路由器将其视为离线。使用该 操作为实例设置标签的值。 Cluster.setInstanceOption(instance, option, value)

instance参数是目标实例的连接字符串 。参数必须是 option格式为 . 参数是在指定 的. 如果值为 ,则从指定的 中删除。对于属于集群的实例,该 操作只接受命名空间。任何其他名称空间都会导致. namespace:optionvalueoptionnamespacenulloptionnamespacesetInstanceOption()tagArgumentError

例如,要使用 JavaScript 将标签设置 为testinstance , 请发出: truemyClusteric-1

mysql-js> myCluster.setInstanceOption("icadmin@ic-1:3306", "tag:test", true);

或者使用 Python在 实例 上设置标签test ,发出: truemyClusteric-1

mysql-py> myCluster.set_instance_option("icadmin@ic-1:3306", "tag:test", True);

从路由中删除实例

当 AdminAPI 和 MySQL Router 一起工作时,它们支持特定的标签,使您能够将实例标记为隐藏并将它们从路由中删除。然后 MySQL Router 从路由目标候选列表中排除这些标记的实例。此功能使您能够安全地使服务器实例脱机,以便应用程序和 MySQL Router 忽略它。例如,当您执行维护任务时,例如服务器升级或配置更改。

_hidden标记设置为 true 时,这会指示 MySQL Router 从客户端应用程序的可能目的地列表中排除该实例。该实例保持联机,但不会路由到新的传入连接。该 _disconnect_existing_sessions_when_hidden标签控制如何关闭与实例的现有连接。此标记假定为 true,它指示针对 InnoDB Cluster、InnoDB ClusterSet 或 InnoDB ReplicaSet 引导的任何 MySQL Router 实例在 _hidden标记为 true 时断开与实例的任何现有连接。

_disconnect_existing_sessions_when_hidden为 false 时,如果为 true,则不会关闭与实例的任何现有客户端连接_hidden。reserved _hidden_disconnect_existing_sessions_when_hidden tags 是特定于实例的,不能在集群级别使用。

警告

use_gr_notifications 启用 MySQL Router 选项时,它默认为 60 秒。这意味着当您设置标签时,MySQL Router 最多需要 60 秒才能检测到更改。要减少等待时间,请更改 use_gr_notifications为较低的值。

例如,假设您 要从路由目标中删除ic-1属于分配给 InnoDB Cluster 一部分的实例。myCluster使用 setInstanceOption()JavaScript 操作启用_hidden_disconnect_existing_sessions_when_hidden 标签:

mysql-js> myCluster.setInstanceOption("icadmin@ic-1:3306", "tag:_hidden", true);

或者使用set_instance_option()Python 操作启用_hidden_disconnect_existing_sessions_when_hidden 标签:

			mysql-js> myCluster.set_instance_option("icadmin@ic-1:3306", "tag:_hidden", true);

您可以通过检查选项来验证元数据中的更改。例如,所做的更改ic-1 将在选项中显示为:

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": true
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": []
        }
    }
}

您可以通过查看日志文件来验证 MySQL Router 是否检测到元数据中的更改。检测到所做更改的 MySQL 路由器ic-1将显示如下更改:

2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700] Potential changes detected in cluster 'testCluster' after metadata refresh
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700] view_id = 4, (3 members)
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RW
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RO
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RO hidden=yes disconnect_when_hidden=yes
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_x_ro listening on 64470 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_x_rw listening on 64460 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_rw listening on 6446 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_ro listening on 6447 got request to disconnect invalid connections: metadata change

要使实例重新联机,请使用 setInstanceOption()删除标记的操作,MySQL Router 会自动将实例添加回路由目标,并且它会变为联机状态以供应用程序使用。例如:

mysql-js> myCluster.setInstanceOption(icadmin@ic-1:3306, "tag:_hidden", false);

通过再次检查选项来验证元数据中的更改:

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": false
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": []
        }
    }
}

在集群上设置标签

该 操作使您能够更改整个集群的命名空间选项的值。参数必须是格式为 . Cluster.setOption(option, value)optionnamespace:option

参数是指定的value要赋值的optionnamespace。如果值为 nulloption则从指定的 中删除namespace。对于集群,该setOption()操作接受tag命名空间。任何其他名称空间都会导致ArgumentError.

小费

在集群级别设置的标签不会覆盖在实例级别设置的标签。您不能使用 Cluster.setOption() 删除在实例级别设置的所有标签。

不需要所有实例都在线,只需要集群有法定人数即可。要 myCluster使用 location标记设置为美国东部来标记分配给的 InnoDB 集群,请在 JavaScript 中发出以下命令:

mysql-js> myCluster.setOption("tag:location", "US East")
mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

或者在 Python 中发出以下命令:

mysql-py> myCluster.set_option("tag:location", "US East")
mysql-pys> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

从集群中删除标签

要从集群中删除标签,请使用 带有 JavaScript 值和 Python 值的操作。 Cluster.setOption(option, value)nullNone

要从分配给标签的 InnoDB Cluster 中删除 myCluster标签 location,请在 JavaScript 中发出以下命令:

mysql-js> myCluster.setOption("tag:location", null)

或者使用 Python:

mysql-js> myCluster.set_option("tag:location", None)

用户定义的标记

AdminAPI 支持tag命名空间,您可以在其中将信息存储在与给定集群、副本集或实例关联的键值对中。命名空间下的选项 tag不受限制,这意味着您可以使用您选择的任何信息进行标记,只要它是有效的 MySQL ASCII 标识符即可。

您可以为标签使用任何名称和值,只要名称遵循以下语法:_ 或字母后跟字母数字和 _ 字符。

namespace选项是一个冒号分隔的字符串,格式为namespace:option,其中namespace是命名空间的名称,option是实际的选项名称。您可以在实例级别、集群或副本集级别设置和删除标签。

标签名称可以有任何值,只要它以字母或下划线开头,可以选择后跟字母数字和 _字符,例如, ^[a-zA-Z_][0-9a-zA-Z_]*。只允许内置标签以下划线_ 字符开头。

如何使用自定义标签取决于您。您可以在集群上设置自定义标签来标记集群的位置。例如, EMEA在集群上设置一个名为 location 的自定义标签,其值为 on。