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个大类。
配置项粒度
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 |
配置项列表
3 - Connect
parameters about connection info and proxy settings
参数概览
参数详解
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 }}
目录整个打成压缩包。
参数概览
默认参数
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中关于机器与操作系统、基础设施的配置参数
参数概览
默认配置
#------------------------------------------------------------------------------
# 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
配置为add
或overwrite
,则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
配置为add
或overwrite
,则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
通过yum安装的额外软件包列表。
与node_packages
类似,但node_packages
通常是全局统一配置,而node_extra_packages
则是针对具体节点进行例外处理。例如,您可以为运行PG的节点安装额外的工具包。该变量通常在集群和实例级别进行覆盖定义。
Pigsty默认安装的额外软件包列表如下:
- patroni,patroni-consul,patroni-etcd,pgbouncer,pgbadger,pg_activity
通过yum安装的元节点软件包列表。
与node_packages
和node_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
这一节定义了部署于元节点上的 基础设施 ,包括:
参数概览
默认参数
#------------------------------------------------------------------------------
# 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集群。
参数概览
默认参数
#------------------------------------------------------------------------------
# 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类型,有两种选项:
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
指定需要安装的软件版本,并在集群层面进行覆盖,为不同的集群安装不同的数据库版本。
参数概览
默认参数
#------------------------------------------------------------------------------
# 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。
参数概览
默认参数
#------------------------------------------------------------------------------
# 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
,pg_role
,pg_seq
属于 身份参数
除了IP地址外,这三个参数是定义一套新的数据库集群的最小必须参数集,如下面的配置所示。
其他参数都可以继承自全局配置或默认配置,但身份参数必须显式指定,手工分配。
pg_cluster
标识了集群的名称,在集群层面进行配置。
pg_role
在实例层面进行配置,标识了实例的角色,只有primary
角色会进行特殊处理,如果不填,默认为replica
角色,此外,还有特殊的delayed
与offline
角色。
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
。
后续可选角色包括:offline
与delayed
。
身份参数,必填参数,实例级参数
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黑白名单规则
关于定制数据库集群的更多信息,请参考 定制集群
参数概览
默认参数
#------------------------------------------------------------------------------
# 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_at
与expire_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
类似,但通常用于集群层面的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规则较为宽松:
- 允许从本地使用密码登陆
- 允许从内网网断使用密码登陆
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
与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_method
为 static
改用静态服务发现,通过配置文件的方式管理所有Exporter。监控已有数据库实例时,建议采用这种方式。
参数概览
默认参数
#------------------------------------------------------------------------------
# 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_exporter
与 pg_exporter
)
binary
:使用拷贝二进制的方式安装(从files
中直接拷贝node_exporter
与 pg_exporter
二进制)
使用yum
安装时,如果指定了exporter_repo_url
(不为空),在执行安装时会首先将该URL下的REPO文件安装至/etc/yum.repos.d
中。这一功能可以在不执行节点基础设施初始化的环境下直接进行Exporter的安装。
使用binary
安装时,用户需要确保已经将 node_exporter
与 pg_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默认提供了两个配置文件:
如果用户采用了不同的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) : 允许(管理)用户绕过连接池直接管理数据库的服务
参数概览
默认参数
#------------------------------------------------------------------------------
# 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)的专有配置项
由服务定义对象构成的数组,在集群层面定义,追加至全局的服务定义中。
如果用户希望为某一个数据库集群创建特殊的服务,例如单独为某一套带有延迟从库的集群创建特殊的服务,则可以使用本配置项。
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负载均衡所使用的算法,可选策略为roundrobin
与leastconn
默认为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。