This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Config

Configuration reference of pigsty

Pigsty uses [declarative configuration] (../reference/config/): the user configuration describes the state, while Pigsty is responsible for tuning the real component to the expected state.

Pigsty configuration files follow Ansible rules in YAML format, see Config Files for details .

Pigsty have 156 parameters, divided into 10 categories and five levels. see Config Entry for details.

Most parameters are optional. There are only 3 mandatory identity parameters to define a new database cluster.

No Category Type Args Function
1 connect Infra 1 Proxy settings, connect information
2 repo Infra 10 local yum repo
3 node Infra 29 node provision (ntp, dns, tuned, etc…)
4 meta Infra 21 setup infrastructure on meta node
5 dcs Infra 8 setup DCS (consul)
6 pg-install PgSQL 11 install postgres (repo, pkgs, extensions,users,dirs)
7 pg-provision PgSQL 27 pull up pg clusters (identity assignment)
8 pg-template PgSQL 19 customize cluster content and template
9 monitor PgSQL 13 install monitor components
10 service PgSQL 17 expose service via haproxy and vip

1 - Config File

Structure, content, merge and split methods of Pigsty configuration files.

Pigsty配置文件遵循Ansible规则,采用YAML格式,默认使用单一配置文件,参考范例

Pigsty的配置文件默认为 pigsty.yml ,配置文件需要与Ansible 配合使用,这是一个流行的DevOps工具。

用户可以在当前目录的 ansible.cfg 中指定默认配置文件路径,或在执行剧本时通过命令行参数:-i pigsty.yml 的方式显式指定配置文件路径。

配置文件结构

Pigsty的配置文件采用Ansible YAML Inventory格式,顶层结构如下:


all:                      # 顶层对象 all
  vars: <123 keys>        # 全局配置 all.vars
  children:               # 分组定义:all.children 每一个项目定义了一个数据库集群 
    meta: <2 keys>...
    pg-meta: <2 keys>...
    pg-test: <2 keys>...  # 一个具体的数据库集群 pg-test 的详细定义
...

每一个具体的数据库集群,以Ansible Group的形式存在,如下所示:

pg-test:                 # 数据库集群名称默认作为群组名称
  vars:                  # 数据库集群级别变量
    pg_cluster: pg-test  # 一个定义在集群级别的必选配置项,在整个pg-test中保持一致。 
  hosts:                 # 数据库集群成员
    10.10.10.11: {pg_seq: 1, pg_role: primary} # 数据库实例成员
    10.10.10.12: {pg_seq: 2, pg_role: replica} # 必须定义身份参数 pg_role 与 pg_seq
    10.10.10.13: {pg_seq: 3, pg_role: offline} # 可以在此指定实例级别的变量

配置项

在Pigsty的配置文件中,配置项 可以出现在三种位置:

层级 范围 优先级 说明 位置
Global 全局 在同一套部署环境内一致 all.vars.xxx
Cluster 集群 在同一套集群内保持一致 all.children.<cls>.vars.xxx
Instance 实例 最细粒度的配置层次 all.children.<cls>.hosts.<ins>.xxx

每一个配置项都由一对键值组成。键是配置项的名称,值是配置项的内容。值的类型各异,详情请参考 配置项

集群vars中定义的配置项会以同名键覆盖的方式覆盖全局配置项实例中定义的配置项又会覆盖集群配置项与全局配置项。因此用户可以有的放矢,可以在不同层次,不同粒度上针对具体集群与具体实例进行精细配置。

分立式配置文件

有时候用户希望采用每个数据库集群一个配置文件的方式使用Pigsty,而不是共用一个巨大的配置清单。

这样做的好处是如果发生误操作,影响范围会局限在这个集群中,避免全局恶性事件。例如,下线某个集群时,错误地指定执行范围,有可能产生误删整个环境中所有数据库。

用户可以使用任何满足Ansible规则与和Pigsty变量层次语义的配置方式,但Pigsty推荐采用以下形式的配置文件拆分规则:

  • group_vars/all.yml : 在这里定义所有全局变量
  • group_vars/<pg_cluster>.yml :在这里定义数据库集群<pg_cluster>的集群变量。
  • pgsql/<pg_cluster>.yml:在这里定义数据库集群<pg_cluster>的实例成员,以及实例变量。
  • host_vars/<pg_instance>.yml:如果单个实例的配置项非常复杂,可在此列为独立配置文件。

采用分立式配置文件的Pigsty沙箱目录结构如下所示:

pigsty
 |
 ^- group_vars               # 全局/集群 配置项定义 (此目录名称固定)
 |     ^------ all.yml       # 全局配置项
 |     ^------ meta.yml      # 元节点配置项
 |     ^------ pg-meta.yml   # pg-meta集群配置项     (覆盖全局定义)
 |     ^------ pg-test.yml   # pg-test集群配置项     (覆盖全局定义)
 |     ^------ <cluster>.yml # <pg_cluster>集群配置项(覆盖全局定义)
 |
 ^- host_vars                # 【可选】抽离实例级变量定义
 |.    ^------ 10.10.10.10.  # 定义了10.10.10.10的实例级配置项 (覆盖全局/集群配置项定义)
 |
 ^- pgsql                    # 集群成员定义/实例级配置项(此目录名称随意)
       ^------ pg-meta.yml   # pg-meta成员与实例配置项(覆盖全局/集群配置项定义)
       ^------ pg-test.yml   # pg-test成员与实例配置项(覆盖全局/集群配置项定义)
       ^------ <cluster>.yml # <pg_cluster>成员与实例配置项(覆盖全局/集群配置项定义)

2 - Config Entry

Introduction to 156 config entries about pigsty

配置项分类

Pigsty的配置项按照负责的领域可以分为以下10个大类。

No 类目 英文 大类 数量 功能
1 连接参数 connect 基础设施 1 代理服务器配置,管理对象的连接信息
2 本地仓库 repo 基础设施 10 定制本地Yum源,离线安装包
3 节点供给 node 基础设施 29 在普通节点上配置基础设施
4 基础设施 meta 基础设施 21 在元节点上安装启用基础设施服务
5 元数据库 dcs 基础设施 8 在所有节点上配置DCS服务(consul/etcd)
6 PG安装 pg-install 数据库 11 安装PostgreSQL数据库
7 PG供给 pg-provision 数据库 25 拉起PostgreSQL数据库集群
8 PG模板 pg-template 数据库 19 定制PostgreSQL数据库内容
9 监控系统 monitor 数据库 13 安装Pigsty数据库监控系统
10 服务供给 service 数据库 17 通过Haproxy或VIP对外暴露数据库服务

配置项粒度

Pigsty的参数可以在不同的粒度进行配置。

Pigsty默认提供三种粒度:全局集群实例

在Pigsty的配置文件中,配置项 可以出现在三种位置。

粒度 范围 优先级 说明 位置
Global 全局 在同一套部署环境内一致 all.vars.xxx
Cluster 集群 在同一套集群内保持一致 all.children.<cls>.vars.xxx
Instance 实例 最细粒度的配置层次 all.children.<cls>.hosts.<ins>.xxx

每一个配置项都由一对键值组成。键是配置项的名称,值是配置项的内容。值的类型各异

集群vars中定义的配置项会以同名键覆盖的方式覆盖全局配置项实例中定义的配置项又会覆盖集群配置项与全局配置项。因此用户可以有的放矢,可以在不同层次,不同粒度上针对具体集群与具体实例进行精细配置。

除了配置项粒度中指定的三种配置粒度,Pigsty配置项目中还有两种额外的优先级。

  • 默认:当一个配置项在全局/集群/实例级别都没有出现时,将使用默认配置项。默认值的优先级最低,所有配置项都有默认值。
  • 参数:当用户通过命令行传入参数时,参数指定的配置项具有最高优先级,将覆盖一切层次的配置。一些配置项只能通过命令行参数的方式指定与使用。
层级 来源 优先级 说明 位置
Default 默认 最低 代码逻辑定义的默认值 roles/<role>/default/main.yml
Global 全局 在同一套部署环境内一致 all.vars.xxx
Cluster 集群 在同一套集群内保持一致 all.children.<cls>.vars.xxx
Instance 实例 最细粒度的配置层次 all.children.<cls>.hosts.<ins>.xxx
Argument 参数 最高 通过命令行参数传入 -e

配置项列表

类目 名称 类型 层级 说明
连接参数 proxy_env dict G 代理服务器配置
本地仓库 repo_enabled bool G 是否启用本地源
本地仓库 repo_name string G 本地源名称
本地仓库 repo_address string G 本地源外部访问地址
本地仓库 repo_port number G 本地源端口
本地仓库 repo_home string G 本地源文件根目录
本地仓库 repo_rebuild bool A 是否重建Yum源
本地仓库 repo_remove bool A 是否移除已有Yum源
本地仓库 repo_upstreams object[] G Yum源的上游来源
本地仓库 repo_packages string[] G Yum源需下载软件列表
本地仓库 repo_url_packages string[] G 通过URL直接下载的软件
节点供给 nodename string I 若指定,覆盖机器HOSTNAME
节点供给 node_dns_hosts string[] G 写入机器的静态DNS解析
节点供给 node_dns_server enum G 如何配置DNS服务器?
节点供给 node_dns_servers string[] G 配置动态DNS服务器
节点供给 node_dns_options string[] G 配置/etc/resolv.conf
节点供给 node_repo_method enum G 节点使用Yum源的方式
节点供给 node_repo_remove bool G 是否移除节点已有Yum源
节点供给 node_local_repo_url string[] G 本地源的URL地址
节点供给 node_packages string[] G 节点安装软件列表
节点供给 node_extra_packages string[] C/I/A 节点额外安装的软件列表
节点供给 node_meta_packages string[] G 元节点所需的软件列表
节点供给 node_disable_numa bool G 关闭节点NUMA
节点供给 node_disable_swap bool G 关闭节点SWAP
节点供给 node_disable_firewall bool G 关闭节点防火墙
节点供给 node_disable_selinux bool G 关闭节点SELINUX
节点供给 node_static_network bool G 是否使用静态DNS服务器
节点供给 node_disk_prefetch string G 是否启用磁盘预读
节点供给 node_kernel_modules string[] G 启用的内核模块
节点供给 node_tune enum G 节点调优模式
节点供给 node_sysctl_params dict G 操作系统内核参数
节点供给 node_admin_setup bool G 是否创建管理员用户
节点供给 node_admin_uid number G 管理员用户UID
节点供给 node_admin_username string G 管理员用户名
节点供给 node_admin_ssh_exchange bool G 在实例间交换管理员SSH密钥
节点供给 node_admin_pks string[] G 可登陆管理员的公钥列表
节点供给 node_ntp_service enum G NTP服务类型:ntp或chrony
节点供给 node_ntp_config bool G 是否配置NTP服务?
节点供给 node_timezone string G NTP时区设置
节点供给 node_ntp_servers string[] G NTP服务器列表
基础设施 ca_method enum G CA的创建方式
基础设施 ca_subject string G 自签名CA主题
基础设施 ca_homedir string G CA证书根目录
基础设施 ca_cert string G CA证书
基础设施 ca_key string G CA私钥名称
基础设施 nginx_upstream object[] G Nginx上游服务器
基础设施 dns_records string[] G 动态DNS解析记录
基础设施 prometheus_data_dir string G Prometheus数据库目录
基础设施 prometheus_options string G Prometheus命令行参数
基础设施 prometheus_reload bool A Reload而非Recreate
基础设施 prometheus_sd_method enum G 服务发现机制:static|consul
基础设施 prometheus_scrape_interval interval G Prom抓取周期
基础设施 prometheus_scrape_timeout interval G Prom抓取超时
基础设施 prometheus_sd_interval interval G Prom服务发现刷新周期
基础设施 grafana_url string G Grafana地址
基础设施 grafana_admin_password string G Grafana管理员密码
基础设施 grafana_plugin enum G 如何安装Grafana插件
基础设施 grafana_cache string G Grafana插件缓存地址
基础设施 grafana_customize bool G 是否定制Grafana
基础设施 grafana_plugins string[] G 安装的Grafana插件列表
基础设施 grafana_git_plugins string[] G 从Git安装的Grafana插件
元数据库 service_registry enum G/C/I 服务注册的位置
元数据库 dcs_type enum G 使用的DCS类型
元数据库 dcs_name string G DCS集群名称
元数据库 dcs_servers dict G DCS服务器名称:IP列表
元数据库 dcs_exists_action enum G/A 若DCS实例存在如何处理
元数据库 dcs_disable_purge bool G/C/I 完全禁止清理DCS实例
元数据库 consul_data_dir string G Consul数据目录
元数据库 etcd_data_dir string G Etcd数据目录
PG安装 pg_dbsu string G/C PG操作系统超级用户
PG安装 pg_dbsu_uid number G/C 超级用户UID
PG安装 pg_dbsu_sudo enum G/C 超级用户的Sudo权限
PG安装 pg_dbsu_home string G/C 超级用户的家目录
PG安装 pg_dbsu_ssh_exchange bool G/C 是否交换超级用户密钥
PG安装 pg_version string G/C 安装的数据库大版本
PG安装 pgdg_repo bool G/C 是否添加PG官方源?
PG安装 pg_add_repo bool G/C 是否添加PG相关源?
PG安装 pg_bin_dir string G/C PG二进制目录
PG安装 pg_packages string[] G/C 安装的PG软件包列表
PG安装 pg_extensions string[] G/C 安装的PG插件列表
PG供给 pg_cluster string C PG数据库集群名称
PG供给 pg_seq number I PG数据库实例序号
PG供给 pg_role enum I PG数据库实例角色
PG供给 pg_hostname bool G/C 将PG实例名称设为HOSTNAME
PG供给 pg_nodename bool G/C 将PG实例名称设为Consul节点名
PG供给 pg_exists bool A 标记位,PG是否已存在
PG供给 pg_exists_action enum G/A PG存在时如何处理
PG供给 pg_disable_purge enum G/C/I 禁止清除存在的PG实例
PG供给 pg_data string G PG数据目录
PG供给 pg_fs_main string G PG主数据盘挂载点
PG供给 pg_fs_bkup path G PG备份盘挂载点
PG供给 pg_listen ip G PG监听的IP地址
PG供给 pg_port number G PG监听的端口
PG供给 pg_localhost string G/C PG使用的UnixSocket地址
PG供给 patroni_mode enum G/C Patroni配置模式
PG供给 pg_namespace string G/C Patroni使用的DCS命名空间
PG供给 patroni_port string G/C Patroni服务端口
PG供给 patroni_watchdog_mode enum G/C Patroni Watchdog模式
PG供给 pg_conf enum G/C Patroni使用的配置模板
PG供给 pg_encoding string G/C PG字符集编码
PG供给 pg_locale enum G/C PG使用的本地化规则
PG供给 pg_lc_collate enum G/C PG使用的本地化排序规则
PG供给 pg_lc_ctype enum G/C PG使用的本地化字符集定义
PG供给 pgbouncer_port number G/C Pgbouncer端口
PG供给 pgbouncer_poolmode enum G/C Pgbouncer池化模式
PG供给 pgbouncer_max_db_conn number G/C Pgbouncer最大单DB连接数
PG模板 pg_init string G/C 自定义PG初始化脚本
PG模板 pg_replication_username string G PG复制用户
PG模板 pg_replication_password string G PG复制用户的密码
PG模板 pg_monitor_username string G PG监控用户
PG模板 pg_monitor_password string G PG监控用户密码
PG模板 pg_admin_username string G PG管理用户
PG模板 pg_admin_password string G PG管理用户密码
PG模板 pg_default_roles role[] G 默认创建的角色与用户
PG模板 pg_default_privilegs string[] G 数据库默认权限配置
PG模板 pg_default_schemas string[] G 默认创建的模式
PG模板 pg_default_extensions extension[] G 默认安装的扩展
PG模板 pg_offline_query bool I 是否允许离线查询
PG模板 pg_reload bool A 是否重载数据库配置(HBA)
PG模板 pg_hba_rules rule[] G 全局HBA规则
PG模板 pg_hba_rules_extra rule[] C/I 集群/实例特定的HBA规则
PG模板 pgbouncer_hba_rules rule[] G/C Pgbouncer全局HBA规则
PG模板 pgbouncer_hba_rules_extra rule[] G/C Pgbounce特定HBA规则
PG模板 pg_databases database[] G/C 业务数据库定义
PG模板 pg_users user[] G/C 业务用户定义
监控系统 exporter_install enum G/C 安装监控组件的方式
监控系统 exporter_repo_url string G/C 监控组件的YumRepo
监控系统 exporter_metrics_path string G/C 监控暴露的URL Path
监控系统 node_exporter_enabled bool G/C 启用节点指标收集器
监控系统 node_exporter_port number G/C 节点指标暴露端口
监控系统 node_exporter_options string G/C 节点指标采集选项
监控系统 pg_exporter_config string G/C PG指标定义文件
监控系统 pg_exporter_enabled bool G/C 启用PG指标收集器
监控系统 pg_exporter_port number G/C PG指标暴露端口
监控系统 pg_exporter_url string G/C 采集对象数据库的连接串(覆盖)
监控系统 pgbouncer_exporter_enabled bool G/C 启用PGB指标收集器
监控系统 pgbouncer_exporter_port number G/C PGB指标暴露端口
监控系统 pgbouncer_exporter_url string G/C 采集对象连接池的连接串
服务供给 pg_weight number I 实例在负载均衡中的相对权重
服务供给 pg_services service[] G 全局通用服务定义
服务供给 pg_services_extra service[] C 集群专有服务定义
服务供给 haproxy_enabled bool G/C/I 是否启用Haproxy
服务供给 haproxy_reload bool A 是否重载Haproxy配置
服务供给 haproxy_admin_auth_enabled bool G/C 是否对Haproxy管理界面启用认证
服务供给 haproxy_admin_username string G/C HAproxy管理员名称
服务供给 haproxy_admin_password string G/C HAproxy管理员密码
服务供给 haproxy_exporter_port number G/C HAproxy指标暴露器端口
服务供给 haproxy_client_timeout interval G/C HAproxy客户端超时
服务供给 haproxy_server_timeout interval G/C HAproxy服务端超时
服务供给 vip_mode enum G/C VIP模式:none
服务供给 vip_reload bool G/C 是否重载VIP配置
服务供给 vip_address string G/C 集群使用的VIP地址
服务供给 vip_cidrmask number G/C VIP地址的网络CIDR掩码
服务供给 vip_interface string G/C VIP使用的网卡

