Skip to content

Configuration Reference

This page lists the configurations recognized by the pgEdge Ansible collection roles. Parameters are set as inventory variables or playbook variables and apply across roles unless noted otherwise.

Configurations

Cluster Identification Parameters

The following table describes parameters that identify the cluster and its nodes:

Parameter Default Description
cluster_name demo Canonical name for the cluster, used for descriptive items and generated values.
zone 1 Zone or region for a node. Zones also serve as Snowflake node IDs; each node must have a distinct integer value.

Repository Configuration Parameters

The following table describes parameters that control which software repository the collection uses:

Parameter Default Description
repo_name release Repository tier to use. Accepted values are release, staging, and daily.
repo_prefix (none) Custom or automated build prefix. Contact pgEdge staff for valid values.

Installation Parameters

The following table describes parameters that control software versions:

Parameter Default Description
pg_version 17 PostgreSQL version to install.
spock_version 5.0.4 Minimum version of the Spock extension to install. The latest available version is always installed.
tls_validity_days 3560 Validity period in days for TLS certificates generated by the collection.

Database Configuration Parameters

The following table describes parameters that control database creation and access:

Parameter Default Description
db_names [demo] List of database names for the Spock cluster. At least one name is required. Any database in the list that does not already exist will be created and owned by db_user.
db_user admin Database superuser username. Must differ from the OS user running the installation.
db_password secret Password for db_user.
pgedge_user pgedge Internal user for node-to-node Spock connections.
pgedge_password secret Password for pgedge_user.
custom_hba_rules [] List of additional pg_hba.conf rules to append to the default rule set. Each rule is a dictionary with contype, users, databases, method, and source fields.

High Availability Parameters

The following table describes parameters that control HA behavior. These parameters apply only when is_ha_cluster is true:

Parameter Default Description
is_ha_cluster false When true, the collection installs and configures etcd, Patroni, and HAProxy on the appropriate nodes.
patroni_dcs type: etcd3 Distributed configuration store Patroni uses for cluster state, given as a dictionary with a type key and a parameters key. Accepted types are etcd3, etcd, consul, zookeeper, and exhibitor. Etcd3 is the only DCS option managed by this collection. The parameters key is optional only for the etcd types, where the collection substitutes defaults for the cluster it deploys, and is required for every other type.
patroni_namespace /db/ Key prefix Patroni uses within the store. Change this per zone only when the prefix itself must differ, such as when the store grants access per prefix; otherwise vary patroni_scope.
patroni_scope {{ pg_version }}-{{ cluster_name }} Cluster name Patroni uses within the store, and the name patronictl reports. Give each zone its own scope when one store serves more than one zone, because the rest of the key is identical on every node.
replication_user replicator Username for Patroni streaming replication.
replication_password secret Password for replication_user.
synchronous_mode false When true, Patroni manages the synchronous_commit and synchronous_standby_names PostgreSQL parameters based on cluster state.
synchronous_mode_strict false When synchronous_mode is enabled, Patroni disables synchronous replication if no synchronous replicas are available. Set this to true to always enforce synchronous commit regardless of replica availability.
proxy_node (none) Overrides automatic HAProxy target selection for Spock subscriptions. When unset, subscriptions target the first HAProxy node in the same zone as the remote pgEdge node, or the first pgEdge node in that zone if no HAProxy node is present.
proxy_port 5432 Port used for Spock subscription connections. Set this to a value different from pg_port to run HAProxy on a pgEdge node rather than a dedicated host; init_server requires it there, since HAProxy cannot bind a port Postgres already holds.

The DCS Configuration document describes the accepted store types, the etcd defaults the collection substitutes, and the changes a playbook needs to use a store the collection does not manage.

HAProxy Parameters

The following table describes parameters that control HAProxy configuration:

