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 - Define cluster name and zone assignments for nodes.
Repository Configuration Parameters - Control which software repository the collection uses.
Installation Parameters - Specify PostgreSQL and extension versions to install.
Database Configuration Parameters - Configure database names, users, and authentication.
High Availability Parameters - Enable and configure etcd, Patroni, and streaming replication.
HAProxy Parameters - Configure HAProxy listeners and routing.
Server Configuration Parameters - Control server-level settings like ports and SELinux.
Backup Configuration Parameters - Configure PgBackRest repositories, encryption, and schedules.
Spock Configuration Parameters - Control logical replication exception handling.
Path Override Parameters - Override default PostgreSQL installation paths.
Internal Variables - Computed variables available for reference.
etcd Internal Parameters - Configure etcd installation and paths.

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.
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.

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.

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.

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.