3 - Connect

parameters about connection info and proxy settings

参数概览

名称 类型 层级 说明
proxy_env dict G 代理服务器配置

参数详解

proxy_env

在某些受到“互联网封锁”的地区,有些软件的下载会受到影响。

例如,从中国大陆访问PostgreSQL的官方源,下载速度可能只有几KB每秒。但如果使用了合适的HTTP代理,则可以达到几MB每秒。因此如果用户有代理服务器,请通过proxy_env进行配置,样例如下:

proxy_env: # global proxy env when downloading packages
  http_proxy: 'http://username:password@proxy.address.com'
  https_proxy: 'http://username:password@proxy.address.com'
  all_proxy: 'http://username:password@proxy.address.com'
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.aliyuncs.com,mirrors.tuna.tsinghua.edu.cn,mirrors.zju.edu.cn"

ansible_host

如果用户的环境使用了跳板机,或者进行了某些定制化修改,无法通过简单的ssh <ip>方式访问,那么可以考虑使用Ansible的连接参数。ansible_host是ansiblel连接参数中最典型的一个。

Ansible中关于SSH连接的参数

  • ansible_host

    The name of the host to connect to, if different from the alias you wish to give to it.

  • ansible_port

    The ssh port number, if not 22

  • ansible_user

    The default ssh user name to use.

  • ansible_ssh_pass

    The ssh password to use (never store this variable in plain text; always use a vault. See Variables and Vaults)

  • ansible_ssh_private_key_file

    Private key file used by ssh. Useful if using multiple keys and you don’t want to use SSH agent.

  • ansible_ssh_common_args

    This setting is always appended to the default command line for sftp, scp, and ssh. Useful to configure a ProxyCommand for a certain host (or group).

  • ansible_sftp_extra_args

    This setting is always appended to the default sftp command line.

  • ansible_scp_extra_args

    This setting is always appended to the default scp command line.

  • ansible_ssh_extra_args

    This setting is always appended to the default ssh command line.

  • ansible_ssh_pipelining

    Determines whether or not to use SSH pipelining. This can override the pipelining setting in ansible.cfg.

最简单的用法是将ssh alias配置为ansible_host,只要用户可以通过 ssh <name>的方式访问目标机器,那么将ansible_host配置为<name>即可。

注意这些变量都是实例级别的变量。

Caveat

请注意,沙箱环境的默认配置使用了 SSH 别名 作为连接参数,这是因为vagrant宿主机访问虚拟机时使用了SSH别名配置。生产环境建议直接使用IP连接。

pg-meta:
  hosts:
    10.10.10.10: {pg_seq: 1, pg_role: primary, ansible_host: meta}

4 - Local Repo

Parameters about local yum repo: content, where to download, etc

Pigsty是一个复杂的软件系统,为了确保系统的稳定,Pigsty会在初始化过程中从互联网下载所有依赖的软件包并建立本地Yum源。

所有依赖的软件总大小约1GB左右,下载速度取决于您的网络情况。尽管Pigsty已经尽量使用镜像源以加速下载,但少量包的下载仍可能受到防火墙的阻挠,可能出现非常慢的情况。您可以通过proxy_env配置项设置下载代理以完成首次下载,或直接下载预先打包好的离线安装包

建立本地Yum源时,如果{{ repo_home }}/{{ repo_name }}目录已经存在,而且里面有repo_complete的标记文件,Pigsty会认为本地Yum源已经初始化完毕,因此跳过软件下载阶段,显著加快速度。离线安装包即是把{{ repo_home }}/{{ repo_name }}目录整个打成压缩包。

参数概览

名称 类型 层级 说明
proxy_env dict G 代理服务器配置
repo_enabled bool G 是否启用本地源
repo_name string G 本地源名称
repo_address string G 本地源外部访问地址
repo_port number G 本地源端口
repo_home string G 本地源文件根目录
repo_rebuild bool A 是否重建Yum源
repo_remove bool A 是否移除已有Yum源
repo_upstreams object[] G Yum源的上游来源
repo_packages string[] G Yum源需下载软件列表
repo_url_packages string[] G 通过URL直接下载的软件

默认参数

repo_enabled: true                            # 是否启用本地源功能
repo_name: pigsty                             # 本地源名称
repo_address: yum.pigsty                      # 外部可访问的源地址 (ip:port 或 url)
repo_port: 80                                 # 源HTTP服务器监听地址
repo_home: /www                               # 默认根目录
repo_rebuild: false                           # 强制重新下载软件包
repo_remove: true                             # 移除已有的yum源
repo_upstreams: [...]                         # 上游Yum源
repo_packages: [...]                          # 需要下载的软件包
repo_url_packages: [...]                      # 通过URL下载的软件

参数详解

repo_enabled

如果为true(默认情况),执行正常的本地yum源创建流程,否则跳过构建本地yum源的操作。

repo_name

本地yum源的名称,默认为pigsty,您可以改为自己喜欢的名称,例如pgsql-rhel7等。

repo_address

本地yum源对外提供服务的地址,可以是域名也可以是IP地址,默认为yum.pigsty

如果使用域名,您必须确保在当前环境中该域名会解析到本地源所在的服务器,也就是元节点。

如果您的本地yum源没有使用标准的80端口,您需要在地址中加入端口,并与repo_port变量保持一致。

您可以通过节点参数中的静态DNS配置来为环境中的所有节点写入Pigsty本地源的域名,沙箱环境中即是采用这种方式来解析默认的yum.pigsty域名。

repo_port

本地yum源使用的HTTP端口,默认为80端口。

repo_home

本地yum源的根目录,默认为www

该目录将作为HTTP服务器的根对外暴露。

repo_rebuild

如果为false(默认情况),什么都不发生,如果为true,那么在任何情况下都会执行Repo重建的工作。

repo_remove

在执行本地源初始化的过程中,是否移除/etc/yum.repos.d中所有已有的repo?默认为true

原有repo文件会备份至/etc/yum.repos.d/backup中。

因为操作系统已有的源内容不可控,建议强制移除并通过repo_upstreams进行显式配置。

repo_upstream

所有添加到/etc/yum.repos.d中的Yum源,Pigsty将从这些源中下载软件。

Pigsty默认使用阿里云的CentOS7镜像源,清华大学Grafana镜像源,PackageCloud的Prometheus源,PostgreSQL官方源,以及SCLo,Harbottle,Nginx, Haproxy等软件源。

- name: base
  description: CentOS-$releasever - Base - Aliyun Mirror
  baseurl:
    - http://mirrors.aliyun.com/centos/$releasever/os/$basearch/
    - http://mirrors.aliyuncs.com/centos/$releasever/os/$basearch/
    - http://mirrors.cloud.aliyuncs.com/centos/$releasever/os/$basearch/
  gpgcheck: no
  failovermethod: priority

- name: updates
  description: CentOS-$releasever - Updates - Aliyun Mirror
  baseurl:
    - http://mirrors.aliyun.com/centos/$releasever/updates/$basearch/
    - http://mirrors.aliyuncs.com/centos/$releasever/updates/$basearch/
    - http://mirrors.cloud.aliyuncs.com/centos/$releasever/updates/$basearch/
  gpgcheck: no
  failovermethod: priority

- name: extras
  description: CentOS-$releasever - Extras - Aliyun Mirror
  baseurl:
    - http://mirrors.aliyun.com/centos/$releasever/extras/$basearch/
    - http://mirrors.aliyuncs.com/centos/$releasever/extras/$basearch/
    - http://mirrors.cloud.aliyuncs.com/centos/$releasever/extras/$basearch/
  gpgcheck: no
  failovermethod: priority

- name: epel
  description: CentOS $releasever - EPEL - Aliyun Mirror
  baseurl: http://mirrors.aliyun.com/epel/$releasever/$basearch
  gpgcheck: no
  failovermethod: priority

- name: grafana
  description: Grafana - TsingHua Mirror
  gpgcheck: no
  baseurl: https://mirrors.tuna.tsinghua.edu.cn/grafana/yum/rpm

- name: prometheus
  description: Prometheus and exporters
  gpgcheck: no
  baseurl: https://packagecloud.io/prometheus-rpm/release/el/$releasever/$basearch

- name: pgdg-common
  description: PostgreSQL common RPMs for RHEL/CentOS $releasever - $basearch
  gpgcheck: no
  baseurl: https://download.postgresql.org/pub/repos/yum/common/redhat/rhel-$releasever-$basearch

- name: pgdg13
  description: PostgreSQL 13 for RHEL/CentOS $releasever - $basearch - Updates testing
  gpgcheck: no
  baseurl: https://download.postgresql.org/pub/repos/yum/13/redhat/rhel-$releasever-$basearch

- name: centos-sclo
  description: CentOS-$releasever - SCLo
  gpgcheck: no
  mirrorlist: http://mirrorlist.centos.org?arch=$basearch&release=7&repo=sclo-sclo

- name: centos-sclo-rh
  description: CentOS-$releasever - SCLo rh
  gpgcheck: no
  mirrorlist: http://mirrorlist.centos.org?arch=$basearch&release=7&repo=sclo-rh

- name: nginx
  description: Nginx Official Yum Repo
  skip_if_unavailable: true
  gpgcheck: no
  baseurl: http://nginx.org/packages/centos/$releasever/$basearch/

- name: haproxy
  description: Copr repo for haproxy
  skip_if_unavailable: true
  gpgcheck: no
  baseurl: https://download.copr.fedorainfracloud.org/results/roidelapluie/haproxy/epel-$releasever-$basearch/

# for latest consul & kubernetes
- name: harbottle
  description: Copr repo for main owned by harbottle
  skip_if_unavailable: true
  gpgcheck: no
  baseurl: https://download.copr.fedorainfracloud.org/results/harbottle/main/epel-$releasever-$basearch/

repo_packages

需要下载的rpm安装包列表,默认下载的软件包如下所示:

