Patroni配置文件4-重要规则

目录

Patroni配置有三种类型

全局动态配置

本地配置文件（patroni.yml）

环境配置

Patroni控制的PostgreSQL参数

PostgreSQL 涉及共享内存的参数

配置生成与验证

示例 Patroni 配置

描述

参数

为运行的实例生成 Patroni 配置

描述

参数

验证 Patroni 配置

描述

参数

Patroni配置有三种类型

全局动态配置

这些选项存储在DCS（分布式配置存储）中，并应用于所有集群节点。可以使用patronictl edit-config工具或Patroni REST API随时设置动态配置。如果更改的选项不属于启动配置的一部分，它们将在每个节点上异步应用（在下一个唤醒周期中），随后节点将重新加载。如果节点需要重启才能应用配置（对于上下文为postmaster的PostgreSQL参数，如果其值已更改），则会在members.data JSON中设置一个表示此情况的特殊标志pending_restart。此外，节点状态还会通过显示"restart_pending": true来指示这一点。

本地配置文件（patroni.yml）

这些选项在配置文件中定义，并且优先于动态配置。可以通过向Patroni进程发送SIGHUP信号、执行POST /reload REST-API请求或运行patronictl reload命令，在运行时更改并重新加载patroni.yml（无需重启Patroni）。本地配置可以是单个YAML文件，也可以是一个目录。如果它是一个目录，则按排序顺序逐个加载该目录中的所有YAML文件。如果某个键在多个文件中定义，则最后一个文件中的定义将优先。

环境配置

可以使用环境变量设置/覆盖一些“本地”配置参数。当您在动态环境中运行且事先不知道某些参数时（例如，在docker内部运行时无法知道您的外部IP地址），环境配置非常有用。

Patroni控制的PostgreSQL参数

一些PostgreSQL参数必须在主库和所有从库上保持相同的值。对于这些参数，无论在本地Patroni配置文件中设置还是在环境变量中设置值，都不会生效。要更改或设置这些参数的值，必须更改DCS中的共享配置。以下是这些参数及其默认值的实际列表：

• max_connections: 100

• max_locks_per_transaction: 64

• max_worker_processes: 8

• max_prepared_transactions: 0

• wal_level: hot_standby

• track_commit_timestamp: off

对于以下参数，PostgreSQL不要求主库和所有从库之间的值相等。但是，考虑到从库随时可能成为主库的可能性，为它们设置不同的值并没有实际意义；因此，Patroni限制只能通过动态配置来设置它们的值。

• max_wal_senders: 5

• max_replication_slots: 5

• wal_keep_segments: 8

• wal_keep_size: 128MB

这些参数会经过验证，以确保它们是合理的或满足最小值要求。

Patroni还控制其他一些Postgres参数：

• listen_addresses：从postgresql.listen或PATRONI_POSTGRESQL_LISTEN环境变量中设置

• port：从postgresql.listen或PATRONI_POSTGRESQL_LISTEN环境变量中设置（注意：这里可能存在重复，因为listen_addresses和port可能都通过同一个环境变量集或通过不同的方式集，但为保持原文意思，不做合并）

• cluster_name：从scope或PATRONI_SCOPE环境变量中设置

• hot_standby：on

为了安全起见，上述列表中的参数不会写入postgresql.conf，而是作为参数列表传递给pg_ctl start，这使得它们具有最高优先级，甚至高于ALTER SYSTEM。

还有一些参数，如postgresql.listen、postgresql.data_dir，只能本地设置，即在Patroni配置文件或通过配置变量中设置。在大多数情况下，本地配置将覆盖动态配置。

在应用本地或动态配置选项时，将执行以下操作：

节点首先检查是否存在postgresql.base.conf文件或是否设置了custom_conf参数。

• 如果设置了custom_conf参数，则使用它指定的文件作为基本配置，忽略postgresql.base.conf和postgresql.conf。

• 如果未设置custom_conf参数且存在postgresql.base.conf，则它包含重命名的“原始”配置，并用作基本配置。

• 如果没有custom_conf也没有postgresql.base.conf，则将原始postgresql.conf重命名为postgresql.base.conf并使用它作为基本配置。

动态选项（上述例外情况除外）会转储到postgresql.conf中，并在postgresql.conf中设置一个包含到基本配置（无论是postgresql.base.conf还是custom_conf指定的文件）的引用。因此，我们能够在不重新读取配置文件以检查是否存在包含引用的情况下应用新选项。

一些对Patroni管理集群至关重要的参数会通过命令行进行覆盖。

如果更改了需要重启的选项（我们应该查看pg_settings中的上下文和这些选项的实际值），则会在该节点上设置pending_restart标志。此标志在任何重启后都会重置。

参数的应用顺序如下（运行时参数具有最高优先级）：

1. 从文件postgresql.base.conf（或如果设置了custom_conf，则从其指定的文件）中加载参数

2. 从文件postgresql.conf中加载参数

3. 从文件postgresql.auto.conf中加载参数

4. 使用-o –name=value的运行时参数

这允许为所有节点（2）进行配置，使用ALTER SYSTEM为特定节点进行配置（3），并确保对Patroni运行至关重要的参数得到强制执行（4），同时为直接管理postgresql.conf而不涉及Patroni的配置工具留出空间（1）。

PostgreSQL 涉及共享内存的参数

PostgreSQL 有一些参数决定了其使用的共享内存的大小，这些参数包括：

• max_connections（最大连接数）

• max_prepared_transactions（最大预准备事务数）

• max_locks_per_transaction（每事务最大锁数）

• max_wal_senders（最大WAL发送者数）

• max_worker_processes（最大工作进程数）

