Info

Important information about Pigsty configuration file

Pigsty uses YAML configuration file that follows the Ansible rules.

Usage

Pigsty’s configuration file is located in ./pigsty.yml by default, and the configuration file needs to be used with Ansible.

You can specify the default configuration file path in the current directory at ansible.cfg. Or you can manually specify a custom configuration file path by means of -i conf/your-config.yml when executing the script on the command line. Please refer to the section Execute script for details.

Structure

The top-level structure of the YAML configuration file is shown here, an outermost all object, where all.children defines the database clusters in the environment. And all.vars defines the global configuration variables in the entire environment.

---
# top-level namespace, match all hosts
all:
  #==================================================================#
  #                           Clusters                               #
  #==================================================================#
  # top-level groups, one group per database cluster (and special group 'meta')
  children:

    #-----------------------------
    # meta controller
    #-----------------------------
    meta: <2 keys>

    #-----------------------------
    # cluster: pg-meta
    #-----------------------------
    pg-meta: <2 keys>

    #-----------------------------
    # cluster: pg-test
    #-----------------------------
    pg-test: <2 keys>

  #==================================================================#
  #                           Globals                                #
  #==================================================================#
  vars: <123 keys>
...

Cluster Definition

Drill down to a specific cluster for example, all.children.pg-test, is the definition section for a single database cluster.

Here hosts defines the members of the database cluster, including sequence number (pg_seq), role (pg_role), and ansible connection method (optional)

Here ansible_host instructs ansible to connect to remote nodes via SSH Alias, rather than IP direct access, which is useful for machines that need a springboard proxy.

The variables defined in vars inside the cluster override the global variables, so you can target different configurations and customizations for different clusters.

#-----------------------------
# cluster: pg-test
#-----------------------------
pg-test: # define cluster named 'pg-test'
  # - cluster members - #
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: primary, ansible_host: node-1}
    10.10.10.12: {pg_seq: 2, pg_role: replica, ansible_host: node-2}
    10.10.10.13: {pg_seq: 3, pg_role: replica, ansible_host: node-3}

  # - cluster configs - #
  vars:
    # basic settings
    pg_cluster: pg-test                 # define actual cluster name
    pg_version: 13                      # define installed pgsql version
    node_tune: tiny                     # tune node into oltp|olap|crit|tiny mode
    pg_conf: tiny.yml                   # tune pgsql into oltp/olap/crit/tiny mode

    pg_users:
      - username: test
        password: test
        comment: default test user
        groups: [ dbrole_readwrite ]    # dborole_admin|dbrole_readwrite|dbrole_readonly
    pg_databases:                       # create a business database 'test'
      - name: test
        extensions: [{name: postgis}]   # create extra extension postgis
        parameters:                     # overwrite database meta's default search_path
          search_path: public,monitor
    pg_default_database: test           # default database will be used as primary monitor target

    # proxy settings
    vip_enabled: true                   # enable/disable vip (require members in same LAN)
    vip_address: 10.10.10.3             # virtual ip address
    vip_cidrmask: 8                     # cidr network mask length
    vip_interface: eth1                 # interface to add virtual ip

Precedence