# - what to download - #
repo_packages:
  # repo bootstrap packages
  - epel-release nginx wget yum-utils yum createrepo                                      # bootstrap packages

  # node basic packages
  - ntp chrony uuid lz4 nc pv jq vim-enhanced make patch bash lsof wget unzip git tuned   # basic system util
  - readline zlib openssl libyaml libxml2 libxslt perl-ExtUtils-Embed ca-certificates     # basic pg dependency
  - numactl grubby sysstat dstat iotop bind-utils net-tools tcpdump socat ipvsadm telnet  # system utils

  # dcs & monitor packages
  - grafana prometheus2 pushgateway alertmanager                                          # monitor and ui
  - node_exporter postgres_exporter nginx_exporter blackbox_exporter                      # exporter
  - consul consul_exporter consul-template etcd                                           # dcs

  # python3 dependencies
  - ansible python python-pip python-psycopg2                                             # ansible & python
  - python3 python3-psycopg2 python36-requests python3-etcd python3-consul                # python3
  - python36-urllib3 python36-idna python36-pyOpenSSL python36-cryptography               # python3 patroni extra deps

  # proxy and load balancer
  - haproxy keepalived dnsmasq                                                            # proxy and dns

  # postgres common Packages
  - patroni patroni-consul patroni-etcd pgbouncer pg_cli pgbadger pg_activity               # major components
  - pgcenter boxinfo check_postgres emaj pgbconsole pg_bloat_check pgquarrel                # other common utils
  - barman barman-cli pgloader pgFormatter pitrery pspg pgxnclient PyGreSQL pgadmin4 tail_n_mail

  # postgres 13 packages
  - postgresql13* postgis31* citus_13 pgrouting_13                                          # postgres 13 and postgis 31
  - pg_repack13 pg_squeeze13                                                                # maintenance extensions
  - pg_qualstats13 pg_stat_kcache13 system_stats_13 bgw_replstatus13                        # stats extensions
  - plr13 plsh13 plpgsql_check_13 plproxy13 plr13 plsh13 plpgsql_check_13 pldebugger13      # PL extensions                                      # pl extensions
  - hdfs_fdw_13 mongo_fdw13 mysql_fdw_13 ogr_fdw13 redis_fdw_13 pgbouncer_fdw13             # FDW extensions
  - wal2json13 count_distinct13 ddlx_13 geoip13 orafce13                                    # MISC extensions
  - rum_13 hypopg_13 ip4r13 jsquery_13 logerrors_13 periods_13 pg_auto_failover_13 pg_catcheck13
  - pg_fkpart13 pg_jobmon13 pg_partman13 pg_prioritize_13 pg_track_settings13 pgaudit15_13
  - pgcryptokey13 pgexportdoc13 pgimportdoc13 pgmemcache-13 pgmp13 pgq-13
  - pguint13 pguri13 prefix13  safeupdate_13 semver13  table_version13 tdigest13

repo_url_packages

采用URL直接下载,而非yum下载的软件包。您可以将自定义的软件包连接添加到这里。

Pigsty默认会通过URL下载三款软件:

  • pg_exporter(必须,监控系统核心组件)
  • vip-manager(可选,启用VIP时必须)
  • polysh(可选,多机管理便捷工具)
repo_url_packages:
  - https://github.com/Vonng/pg_exporter/releases/download/v0.3.1/pg_exporter-0.3.1-1.el7.x86_64.rpm
  - https://github.com/cybertec-postgresql/vip-manager/releases/download/v0.6/vip-manager_0.6-1_amd64.rpm
  - http://guichaz.free.fr/polysh/files/polysh-0.4-1.noarch.rpm

5 - Node Provision

Parameters about os, machine, infrastructure on all nodes

Pigsty中关于机器与操作系统、基础设施的配置参数

参数概览

名称 类型 层级 说明
nodename string I 若指定,覆盖机器HOSTNAME
node_dns_hosts string[] G 写入机器的静态DNS解析
node_dns_server enum G 如何配置DNS服务器?
node_dns_servers string[] G 配置动态DNS服务器
node_dns_options string[] G 配置/etc/resolv.conf
node_repo_method enum G 节点使用Yum源的方式
node_repo_remove bool G 是否移除节点已有Yum源
node_local_repo_url string[] G 本地源的URL地址
node_packages string[] G 节点安装软件列表
node_extra_packages string[] C/I/A 节点额外安装的软件列表
node_meta_packages string[] G 元节点所需的软件列表
node_disable_numa bool G 关闭节点NUMA
node_disable_swap bool G 关闭节点SWAP
node_disable_firewall bool G 关闭节点防火墙
node_disable_selinux bool G 关闭节点SELINUX
node_static_network bool G 是否使用静态DNS服务器
node_disk_prefetch string G 是否启用磁盘预读
node_kernel_modules string[] G 启用的内核模块
node_tune enum G 节点调优模式
node_sysctl_params dict G 操作系统内核参数
node_admin_setup bool G 是否创建管理员用户
node_admin_uid number G 管理员用户UID
node_admin_username string G 管理员用户名
node_admin_ssh_exchange bool G 在实例间交换管理员SSH密钥
node_admin_pks string[] G 可登陆管理员的公钥列表
node_ntp_service enum G NTP服务类型:ntp或chrony
node_ntp_config bool G 是否配置NTP服务?
node_timezone string G NTP时区设置
node_ntp_servers string[] G NTP服务器列表

默认配置

#------------------------------------------------------------------------------
# NODE PROVISION
#------------------------------------------------------------------------------
# this section defines how to provision nodes
# nodename:                                   # if defined, node's hostname will be overwritten

# - node dns - #
node_dns_hosts: # static dns records in /etc/hosts
  - 10.10.10.10 yum.pigsty
node_dns_server: add                          # add (default) | none (skip) | overwrite (remove old settings)
node_dns_servers: # dynamic nameserver in /etc/resolv.conf
  - 10.10.10.10
node_dns_options: # dns resolv options
  - options single-request-reopen timeout:1 rotate
  - domain service.consul

# - node repo - #
node_repo_method: local                       # none|local|public (use local repo for production env)
node_repo_remove: true                        # whether remove existing repo
# local repo url (if method=local, make sure firewall is configured or disabled)
node_local_repo_url:
  - http://yum.pigsty/pigsty.repo

# - node packages - #
node_packages: # common packages for all nodes
  - wget,yum-utils,ntp,chrony,tuned,uuid,lz4,vim-minimal,make,patch,bash,lsof,wget,unzip,git,readline,zlib,openssl
  - numactl,grubby,sysstat,dstat,iotop,bind-utils,net-tools,tcpdump,socat,ipvsadm,telnet,tuned,pv,jq
  - python3,python3-psycopg2,python36-requests,python3-etcd,python3-consul
  - python36-urllib3,python36-idna,python36-pyOpenSSL,python36-cryptography
  - node_exporter,consul,consul-template,etcd,haproxy,keepalived,vip-manager
node_extra_packages: # extra packages for all nodes
  - patroni,patroni-consul,patroni-etcd,pgbouncer,pgbadger,pg_activity
node_meta_packages: # packages for meta nodes only
  - grafana,prometheus2,alertmanager,nginx_exporter,blackbox_exporter,pushgateway
  - dnsmasq,nginx,ansible,pgbadger,polysh

# - node features - #
node_disable_numa: false                      # disable numa, important for production database, reboot required
node_disable_swap: false                      # disable swap, important for production database
node_disable_firewall: true                   # disable firewall (required if using kubernetes)
node_disable_selinux: true                    # disable selinux  (required if using kubernetes)
node_static_network: true                     # keep dns resolver settings after reboot
node_disk_prefetch: false                     # setup disk prefetch on HDD to increase performance

# - node kernel modules - #
node_kernel_modules:
  - softdog
  - br_netfilter
  - ip_vs
  - ip_vs_rr
  - ip_vs_rr
  - ip_vs_wrr
  - ip_vs_sh
  - nf_conntrack_ipv4

# - node tuned - #
node_tune: tiny                               # install and activate tuned profile: none|oltp|olap|crit|tiny
node_sysctl_params: # set additional sysctl parameters, k:v format
  net.bridge.bridge-nf-call-iptables: 1       # for kubernetes

# - node user - #
node_admin_setup: true                        # setup an default admin user ?
node_admin_uid: 88                            # uid and gid for admin user
node_admin_username: admin                    # default admin user
node_admin_ssh_exchange: true                 # exchange ssh key among cluster ?
node_admin_pks: # public key list that will be installed
  - 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC7IMAMNavYtWwzAJajKqwdn3ar5BhvcwCnBTxxEkXhGlCO2vfgosSAQMEflfgvkiI5nM1HIFQ8KINlx1XLO7SdL5KdInG5LIJjAFh0pujS4kNCT9a5IGvSq1BrzGqhbEcwWYdju1ZPYBcJm/MG+JD0dYCh8vfrYB/cYMD0SOmNkQ== vagrant@pigsty.com'

# - node ntp - #
node_ntp_service: ntp                         # ntp or chrony
node_ntp_config: true                         # overwrite existing ntp config?
node_timezone: Asia/Shanghai                  # default node timezone
node_ntp_servers: # default NTP servers
  - pool cn.pool.ntp.org iburst
  - pool pool.ntp.org iburst
  - pool time.pool.aliyun.com iburst
  - server 10.10.10.10 iburst

参数详解

nodename

如果配置了该参数,那么实例的HOSTNAM将会被该名称覆盖。

该选项可用于为节点显式指定名称。如果要使用PG的实例名称作为节点名称,可以使用pg_hostname选项

node_dns_hosts

机器节点的默认静态DNS解析记录,每一条记录都会在机器节点初始化时写入/etc/hosts中,特别适合用于配置基础设施地址。

node_dns_hosts是一个数组,每一个元素都是形如ip domain_name的字符串,代表一条DNS解析记录。

默认情况下,Pigsty会向/etc/hosts中写入10.10.10.10 yum.pigsty,这样可以在DNS Nameserver启动之前,采用域名的方式访问本地yum源。

node_dns_server

机器节点默认的动态DNS服务器的配置方式,有三种模式:

  • add:将node_dns_servers中的记录追加至/etc/resolv.conf,并保留已有DNS服务器。(默认)
  • overwrite:使用将node_dns_servers中的记录覆盖/etc/resolv.conf
  • none:跳过DNS服务器配置

node_dns_servers

如果node_dns_server配置为addoverwrite,则node_dns_servers中的记录会被追加或覆盖至/etc/resolv.conf中。具体格式请参考Linux文档关于/etc/resolv.conf的说明。

Pigsty默认会添加元节点作为DNS Server,元节点上的DNSMASQ会响应环境中的DNS请求。

node_dns_servers: # dynamic nameserver in /etc/resolv.conf
  - 10.10.10.10

node_dns_options

如果node_dns_server配置为addoverwrite,则node_dns_options中的记录会被追加或覆盖至/etc/resolv.conf中。具体格式请参考Linux文档关于/etc/resolv.conf的说明

Pigsty默认添加的解析选项为:

- options single-request-reopen timeout:1 rotate
- domain service.consul

node_repo_method

机器节点Yum软件源的配置方式,有三种模式:

  • local:使用元节点上的本地Yum源,默认行为,推荐。
  • public:直接使用互联网源安装,将repo_upstream中的公共repo写入/etc/yum.repos.d/
  • none:不对本地源进行配置与修改。

node_repo_remove

原有Yum源的处理方式,是否移除节点上原有的Yum源?

Pigsty默认会移除/etc/yum.repos.d中原有的配置文件,并备份至/etc/yum.repos.d/backup

node_local_repo_url

如果node_repo_method配置为local,则这里列出的Repo文件URL会被下载至/etc/yum.repos.d

这里是一个Repo File URL 构成的数组,Pigsty默认会将元节点上的本地Yum源加入机器的源配置中。

node_local_repo_url:
  - http://yum.pigsty/pigsty.repo

node_packages

通过yum安装的软件包列表。

软件包列表为数组,但每个元素可以包含由逗号分隔的多个软件包,Pigsty默认安装的软件包列表如下:

node_packages: # common packages for all nodes
  - wget,yum-utils,ntp,chrony,tuned,uuid,lz4,vim-minimal,make,patch,bash,lsof,wget,unzip,git,readline,zlib,openssl
  - numactl,grubby,sysstat,dstat,iotop,bind-utils,net-tools,tcpdump,socat,ipvsadm,telnet,tuned,pv,jq
  - python3,python3-psycopg2,python36-requests,python3-etcd,python3-consul
  - python36-urllib3,python36-idna,python36-pyOpenSSL,python36-cryptography
  - node_exporter,consul,consul-template,etcd,haproxy,keepalived,vip-manager

node_extra_packages

通过yum安装的额外软件包列表。

node_packages类似,但node_packages通常是全局统一配置,而node_extra_packages则是针对具体节点进行例外处理。例如,您可以为运行PG的节点安装额外的工具包。该变量通常在集群和实例级别进行覆盖定义。

Pigsty默认安装的额外软件包列表如下:

- patroni,patroni-consul,patroni-etcd,pgbouncer,pgbadger,pg_activity

node_meta_packages

通过yum安装的元节点软件包列表。

node_packagesnode_extra_packages类似,但node_meta_packages中列出的软件包只会在元节点上安装。因此通常都是监控软件,管理工具,构建工具等。

Pigsty默认安装的元节点软件包列表如下:

node_meta_packages:                           # packages for meta nodes only
  - grafana,prometheus2,alertmanager,nginx_exporter,blackbox_exporter,pushgateway
  - dnsmasq,nginx,ansible,pgbadger,polysh

node_disable_numa

是否关闭Numa,注意,该选项需要重启后生效!默认不关闭,但生产环境强烈建议关闭NUMA。

node_disable_swap

是否禁用SWAP,如果您有足够的内存,且数据库采用独占式部署,建议直接关闭SWAP提高性能,默认关闭。

node_disable_firewall

是否关闭防火墙,这个东西非常讨厌,建议关闭,默认关闭。

node_disable_selinux

是否关闭SELinux,这个东西非常讨厌,建议关闭,默认关闭。

node_static_network

是否采用静态网络配置,默认启用

启用静态网络,意味着您的DNS Resolv配置不会因为机器重启与网卡变动被覆盖。建议启用。

node_disk_prefetch

是否启用磁盘预读?

针对HDD部署的实例可以优化吞吐量,默认关闭。

node_kernel_modules

需要安装的内核模块

Pigsty默认会启用以下内核模块

node_kernel_modules: [softdog, ip_vs, ip_vs_rr, ip_vs_rr, ip_vs_wrr, ip_vs_sh]

node_tune

针对机器进行调优的预制方案

node_sysctl_params

修改sysctl系统参数

字典KV结构

node_admin_setup

是否在每个节点上创建管理员用户(免密sudo与ssh),默认会创建。

Pigsty默认会创建名为admin (uid=88)的管理用户,可以从元节点上通过SSH免密访问环境中的其他节点并执行免密sudo。

node_admin_uid

管理员用户的uid,默认为88

node_admin_username

管理员用户的名称,默认为admin

node_admin_ssh_exchange

是否在当前执行命令的机器之间相互交换管理员用户的SSH密钥?

默认会执行交换,这样管理员可以在机器间快速跳转。

node_admin_pks

写入到管理员~/.ssh/authorized_keys中的密钥

持有对应私钥的用户可以以管理员身份登陆。

node_ntp_service

指明系统使用的NTP服务类型:

  • ntp:传统NTP服务
  • chrony:CentOS 7/8默认使用的时间服务

node_ntp_config

是否覆盖现有NTP配置?

布尔选项,默认覆盖。

node_timezone

默认使用的时区

Pigsty默认使用Asia/Shanghai,请根据您的实际情况调整。

node_ntp_servers

NTP服务器地址

Pigsty默认会使用以下NTP服务器

- pool cn.pool.ntp.org iburst
- pool pool.ntp.org iburst
- pool time.pool.aliyun.com iburst
- server 10.10.10.10 iburst

6 - Infrastructure

