配置文件

Pigsty采用声明式配置:用户配置描述状态,而Pigsty负责将真实组件调整至所期待的状态。

配置Pigsty

Pigsty采用声明式配置:用户配置描述状态,而Pigsty负责将真实组件调整至所期待的状态。

Pigsty通过配置清单(Inventory)来定义基础设施与数据库集群,每一套Pigsty部署都有一份对应的配置:无论是几百集群的生产环境,还是1核1GB的本地沙箱,在Pigsty中除了配置内容外没有任何区别。Pigsty的配置采用"Infra as Data"的哲学:用户通过声明式的配置描述自己的需求,而Pigsty负责将真实组件调整至所期待的状态。

在形式上,配置清单的具体实现可以是默认的本地配置文件,也可以是来自CMDB中的动态配置数据,本文介绍时均以默认YAML配置文件pigsty.yml 为例。在 配置过程 中,Pigsty会检测当前节点环境,并自动生成推荐的配置文件。

配置清单的内容主要是配置项,Pigsty提供了220个配置参数,可以在多个层次进行配置,大多数参数可以直接使用默认值。配置项按照类目可以分为四大类:INFRA/基础设施NODES/主机节点PGSQL/PG数据库REDIS/Redis数据库,并可进一步细分为32个小类。


配置过程

进入 Pigsty 项目目录执行 configure,Pigsty会检测根据当前机器环境生成推荐配置文件,这一过程称作 配置 / Configure

./configure [-n|--non-interactive] [-d|--download] [-i|--ip <ipaddr>] [-m|--mode {auto|demo}]

configure会检查下列事项,小问题会自动尝试修复,否则提示报错退出。

check_kernel     # kernel        = Linux
check_machine    # machine       = x86_64
check_release    # release       = CentOS 7.x
check_sudo       # current_user  = NOPASSWD sudo
check_ssh        # current_user  = NOPASSWD ssh
check_ipaddr     # primary_ip (arg|probe|input)              (INTERACTIVE: ask for ip)
check_admin      # check current_user@primary_ip nopass ssh sudo
check_mode       # check machine spec to determine node mode (tiny|oltp|olap|crit)
check_config     # generate config according to primary_ip and mode
check_pkg        # check offline installation package exists (INTERACTIVE: ask for download)
check_repo       # create repo from pkg.tgz if exists
check_repo_file  # create local file repo file if repo exists
check_utils      # check ansible sshpass and other utils installed

直接运行 ./configure 将启动交互式命令行向导,提示用户回答以下三个问题:

IP地址

当检测到当前机器上有多块网卡与多个IP地址时,配置向导会提示您输入主要使用的IP地址, 即您用于从内部网络访问该节点时使用的IP地址。注意请不要使用公网IP地址。

下载软件包

当节点的/tmp/pkg.tgz路径下未找到离线软件包时,配置向导会询问是否从Github下载。 选择Y即会开始下载,选择N则会跳过。如果您的节点有良好的互联网访问与合适的代理配置,或者需要自行制作离线软件包,可以选择N

配置模板

使用什么样的配置文件模板。 配置向导会根据当前机器环境自动选择配置模板,因此不会询问用户这个问题,用户通常也无需关心。 但用户总是可以通过命令行参数-m <mode>手工指定想要使用的配置模板,例如:

  • demo 项目默认配置文件,4节点沙箱使用的配置文件,启用全部功能。
  • auto 在生产环境中部署时推荐的配置文件模板,配置更加稳定保守。
  • 此外Pigsty预置了几种配置模板,可以直接通过-m参数指定并使用,详见files/conf目录

configure过程中,配置向导会根据当前机器环境自动选择配置模板,但用户可以通过-m <mode>手工指定使用配置模板。配置模板最重要的部分是将模板中占位IP地址10.10.10.10替换为当前机器的真实IP地址(内网主IP),并根据当前机器的配置选择合适的数据库规格模板。您可以直接使用默认生成的配置文件,或基于自动生成的配置文件进行进一步的定制与修改。

配置过程的标准输出
$ ./configure
configure pigsty v1.5.1 begin
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] release = 7.8.2003 , perfect
[ OK ] sudo = root ok
[ OK ] ssh = root@127.0.0.1 ok
[ OK ] primary_ip = 10.10.10.10  (from probe)
[ OK ] admin = root@10.10.10.10 ok
[ OK ] spec = mini (cpu = 2)
[ OK ] config = auto @ 10.10.10.10
[ OK ] cache = /tmp/pkg.tgz exists
[ OK ] repo = /www/pigsty ok
[ OK ] repo file = /etc/yum.repos.d/pigsty-local.repo
[ OK ] utils = install from local file repo
[ OK ] ansible = ansible 2.9.27
configure pigsty done. Use 'make install' to proceed

配置文件

Pigsty项目根目录下有一个具体的配置文件样例:pigsty.yml

配置文件顶层是一个keyall的单个对象,包含两个子项目:varschildren

all:                      # 顶层对象 all
  vars: <123 keys>        # 全局配置 all.vars

  children:               # 分组定义:all.children 每一个项目定义了一个数据库集群 
    meta: <2 keys>...     # 特殊分组 meta ,定义了环境元节点
    
    pg-meta: <2 keys>...  # 数据库集群 pg-meta 的详细定义
    pg-test: <2 keys>...  # 数据库集群 pg-test 的详细定义
    ...