Parameter Default Description
haproxy_extra_routes {replica: {port: 5433}} Additional HAProxy listeners corresponding to Patroni REST endpoint check types. Each entry requires a port sub-key and accepts an optional lag sub-key for maximum replica lag.
pooler_port 6432 Port the HAProxy node listens on for pooled connections, forwarding them to pgbouncer_port on the zone's current primary, exactly as proxy_port fronts pg_port. It is the client-facing half of the pair: clients connect here, not to pgbouncer_port. Nothing is emitted on this port unless pgbouncer_enabled is set.
haproxy_max_conn 100 (plus the pooled listener's ceiling where the cluster pools) HAProxy's global connection ceiling, which must cover the sum of the listeners' own.
haproxy_pooler_max_conn pgbouncer_max_client_conn on the zone's first node Connection ceiling for the pooled listener. Only the leader's pooler takes traffic, so this is one pooler's limit rather than the sum across pooled nodes.

Pooling Parameters

The following table describes parameters that control the pgBouncer connection pooler. They apply only where pgbouncer_enabled is set, which is a cluster-wide choice made on the pgedge group:

Parameter Default Description
pgbouncer_enabled false When true, every pgEdge node runs a pooler in front of its own PostgreSQL and serves a pooled endpoint on pgbouncer_port. Cluster-wide, like is_ha_cluster: init_server rejects an inventory whose pgEdge nodes disagree.
pgbouncer_package pgedge-pgbouncer Package install_pgbouncer installs. The collection requires pgBouncer 1.21 or later.
pgbouncer_port 6432 Port each pooled pgEdge node's own pooler listens on, behind pooler_port. Must differ from pg_port. Sharing its default with pooler_port is fine while HAProxy has a host to itself; the two must differ where HAProxy shares a host with pgBouncer. See The Port Model.
pgbouncer_listen_addr * Addresses the pooler binds.
pgbouncer_auth_user pgbouncer_auth PostgreSQL role the pooler logs in as to look up client credentials. Also the only account admitted to the pooler's admin console.
pgbouncer_auth_password secret Password for pgbouncer_auth_user. The only password written to disk, and init_server refuses to deploy a pooled cluster while it is unchanged.
pgbouncer_pool_mode session How much of a session the pooler reuses. Accepted values are session and transaction.
pgbouncer_max_client_conn 1000 Client connections the pooler accepts. Also sizes the pooler's file descriptor limit and the pooled HAProxy listener.
pgbouncer_default_pool_size 25 Backend connections per user and database pair.
pgbouncer_max_prepared_statements 0 Protocol-level prepared statements tracked per connection, which is what makes prepared statements usable in transaction mode.
pgbouncer_ignore_startup_parameters extra_float_digits Startup parameters the pooler accepts from a client and then discards rather than forwarding.
pgbouncer_client_tls_sslmode allow TLS policy on the pooled endpoint. Accepted values are disable, allow, prefer, and require.
pgbouncer_tls_cert_source tls/postgres/server.crt Controller-side certificate the pooled endpoint presents.
pgbouncer_tls_key_source tls/postgres/server.key Controller-side private key for that certificate.
pgbouncer_hba_rules [] Additional client authentication rules for the pooled endpoint only, in the same shape as custom_hba_rules.
pgbouncer_limit_nofile pgbouncer_max_client_conn * 2 + 1024 File descriptor limit in the pooler's systemd drop-in.

The Pooling Configuration document describes the authentication model, the client authentication rules the pooler enforces, and the rules it cannot.

Server Configuration Parameters

The following table describes parameters that control server-level behavior:

Parameter Default Description
pg_port 5432 Port on which PostgreSQL listens.
debug_pgedge true When true, configures kernel settings to retain core files produced during a process crash.
disable_selinux true When true, disables SELinux on RHEL-based nodes. A system reboot may be required for the change to take effect.
manage_host_file true When true, adds all cluster nodes to the /etc/hosts file on every node. Set to false when external DNS is in use or when inventory hostnames are IP addresses.

Backup Configuration Parameters

The following table describes parameters that control PgBackRest backup behavior:

Parameter Default Description
backup_host (none) Hostname of the dedicated backup server. When empty and backup_repo_type is ssh, the first node in the backup host group in the same zone is used.
backup_user backrest PostgreSQL user created for backup operations. This user is granted pg_checkpoint privileges.
backup_password secret Password for backup_user.
backup_repo_type ssh Backup repository type. Accepted values are ssh (dedicated backup server) and s3 (AWS S3 bucket).
backup_repo_user Ansible user OS user that owns the PgBackRest repository on the backup server in SSH mode.
backup_repo_path /home/backrest Path to the PgBackRest repository on the backup server.
backup_repo_cipher_type aes-256-cbc Encryption algorithm for backup files stored in the PgBackRest repository.
backup_repo_cipher (generated) Encryption password for backup files. When unset, a 20-character deterministic random string is generated from the repository name.
full_backup_count 1 Number of full backups to retain in the repository.
diff_backup_count 6 Number of differential backups to retain in the repository.
full_backup_schedule 10 0 * * 0 Cron schedule for full backups. The default runs every Sunday at 00:10 UTC.
diff_backup_schedule 10 0 * * 1-6 Cron schedule for differential backups. The default runs Monday through Saturday at 00:10 UTC.
backup_repo_params (see below) Dictionary of S3 repository parameters. Required when backup_repo_type is s3.

The backup_repo_params dictionary accepts the following keys with the defaults shown:

backup_repo_params:
  region: us-east-1
  endpoint: s3.amazonaws.com
  bucket: pgbackrest
  access_key: ''
  secret_key: ''

Spock Configuration Parameters

The following table describes parameters that control Spock logical replication behavior:

Parameter Default Description
exception_behaviour transdiscard How Spock handles replication exceptions. Accepted values are discard, transdiscard, and sub_disable. See the pgEdge exception documentation for details.

Path Override Parameters

The following parameters control PostgreSQL installation paths. The role_config role sets OS-specific defaults; override them only when your system uses non-standard locations.

Parameter Debian default RHEL default Description
pg_home /var/lib/postgresql /var/lib/pgsql Home directory for the postgres OS user.
pg_path /usr/lib/postgresql/VERSION /usr/pgsql-VERSION Path to PostgreSQL binaries.
pg_data pg_home/VERSION/main pg_home/VERSION/data Path to the PostgreSQL data directory.

Internal Variables

The following table describes variables computed by the role_config role. These variables are available for reference when modifying or extending the collection roles. The values differ by operating system family.

Variable Debian value RHEL value Description
pg_config_dir /etc/postgresql/VERSION/CLUSTER pg_data Path to the PostgreSQL configuration directory.
pg_service_name postgresql@VERSION-CLUSTER pgedge-postgres-VERSION Systemd service name for PostgreSQL.
patroni_service_name patroni@VERSION-CLUSTER patroni Systemd service name for Patroni.
nodes_in_zone (computed) (computed) List of all nodes in the pgedge host group that share the same zone as the current node.
cluster_is_pooled (computed) (computed) Whether pgbouncer_enabled is set for this cluster, read from the pgEdge nodes' own variables so that a proxy or backup host can answer it too.
pooled_nodes_in_zone (computed) (computed) Nodes the zone's pooled endpoint routes to: every node of the zone where the cluster pools, and an empty list where it does not.
pgbouncer_user postgres pgbouncer System user the pgBouncer service runs as. The Debian package creates no pgbouncer user.
pgbouncer_log_file /var/log/postgresql/pgbouncer.log /var/log/pgbouncer/pgbouncer.log Path to the pooler's log file. Each platform's own path, so the packaged logrotate rule already covers it.
pgbouncer_pid_file /var/run/postgresql/pgbouncer.pid /run/pgbouncer/pgbouncer.pid Path to the pooler's pid file.
pgbouncer_socket_dir /var/run/postgresql /run/pgbouncer Directory holding the pooler's unix socket. Its permissions decide who can administer the pooler locally.

etcd Internal Parameters

The following parameters control etcd installation paths and behavior. Default values are sufficient for most deployments.

Parameter Default Description
etcd_version 3.6.5 etcd version to install.
etcd_user etcd System user that runs the etcd service.
etcd_group etcd System group for the etcd service.
etcd_install_dir /usr/local/etcd Directory where etcd binaries are installed.
etcd_config_dir /etc/etcd Directory for etcd configuration files.
etcd_data_dir /var/lib/etcd Directory for etcd data storage.
etcd_tls_dir /etc/etcd/tls Directory for etcd TLS certificates and keys.
patroni_tls_dir /etc/patroni/tls Directory for Patroni TLS certificates.