Parameteres about infrastructures

这一节定义了部署于元节点上的 基础设施 ,包括:

参数概览

名称 类型 层级 说明
ca_method enum G CA的创建方式
ca_subject string G 自签名CA主题
ca_homedir string G CA证书根目录
ca_cert string G CA证书
ca_key string G CA私钥名称
nginx_upstream object[] G Nginx上游服务器
dns_records string[] G 动态DNS解析记录
prometheus_data_dir string G Prometheus数据库目录
prometheus_options string G Prometheus命令行参数
prometheus_reload bool A Reload而非Recreate
prometheus_sd_method enum G 服务发现机制:static|consul
prometheus_scrape_interval interval G Prom抓取周期
prometheus_scrape_timeout interval G Prom抓取超时
prometheus_sd_interval interval G Prom服务发现刷新周期
grafana_url string G Grafana地址
grafana_admin_password string G Grafana管理员密码
grafana_plugin enum G 如何安装Grafana插件
grafana_cache string G Grafana插件缓存地址
grafana_customize bool G 是否定制Grafana
grafana_plugins string[] G 安装的Grafana插件列表
grafana_git_plugins string[] G 从Git安装的Grafana插件

默认参数

#------------------------------------------------------------------------------
# META PROVISION
#------------------------------------------------------------------------------
# - ca - #
ca_method: create                             # create|copy|recreate
ca_subject: "/CN=root-ca"                     # self-signed CA subject
ca_homedir: /ca                               # ca cert directory
ca_cert: ca.crt                               # ca public key/cert
ca_key: ca.key                                # ca private key

# - nginx - #
nginx_upstream:
  - { name: home,          host: pigsty,   url: "127.0.0.1:3000"}
  - { name: consul,        host: c.pigsty, url: "127.0.0.1:8500" }
  - { name: grafana,       host: g.pigsty, url: "127.0.0.1:3000" }
  - { name: prometheus,    host: p.pigsty, url: "127.0.0.1:9090" }
  - { name: alertmanager,  host: a.pigsty, url: "127.0.0.1:9093" }
  - { name: haproxy,       host: h.pigsty, url: "127.0.0.1:9091" }

# - nameserver - #
dns_records: # dynamic dns record resolved by dnsmasq
  - 10.10.10.2  pg-meta                       # sandbox vip for pg-meta
  - 10.10.10.3  pg-test                       # sandbox vip for pg-test
  - 10.10.10.10 meta-1                        # sandbox node meta-1 (node-0)
  - 10.10.10.11 node-1                        # sandbox node node-1
  - 10.10.10.12 node-2                        # sandbox node node-2
  - 10.10.10.13 node-3                        # sandbox node node-3
  - 10.10.10.10 pigsty
  - 10.10.10.10 y.pigsty yum.pigsty
  - 10.10.10.10 c.pigsty consul.pigsty
  - 10.10.10.10 g.pigsty grafana.pigsty
  - 10.10.10.10 p.pigsty prometheus.pigsty
  - 10.10.10.10 a.pigsty alertmanager.pigsty
  - 10.10.10.10 n.pigsty ntp.pigsty
  - 10.10.10.10 h.pigsty haproxy.pigsty

# - prometheus - #
prometheus_data_dir: /export/prometheus/data  # prometheus data dir
prometheus_options: '--storage.tsdb.retention=30d'
prometheus_reload: false                      # reload prometheus instead of recreate it
prometheus_sd_method: consul                  # service discovery method: static|consul|etcd
prometheus_scrape_interval: 2s                # global scrape & evaluation interval
prometheus_scrape_timeout: 1s                 # scrape timeout
prometheus_sd_interval: 2s                    # service discovery refresh interval

# - grafana - #
grafana_url: http://admin:admin@10.10.10.10:3000 # grafana url
grafana_admin_password: admin                  # default grafana admin user password
grafana_plugin: install                        # none|install|reinstall
grafana_cache: /www/pigsty/grafana/plugins.tar.gz # path to grafana plugins tarball
grafana_customize: true                        # customize grafana resources
grafana_plugins: # default grafana plugins list
  - redis-datasource
  - simpod-json-datasource
  - fifemon-graphql-datasource
  - sbueringer-consul-datasource
  - camptocamp-prometheus-alertmanager-datasource
  - ryantxu-ajax-panel
  - marcusolsson-hourly-heatmap-panel
  - michaeldmoore-multistat-panel
  - marcusolsson-treemap-panel
  - pr0ps-trackmap-panel
  - dalvany-image-panel
  - magnesium-wordcloud-panel
  - cloudspout-button-panel
  - speakyourcode-button-panel
  - jdbranham-diagram-panel
  - grafana-piechart-panel
  - snuids-radar-panel
  - digrich-bubblechart-panel
grafana_git_plugins:
  - https://github.com/Vonng/grafana-echarts

参数详解

ca_method

  • create:创建新的公私钥用于CA
  • copy:拷贝现有的CA公私钥用于构建CA

ca_subject

CA自签名的主题

默认主题为:

"/CN=root-ca"

ca_homedir

CA文件的根目录

默认为/ca

ca_cert

CA公钥证书名称

默认为:ca.crt

ca_key

CA私钥文件名称

默认为ca.key

nginx_upstream

Nginx上游服务的URL与域名

Nginx会通过Host进行流量转发,因此确保访问Pigsty基础设施服务时,配置有正确的域名。

不要修改name 部分的定义。

nginx_upstream:
- { name: home,          host: pigsty,   url: "127.0.0.1:3000"}
- { name: consul,        host: c.pigsty, url: "127.0.0.1:8500" }
- { name: grafana,       host: g.pigsty, url: "127.0.0.1:3000" }
- { name: prometheus,    host: p.pigsty, url: "127.0.0.1:9090" }
- { name: alertmanager,  host: a.pigsty, url: "127.0.0.1:9093" }
- { name: haproxy,       host: h.pigsty, url: "127.0.0.1:9091" }

dns_records

动态DNS解析记录

每一条记录都会写入元节点的/etc/hosts中,并由元节点上的域名服务器提供解析。

prometheus_data_dir

Prometheus数据目录

默认位于/export/prometheus/data

prometheus_options

Prometheus命令行参数

默认参数为:--storage.tsdb.retention=30d,即保留30天的监控数据

参数prometheus_retention的功能被此参数覆盖,于v0.6后弃用。

prometheus_reload

如果为true,执行Prometheus任务时不会清除已有数据目录。

默认为:false,即执行prometheus剧本时会清除已有监控数据。

prometheus_sd_method

Prometheus使用的服务发现机制,默认为consul,可选项:

  • consul:基于Consul进行服务发现
  • static:基于本地配置文件进行服务发现

Pigsty建议使用consul服务发现,当服务器发生Failover时,监控系统会自动更正目标实例所注册的身份。