Variables in Pigsty follow Ansible’s merge rules, and all variables are eventually merged overwritten in order of priority, eventually flattening to the host level. See [Ansible variable priorities](https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i- put-a-variable)

  1. command line values (for example, -u my_user, these are not variables)
  2. role defaults (defined in role/defaults/main.yml) 1
  3. inventory file or script group vars 2
  4. inventory group_vars/all 3
  5. playbook group_vars/all 3
  6. inventory group_vars/* 3
  7. playbook group_vars/* 3
  8. inventory file or script host vars 2
  9. inventory host_vars/* 3
  10. playbook host_vars/* 3
  11. host facts / cached set_facts 4
  12. play vars
  13. play vars_prompt
  14. play vars_files
  15. role vars (defined in role/vars/main.yml)
  16. block vars (only for tasks in block)
  17. task vars (only for the task)
  18. include_vars
  19. set_facts / registered vars
  20. role (and include_role) params
  21. include params
  22. extra vars (for example, -e "user=my_user")(always win precedence)

There are three variable levels in config files

  • group_vars/all

    Global variable, defined in all.vars

    Sets parameters (such as infrastructure information) that are uniform across the environment, with the lowest priority.

  • group_vars/*

    Cluster variable, defined in all.children.<cluster-name>.vars

    Used to set specific configurations for a cluster, such as the cluster name.

  • host_vars/*

    Instance variable, defined in all.children.<cluster-name>.hosts.<host-name>

    Used to set instance-specific configuration, such as the instance label.

You can override the options in the configuration file with the -e command line argument when executing the script, e.g.

./pgsql.yml -e pg_exists_action=clean

Here -e pg_exists_action=clean will then override the option in the configuration file to force the wiping of already existing database instances during initialization (very dangerous).

Configuration items (variables)

Pigsty comes with many configuration item variables, divided into 10 sections

详细列表如下：

#------------------------------------------------------------------------------
# CONNECTION PARAMETERS
#------------------------------------------------------------------------------
proxy_env
#------------------------------------------------------------------------------
# REPO PROVISION
#------------------------------------------------------------------------------
repo_enabled
repo_name
repo_address
repo_port
repo_home
repo_rebuild
repo_remove
repo_upstreams
repo_packages
repo_url_packages
#------------------------------------------------------------------------------
# NODE PROVISION
#------------------------------------------------------------------------------
node_dns_hosts
node_dns_server
node_dns_servers
node_dns_options
node_repo_method
node_repo_remove
node_local_repo_url
node_packages
node_extra_packages
node_meta_packages
node_disable_numa
node_disable_swap
node_disable_firewall
node_disable_selinux
node_static_network
node_disk_prefetch
node_kernel_modules
node_tune
node_sysctl_params
node_admin_setup
node_admin_uid
node_admin_username
node_admin_ssh_exchange
node_admin_pks
node_ntp_service
node_ntp_config
node_timezone
node_ntp_servers
#------------------------------------------------------------------------------
# META PROVISION
#------------------------------------------------------------------------------
ca_method
ca_subject
ca_homedir
ca_cert
ca_key
nginx_upstream
dns_records
prometheus_scrape_interval
prometheus_scrape_timeout
prometheus_metrics_path
prometheus_data_dir
prometheus_retention
grafana_url
grafana_admin_password
grafana_plugin
grafana_cache
grafana_customize
grafana_plugins
grafana_git_plugins
#------------------------------------------------------------------------------
# DCS PROVISION
#------------------------------------------------------------------------------
dcs_type
dcs_name
dcs_servers
dcs_exists_action
consul_data_dir
etcd_data_dir
#------------------------------------------------------------------------------
# POSTGRES INSTALLATION
#------------------------------------------------------------------------------
pg_dbsu
pg_dbsu_uid
pg_dbsu_sudo
pg_dbsu_home
pg_dbsu_ssh_exchange
pg_version
pgdg_repo
pg_add_repo
pg_bin_dir
pg_packages
pg_extensions
#------------------------------------------------------------------------------
# POSTGRES PROVISION
#------------------------------------------------------------------------------
pg_cluster         
pg_seq           
pg_role    
pg_hostname
pg_nodename
pg_exists
pg_exists_action
pg_data
pg_fs_main
pg_fs_bkup
pg_listen
pg_port
patroni_mode
pg_namespace
patroni_port
patroni_watchdog_mode
pg_conf
pgbouncer_port
pgbouncer_poolmode
pgbouncer_max_db_conn
#------------------------------------------------------------------------------
# POSTGRES TEMPLATE
#------------------------------------------------------------------------------
pg_init
pg_replication_username
pg_replication_password
pg_monitor_username
pg_monitor_password
pg_admin_username
pg_admin_password
pg_default_roles
pg_default_privilegs
pg_default_schemas
pg_default_extensions
pg_hba_rules
pg_hba_rules_extra
pgbouncer_hba_rules
pgbouncer_hba_rules_extra
#------------------------------------------------------------------------------
# MONITOR PROVISION
#------------------------------------------------------------------------------
pg_exporter_config
node_exporter_port
pg_exporter_port
pgbouncer_exporter_port
exporter_metrics_path
pg_localhost
#------------------------------------------------------------------------------
# PROXY PROVISION
#------------------------------------------------------------------------------
haproxy_enabled
haproxy_policy
haproxy_admin_auth_enabled
haproxy_admin_username
haproxy_admin_password
haproxy_client_timeout
haproxy_server_timeout
haproxy_exporter_port
haproxy_check_port
haproxy_primary_port
haproxy_replica_port
haproxy_backend_port
haproxy_weight
haproxy_weight_fallback
vip_enabled
vip_address
vip_cidrmask
vip_interface
Last modified 2021-02-08: update en deploy doc (c50b13b)