vars的内容为KV键值对,定义了全局配置参数,K为配置项名称,V为配置项内容。

children 的内容也是KV结构,K为集群名称,V为具体的集群定义,一个样例集群的定义如下所示:

  • 集群定义同样包括两个子项目:vars定义了集群层面的配置。hosts定义了集群的实例成员。
  • 集群配置中的参数会覆盖全局配置中的对应参数,而集群的配置参数又会被实例级别的同名配置参数所覆盖。集群配置参数中,唯pg_cluster为必选项,这是集群的名称,须与上层集群名保持一致。
  • hosts中采用KV的方式定义集群实例成员,K为IP地址(须ssh可达),V为具体的实例配置参数
  • 实例配置参数中有两个必须参数:pg_seq,与 pg_role,分别为实例的唯一序号和实例的角色。
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配置文件遵循Ansible规则,采用YAML格式,默认使用单一配置文件。Pigsty的默认配置文件路径为Pigsty源代码根目录下的 pigsty.yml 。默认配置文件是在同目录下的ansible.cfg通过inventory = pigsty.yml指定的。您可以在执行任何剧本时,通过-i <config_path>参数指定其他的配置文件。

配置文件需要与Ansible 配合使用。Ansible是一个流行的DevOps工具,但普通用户无需了解Ansible的具体细节。如果您精通Ansible,则可以根据Ansible的清单组织规则自行调整配置文件的组织与结构:例如,使用分立式的配置文件,为每个集群设置单独的群组定义与变量定义文件。

您并不需要精通Ansible,用几分钟时间浏览Ansible快速上手,便足以开始使用Ansible执行剧本。

配置项

配置项的形式为键值对:键是配置项的名称,值是配置项的内容。值的形式各异,可能是简单的单个字符串,也可能是复杂的对象数组。

Pigsty的参数可以在不同的层次进行配置,并依据规则继承与覆盖,高优先级的配置项会覆盖低优先级的同名配置项。因此用户可以有的放矢,可以在不同层次,不同粒度上针对具体集群与具体实例进行精细配置。

配置项的层次

在Pigsty的配置文件中,配置项 可以出现在三种位置,全局集群实例集群vars中定义的配置项会以同名键覆盖的方式覆盖全局配置项实例中定义的配置项又会覆盖集群配置项与全局配置项。

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

并非所有配置项都适合在所有层次使用。例如,基础设施的参数通常只会在全局配置中定义,数据库实例的标号,角色,负载均衡权重等参数只能在实例层次配置,而一些操作选项则只能使用命令行参数提供(例如要创建的数据库名称),关于配置项的详情与适用范围,请参考配置项清单

兜底与覆盖

除了配置文件中的三种配置粒度,Pigsty配置项目中还有两种额外的优先级层次:默认值兜底与命令行参数强制覆盖:

  • 默认:当一个配置项在全局/集群/实例级别都没有出现时,将使用默认配置项。默认值的优先级最低,所有配置项都有默认值。默认参数定义于roles/<role>/default/main.yml中。
  • 参数:当用户通过命令行传入参数时,参数指定的配置项具有最高优先级,将覆盖一切层次的配置。一些配置项只能通过命令行参数的方式指定与使用。
层级 来源 优先级 说明 位置
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

配置类目

Pigsty包含了220个固定配置项,分为四个部分:INFRA, NODES, PGSQL, REDIS,共计32类。

通常只有节点/数据库身份参数是必选参数,其他配置参数可直接使用默认值,按需修改。

Category Section Description Count
INFRA CONNECT 连接参数 1
INFRA REPO 本地源基础设施 10
INFRA CA 公私钥基础设施 5
INFRA NGINX NginxWeb服务器 5
INFRA NAMESERVER DNS服务器 1
INFRA PROMETHEUS 监控时序数据库 7
INFRA EXPORTER 通用Exporter配置 3
INFRA GRAFANA Grafana可视化平台 9
INFRA LOKI Loki日志收集平台 5
INFRA DCS 分布式配置存储元数据库 8
NODES NODE_IDENTITY 节点身份参数 5
NODES NODE_DNS 节点域名解析 5
NODES NODE_REPO 节点软件源 3
NODES NODE_PACKAGES 节点软件包 4
NODES NODE_FEATURES 节点功能特性 6
NODES NODE_MODULES 节点内核模块 1
NODES NODE_TUNE 节点参数调优 2
NODES NODE_ADMIN 节点管理员 6
NODES NODE_TIME 节点时区与时间同步 4
NODES NODE_EXPORTER 节点指标暴露器 3
NODES PROMTAIL 日志收集组件 5
PGSQL PG_IDENTITY PGSQL数据库身份参数 13
PGSQL PG_BUSINESS PGSQL业务对象定义 11
PGSQL PG_INSTALL PGSQL安装 11
PGSQL PG_BOOTSTRAP PGSQL集群初始化 24
PGSQL PG_PROVISION PGSQL集群模板置备 9
PGSQL PG_EXPORTER PGSQL指标暴露器 13
PGSQL PG_SERVICE PGSQL服务接入 16
REDIS REDIS_IDENTITY REDIS身份参数 3
REDIS REDIS_PROVISION REDIS集群置备 14
REDIS REDIS_EXPORTER REDIS指标暴露器 3

最后修改 2022-06-18: v1.5.1 (8de4142)