static服务发现依赖/etc/prometheus/targets/*.yml中的配置进行服务发现。采用这种方式的优势是不依赖Consul。当Pigsty监控系统与外部管控方案集成时,这种模式对原系统的侵入性较小。同时,当集群内发生主从切换时,您需要自行维护实例角色信息。

手动维护时,可以根据以下命令从配置文件生成Prometheus所需的监控对象配置文件。

./infra.yml --tags=prometheus_targtes,prometheus_reload

详细信息请参考:服务发现

prometheus_sd_target(过时)

目前Pigsty中Prometheus的服务发现对象统一采用集群模式管理,不再提供配置

prometheus_sd_method == 'static' 时,监控目标定义文件管理的方式:

  • batch:使用批量管理的单一配置文件:/etc/prometheus/targets/all.yml
  • single:使用每个实例一个的配置文件:/etc/prometheus/targets/{{ pg_instance }}.yml

使用批量管理的单一配置文件管理简单,但用户必须使用默认的单一配置文件方式(即所有数据库集群的定义都在同一个配置文件中),才可以使用这种管理方式。

当使用分立式的配置文件(每个集群一个配置文件)时,用户需要使用 single 管理模式。每一个新数据库实例都会在元节点的 /etc/prometheus/targets/ 目录下创建一个新的定义文件。

prometheus_scrape_interval

Prometheus抓取周期

默认为2s,建议在生产环境中使用15s

prometheus_scrape_timeout

Prometheus抓取超时

默认为1s,建议在生产环境中使用10s,或根据实际需求进行配置。

prometheus_sd_interval

Prometheus刷新服务发现列表的周期

默认为5s,建议在生产环境中使用更长的间隔,或根据实际需求进行配置。

prometheus_metrics_path (弃用)

Prometheus 抓取指标暴露器的URL路径,默认为/metrics

已经被外部变量引用exporter_metrics_path所替代,不再生效。

prometheus_retention(弃用)

Prometheus数据保留期限,默认配置30天

参数prometheus_retention的功能被参数prometheus_options覆盖,于v0.6后弃用。

grafana_url

Grafana对外提供服务的端点,需要带上用户名与密码。

Grafana Provision的过程中会使用该URL调用Grafana API

grafana_admin_password

Grafana管理用户的密码

默认为admin

grafana_plugin

Grafana插件的供给方式

  • none:不安装插件
  • install: 安装Grafana插件(默认)
  • reinstall: 强制重新安装Grafana插件

Grafana需要访问互联网以下载若干扩展插件,如果您的元节点没有互联网访问,离线安装包中已经包含了所有下载好的Grafana插件。Pigsty会在插件下载完成后重新制作新的插件缓存安装包。

grafana_cache

Grafana插件缓存文件地址

离线安装包中已经包含了所有下载并打包好的Grafana插件,如果插件包目录已经存在,Pigsty就不会尝试从互联网重新下载Grafana插件。

默认的离线插件缓存地址为:/www/pigsty/grafana/plugins.tar.gz (假设本地Yum源名为pigsty

grafana_customize

标记,是否要定制Grafana

如果选择是,Grafana的Logo会被替换为Pigsty,你懂的。

grafana_plugins

Grafana插件列表

数组,每个元素是一个插件名称。

插件会通过grafana-cli plugins install的方式进行安装。

默认安装的插件有:

grafana_plugins: # default grafana plugins list
  - redis-datasource
  - simpod-json-datasource
  - fifemon-graphql-datasource
  - sbueringer-consul-datasource
  - camptocamp-prometheus-alertmanager-datasource
  - ryantxu-ajax-panel
  - marcusolsson-hourly-heatmap-panel
  - michaeldmoore-multistat-panel
  - marcusolsson-treemap-panel
  - pr0ps-trackmap-panel
  - dalvany-image-panel
  - magnesium-wordcloud-panel
  - cloudspout-button-panel
  - speakyourcode-button-panel
  - jdbranham-diagram-panel
  - grafana-piechart-panel
  - snuids-radar-panel
  - digrich-bubblechart-panel

grafana_git_plugins

Grafana的Git插件

一些插件无法通过官方命令行下载,但可以通过Git Clone的方式下载,则可以考虑使用本参数。

数组,每个元素是一个插件名称。

插件会通过cd /var/lib/grafana/plugins && git clone 的方式进行安装。

默认会下载一个可视化插件:

grafana_git_plugins:
  - https://github.com/Vonng/grafana-echarts

7 - DCS

Parameters about distributed configuration storage

Pigsty使用DCS(Distributive Configuration Storage)作为元数据库。DCS有三个重要作用:

  • 主库选举:Patroni基于DCS进行选举与切换
  • 配置管理:Patroni使用DCS管理Postgres的配置
  • 身份管理:监控系统基于DCS管理并维护数据库实例的身份信息。

DCS对于数据库的稳定至关重要,Pigsty出于演示目的提供了基本的Consul与Etcd支持,在元节点部署了DCS服务。建议在生产环境中使用专用机器部署专用DCS集群。

参数概览

名称 类型 层级 说明
service_registry enum G/C/I 服务注册的位置
dcs_type enum G 使用的DCS类型
dcs_name string G DCS集群名称
dcs_servers dict G DCS服务器名称:IP列表
dcs_exists_action enum G/A 若DCS实例存在如何处理
dcs_disable_purge bool G/C/I 完全禁止清理DCS实例
consul_data_dir string G Consul数据目录
etcd_data_dir string G Etcd数据目录

默认参数

#------------------------------------------------------------------------------
# DCS PROVISION
#------------------------------------------------------------------------------
service_registry: consul                      # where to register services: none | consul | etcd | both
dcs_type: consul                              # consul | etcd | both
dcs_name: pigsty                              # consul dc name | etcd initial cluster token
dcs_servers:                                  # dcs server dict in name:ip format
  meta-1: 10.10.10.10                         # you could use existing dcs cluster
  # meta-2: 10.10.10.11                       # host which have their IP listed here will be init as server
  # meta-3: 10.10.10.12                       # 3 or 5 dcs nodes are recommend for production environment
dcs_exists_action: skip                       # abort|skip|clean if dcs server already exists
dcs_disable_purge: false                      # set to true to disable purge functionality for good (force dcs_exists_action = abort)
consul_data_dir: /var/lib/consul              # consul data dir (/var/lib/consul by default)
etcd_data_dir: /var/lib/etcd                  # etcd data dir (/var/lib/consul by default)

参数详解

service_registry

服务注册的地址,被多个组件引用。

  • none:不执行服务注册(当执行仅监控部署时,必须指定none模式)
  • consul:将服务注册至Consul中
  • etcd:将服务注册至Etcd中(尚未支持)

dcs_type

DCS类型,有两种选项:

  • Consul

  • Etcd (支持尚不完善)

dcs_name

DCS集群名称

默认为pigsty

在Consul中代表 DataCenter名称

dcs_servers

DCS服务器名称与地址,采用字典格式,Key为DCS服务器实例名称,Value为对应的IP地址。

可以使用外部的已有DCS服务器,也可以在目标机器上初始化新的DCS服务器。

如果采用初始化新DCS实例的方式,建议先在所有DCS Server(通常也是元节点)上完成DCS初始化。

尽管您也可以一次性初始化所有的DCS Server与DCS Agent,但必须在完整初始化时将所有Server囊括在内。此时所有IP地址匹配dcs_servers项的目标机器将会在DCS初始化过程中,初始化为DCS Server。

强烈建议使用奇数个DCS Server,演示环境可使用单个DCS Server,生产环境建议使用3~5个确保DCS可用性。

您必须根据实际情况显式配置DCS Server,例如在沙箱环境中,您可以选择启用1个或3个DCS节点。

dcs_servers:
  meta-1: 10.10.10.10
  meta-2: 10.10.10.11 
  meta-3: 10.10.10.12 

dcs_exists_action

安全保险,当Consul实例已经存在时,系统应当执行的动作

  • abort: 中止整个剧本的执行(默认行为)
  • clean: 抹除现有DCS实例并继续(极端危险)
  • skip: 忽略存在DCS实例的目标(中止),在其他目标机器上继续执行。

如果您真的需要强制清除已经存在的DCS实例,建议先使用pgsql-rm.yml完成集群与实例的下线与销毁,在重新执行初始化。否则,则需要通过命令行参数-e dcs_exists_action=clean完成覆写,强制在初始化过程中抹除已有实例。

dcs_disable_purge

双重安全保险,默认为false。如果为true,强制设置dcs_exists_action变量为abort

等效于关闭dcs_exists_action的清理功能,确保任何情况下DCS实例都不会被抹除。

consul_data_dir

Consul数据目录地址

默认为/var/lib/consul

etcd_data_dir

Etcd数据目录地址

默认为/var/lib/etcd

8 - PG Install

Parameters about postgres installation

PG Install 部分负责在一台装有基本软件的机器上完成所有PostgreSQL依赖项的安装。用户可以配置数据库超级用户的名称、ID、权限、访问,配置安装所用的源,配置安装地址,安装的版本,所需的软件包与扩展插件。

这里的大多数参数只需要在整体升级数据库大版本时修改,用户可以通过pg_version指定需要安装的软件版本,并在集群层面进行覆盖,为不同的集群安装不同的数据库版本。

参数概览

名称 类型 层级 说明
pg_dbsu string G/C PG操作系统超级用户
pg_dbsu_uid number G/C 超级用户UID
pg_dbsu_sudo enum G/C 超级用户的Sudo权限
pg_dbsu_home string G/C 超级用户的家目录
pg_dbsu_ssh_exchange bool G/C 是否交换超级用户密钥
pg_version string G/C 安装的数据库大版本
pgdg_repo bool G/C 是否添加PG官方源?
pg_add_repo bool G/C 是否添加PG相关源?
pg_bin_dir string G/C PG二进制目录
pg_packages string[] G/C 安装的PG软件包列表
pg_extensions string[] G/C 安装的PG插件列表

默认参数

#------------------------------------------------------------------------------
# POSTGRES INSTALLATION
#------------------------------------------------------------------------------
# - dbsu - #
pg_dbsu: postgres                             # os user for database, postgres by default (change it is not recommended!)
pg_dbsu_uid: 26                               # os dbsu uid and gid, 26 for default postgres users and groups
pg_dbsu_sudo: limit                           # none|limit|all|nopass (Privilege for dbsu, limit is recommended)
pg_dbsu_home: /var/lib/pgsql                  # postgresql binary
pg_dbsu_ssh_exchange: false                   # exchange ssh key among same cluster

# - postgres packages - #
pg_version: 13                                # default postgresql version
pgdg_repo: false                              # use official pgdg yum repo (disable if you have local mirror)
pg_add_repo: false                            # add postgres related repo before install (useful if you want a simple install)
pg_bin_dir: /usr/pgsql/bin                    # postgres binary dir
pg_packages:
  - postgresql${pg_version}*
  - postgis31_${pg_version}*
  - pgbouncer patroni pg_exporter pgbadger
  - patroni patroni-consul patroni-etcd pgbouncer pgbadger pg_activity
  - python3 python3-psycopg2 python36-requests python3-etcd python3-consul
  - python36-urllib3 python36-idna python36-pyOpenSSL python36-cryptography

pg_extensions:
  - pg_repack${pg_version} pg_qualstats${pg_version} pg_stat_kcache${pg_version} wal2json${pg_version}
  # - ogr_fdw${pg_version} mysql_fdw_${pg_version} redis_fdw_${pg_version} mongo_fdw${pg_version} hdfs_fdw_${pg_version}
  # - count_distinct${version}  ddlx_${version}  geoip${version}  orafce${version}                                   # popular features
  # - hypopg_${version}  ip4r${version}  jsquery_${version}  logerrors_${version}  periods_${version}  pg_auto_failover_${version}  pg_catcheck${version}
  # - pg_fkpart${version}  pg_jobmon${version}  pg_partman${version}  pg_prioritize_${version}  pg_track_settings${version}  pgaudit15_${version}
  # - pgcryptokey${version}  pgexportdoc${version}  pgimportdoc${version}  pgmemcache-${version}  pgmp${version}  pgq-${version}  pgquarrel pgrouting_${version}
  # - pguint${version}  pguri${version}  prefix${version}   safeupdate_${version}  semver${version}   table_version${version}  tdigest${version}


参数详解

pg_dbsu

数据库默认使用的操作系统用户(超级用户)的用户名称,默认为postgres,不建议修改。

pg_dbsu_uid

数据库默认使用的操作系统用户(超级用户)的UID,默认为26

与CentOS下PostgreSQL官方RPM包的配置一致,不建议修改。

pg_dbsu_sudo

数据库超级用户的默认权限:

  • none:没有sudo权限
  • limit:有限的sudo权限,可以执行数据库相关组件的systemctl命令,默认
  • all:带有完整sudo权限,但需要密码。
  • nopass:不需要密码的完整sudo权限(不建议)

pg_dbsu_home

数据库超级用户的家目录,默认为/var/lib/pgsql

pg_dbsu_ssh_exchange

是否在执行的机器之间交换超级用户的SSH公私钥

pg_version

希望安装的PostgreSQL版本,默认为13

建议在集群级别按需覆盖此变量。

pgdg_repo

标记,是否使用PostgreSQL官方源?默认不使用

使用该选项,可以在没有本地源的情况下,直接从互联网官方源下载安装PostgreSQL相关软件包。

pg_add_repo

如果使用,则会在安装PostgreSQL前添加PGDG的官方源

启用此选项,则可以在未执行基础设施初始化的前提下直接执行数据库初始化,尽管可能会很慢,但对于缺少基础设施的场景尤为实用。

pg_bin_dir

PostgreSQL二进制目录

默认为/usr/pgsql/bin/,这是一个安装过程中手动创建的软连接,指向安装的具体Postgres版本目录。

例如/usr/pgsql -> /usr/pgsql-13

pg_packages

默认安装的PostgreSQL软件包

软件包中的${pg_version}会被替换为实际安装的PostgreSQL版本。

pg_extensions

需要安装的PostgreSQL扩展插件软件包

软件包中的${pg_version}会被替换为实际安装的PostgreSQL版本。

默认安装的插件包括:

pg_repack${pg_version}
pg_qualstats${pg_version}
pg_stat_kcache${pg_version}
wal2json${pg_version}

按需启用,但强烈建议安装pg_repack扩展。

9 - PG Provision

Parameters about how to pull up new clusters and assign identity to entities

PG供给,是在一台安装完Postgres的机器上,创建并拉起一套数据库的过程,包括:

  • 集群身份定义,清理现有实例,创建目录结构,拷贝工具与脚本,配置环境变量
  • 渲染Patroni模板配置文件,使用Patroni拉起主库,使用Patroni拉起从库
  • 配置Pgbouncer,初始化业务用户与数据库,将数据库与数据源服务注册至DCS。

参数概览

名称 类型 层级 说明
pg_cluster string C PG数据库集群名称身份参数
pg_seq number I PG数据库实例序号身份参数
pg_role enum I PG数据库实例角色身份参数
pg_shard string C PG数据库分片集簇名身份参数
pg_sindex number C PG数据库分片集簇号身份参数
pg_hostname bool G/C 将PG实例名称设为HOSTNAME
pg_nodename bool G/C 将PG实例名称设为Consul节点名
pg_exists bool A 标记位,PG是否已存在
pg_exists_action enum G/A PG存在时如何处理
pg_disable_purge enum G/C/I 禁止清除存在的PG实例
pg_data string G PG数据目录
pg_fs_main string G PG主数据盘挂载点
pg_fs_bkup path G PG备份盘挂载点
pg_listen ip G PG监听的IP地址
pg_port number G PG监听的端口
pg_localhost string G/C PG使用的UnixSocket地址
patroni_mode enum G/C Patroni配置模式
pg_namespace string G/C Patroni使用的DCS命名空间
patroni_port string G/C Patroni服务端口
patroni_watchdog_mode enum G/C Patroni Watchdog模式
pg_conf enum G/C Patroni使用的配置模板
pg_encoding string G/C PG字符集编码
pg_locale enum G/C PG使用的本地化规则
pg_lc_collate enum G/C PG使用的本地化排序规则
pg_lc_ctype enum G/C PG使用的本地化字符集定义
pgbouncer_port number G/C Pgbouncer端口
pgbouncer_poolmode enum G/C Pgbouncer池化模式
pgbouncer_max_db_conn number G/C Pgbouncer最大单DB连接数

默认参数

#------------------------------------------------------------------------------
# POSTGRES PROVISION
#------------------------------------------------------------------------------
# - identity - #
# pg_cluster:                                 # [REQUIRED] cluster name (validated during pg_preflight)
# pg_seq: 0                                   # [REQUIRED] instance seq (validated during pg_preflight)
# pg_role: replica                            # [REQUIRED] service role (validated during pg_preflight)
pg_hostname: false                            # overwrite node hostname with pg instance name
pg_nodename: true                             # overwrite consul nodename with pg instance name

# - retention - #
# pg_exists_action, available options: abort|clean|skip
#  - abort: abort entire play's execution (default)
#  - clean: remove existing cluster (dangerous)
#  - skip: end current play for this host
# pg_exists: false                            # auxiliary flag variable (DO NOT SET THIS)
pg_exists_action: clean
pg_disable_purge: false                       # set to true to disable pg purge functionality for good (force pg_exists_action = abort)

# - storage - #
pg_data: /pg/data                             # postgres data directory
pg_fs_main: /export                           # data disk mount point     /pg -> {{ pg_fs_main }}/postgres/{{ pg_instance }}
pg_fs_bkup: /var/backups                      # backup disk mount point   /pg/* -> {{ pg_fs_bkup }}/postgres/{{ pg_instance }}/*

# - connection - #
pg_listen: '0.0.0.0'                          # postgres listen address, '0.0.0.0' by default (all ipv4 addr)
pg_port: 5432                                 # postgres port (5432 by default)
pg_localhost: /var/run/postgresql             # localhost unix socket dir for connection

# - patroni - #
# patroni_mode, available options: default|pause|remove
#   - default: default ha mode
#   - pause:   into maintenance mode
#   - remove:  remove patroni after bootstrap
patroni_mode: default                         # pause|default|remove
pg_namespace: /pg                             # top level key namespace in dcs
patroni_port: 8008                            # default patroni port
patroni_watchdog_mode: automatic              # watchdog mode: off|automatic|required
pg_conf: tiny.yml                             # user provided patroni config template path

# - localization - #
pg_encoding: UTF8                             # default to UTF8
pg_locale: C                                  # default to C
pg_lc_collate: C                              # default to C
pg_lc_ctype: en_US.UTF8                       # default to en_US.UTF8

# - pgbouncer - #
pgbouncer_port: 6432                          # pgbouncer port (6432 by default)
pgbouncer_poolmode: transaction               # pooling mode: (transaction pooling by default)
pgbouncer_max_db_conn: 100                    # important! do not set this larger than postgres max conn or conn limit

身份参数

名称 类型 层级 说明
pg_cluster string C PG数据库集群名称
pg_seq number I PG数据库实例序号
pg_role enum I PG数据库实例角色
pg_shard string C PG数据库分片集簇名 (可选)
pg_sindex number C PG数据库分片集簇号 (可选)

pg_clusterpg_rolepg_seq 属于 身份参数

除了IP地址外,这三个参数是定义一套新的数据库集群的最小必须参数集,如下面的配置所示。

其他参数都可以继承自全局配置或默认配置,但身份参数必须显式指定手工分配

  • pg_cluster 标识了集群的名称,在集群层面进行配置。
  • pg_role 在实例层面进行配置,标识了实例的角色,只有primary角色会进行特殊处理,如果不填,默认为replica角色,此外,还有特殊的delayedoffline角色。
  • pg_seq 用于在集群内标识实例,通常采用从0或1开始递增的整数,一旦分配不再更改。
  • {{ pg_cluster }}-{{ pg_seq }} 被用于唯一标识实例,即pg_instance
  • {{ pg_cluster }}-{{ pg_role }} 用于标识集群内的服务,即pg_service
pg-test:
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: replica}
    10.10.10.12: {pg_seq: 2, pg_role: primary}
    10.10.10.13: {pg_seq: 3, pg_role: replica}
  vars:
    pg_cluster: pg-test

参数详解

pg_cluster

PG数据库集群的名称,将用作集群内资源的命名空间。

集群命名需要遵循特定命名规则:[a-z][a-z0-9-]*,以兼容不同约束对身份标识的要求。

身份参数,必填参数,集群级参数

pg_seq

数据库实例的序号,在集群内部唯一,用于区别与标识集群内的不同实例,从0或1开始分配。

身份参数,必填参数,实例级参数

pg_role

数据库实例的角色,默认角色包括:primary, replica

后续可选角色包括:offlinedelayed

身份参数,必填参数,实例级参数

pg_shard

只有分片集群需要设置此参数。

当多个数据库集群以水平分片的方式共同服务于同一个 业务时,Pigsty将这一组集群称为 分片集簇(Sharding Cluster)pg_shard是数据库集群所属分片集簇的名称,一个分片集簇可以指定任意名称,但Pigsty建议采用具有意义的命名规则。

例如参与分片集簇的集群,可以使用 分片集簇名 pg_shard + shard + 集群所属分片编号pg_sindex构成集群名称:

shard:  test
pg-testshard1
pg-testshard2
pg-testshard3
pg-testshard4

身份参数,可选参数,集群级参数

pg_sindex

集群在分片集簇中的编号,通常从0或1开始依次分配。

只有分片集群需要设置此参数。

身份参数,选填参数,集群级参数

pg_hostname

是否将PG实例的名称pg_instance 注册为主机名,默认禁用。

pg_nodename

是否将PG实例的名称注册为Consul中的节点名称,默认启用。

pg_exists

PG实例是否存在的标记位,不可配置。

pg_exists_action

安全保险,当PostgreSQL实例已经存在时,系统应当执行的动作

  • abort: 中止整个剧本的执行(默认行为)
  • clean: 抹除现有实例并继续(极端危险)
  • skip: 忽略存在实例的目标(中止),在其他目标机器上继续执行。

如果您真的需要强制清除已经存在的数据库实例,建议先使用pgsql-rm.yml完成集群与实例的下线与销毁,在重新执行初始化。否则,则需要通过命令行参数-e pg_exists_action=clean完成覆写,强制在初始化过程中抹除已有实例。

pg_disable_purge

双重安全保险,默认为false。如果为true,强制设置pg_exists_action变量为abort

等效于关闭pg_exists_action的清理功能,确保任何情况下Postgres实例都不会被抹除。

这意味着您需要通过专用下线脚本pgsql-rm.yml来完成已有实例的清理,然后才可以在清理干净的节点上重新完成数据库的初始化。

pg_data

默认数据目录,默认为/pg/data

pg_fs_main

主数据盘目录,默认为/export

Pigsty的默认目录结构假设系统中存在一个主数据盘挂载点,用于盛放数据库目录。

pg_fs_bkup

归档与备份盘目录,默认为/var/backups

Pigsty的默认目录结构假设系统中存在一个备份数据盘挂载点,用于盛放备份与归档数据。备份盘并不是必选项,如果系统中不存在备份盘,用户也可以指定一个主数据盘上的子目录作为备份盘根目录挂载点。

pg_listen

数据库监听的IP地址,默认为所有IPv4地址0.0.0.0,如果要包括所有IPv6地址,可以使用*

pg_port

数据库监听的端口,默认端口为5432,不建议修改。

pg_localhost

Unix Socket目录,用于盛放PostgreSQL与Pgbouncer的Unix socket文件。

默认为/var/run/postgresql

patroni_mode

Patroni的工作模式:

  • default: 启用Patroni
  • pause: 启用Patroni,但在完成初始化后自动进入维护模式(不自动执行主从切换)
  • remove: 依然使用Patroni初始化集群,但初始化完成后移除Patroni

pg_namespace

Patroni在DCS中使用的KV存储顶层命名空间

默认为pg

patroni_port

Patroni API服务器默认监听的端口

默认端口为8008

patroni_watchdog_mode

当发生主从切换时,Patroni会尝试在提升从库前关闭主库。如果指定超时时间内主库仍未成功关闭,Patroni会根据配置使用Linux内核功能softdog进行fencing关机。

  • off:不使用watchdog
  • automatic:如果内核启用了softdog,则启用watchdog,不强制,默认行为。
  • required:强制使用watchdog,如果系统未启用softdog则拒绝启动。

pg_conf

拉起Postgres集群所用的Patroni模板。Pigsty预制了4种模板

  • oltp.yml 常规OLTP模板,默认配置
  • olap.yml OLAP模板,提高并行度,针对吞吐量优化,针对长时间运行的查询进行优化。
  • crit.yml) 核心业务模板,基于OLTP模板针对安全性,数据完整性进行优化,采用同步复制,强制启用数据校验和。
  • tiny.yml 微型数据库模板,针对低资源场景进行优化,例如运行于虚拟机中的演示数据库集群。

pg_encoding

PostgreSQL实例初始化时,使用的字符集编码。

默认为UTF8,如果没有特殊需求,不建议修改此参数。

pg_locale

PostgreSQL实例初始化时,使用的本地化规则。

默认为C,如果没有特殊需求,不建议修改此参数。

pg_lc_collate

PostgreSQL实例初始化时,使用的本地化字符串排序规则。

默认为C,如果没有特殊需求,强烈不建议修改此参数。用户总是可以通过COLLATE表达式实现本地化排序相关功能,错误的本地化排序规则可能导致某些操作产生成倍的性能损失,请在真的有本地化需求的情况下修改此参数。

pg_lc_ctype

PostgreSQL实例初始化时,使用的本地化字符集定义

默认为en_US.UTF8,因为一些PG扩展(pg_trgm)需要额外的字符分类定义才可以针对国际化字符正常工作,因此Pigsty默认会使用en_US.UTF8字符集定义,不建议修改此参数。

pgbouncer_port

Pgbouncer连接池默认监听的端口

默认为6432

pgbouncer_poolmode

Pgbouncer连接池默认使用的Pool模式

默认为transaction,即事务级连接池。其他可选项包括:session|statemente

pgbouncer_max_db_conn

允许连接池与单个数据库之间建立的最大连接数

默认值为100

使用事务Pooling模式时,活跃服务端连接数通常处于个位数。如果采用会话Pooling,可以适当增大此参数。

10 - PG Template

Parameters about customize template and other database content.

PG Provision负责拉起一套全新的Postgres集群,而PG Template负责在PG Provision的基础上,在这套全新的数据库集群中创建默认的对象,包括

  • 基本角色:只读角色,读写角色、管理角色
  • 基本用户:复制用户、超级用户、监控用户、管理用户
  • 模板数据库中的默认权限
  • 默认 模式
  • 默认 扩展
  • HBA黑白名单规则

关于定制数据库集群的更多信息,请参考 定制集群

参数概览

名称 类型 层级 说明
pg_init string G/C 自定义PG初始化脚本
pg_replication_username string G PG复制用户
pg_replication_password string G PG复制用户的密码
pg_monitor_username string G PG监控用户
pg_monitor_password string G PG监控用户密码
pg_admin_username string G PG管理用户
pg_admin_password string G PG管理用户密码
pg_default_roles role[] G 默认创建的角色与用户
pg_default_privilegs string[] G 数据库默认权限配置
pg_default_schemas string[] G 默认创建的模式
pg_default_extensions extension[] G 默认安装的扩展
pg_offline_query string I 是否允许离线查询
pg_reload bool A 是否重载数据库配置(HBA)
pg_hba_rules rule[] G 全局HBA规则
pg_hba_rules_extra rule[] C/I 集群/实例特定的HBA规则
pgbouncer_hba_rules rule[] G/C Pgbouncer全局HBA规则
pgbouncer_hba_rules_extra rule[] G/C Pgbounce特定HBA规则
pg_databases database[] C 业务数据库定义
pg_users user[] C 业务用户定义

默认参数

#------------------------------------------------------------------------------
# POSTGRES TEMPLATE
#------------------------------------------------------------------------------
# - template - #
pg_init: pg-init                              # init script for cluster template

# - system roles - #
pg_replication_username: replicator           # system replication user
pg_replication_password: DBUser.Replicator    # system replication password
pg_monitor_username: dbuser_monitor           # system monitor user
pg_monitor_password: DBUser.Monitor           # system monitor password
pg_admin_username: dbuser_admin               # system admin user
pg_admin_password: DBUser.Admin               # system admin password

# - default roles - #
# chekc http://pigsty.cc/zh/docs/concepts/provision/acl/ for more detail
pg_default_roles:

  # common production readonly user
  - name: dbrole_readonly                 # production read-only roles
    login: false
    comment: role for global readonly access

  # common production read-write user
  - name: dbrole_readwrite                # production read-write roles
    login: false
    roles: [dbrole_readonly]             # read-write includes read-only access
    comment: role for global read-write access

  # offline have same privileges as readonly, but with limited hba access on offline instance only
  # for the purpose of running slow queries, interactive queries and perform ETL tasks
  - name: dbrole_offline
    login: false
    comment: role for restricted read-only access (offline instance)

  # admin have the privileges to issue DDL changes
  - name: dbrole_admin
    login: false
    bypassrls: true
    comment: role for object creation
    roles: [dbrole_readwrite,pg_monitor,pg_signal_backend]

  # dbsu, name is designated by `pg_dbsu`. It's not recommend to set password for dbsu
  - name: postgres
    superuser: true
    comment: system superuser

  # default replication user, name is designated by `pg_replication_username`, and password is set by `pg_replication_password`
  - name: replicator
    replication: true
    roles: [pg_monitor, dbrole_readonly]
    comment: system replicator

  # default replication user, name is designated by `pg_monitor_username`, and password is set by `pg_monitor_password`
  - name: dbuser_monitor
    connlimit: 16
    comment: system monitor user
    roles: [pg_monitor, dbrole_readonly]

  # default admin user, name is designated by `pg_admin_username`, and password is set by `pg_admin_password`
  - name: dbuser_admin
    bypassrls: true
    comment: system admin user
    roles: [dbrole_admin]

  # default stats user, for ETL and slow queries
  - name: dbuser_stats
    password: DBUser.Stats
    comment: business offline user for offline queries and ETL
    roles: [dbrole_offline]


# - privileges - #
# object created by dbsu and admin will have their privileges properly set
pg_default_privileges:
  - GRANT USAGE                         ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT                        ON TABLES    TO dbrole_readonly
  - GRANT SELECT                        ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE                       ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE                         ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT                        ON TABLES    TO dbrole_offline
  - GRANT SELECT                        ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE                       ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT, UPDATE, DELETE        ON TABLES    TO dbrole_readwrite
  - GRANT USAGE,  UPDATE                ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE, REFERENCES, TRIGGER ON TABLES    TO dbrole_admin
  - GRANT CREATE                        ON SCHEMAS   TO dbrole_admin

# - schemas - #
pg_default_schemas: [monitor]                 # default schemas to be created

# - extension - #
pg_default_extensions:                        # default extensions to be created
  - { name: 'pg_stat_statements',  schema: 'monitor' }
  - { name: 'pgstattuple',         schema: 'monitor' }
  - { name: 'pg_qualstats',        schema: 'monitor' }
  - { name: 'pg_buffercache',      schema: 'monitor' }
  - { name: 'pageinspect',         schema: 'monitor' }
  - { name: 'pg_prewarm',          schema: 'monitor' }
  - { name: 'pg_visibility',       schema: 'monitor' }
  - { name: 'pg_freespacemap',     schema: 'monitor' }
  - { name: 'pg_repack',           schema: 'monitor' }
  - name: postgres_fdw
  - name: file_fdw
  - name: btree_gist
  - name: btree_gin
  - name: pg_trgm
  - name: intagg
  - name: intarray

# - hba - #
pg_offline_query: false                       # set to true to enable offline query on instance
pg_hba_rules:                                 # postgres host-based authentication rules
  - title: allow meta node password access
    role: common
    rules:
      - host    all     all                         10.10.10.10/32      md5

  - title: allow intranet admin password access
    role: common
    rules:
      - host    all     +dbrole_admin               10.0.0.0/8          md5
      - host    all     +dbrole_admin               172.16.0.0/12       md5
      - host    all     +dbrole_admin               192.168.0.0/16      md5

  - title: allow intranet password access
    role: common
    rules:
      - host    all             all                 10.0.0.0/8          md5
      - host    all             all                 172.16.0.0/12       md5
      - host    all             all                 192.168.0.0/16      md5

  - title: allow local read/write (local production user via pgbouncer)
    role: common
    rules:
      - local   all     +dbrole_readonly                                md5
      - host    all     +dbrole_readonly           127.0.0.1/32         md5

  - title: allow offline query (ETL,SAGA,Interactive) on offline instance
    role: offline
    rules:
      - host    all     +dbrole_offline               10.0.0.0/8        md5
      - host    all     +dbrole_offline               172.16.0.0/12     md5
      - host    all     +dbrole_offline               192.168.0.0/16    md5

pg_hba_rules_extra: []                        # extra hba rules (for cluster/instance overwrite)

pgbouncer_hba_rules:                          # pgbouncer host-based authentication rules
  - title: local password access
    role: common
    rules:
      - local  all          all                                     md5
      - host   all          all                     127.0.0.1/32    md5

  - title: intranet password access
    role: common
    rules:
      - host   all          all                     10.0.0.0/8      md5
      - host   all          all                     172.16.0.0/12   md5
      - host   all          all                     192.168.0.0/16  md5

pgbouncer_hba_rules_extra: []                 # extra pgbouncer hba rules (for cluster/instance overwrite)

参数详解

pg_init

用于初始化数据库模板的Shell脚本位置,默认为pg-init,该脚本会被拷贝至/pg/bin/pg-init后执行。

默认的pg-init 只是预渲染SQL命令的包装:

# system default roles
psql postgres -qAXwtf /pg/tmp/pg-init-roles.sql

# system default template
psql template1 -qAXwtf /pg/tmp/pg-init-template.sql

# make postgres same as templated database (optional)
psql postgres  -qAXwtf /pg/tmp/pg-init-template.sql

用户可以在自定义的pg-init脚本中添加自己的集群初始化逻辑。

pg_replication_username

用于执行PostgreSQL流复制的数据库用户名

默认为replicator

pg_replication_password

用于执行PostgreSQL流复制的数据库用户密码,必须使用明文

默认为DBUser.Replicator,强烈建议修改!

pg_monitor_username

用于执行PostgreSQL与Pgbouncer监控任务的数据库用户名

默认为dbuser_monitor

pg_monitor_password

用于执行PostgreSQL与Pgbouncer监控任务的数据库用户密码,必须使用明文

默认为DBUser.Monitor,强烈建议修改!

pg_admin_username

用于执行PostgreSQL数据库管理任务(DDL变更)的数据库用户名

默认为dbuser_admin

pg_admin_password

用于执行PostgreSQL数据库管理任务(DDL变更)的数据库用户密码,必须使用明文

默认为DBUser.Admin,强烈建议修改!

pg_default_roles

定义了PostgreSQL中默认的角色与用户,形式为对象数组,每一个对象定义一个用户或角色。

每一个用户或角色必须指定 name ,其余字段均为可选项。

  • password是可选项,如果留空则不设置密码,可以使用MD5密文密码。

  • login, superuser, createdb, createrole, inherit, replication, bypassrls 都是布尔类型,用于设置用户属性。如果不设置,则采用系统默认值。

  • 用户通过CREATE USER创建,所以默认具有login属性,如果创建的是角色,需要指定login: false

  • expire_atexpire_in用于控制用户过期时间,expire_at使用形如YYYY-mm-DD的日期时间戳。expire_in使用从现在开始的过期天数,如果expire_in存在则会覆盖expire_at选项。

  • 新用户默认不会添加至Pgbouncer用户列表中,必须显式定义pgbouncer: true,该用户才会被加入到Pgbouncer用户列表。

  • 用户/角色会按顺序创建,后面定义的用户可以属于前面定义的角色。

pg_users:
  # complete example of user/role definition for production user
  - name: dbuser_meta               # example production user have read-write access
    password: DBUser.Meta           # example user's password, can be encrypted
    login: true                     # can login, true by default (should be false for role)
    superuser: false                # is superuser? false by default
    createdb: false                 # can create database? false by default
    createrole: false               # can create role? false by default
    inherit: true                   # can this role use inherited privileges?
    replication: false              # can this role do replication? false by default
    bypassrls: false                # can this role bypass row level security? false by default
    connlimit: -1                   # connection limit, -1 disable limit
    expire_at: '2030-12-31'         # 'timestamp' when this role is expired
    expire_in: 365                  # now + n days when this role is expired (OVERWRITE expire_at)
    roles: [dbrole_readwrite]       # dborole_admin|dbrole_readwrite|dbrole_readonly|dbrole_offline
    pgbouncer: true                 # add this user to pgbouncer? false by default (true for production user)
    parameters:                     # user's default search path
      search_path: public
    comment: test user

Pigsty定义了由四个默认角色与四个默认用户组成的基本访问控制系统,详细信息请参考 访问控制

pg_default_privileges

定义数据库模板中的默认权限。

任何由{{ dbsu」}}{{ pg_admin_username }}创建的对象都会具有以下默认权限:

pg_default_privileges:
  - GRANT USAGE                         ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT                        ON TABLES    TO dbrole_readonly
  - GRANT SELECT                        ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE                       ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE                         ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT                        ON TABLES    TO dbrole_offline
  - GRANT SELECT                        ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE                       ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT, UPDATE, DELETE        ON TABLES    TO dbrole_readwrite
  - GRANT USAGE,  UPDATE                ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE, REFERENCES, TRIGGER ON TABLES    TO dbrole_admin
  - GRANT CREATE                        ON SCHEMAS   TO dbrole_admin

详细信息请参考 访问控制

pg_default_schemas

创建于模版数据库的默认模式

Pigsty默认会创建名为monitor的模式用于安装监控扩展。

pg_default_schemas: [monitor]                 # default schemas to be created

pg_default_extensions

默认安装于模板数据库的扩展,对象数组。

如果没有指定schema字段,扩展会根据当前的search_path安装至对应模式中。

pg_default_extensions:
  - { name: 'pg_stat_statements',  schema: 'monitor' }
  - { name: 'pgstattuple',         schema: 'monitor' }
  - { name: 'pg_qualstats',        schema: 'monitor' }
  - { name: 'pg_buffercache',      schema: 'monitor' }
  - { name: 'pageinspect',         schema: 'monitor' }
  - { name: 'pg_prewarm',          schema: 'monitor' }
  - { name: 'pg_visibility',       schema: 'monitor' }
  - { name: 'pg_freespacemap',     schema: 'monitor' }
  - { name: 'pg_repack',           schema: 'monitor' }
  - name: postgres_fdw
  - name: file_fdw
  - name: btree_gist
  - name: btree_gin
  - name: pg_trgm
  - name: intagg
  - name: intarray

pg_offline_query

实例级变量,布尔类型,默认为false

设置为true时,无论当前实例的角色为何,用户组dbrole_offline都可以连接至该实例并执行离线查询。

对于实例数量较少(例如一主一从)的情况较为实用,用户可以将唯一的从库标记为pg_offline_query = true,从而接受ETL,慢查询与交互式访问。详细信息请参考 访问控制-离线用户

pg_reload

命令行参数,布尔类型,默认为true

设置为true时,Pigsty会在生成HBA规则后立刻执行pg_ctl reload应用。

当您希望生成pg_hba.conf文件,并手工比较后再应用生效时,可以指定-e pg_reload=false来禁用它。

pg_hba_rules

设置数据库的客户端IP黑白名单规则。对象数组,每一个对象都代表一条规则。

每一条规则由三部分组成:

  • title,规则标题,会转换为HBA文件中的注释
  • role,应用角色,common代表应用至所有实例,其他取值(如replica, offline)则仅会安装至匹配的角色上。例如role='replica'代表这条规则只会应用到pg_role == 'replica' 的实例上。
  • rules,字符串数组,每一条记录代表一条最终写入pg_hba.conf的规则。

作为一个特例,role == 'offline' 的HBA规则,还会额外安装至 pg_offline_query == true 的实例上。

pg_hba_rules:
  - title: allow meta node password access
    role: common
    rules:
      - host    all     all                         10.10.10.10/32      md5

  - title: allow intranet admin password access
    role: common
    rules:
      - host    all     +dbrole_admin               10.0.0.0/8          md5
      - host    all     +dbrole_admin               172.16.0.0/12       md5
      - host    all     +dbrole_admin               192.168.0.0/16      md5

  - title: allow intranet password access
    role: common
    rules:
      - host    all             all                 10.0.0.0/8          md5
      - host    all             all                 172.16.0.0/12       md5
      - host    all             all                 192.168.0.0/16      md5

  - title: allow local read-write access (local production user via pgbouncer)
    role: common
    rules:
      - local   all     +dbrole_readwrite                               md5
      - host    all     +dbrole_readwrite           127.0.0.1/32        md5

  - title: allow read-only user (stats, personal) password directly access
    role: replica
    rules:
      - local   all     +dbrole_readonly                               md5
      - host    all     +dbrole_readonly           127.0.0.1/32        md5

建议在全局配置统一的pg_hba_rules,针对特定集群使用pg_hba_rules_extra进行额外定制。

pg_hba_rules_extra

pg_hba_rules类似,但通常用于集群层面的HBA规则设置。

pg_hba_rules_extra 会以同样的方式 追加pg_hba.conf中。

如果用户需要彻底覆写集群的HBA规则,即不想继承全局HBA配置,则应当在集群层面配置pg_hba_rules并覆盖全局配置。

pgbouncer_hba_rules

pg_hba_rules类似,用于Pgbouncer的HBA规则设置。

默认的Pgbouncer HBA规则很简单,用户可以按照自己的需求进行定制。

默认的Pgbouncer HBA规则较为宽松:

  1. 允许从本地使用密码登陆
  2. 允许从内网网断使用密码登陆
pgbouncer_hba_rules:
  - title: local password access
    role: common
    rules:
      - local  all          all                                     md5
      - host   all          all                     127.0.0.1/32    md5

  - title: intranet password access
    role: common
    rules:
      - host   all          all                     10.0.0.0/8      md5
      - host   all          all                     172.16.0.0/12   md5
      - host   all          all                     192.168.0.0/16  md5

pgbouncer_hba_rules_extra

pg_hba_rules_extras类似,用于在集群层次对Pgbouncer的HBA规则进行额外配置。

业务模板

以下两个参数属于业务模板,用户应当在这里定义所需的业务用户与业务数据库。

在这里定义的用户与数据库,会在以下两个步骤中完成应用,不仅仅包括数据库中的用户与DB,还有Pgbouncer连接池中的对应配置。

./pgsql.yml --tags=pg_biz_init,pg_biz_pgbouncer

pg_users

通常用于在数据库集群层面定义业务用户,与 pg_default_roles 采用相同的形式。

对象数组,每个对象定义一个业务用户。用户名name字段为必选项,密码可以使用MD5密文密码

用户可以通过roles字段为业务用户添加默认权限组:

  • dbrole_readonly:默认生产只读用户,具有全局只读权限。(只读生产访问)
  • dbrole_offline:默认离线只读用户,在特定实例上具有只读权限。(离线查询,个人账号,ETL)
  • dbrole_readwrite:默认生产读写用户,具有全局CRUD权限。(常规生产使用)
  • dbrole_admin:默认生产管理用户,具有执行DDL变更的权限。(管理员)

应当为生产账号配置 pgbouncer: true,允许其通过连接池访问,普通用户不应当通过连接池访问数据库。

下面是一个创建业务账号的例子:

pg_users:
  # complete example of user/role definition for production user
  - name: dbuser_meta               # example production user have read-write access
    password: DBUser.Meta           # example user's password, can be encrypted
    login: true                     # can login, true by default (should be false for role)
    superuser: false                # is superuser? false by default
    createdb: false                 # can create database? false by default
    createrole: false               # can create role? false by default
    inherit: true                   # can this role use inherited privileges?
    replication: false              # can this role do replication? false by default
    bypassrls: false                # can this role bypass row level security? false by default
    connlimit: -1                   # connection limit, -1 disable limit
    expire_at: '2030-12-31'         # 'timestamp' when this role is expired
    expire_in: 365                  # now + n days when this role is expired (OVERWRITE expire_at)
    roles: [dbrole_readwrite]       # dborole_admin|dbrole_readwrite|dbrole_readonly
    pgbouncer: true                 # add this user to pgbouncer? false by default (true for production user)
    parameters:                     # user's default search path
      search_path: public
    comment: test user

  # simple example for personal user definition
  - name: dbuser_vonng2              # personal user example which only have limited access to offline instance
    password: DBUser.Vonng          # or instance with explict mark `pg_offline_query = true`
    roles: [dbrole_offline]         # personal/stats/ETL user should be grant with dbrole_offline
    expire_in: 365                  # expire in 365 days since creation
    pgbouncer: false                # personal user should NOT be allowed to login with pgbouncer
    comment: example personal user for interactive queries

pg_databases

对象数组,每个对象定义一个业务数据库。每个数据库定义中,数据库名称 name 为必选项,其余均为可选项。

  • name:数据库名称,必选项
  • owner:数据库属主,默认为postgres
  • template:数据库创建时使用的模板,默认为template1
  • encoding:数据库默认字符编码,默认为UTF8,默认与实例保持一致。建议不要配置与修改。
  • locale:数据库默认的本地化规则,默认为C,建议不要配置,与实例保持一致。
  • lc_collate:数据库默认的本地化字符串排序规则,默认与实例设置相同,建议不要修改,必须与模板数据库一致。强烈建议不要配置,或配置为C
  • lc_ctype:数据库默认的LOCALE,默认与实例设置相同,建议不要修改或设置,必须与模板数据库一致。建议配置为C或en_US.UTF8
  • allowconn:是否允许连接至数据库,默认为true,不建议修改。
  • revokeconn:是否回收连接至数据库的权限?默认为false。如果为true,则数据库上的PUBLIC CONNECT权限会被回收。只有默认用户(dbsu|monitor|admin|replicator|owner)可以连接。此外,admin|owner 会拥有GRANT OPTION,可以赋予其他用户连接权限。
  • tablespace:数据库关联的表空间,默认为pg_default
  • connlimit:数据库连接数限制,默认为-1,即没有限制。
  • extensions:对象数组 ,每一个对象定义了一个数据库中的扩展,以及其安装的模式
  • parameters:KV对象,每一个KV定义了一个需要针对数据库通过ALTER DATABASE修改的参数。
  • pgbouncer:布尔选项,是否将该数据库加入到Pgbouncer中。所有数据库都会加入至Pgbouncer,除非显式指定pgbouncer: false
  • comment:数据库备注信息。
pg_databases:
  - name: meta                      # name is the only required field for a database
    owner: postgres                 # optional, database owner
    template: template1             # optional, template1 by default
    encoding: UTF8                  # optional, UTF8 by default
    locale: C                       # optional, C by default
    lc_collate: C                   # optional, C by default , must same as template database, leave blank to set to db default
    lc_ctype: C                     # optional, C by default , must same as template database, leave blank to set to db default
    allowconn: true                 # optional, true by default, false disable connect at all
    revokeconn: false               # optional, false by default, true revoke connect from public # (only default user and owner have connect privilege on database)
    tablespace: pg_default          # optional, 'pg_default' is the default tablespace
    connlimit: -1                   # optional, connection limit, -1 or none disable limit (default)
    extensions:                     # optional, extension name and where to create
      - {name: postgis, schema: public}
    parameters:                     # optional, extra parameters with ALTER DATABASE
      enable_partitionwise_join: true
    pgbouncer: true                 # optional, add this database to pgbouncer list? true by default
    comment: pigsty meta database   # optional, comment string for database

11 - Monitor

Parameters about monitoring components

Pigsty的监控系统包含两个组件:Node Exporter , PG Exporter

Node Exporter用于暴露机器节点的监控指标,PG Exporter用于拉取数据库与Pgbouncer连接池的监控指标;此外,Haproxy将直接通过管理端口对外暴露监控指标。

默认情况下,所有监控Exporter都会被注册至Consul,Prometheus会通过服务发现的方式管理这些任务。但用户可以通过配置 prometheus_sd_methodstatic 改用静态服务发现,通过配置文件的方式管理所有Exporter。监控已有数据库实例时,建议采用这种方式。

参数概览

名称 类型 层级 说明
exporter_install enum G/C 安装监控组件的方式
exporter_repo_url string G/C 监控组件的YumRepo
exporter_metrics_path string G/C 监控暴露的URL Path
node_exporter_enabled bool G/C 启用节点指标收集器
node_exporter_port number G/C 节点指标暴露端口
node_exporter_options string G/C 节点指标采集选项
pg_exporter_config string G/C PG指标定义文件
pg_exporter_enabled bool G/C 启用PG指标收集器
pg_exporter_port number G/C PG指标暴露端口
pg_exporter_url string G/C 采集对象数据库的连接串(覆盖)
pgbouncer_exporter_enabled bool G/C 启用PGB指标收集器
pgbouncer_exporter_port number G/C PGB指标暴露端口
pgbouncer_exporter_url string G/C 采集对象连接池的连接串

默认参数

#------------------------------------------------------------------------------
# MONITOR PROVISION
#------------------------------------------------------------------------------
# - install - #
exporter_install: none                        # none|yum|binary, none by default
exporter_repo_url: ''                         # if set, repo will be added to /etc/yum.repos.d/ before yum installation

# - collect - #
exporter_metrics_path: /metrics               # default metric path for pg related exporter

# - node exporter - #
node_exporter_enabled: true                   # setup node_exporter on instance
node_exporter_port: 9100                      # default port for node exporter
node_exporter_options: '--no-collector.softnet --collector.systemd --collector.ntp --collector.tcpstat --collector.processes'

# - pg exporter - #
pg_exporter_config: pg_exporter-demo.yaml     # default config files for pg_exporter
pg_exporter_enabled: true                     # setup pg_exporter on instance
pg_exporter_port: 9630                        # default port for pg exporter
pg_exporter_url: ''                           # optional, if not set, generate from reference parameters

# - pgbouncer exporter - #
pgbouncer_exporter_enabled: true              # setup pgbouncer_exporter on instance (if you don't have pgbouncer, disable it)
pgbouncer_exporter_port: 9631                 # default port for pgbouncer exporter
pgbouncer_exporter_url: ''                    # optional, if not set, generate from reference parameters

参数详解

exporter_install

指明安装Exporter的方式:

  • none:不安装,(默认行为,Exporter已经在先前由 node.pkgs 任务完成安装)
  • yum:使用yum安装(如果启用yum安装,在部署Exporter前执行yum安装 node_exporterpg_exporter
  • binary:使用拷贝二进制的方式安装(从files中直接拷贝node_exporterpg_exporter 二进制)

使用yum安装时,如果指定了exporter_repo_url(不为空),在执行安装时会首先将该URL下的REPO文件安装至/etc/yum.repos.d中。这一功能可以在不执行节点基础设施初始化的环境下直接进行Exporter的安装。

使用binary安装时,用户需要确保已经将 node_exporterpg_exporter 的Linux二进制程序放置在files目录中。

<meta>:<pigsty>/files/node_exporter ->  <target>:/usr/bin/node_exporter
<meta>:<pigsty>/files/pg_exporter   ->  <target>:/usr/bin/pg_exporter

exporter_binary_install(弃用)

该参数已被expoter_install 参数覆盖

是否采用复制二进制文件的方式安装Node Exporter与PG Exporter,默认为false

该选项主要用于集成外部供给方案时,减少对原有系统的工作假设。启用该选项将直接将Linux二进制文件复制至目标机器。

<meta>:<pigsty>/files/node_exporter ->  <target>:/usr/bin/node_exporter
<meta>:<pigsty>/files/pg_exporter   ->  <target>:/usr/bin/pg_exporter

用户需要通过files/download-exporter.sh从Github下载Linux二进制程序至files目录,方可启用该选项。

exporter_metrics_path

所有Exporter对外暴露指标的URL PATH,默认为/metrics

该变量被外部角色prometheus引用,Prometheus会根据这里的配置,针对job = pg的监控对象应用此配置。

node_exporter_enabled

是否安装并配置node_exporter,默认为true

node_exporter_port

node_exporter监听的端口

默认端口9100

node_exporter_options

node_exporter 使用的额外命令行选项。

该选项主要用于定制 node_exporter 启用的指标收集器,Node Exporter支持的收集器列表可以参考:Node Exporter Collectors

该选项的默认值为:

node_exporter_options: '--no-collector.softnet --collector.systemd --collector.ntp --collector.tcpstat --collector.processes'

pg_exporter_config

pg_exporter使用的默认配置文件,定义了Pigsty中的指标。

Pigsty默认提供了两个配置文件:

  • pg_exporter-demo.yaml 用于沙箱演示环境,缓存TTL更低(1s),监控实时性更好,但性能冲击更大。

  • pg_exporter.yaml,用于生产环境,有着正常的缓存TTL(10s),显著降低多个Prometheus同时抓取的负载。

如果用户采用了不同的Prometheus架构,建议对pg_exporter的配置文件进行检查与调整。

Pigsty使用的PG Exporter配置文件默认从PostgreSQL 10.0 开始提供支持,目前支持至最新的PG 13版本

pg_exporter_enabled

是否安装并配置pg_exporter,默认为true

pg_exporter_url

PG Exporter用于连接至数据库的PGURL

可选参数,默认为空字符串。

Pigsty默认使用以下规则生成监控的目标URL,如果配置了pg_exporter_url选项,则会直接使用该URL作为连接串。

PG_EXPORTER_URL='postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@:{{ pg_port }}/{{ pg_default_database }}?host={{ pg_localhost }}&sslmode=disable'

该选项以环境变量的方式配置于 /etc/default/pg_exporter 中。

pgbouncer_exporter_enabled

是否安装并配置pgbouncer_exporter,默认为true

pg_exporter_port

pg_exporter监听的端口

默认端口9630

pgbouncer_exporter_port

pgbouncer_exporter监听的端口

默认端口9631

pgbouncer_exporter_url

PGBouncer Exporter用于连接至数据库的URL

可选参数,默认为空字符串。

Pigsty默认使用以下规则生成监控的目标URL,如果配置了pgbouncer_exporter_url选项,则会直接使用该URL作为连接串。

PG_EXPORTER_URL='postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@:{{ pgbouncer_port }}/pgbouncer?host={{ pg_localhost }}&sslmode=disable'

该选项以环境变量的方式配置于 /etc/default/pgbouncer_exporter 中。

12 - Service Provision

Parameters about exposing cluster’s service

服务(Service),是数据库集群对外提供功能的形式。通常来说,一个数据库集群至少应当提供两种服务:

  • 读写服务(primary) :用户可以写入数据库
  • 只读服务(replica) :用户可以访问只读副本

此外,根据具体的业务场景,可能还会有其他的服务:

  • 离线从库服务(offline):不承接线上只读流量的专用从库,用于ETL与个人用户查询。
  • 同步从库服务(standby) :采用同步提交,没有复制延迟的只读服务。
  • 延迟从库服务(delayed) : 允许业务访问固定时间间隔之前的旧数据。
  • 默认直连服务(default) : 允许(管理)用户绕过连接池直接管理数据库的服务

参数概览

名称 类型 层级 说明
pg_weight number I 实例在负载均衡中的相对权重
pg_services service[] G 全局通用服务定义
pg_services_extra service[] C 集群专有服务定义
haproxy_enabled bool G/C/I 是否启用Haproxy
haproxy_reload bool A 是否重载Haproxy配置
haproxy_admin_auth_enabled bool G/C 是否对Haproxy管理界面启用认证
haproxy_admin_username string G/C HAproxy管理员名称
haproxy_admin_password string G/C HAproxy管理员密码
haproxy_exporter_port number G/C HAproxy指标暴露器端口
haproxy_client_timeout interval G/C HAproxy客户端超时
haproxy_server_timeout interval G/C HAproxy服务端超时
vip_mode enum G/C VIP模式:none
vip_reload bool G/C 是否重载VIP配置
vip_address string G/C 集群使用的VIP地址
vip_cidrmask number G/C VIP地址的网络CIDR掩码
vip_interface string G/C VIP使用的网卡

默认参数

#------------------------------------------------------------------------------
# SERVICE PROVISION
#------------------------------------------------------------------------------
pg_weight: 100              # default load balance weight (instance level)

# - service - #
pg_services:                                  # how to expose postgres service in cluster?
  # primary service will route {ip|name}:5433 to primary pgbouncer (5433->6432 rw)
  - name: primary           # service name {{ pg_cluster }}_primary
    src_ip: "*"
    src_port: 5433
    dst_port: pgbouncer     # 5433 route to pgbouncer
    check_url: /primary     # primary health check, success when instance is primary
    selector: "[]"          # select all instance as primary service candidate

  # replica service will route {ip|name}:5434 to replica pgbouncer (5434->6432 ro)
  - name: replica           # service name {{ pg_cluster }}_replica
    src_ip: "*"
    src_port: 5434
    dst_port: pgbouncer
    check_url: /read-only   # read-only health check. (including primary)
    selector: "[]"          # select all instance as replica service candidate
    selector_backup: "[? pg_role == `primary`]"   # primary are used as backup server in replica service

  # default service will route {ip|name}:5436 to primary postgres (5436->5432 primary)
  - name: default           # service's actual name is {{ pg_cluster }}-{{ service.name }}
    src_ip: "*"             # service bind ip address, * for all, vip for cluster virtual ip address
    src_port: 5436          # bind port, mandatory
    dst_port: postgres      # target port: postgres|pgbouncer|port_number , pgbouncer(6432) by default
    check_method: http      # health check method: only http is available for now
    check_port: patroni     # health check port:  patroni|pg_exporter|port_number , patroni by default
    check_url: /primary     # health check url path, / as default
    check_code: 200         # health check http code, 200 as default
    selector: "[]"          # instance selector
    haproxy:                # haproxy specific fields
      maxconn: 3000         # default front-end connection
      balance: roundrobin   # load balance algorithm (roundrobin by default)
      default_server_options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

  # offline service will route {ip|name}:5438 to offline postgres (5438->5432 offline)
  - name: offline           # service name {{ pg_cluster }}_replica
    src_ip: "*"
    src_port: 5438
    dst_port: postgres
    check_url: /replica     # offline MUST be a replica
    selector: "[? pg_role == `offline` || pg_offline_query ]"         # instances with pg_role == 'offline' or instance marked with 'pg_offline_query == true'
    selector_backup: "[? pg_role == `replica` && !pg_offline_query]"  # replica are used as backup server in offline service

pg_services_extra: []        # extra services to be added

# - haproxy - #
haproxy_enabled: true                         # enable haproxy among every cluster members
haproxy_reload: true                          # reload haproxy after config
haproxy_admin_auth_enabled: false             # enable authentication for haproxy admin?
haproxy_admin_username: admin                 # default haproxy admin username
haproxy_admin_password: admin                 # default haproxy admin password
haproxy_exporter_port: 9101                   # default admin/exporter port
haproxy_client_timeout: 3h                    # client side connection timeout
haproxy_server_timeout: 3h                    # server side connection timeout

# - vip - #
vip_mode: none                                # none | l2 | l4
vip_reload: true                ·              # whether reload service after config
# vip_address: 127.0.0.1                      # virtual ip address ip (l2 or l4)
# vip_cidrmask: 24                            # virtual ip address cidr mask (l2 only)
# vip_interface: eth0                         # virtual ip network interface (l2 only)

参数详解

pg_weight

当执行负载均衡时,数据库实例的相对权重。默认为100

pg_services

由服务定义对象构成的数组,定义了每一个数据库集群中对外暴露的服务。

每一个集群都可以定义多个服务,每个服务包含任意数量的集群成员,服务通过端口进行区分。

每一个服务的定义结构如下例所示:

- name: default           # service's actual name is {{ pg_cluster }}-{{ service.name }}
  src_ip: "*"             # service bind ip address, * for all, vip for cluster virtual ip address
  src_port: 5436          # bind port, mandatory
  dst_port: postgres      # target port: postgres|pgbouncer|port_number , pgbouncer(6432) by default
  check_method: http      # health check method: only http is available for now
  check_port: patroni     # health check port:  patroni|pg_exporter|port_number , patroni by default
  check_url: /primary     # health check url path, / as default
  check_code: 200         # health check http code, 200 as default
  selector: "[]"          # instance selector
  haproxy:                # haproxy specific fields
    maxconn: 3000         # default front-end connection
    balance: roundrobin   # load balance algorithm (roundrobin by default)
    default_server_options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

必选项目

  • 名称(service.name

    服务名称,服务的完整名称以数据库集群名为前缀,以service.name为后缀,通过-连接。例如在pg-test集群中name=primary的服务,其完整服务名称为pg-test-primary

  • 端口(service.port

    在Pigsty中,服务默认采用NodePort的形式对外暴露,因此暴露端口为必选项。但如果使用外部负载均衡服务接入方案,您也可以通过其他的方式区分服务。

  • 选择器(service.selector

    选择器指定了服务的实例成员,采用JMESPath的形式,从所有集群实例成员中筛选变量。默认的[]选择器会选取所有的集群成员。

可选项目

  • 备份选择器(service.selector

    可选的 备份选择器service.selector_backup会选择或标记用于服务备份的实例列表,即集群中所有其他成员失效时,备份实例才接管服务。例如可以将primary实例加入replica服务的备选集中,当所有从库失效后主库依然可以承载集群的只读流量。

  • 源端IP(service.src_ip

    表示服务对外使用的IP地址,默认为*,即本机所有IP地址。使用vip则会使用vip_address变量取值,或者也可以填入网卡支持的特定IP地址。

  • 宿端口(service.dst_port

    服务的流量将指向目标实例上的哪个端口?postgres 会指向数据库监听的端口,pgbouncer会指向连接池所监听的端口,也可以填入固定的端口号。

  • 健康检查方式(service.check_method:

    服务如何检查实例的健康状态?目前仅支持HTTP

  • 健康检查端口(service.check_port:

    服务检查实例的哪个端口获取实例的健康状态? patroni会从Patroni(默认8008)获取,pg_exporter会从PG Exporter(默认9630)获取,用户也可以填入自定义的端口号。

  • 健康检查路径(service.check_url:

    服务执行HTTP检查时,使用的URL PATH。默认会使用/作为健康检查,PG Exporter与Patroni提供了多样的健康检查方式,可以用于主从流量区分。例如,/primary仅会对主库返回成功,/replica仅会对从库返回成功。/read-only则会对任何支持只读的实例(包括主库)返回成功。

  • 健康检查代码(service.check_code:

    HTTP健康检查所期待的代码,默认为200

  • Haproxy特定配置(service.haproxy

    关于服务供应软件(HAproxy)的专有配置项

pg_services_extra

由服务定义对象构成的数组,在集群层面定义,追加至全局的服务定义中。

如果用户希望为某一个数据库集群创建特殊的服务,例如单独为某一套带有延迟从库的集群创建特殊的服务,则可以使用本配置项。

haproxy_enabled

是否启用Haproxy组件

Pigsty默认会在所有数据库节点上部署Haproxy,您可以通过覆盖实例级变量,仅在特定实例/节点上启用Haproxy负载均衡器。

haproxy_admin_auth_enabled

是否启用为Haproxy管理界面启用基本认证

默认不启用,建议在生产环境启用,或在Nginx或其他接入层添加访问控制。

haproxy_admin_username

启用Haproxy管理界面认证默认用户名,默认为admin

haproxy_admin_password

启用Haproxy管理界面认证默认密码,默认为admin

haproxy_client_timeout

Haproxy客户端连接超时,默认为3小时

haproxy_server_timeout

Haproxy服务端连接超时,默认为3小时

haproxy_exporter_port

Haproxy管理界面与监控指标暴露端点所监听的端口。

默认端口为9101

vip_mode

VIP的模式,枚举类型,可选值包括:

  • none:不设置VIP
  • l2:配置绑定在主库上的二层VIP(需要所有成员位于同一个二层网络广播域中)
  • l4 :通过外部L4负载均衡器进行流量分发。(未纳入Pigsty当前实现中)

VIP用于确保读写服务负载均衡器的高可用,当使用L2 VIP时,Pigsty的VIP由vip-manager托管,会绑定在集群主库上。

这意味着您始终可以通过VIP访问集群主库,或者通过VIP访问主库上的负载均衡器(如果主库的压力很大,这样做可能会有性能压力)。

注意,您必须保证VIP候选实例处于同一个二层网络(VLAN、交换机)下。

vip_address

VIP地址,可用于L2或L4 VIP。

vip_address没有默认值,用户必须为每一个集群显式指定并分配VIP地址

vip_cidrmask

VIP的CIDR网络长度,仅当使用L2 VIP时需要。

vip_cidrmask没有默认值,用户必须为每一个集群显式指定VIP的网络CIDR。

vip_interface

VIP网卡名称,仅当使用L2 VIP时需要。

默认为eth0,用户必须为每一个集群/实例指明VIP使用的网卡名称。

过时参数

这些参数现在定义于服务中,不再使用。

haproxy_policy

haproxy负载均衡所使用的算法,可选策略为roundrobinleastconn

默认为roundrobin

haproxy_check_port

Haproxy对后端PostgreSQL进程执行健康检查的端口。

默认端口为8008,即Patroni的端口。

其他的选项包括9630,即使用pg_exporter作为健康检查的端口。

haproxy_primary_port

Haproxy中集群读写服务默认端口,所有链接至该端口的客户端链接都会被转发至主实例的对应端口。

默认读写服务的端口为5433

haproxy_replica_port

Haproxy中集群只读服务默认端口,所有链接至该端口的客户端链接都会被转发至主从例的对应端口。

默认读写服务的端口为5434

haproxy_backend_port

Haproxy将客户端连接转发至后端的对应端口,可选:5432/6432

默认为6432,即Haproxy会将流量转发至6432连接池端口,修改为5432表示直接将流量转发至数据库。

haproxy_weight

Haproxy进行负载均衡时的标准权重,默认为100,建议在实例层次进行覆盖。

haproxy_weight_fallback

用于控制主库承载只读流量的权重。

如果haproxy_weight_fallback为0,主库不会承担任何只读流量(发送至haproxy_replica_port)。

如果haproxy_weight_fallback为1(或更高的值时),在集群正常工作时,主库会在从库服务集中承担 1/总权重 的微小流量,而当从库集中所有的只读实例故障时,只读流量可以漂移至主库承载。

该配置对于一主一从的情况非常实用,如果您有多台从库,建议将其配置为0。