更改这些参数需要重启 PostgreSQL 才能生效，并且在备节点上，这些参数的共享内存结构不能小于主节点上的大小。

如前所述，Patroni 限制通过动态配置更改这些值，通常包括：

• 使用 patronictl edit-config（或通过 REST API 的 /config 端点）应用更改

• 使用 patronictl restart（或通过 REST API 的 /restart 端点）重启节点

注意：请记住，应通过 patronictl restart 命令或通过 REST API 的 /restart 端点来重启 PostgreSQL 节点。如果你尝试通过重启 Patroni 守护进程（例如，执行 systemctl restart patroni）来重启 PostgreSQL，尤其是在重启主节点时，这可能会导致集群发生故障转移。

然而，由于这些设置管理共享内存，因此在重启节点时需要格外小心：

• 如果要增加这些设置中的任何一个的值：

1. 首先重启所有备节点
2. 然后重启主节点

• 如果要减少这些设置中的任何一个的值：

1. 首先重启主节点
2. 然后重启所有备节点

注意：如果在减少这些设置中的任何一个的值后一次性尝试重启所有节点，Patroni 将忽略更改并以原始设置值重启备节点，因此你稍后需要再次重启备节点。Patroni 这样做是为了防止备节点进入无限崩溃循环，因为如果你尝试将这些参数设置为低于备节点 pg_controldata 中显示的值，PostgreSQL 将以 FATAL 消息退出。换句话说，只有在备节点的 pg_controldata 关于主节点上的这些更改已经更新后，我们才能在备节点上减少这些设置的值。

有关此的更多信息，请参阅 PostgreSQL 管理员概览。

Patroni 配置参数

此外，以下 Patroni 配置选项也只能动态更改：

• ttl: 30

• loop_wait: 10

• retry_timeouts: 10

• maximum_lag_on_failover: 1048576

• max_timelines_history: 0

• check_timeline: false

• postgresql.use_slots: true

更改这些选项后，Patroni 将读取存储在 DCS 中的配置的相关部分，并更改其运行时值。

Patroni 节点在每次配置更改时都会将 DCS 选项的状态转储到位于 Postgres 数据目录中的 patroni.dynamic.json 文件中。如果这些选项在 DCS 中完全缺失或无效，则只有领导者节点才允许从这些磁盘转储中恢复这些选项。

配置生成与验证

Patroni 提供了命令行接口，用于生成和验证 Patroni 的本地配置。使用 patroni 可执行文件，您可以：

• 创建一个示例的本地 Patroni 配置；

• 为本地运行的 PostgreSQL 实例创建一个 Patroni 配置文件（例如，作为 Patroni 集成的准备步骤）；

• 验证给定的 Patroni 配置文件。

示例 Patroni 配置

patroni --generate-sample-config [configfile]

描述

生成一个 yaml 格式的示例 Patroni 配置文件。参数值使用环境配置进行定义，否则，如果未设置，则使用 Patroni 中的默认值或 #FIXME 字符串来表示应由用户稍后定义的值。

一些默认值根据本地设置进行定义：

• postgresql.listen：当前机器主机名通过 gethostname 调用返回的 IP 地址和标准 5432 端口。

• postgresql.connect_address：与 postgresql.listen 相同。

• postgresql.authentication.rewind：仅当可以从二进制文件确定 PostgreSQL 版本且版本为 11 或更高时定义。

• restapi.listen 和 restapi.connect_address：与 postgresql.listen 类似，但使用标准 8008 端口。

参数

• configfile：用于存储结果的配置文件的完整路径。如果未提供，结果将发送到标准输出。

为运行的实例生成 Patroni 配置

patroni --generate-config [--dsn DSN] [configfile]

描述

为本地运行的 PostgreSQL 实例生成一个 yaml 格式的 Patroni 配置。将使用提供的 DSN（优先）或 PostgreSQL 环境变量进行 PostgreSQL 连接。如果未提供密码，则应通过提示输入。

源 PostgreSQL 实例中定义的所有非内部 GUC（全局用户配置）都将用作以下 Patroni 配置参数的来源：

• scope：cluster_name GUC 值；

• postgresql.listen：listen_addresses 和 port GUC 值；

• postgresql.datadir：data_directory GUC 值；

• postgresql.parameters：archive_command、restore_command、archive_cleanup_command、recovery_end_command、ssl_passphrase_command、hba_file、ident_file、config_file GUC 值；

• bootstrap.dcs：收集的所有其他 PostgreSQL GUC。

如果 scope、postgresql.listen 或 postgresql.datadir 未从 Postgres GUC 设置，则使用相应的环境配置值。

值定义的其他规则：

• name：如果设置了 PATRONI_NAME 环境变量值，则使用该值，否则使用当前机器的主机名。

• postgresql.bin_dir：从运行的实例中收集的 Postgres 二进制文件的路径。

• postgresql.connect_address：当前机器主机名通过 gethostname 调用返回的 IP 地址和用于实例连接的端口或 port GUC 值。

• 其他参数也根据环境配置进行定义。

参数

• configfile：用于存储结果的配置文件的完整路径。如果未提供，结果将发送到标准输出。

• dsn：可选的 DSN 字符串，用于从本地 PostgreSQL 实例获取 GUC 值。

验证 Patroni 配置

patroni --validate-config [configfile] [--ignore-listen-port | -i]

描述

验证给定的 Patroni 配置，并打印有关失败检查的信息。

参数

• configfile：要检查的配置文件的完整路径。如果未提供或文件不存在，将尝试从 PATRONI_CONFIG_VARIABLE 环境变量或（如果未设置）从 Patroni 环境变量中读取。

• --ignore-listen-port | -i：可选标志，用于在验证配置文件时忽略已在使用中的监听端口的绑定失败。