Patroni configuration

• 1: Dynamic Configuration Settings
• 2: YAML Configuration Settings
• 3: Environment Configuration Settings

patroni --generate-sample-config [configfile]

patroni --generate-config [--dsn DSN] [configfile]

patroni --validate-config [configfile] [--ignore-listen-port | -i]

1 - Dynamic Configuration Settings

Source: https://patroni.readthedocs.io/en/latest/dynamic_configuration.html

Dynamic configuration is stored in the DCS (Distributed Configuration Store) and applied on all cluster nodes.

Change dynamic configuration with patronictl_edit_config or the Patroni REST API.

• loop_wait: the number of seconds the loop will sleep. Default value: 10, minimum possible value: 1
• ttl: leader lock TTL, in seconds. This is the interval before automatic failover can start. Default: 30. Minimum: 20.
• retry_timeout: timeout for DCS and PostgreSQL operation retries (in seconds). DCS or network issues shorter than this will not cause Patroni to demote the leader. Default value: 10, minimum possible value: 3

loop_wait + 2 * retry_timeout <= ttl

• maximum_lag_on_failover: the maximum bytes a follower may lag to be able to participate in leader election.
• primary_race_backoff: delays standby leader races by primary_race_backoff seconds while WAL replication from the primary advances. This reduces unnecessary failovers when Patroni is briefly unresponsive. Default: 0 (disabled).
• maximum_lag_on_syncnode: maximum synchronous replica lag in bytes before replacement by a healthy asynchronous replica. With multiple replicas, Patroni uses the maximum replica LSN. Otherwise, it uses the leader’s current WAL LSN. Default: -1. Values of 0 or less disable replacement. Use a sufficiently high value to avoid frequent replacements during high transaction volume.
• max_timelines_history: maximum number of timeline history items kept in DCS. Default value: 0. When set to 0, it keeps the full history in DCS.
• primary_start_timeout: seconds allowed for primary recovery before failover. Default: 300. A value of 0 permits immediate failover after crash detection. Asynchronous failover can lose transactions. Worst-case failover time is loop_wait + primary_start_timeout + loop_wait, or only loop_wait when primary_start_timeout is zero. Select the value for your durability and availability requirements.
• primary_stop_timeout: seconds Patroni can wait for Postgres shutdown when synchronous_mode is enabled. With synchronous_mode enabled and a value > 0, Patroni sends SIGKILL to postmaster if shutdown exceeds this interval. Select the value for your durability and availability requirements. Unset values or values <= 0 disable this timeout.
• synchronous_mode: synchronous replication mode: off, on, or quorum. The leader manages synchronous_standby_names. Only the last known leader or synchronous replicas can enter a leader race. This protects successful commits during failover but can block writes when Patroni cannot guarantee durability. See replication modes documentation.
• synchronous_mode_strict: keeps synchronous replication enabled when no synchronous replica is available, blocking client writes. Without an eligible streaming replica, Patroni uses the last synchronous nodes from /sync for synchronous_standby_names. If no prior state exists, it uses __patroni_strict_sync_replica_placeholder__. Do not use that reserved value for the node name in patroni.yaml. See replication modes documentation.
• synchronous_node_count: required synchronous standby count when synchronous_mode is enabled. Patroni updates the DCS and PostgreSQL synchronous_standby_names as members join or leave. It reduces the count if it exceeds the number of eligible nodes. Default: 1.
• failsafe_mode: Enables DCS Failsafe Mode. Defaults to false.
• postgresql:
  • use_pg_rewind: enables pg_rewind. Default: false. For correct operation, pg_rewind requires data page checksums and/or wal_log_hints set to on. Enable checksums with the --data-checksums option for initdb.
  • use_slots: whether or not to use replication slots. Defaults to true on PostgreSQL 9.4+.
  • recovery_conf: extra recovery.conf settings for replicas. PostgreSQL 12 no longer uses recovery.conf. You can still use this section because Patroni handles the version difference.
  • parameters: configuration parameters (GUCs) for Postgres in format {max_connections: 100, wal_level: "replica", max_wal_senders: 10, wal_log_hints: "on"}. Many of these are required for replication to work.
  • parameters_primary: (optional) role-specific parameter overrides for primary. These values are merged with and override the base parameters.
  • parameters_replica: (optional) role-specific parameter overrides for replica. These values are merged with and override the base parameters.
  • parameters_standby_leader: (optional) role-specific parameter overrides for standby_leader. These values are merged with and override the base parameters.
  • pg_hba: list of lines that Patroni will use to generate pg_hba.conf. Patroni ignores this parameter if hba_file PostgreSQL parameter is set to a non-default value.
    • - host all all 0.0.0.0/0 md5
    • - host replication replicator 127.0.0.1/32 md5: A line like this is required for replication.
  • pg_hba_primary: (optional) role-specific pg_hba entries for primary. These completely replace pg_hba (no merging). If not defined, pg_hba is used.
  • pg_hba_replica: (optional) role-specific pg_hba entries for replica. These completely replace pg_hba (no merging). If not defined, pg_hba is used.
  • pg_hba_standby_leader: (optional) role-specific pg_hba entries for standby_leader. These completely replace pg_hba (no merging). If not defined, pg_hba is used.
  • pg_ident: list of lines that Patroni will use to generate pg_ident.conf. Patroni ignores this parameter if ident_file PostgreSQL parameter is set to a non-default value.
    • - mapname1 systemname1 pguser1
    • - mapname1 systemname2 pguser2
  • pg_ident_primary: (optional) role-specific pg_ident entries for primary. These completely replace pg_ident (no merging). If not defined, pg_ident is used.
  • pg_ident_replica: (optional) role-specific pg_ident entries for replica. These completely replace pg_ident (no merging). If not defined, pg_ident is used.
  • pg_ident_standby_leader: (optional) role-specific pg_ident entries for standby_leader. These completely replace pg_ident (no merging). If not defined, pg_ident is used.
• standby_cluster: if this section is defined, we want to bootstrap a standby cluster.
  • host: an address of remote node
  • port: a port of remote node
  • primary_slot_name: replication slot on the remote node. Optional. The default comes from the instance name; see slot_name_from_member_name.
  • create_replica_methods: ordered methods to bootstrap the standby leader from the remote primary. This list can differ from postgresql_settings.
  • restore_command: command to restore remote primary WAL records to standby cluster nodes. It can differ from postgresql_settings.
  • archive_cleanup_command: cleanup command for standby leader
  • recovery_min_apply_delay: how long to wait before actually apply WAL records on a standby leader
• member_slots_ttl: physical slot retention after replicas shut down. Default: 30min. A value of 0 restores immediate removal when the member key expires from the DCS. Requires PostgreSQL 11 or later.
• slots: permanent replication slots, retained through switchover and failover. Patroni creates missing slots. On PostgreSQL 11 and later, it creates physical slots on all nodes and advances them every loop_wait seconds. Earlier versions maintain permanent physical slots only on the primary. Logical slots are copied from the primary to a standby with restart. Their positions then advance every loop_wait seconds if necessary. Patroni copies logical slot files through libpq with rewind or superuser credentials; see postgresql.authentication. A replica slot can lag behind the old primary. Applications must handle repeated messages after failover, for example by tracking confirmed_flush_lsn. Permanent slots require postgresql.use_slots set to true. Permanent logical slots automatically enable hot_standby_feedback. Logical slot failover is unsafe on PostgreSQL 9.6 and older, and PostgreSQL 10 lacks required functions. This feature requires PostgreSQL 11+.
  • my_slot_name: permanent slot name. Patroni does not create a slot on the node with the same name. A permanent physical slot named after a member remains even when that member becomes unresponsive. Normally, Patroni would remove it. This preserves member slots during temporary failures or migration to Patroni; see Convert a Standalone to a Patroni Cluster. Remove these matching names from DCS configuration when the slots are no longer required. Otherwise, they affect normal Patroni operation.
    • type: physical or logical. Logical slots also require database and plugin. Physical slots optionally accept cluster_type.
    • database: the database name where logical slots should be created.
    • plugin: the plugin name for the logical slot.
    • cluster_type: create the slot only on this cluster type: primary or standby. On other types, Patroni skips creation or drops an existing slot.
• ignore_slots: sets of slot properties that Patroni must ignore. Use this for slots managed outside Patroni. Any matching subset of properties causes a slot to be ignored.
  • name: the name of the replication slot.
  • type: slot type. Can be physical or logical. If the slot is logical, you may additionally define database and/or plugin.
  • database: the database name (when matching a logical slot).
  • plugin: the logical decoding plugin (when matching a logical slot).

Note: slots is a hashmap while ignore_slots is an array. For example:

slots:
  permanent_logical_slot_name:
    type: logical
    database: my_db
    plugin: test_decoding
  permanent_physical_slot_name:
    type: physical
  ...
ignore_slots:
  - name: ignored_logical_slot_name
    type: logical
    database: my_db
    plugin: test_decoding
  - name: ignored_physical_slot_name
    type: physical
  ...

Note: On PostgreSQL v11 or later, Patroni maintains physical slots on all nodes eligible to become leader. Replicas therefore retain WAL segments that other nodes may need. After an absent node’s DCS member key expires, Patroni drops its slot after member_slots_ttl, which defaults to 30min. Adjust retention for your requirements.

For a fixed topology with stable node names, you can configure permanent physical slots named after the nodes. This prevents slot removal and WAL recycling while a replica is temporarily down:

slots:
  node_name1:
    type: physical
  node_name2:
    type: physical
  node_name3:
    type: physical
  ...

2 - YAML Configuration Settings

Source: https://patroni.readthedocs.io/en/latest/yaml_configuration.html

Global/Universal

• thread_pool_size: thread pool size for asynchronous tasks and REST API communication with other members during leader races or failsafe checks. Minimum: 5. Default: 5.
• thread_stack_size: stack size for Patroni threads. Use a multiple of 64kB. Minimum: 64kB. Patroni default: 512kB.
• name: the name of the host. Must be unique for the cluster. The value __patroni_strict_sync_replica_placeholder__ is reserved for internal use by Patroni and cannot be used as a node name.
• namespace: path within the configuration store where Patroni will keep information about the cluster. Default value: “/service”
• scope: cluster name

Log

• type: sets the format of logs. Can be either plain or json. To use json format, you must have the jsonlogger installed. The default value is plain.
• level: sets the general logging level. Default value is INFO (see the docs for Python logging)
• traceback_level: sets the level where tracebacks will be visible. Default value is ERROR. Set it to DEBUG if you want to see tracebacks only if you enable log.level=DEBUG.
• format: log format. For plain logs, use a string. For json, use a string or a list of LogRecord attributes. In lists, use field names without %( and ). To rename a field, use a dictionary with the original field as key and the output name as value. Default: %(asctime)s %(levelname)s: %(message)s.
• dateformat: sets the datetime formatting string. (see the formatTime() documentation)
• static_fields: add additional fields to the log. This option is only available when the log type is set to json.
• max_queue_size: maximum internal log queue size. Patroni writes records to an in-memory queue. A separate thread reads them and writes to stderr or a file. The default 1000 records retain approximately 1h20m of logs.
• dir: application log directory. It must exist and be writable by the Patroni user. By default, Patroni retains four 25MB files. Adjust retention with file_num and file_size.
• mode: Permissions for log files (for example, 0644). If not specified, permissions will be set based on the current umask value.
• file_num: The number of application logs to retain.
• file_size: Size of patroni.log file (in bytes) that triggers a log rolling.
• loggers: This section allows redefining logging level per python module
  • patroni.postmaster: WARNING
  • urllib3: DEBUG
• deduplicate_heartbeat_logs: suppresses consecutive identical heartbeat messages when true. Default: false.

For JSON logging, use this example:

log:
   type: json
   format:
      - message
      - module
      - asctime: '@timestamp'
      - levelname: level
   static_fields:
      app: patroni

Bootstrap configuration

• bootstrap:

  • dcs: global dynamic cluster configuration. Put parameters from Dynamic Configuration settings under bootstrap.dcs. After bootstrap, Patroni writes this section to /<namespace>/<scope>/config in the configuration store.

  • method: custom script to use for bootstrapping this cluster.

    See custom bootstrap methods. Set method to initdb, or omit it, to use the default initdb command.

  • initdb: (optional) list options to be passed on to initdb.

    • - data-checksums: Must be enabled when pg_rewind is needed on 9.3.
    • - encoding: UTF8: default encoding for new databases.
    • - locale: UTF8: default locale for new databases.

  • post_bootstrap or post_init: script to run after cluster initialization. It receives a connection URL with the cluster superuser name. PGPASSFILE points to the pgpass file.

Citus

Enable Citus integration. Patroni then registers workers on the coordinator. See Citus support.

• group: the Citus group id, integer. Use 0 for coordinator and 1, 2, etc… for workers
• database: database for the citus extension. Use the same database on the coordinator and all workers. Currently, only one database is supported.

Consul

Most of the parameters are optional, but you have to specify one of the host or url

• host: the host:port for the Consul local agent.
• url: url for the Consul local agent, in format: http(s)://host:port.
• port: (optional) Consul port.
• scheme: (optional) http or https, defaults to http.
• token: (optional) ACL token.
• verify: (optional) whether to verify the SSL certificate for HTTPS requests.
• cacert: (optional) The ca certificate. If present it will enable validation.
• cert: (optional) file with the client certificate.
• key: (optional) file with the client key. Can be empty if the key is part of cert.
• dc: (optional) Datacenter to communicate with. By default the datacenter of the host is used.
• consistency: (optional) Select consul consistency mode. Possible values are default, consistent, or stale (more details in consul API reference)
• checks: (optional) list of Consul health checks used for the session. By default an empty list is used.
• register_service: (optional) registers a service named by scope. Its role tag is master, primary, replica, or standby-leader. Default: false.
• service_tags: (optional) additional static tags to add to the Consul service apart from the role (primary/replica/standby-leader). By default an empty list is used.
• service_check_interval: (optional) how often to perform health check against registered url. Defaults to ‘5s’.
• service_check_tls_server_name: (optional) override SNI host when connecting via TLS, see also consul agent check API reference.

The token needs to have the following ACL permissions:

service_prefix "${scope}" {
    policy = "write"
}
key_prefix "${namespace}/${scope}" {
    policy = "write"
}
session_prefix "" {
    policy = "write"
}

Etcd

Most of the parameters are optional, but you have to specify one of the host, hosts, url, proxy or srv

• host: the host:port for the etcd endpoint.
• hosts: list of etcd endpoint in format host1:port1,host2:port2,etc… Could be a comma separated string or an actual yaml list.
• use_proxies: if true, treats hosts as proxies. Patroni does not discover etcd topology.
• url: url for the etcd.
• proxy: proxy url for the etcd. If you are connecting to the etcd using proxy, use this parameter instead of url.
• srv: domain for SRV-based cluster discovery. Patroni queries these services in order until one succeeds: _etcd-client-ssl, _etcd-client, _etcd-ssl, _etcd, _etcd-server-ssl, _etcd-server. For _etcd-server-ssl or _etcd-server, it queries available members through the ETCD peer protocol. Otherwise, it uses hosts from the SRV records.
• srv_suffix: suffix for discovery SRV names. Requires srv. Use it to distinguish etcd clusters in one domain. For example, srv_suffix: foo and srv: example.org produce _etcd-client-ssl-foo._tcp.example.com. Patroni applies this suffix to each possible ETCD SRV service name.
• protocol: (optional) http or https, if not specified http is used. If the url or proxy is specified - will take protocol from them.
• username: (optional) username for etcd authentication.
• password: (optional) password for etcd authentication.
• cacert: (optional) The ca certificate. If present it will enable validation.
• cert: (optional) file with the client certificate.
• key: (optional) file with the client key. Can be empty if the key is part of cert.

Etcdv3

To use Etcd protocol version 3, configure the etcd3 section. Its parameters are the same as etcd.

ZooKeeper

• hosts: List of ZooKeeper cluster members in format: $$'host1:port1', 'host2:port2', 'etc...'$$.
• use_ssl: (optional) Whether SSL is used or not. Defaults to false. If set to false, all SSL specific parameters are ignored.
• cacert: (optional) The CA certificate. If present it will enable validation.
• cert: (optional) File with the client certificate.
• key: (optional) File with the client key.
• key_password: (optional) The client key password.
• verify: (optional) Whether to verify certificate or not. Defaults to true.
• set_acls: (optional) default ACL that Kazoo applies to each new ZNode. Use x509 (default) or another supported ZooKeeper scheme, such as digest. Supply a dictionary: each key is the full principal, optionally prefixed with its scheme. Each value lists one or more permissions: CREATE, READ, WRITE, DELETE, ADMIN, or ALL. Example: set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]}.
• auth_data: (optional) connection authentication dictionary. Use scheme as the key and credential as the value. Default: empty dictionary.

Exhibitor

• hosts: initial list of Exhibitor (ZooKeeper) nodes in format: ‘host1,host2,etc…’. This list updates automatically whenever the Exhibitor (ZooKeeper) cluster topology changes.
• poll_interval: how often the list of ZooKeeper and Exhibitor nodes should be updated from Exhibitor.
• port: Exhibitor port.

Kubernetes

• bypass_api_service: (optional) normally, Patroni contacts the kubernetes service at KUBERNETES_SERVICE_HOST. With bypass_api_service set to true, it discovers the API nodes behind the service and contacts them directly.
• namespace: (optional) Kubernetes namespace where Patroni pod is running. Default value is default.
• labels: labels in {label1: value1, label2: value2} format. Patroni uses them to find cluster Pods and Endpoints or ConfigMaps. It also adds them to each Endpoint or ConfigMap it creates.
• scope_label: (optional) name of the label containing cluster name. Default value is cluster-name.
• bootstrap_labels: (optional) labels in {label1: value1, label2: value2} format. Patroni assigns them to pods in these states: initializing new cluster, running custom bootstrap script, starting after custom bootstrap, or creating replica.
• role_label: (optional) name of the label containing role (primary, replica, or other custom value). Patroni will set this label on the pod it runs in. Default value is role.
• leader_label_value: (optional) value of the pod label when Postgres role is primary. Default value is primary.
• follower_label_value: (optional) value of the pod label when Postgres role is replica. Default value is replica.
• standby_leader_label_value: (optional) value of the pod label when Postgres role is standby_leader. Default value is primary.
• tmp_role_label: (optional) name of the temporary label containing role (primary or replica). Value of this label will always use the default of corresponding role. Set only when necessary.
• use_endpoints: (optional) if set to true, Patroni will use Endpoints instead of ConfigMaps to run leader elections and keep cluster state.
• pod_ip: (optional) Patroni pod IP address. Required when use_endpoints is enabled. On promotion, Patroni uses this value to populate leader endpoint subsets.
• ports: (optional) named Service ports require identical Endpoint port names. Otherwise, the service cannot work. For {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}}, set kubernetes.ports: [{"name": "postgresql", "port": 5432}]. Patroni uses this value to update leader Endpoint subsets. Applies only with kubernetes.use_endpoints.
• cacert: (optional) CA_BUNDLE file with trusted CA certificates for Kubernetes API SSL verification. Defaults to the ServiceAccount secret value.
• retriable_http_codes: (optional) Kubernetes API status codes to retry. By default, Patroni retries 500, 503, and 504, and responses with a retry-after HTTP header.

Raft (deprecated)

• self_addr: ip:port to listen on for Raft connections. The self_addr must be accessible from other nodes of the cluster. If not set, the node will not participate in consensus.

• bind_addr: (optional) ip:port to listen on for Raft connections. If not specified the self_addr will be used.

• partner_addrs: list of other Patroni nodes in the cluster in format:

  $$'ip1:port', 'ip2:port', 'etc...'$$

• data_dir: directory where to store Raft log and snapshot. If not specified the current working directory is used.

• password: (optional) Encrypt Raft traffic with a specified password, requires cryptography python module.

• min_timeout: (optional) minimum election timeout in seconds for the underlying pysyncobj Raft implementation. Must be greater than 3 * append_entries_period. Default: 0.4.

• max_timeout: (optional) maximum election timeout in seconds for the underlying pysyncobj Raft implementation. Must be greater than min_timeout. Default: 1.4.

• connection_timeout: (optional) time in seconds after which a connection with no data received is considered dead. Must be greater than or equal to max_timeout. Default: 3.5.

• append_entries_period: (optional) interval in seconds for sending heartbeat (append_entries) commands. Must be less than one-third of min_timeout. Default: 0.1.

• connection_retry_time: (optional) interval in seconds between reconnection attempts to offline nodes. Default: 5.0.

• leader_fallback_timeout: (optional) time in seconds after which a leader with no response from the majority falls back to follower state. Must be greater than append_entries_period. Default: 30.0.

Short FAQ about Raft implementation

• Q: How to list all the nodes providing consensus?

  A: syncobj_admin -conn host:port -status where the host:port is the address of one of the cluster nodes

• Q: Node that was a part of consensus and has gone and I can’t reuse the same IP for other node. How to remove this node from the consensus?

  A: syncobj_admin -conn host:port -remove host2:port2 where the host2:port2 is the address of the node you want to remove from consensus.

• Q: Where to get the syncobj_admin utility?

  A: It is installed together with pysyncobj module (python RAFT implementation), which is Patroni dependency.

• Q: it is possible to run Patroni node without adding in to the consensus?

  A: Yes, just comment out or remove raft.self_addr from Patroni configuration.

• Q: It is possible to run Patroni and PostgreSQL only on two nodes?

  A: Yes, on the third node you can run patroni_raft_controller (without Patroni and PostgreSQL). In such a setup, one can temporarily lose one node without affecting the primary.

PostgreSQL

• postgresql:

  • authentication:

    • superuser:
      • username: name for the superuser, set during initialization (initdb) and later used by Patroni to connect to the postgres.
      • password: password for the superuser, set during initialization (initdb).
      • sslmode: (optional) maps to sslmode. Specifies the TLS negotiation mode. See the PostgreSQL documentation for each mode. Default: prefer.
      • sslkey: (optional) maps to sslkey. Path to the secret key for the client certificate.
      • sslpassword: (optional) maps to sslpassword. Password for the secret key in sslkey.
      • sslcert: (optional) maps to sslcert. Path to the client certificate.
      • sslrootcert: (optional) maps to sslrootcert. File containing one or more trusted CA certificates. The client uses them to verify the server certificate.
      • sslcrl: (optional) maps to sslcrl. Certificate revocation list file. The client rejects servers whose certificates appear in the list.
      • sslcrldir: (optional) maps to sslcrldir. Directory containing certificate revocation list files. The client rejects servers whose certificates appear in these lists.
      • sslnegotiation: (optional) maps to sslnegotiation. Controls server SSL negotiation when SSL is used.
      • gssencmode: (optional) maps to gssencmode. Controls whether to negotiate secure GSS TCP/IP and its priority.
      • channel_binding: (optional) maps to channel_binding. Controls client channel binding.
    • replication:
      • username: replication username; the user will be created during initialization. Replicas will use this user to access the replication source via streaming replication
      • password: replication password; the user will be created during initialization.
      • sslmode: (optional) maps to sslmode. Specifies the TLS negotiation mode. See the PostgreSQL documentation for each mode. Default: prefer.
      • sslkey: (optional) maps to sslkey. Path to the secret key for the client certificate.
      • sslpassword: (optional) maps to sslpassword. Password for the secret key in sslkey.
      • sslcert: (optional) maps to sslcert. Path to the client certificate.
      • sslrootcert: (optional) maps to sslrootcert. File containing one or more trusted CA certificates. The client uses them to verify the server certificate.
      • sslcrl: (optional) maps to sslcrl. Certificate revocation list file. The client rejects servers whose certificates appear in the list.
      • sslcrldir: (optional) maps to sslcrldir. Directory containing certificate revocation list files. The client rejects servers whose certificates appear in these lists.
      • sslnegotiation: (optional) maps to sslnegotiation. Controls server SSL negotiation when SSL is used.
      • gssencmode: (optional) maps to gssencmode. Controls whether to negotiate secure GSS TCP/IP and its priority.
      • channel_binding: (optional) maps to channel_binding. Controls client channel binding.
    • rewind:
      • username: (optional) name for the user for pg_rewind; the user will be created during initialization of postgres 11+ and all necessary permissions will be granted.
      • password: (optional) password for the user for pg_rewind; the user will be created during initialization.
      • sslmode: (optional) maps to sslmode. Specifies the TLS negotiation mode. See the PostgreSQL documentation for each mode. Default: prefer.
      • sslkey: (optional) maps to sslkey. Path to the secret key for the client certificate.
      • sslpassword: (optional) maps to sslpassword. Password for the secret key in sslkey.
      • sslcert: (optional) maps to sslcert. Path to the client certificate.
      • sslrootcert: (optional) maps to sslrootcert. File containing one or more trusted CA certificates. The client uses them to verify the server certificate.
      • sslcrl: (optional) maps to sslcrl. Certificate revocation list file. The client rejects servers whose certificates appear in the list.
      • sslcrldir: (optional) maps to sslcrldir. Directory containing certificate revocation list files. The client rejects servers whose certificates appear in these lists.
      • sslnegotiation: (optional) maps to sslnegotiation. Controls server SSL negotiation when SSL is used.
      • gssencmode: (optional) maps to gssencmode. Controls whether to negotiate secure GSS TCP/IP and its priority.
      • channel_binding: (optional) maps to channel_binding. Controls client channel binding.

  • callbacks: callback scripts to run on certain actions. Patroni will pass the action, role and cluster name. (See scripts/aws.py as an example of how to write them.)

    • on_reload: run this script when configuration reload is triggered.
    • on_restart: run this script when the postgres restarts (without changing role).
    • on_role_change: run this script when the postgres is being promoted or demoted.
    • on_start: run this script when the postgres starts.
    • on_stop: run this script when the postgres stops.

  • connect_address: IP address + port through which Postgres is accessible from other nodes and applications.

  • proxy_address: address and port of the connection pool beside Postgres, such as pgbouncer. Patroni stores it as proxy_url in the DCS member key for service discovery.

  • create_replica_methods: ordered methods for creating replicas. The default is “basebackup”. Other methods refer to scripts, each with its own configuration section. See custom replica creation methods.

  • data_dir: The location of the Postgres data directory, either existing or to be initialized by Patroni.

  • config_dir: The location of the Postgres configuration directory, defaults to the data directory. Must be writable by Patroni.

  • bin_dir: (optional) Path to PostgreSQL binaries (pg_ctl, initdb, pg_controldata, pg_basebackup, postgres, pg_isready, pg_rewind). If not provided or is an empty string, PATH environment variable will be used to find the executables.

  • bin_name: (optional) Make it possible to override Postgres binary names, if you are using a custom Postgres distribution:

    • pg_ctl: (optional) Custom name for pg_ctl binary.
    • initdb: (optional) Custom name for initdb binary.
    • pgcontroldata: (optional) Custom name for pg_controldata binary.
    • pg_basebackup: (optional) Custom name for pg_basebackup binary.
    • postgres: (optional) Custom name for postgres binary.
    • pg_isready: (optional) Custom name for pg_isready binary.
    • pg_rewind: (optional) Custom name for pg_rewind binary.

  • listen: Postgres listen addresses and port. With streaming replication, other cluster nodes must be able to reach this address. Separate multiple addresses with commas and append the port after the last address: listen: 127.0.0.1,127.0.0.2:5432. Patroni uses the first address for local connections.

  • use_unix_socket: prefer Unix sockets for cluster connections. Default: false. If unix_socket_directories is set, use its first suitable value, or TCP if none is suitable. If absent from postgresql.parameters, assume the default socket directory and omit host from connection parameters.

  • use_unix_socket_repl: prefer Unix sockets for replication user connections. Default: false. If unix_socket_directories is set, use its first suitable value, or TCP if none is suitable. If absent from postgresql.parameters, assume the default socket directory and omit host from connection parameters.

  • pgpass: path to the .pgpass password file. Patroni creates this file before executing pg_basebackup, the post_init script and under some other circumstances. The location must be writable by Patroni.

  • recovery_conf: additional configuration settings written to recovery.conf when configuring follower.

  • custom_conf : optional custom postgresql.conf file to use instead of postgresql.base.conf. It must exist on all nodes and be readable by PostgreSQL. The actual postgresql.conf includes it from its location. Patroni neither monitors nor backs up this file. Patroni configuration can still override its settings; see dynamic configuration.

  • parameters: configuration parameters (GUCs) for Postgres in format {ssl: "on", ssl_cert_file: "cert_file"}.

  • parameters_primary: (optional) role-specific parameter overrides for primary. These values are merged with and override the base parameters.

  • parameters_replica: (optional) role-specific parameter overrides for replica. These values are merged with and override the base parameters.

  • parameters_standby_leader: (optional) role-specific parameter overrides for standby_leader. These values are merged with and override the base parameters.

  • pg_hba: list of lines that Patroni will use to generate pg_hba.conf. Patroni ignores this parameter if hba_file PostgreSQL parameter is set to a non-default value. Together with dynamic configuration this parameter simplifies management of pg_hba.conf.

    • - host all all 0.0.0.0/0 md5
    • - host replication replicator 127.0.0.1/32 md5: A line like this is required for replication.

  • pg_hba_primary: (optional) role-specific pg_hba entries for primary. These completely replace pg_hba (no merging). If not defined, pg_hba is used.

  • pg_hba_replica: (optional) role-specific pg_hba entries for replica. These completely replace pg_hba (no merging). If not defined, pg_hba is used.

  • pg_hba_standby_leader: (optional) role-specific pg_hba entries for standby_leader. These completely replace pg_hba (no merging). If not defined, pg_hba is used.

  • pg_ident: list of lines that Patroni will use to generate pg_ident.conf. Patroni ignores this parameter if ident_file PostgreSQL parameter is set to a non-default value. Together with dynamic configuration this parameter simplifies management of pg_ident.conf.

    • - mapname1 systemname1 pguser1
    • - mapname1 systemname2 pguser2

  • pg_ident_primary: (optional) role-specific pg_ident entries for primary. These completely replace pg_ident (no merging). If not defined, pg_ident is used.

  • pg_ident_replica: (optional) role-specific pg_ident entries for replica. These completely replace pg_ident (no merging). If not defined, pg_ident is used.

  • pg_ident_standby_leader: (optional) role-specific pg_ident entries for standby_leader. These completely replace pg_ident (no merging). If not defined, pg_ident is used.

  • pg_ctl_timeout: How long should pg_ctl wait when doing start, stop or restart. Default value is 60 seconds.

  • use_pg_rewind: try pg_rewind when the old leader rejoins as a replica. For correct operation, pg_rewind requires data page checksums and/or wal_log_hints set to on. Enable checksums with the --data-checksums option for initdb.

  • rewind: (optional) custom options to pass to the pg_rewind command. Can be specified as a list of strings and/or single key-value dictionaries. Not allowed options include: target-pgdata, source-pgdata, source-server, write-recovery-conf, dry-run, restore-target-wal, config-file, no-ensure-shutdown, version, and help. Example usage:

    postgresql:
      rewind:
        - debug
        - progress
        - sync-method: fsync

  • remove_data_directory_on_rewind_failure: If this option is enabled, Patroni will remove the PostgreSQL data directory and recreate the replica. Otherwise it will try to follow the new leader. Default value is false.

  • remove_data_directory_on_diverged_timelines: remove the data directory and recreate the replica if timelines diverge and the old primary cannot stream from the new primary. Use this when pg_rewind is unavailable. On PostgreSQL v10 and older, Patroni checks divergence by connecting to the “postgres” database with replication credentials. Permit this access in pg_hba.conf. Default: false.

  • replica_method: add a section for each create_replica_methods entry other than basebackup. Use the method name as the section name. At minimum, set “command” to the full script path. Patroni passes other parameters to the script as “parameter=value”.

  • pre_promote: fencing script run after leader lock acquisition and before replica promotion during failover. A non-zero exit prevents promotion and removes the DCS leader key.

  • before_stop: script run immediately before Postgres stops. It runs synchronously and blocks shutdown until completion. Shutdown then proceeds regardless of its exit code.

REST API

• restapi:
  • thread_pool_size: size of thread pool used by Patroni to process REST API requests. Minimal value is 5, default value is 5.
  • connect_address: address or host name and port for the REST API. Every cluster member must reach it. Use a non-loopback address except for a local demonstration; “localhost” and “127.0.0.1” are unsuitable for other deployments. It supports HTTP health checks, user queries, and member checks during leader elections. These checks determine whether the leader runs or another node has a later WAL position. Patroni stores connect_address in the DCS member key so member names resolve to REST API addresses.
  • listen: address or host name and port for REST API health checks and communication between cluster members. HAProxy and other load balancers can use HTTP “OPTION” or “GET” checks.
  • authentication: (optional)
    • username: Basic-auth username to protect unsafe REST API endpoints.
    • password: Basic-auth password to protect unsafe REST API endpoints.
  • certfile: (optional): Specifies the file with the certificate in the PEM format. If the certfile is not specified or is left empty, the API server will work without SSL.
  • keyfile: (optional): Specifies the file with the secret key in the PEM format.
  • keyfile_password: (optional): Specifies a password for decrypting the keyfile.
  • cafile: (optional): Specifies the file with the CA_BUNDLE with certificates of trusted CAs to use while verifying client certs.
  • ciphers: (optional): Specifies the permitted cipher suites (e.g. “ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”)
  • verify_client: (optional) client certificate verification mode: none (default), optional, or required. none disables verification. required requires certificates for all calls; successful signature verification authenticates the client. optional requires and checks certificates only for unsafe PUT, POST, PATCH, and DELETE requests.
  • allowlist: (optional) hosts permitted to call unsafe endpoints. Each entry can be a host name, IP address, or CIDR network. Default: allow all. With allowlist or allowlist_include_members set, all unlisted sources are rejected.
  • allowlist_include_members: (optional) if true, permits unsafe endpoint access from cluster members registered in the DCS. It uses each member’s api_url host name or IP address. The operating system may use a different address for outgoing connections.
  • http_extra_headers: (optional): HTTP headers let the REST API server pass additional information with an HTTP response.
  • https_extra_headers: (optional): HTTPS headers let the REST API server pass additional information with an HTTP response when TLS is enabled. This will also pass additional information set in http_extra_headers.
  • request_queue_size: (optional): Sets request queue size for TCP socket used by Patroni REST API. Once the queue is full, further requests get a “Connection denied” error. The default value is 5.
  • server_tokens: (optional): Configures the value of the Server HTTP header.
    • Minimal: The header will contain only the Patroni version, e.g. Patroni/4.0.0.
    • ProductOnly: The header will contain only the product name, e.g. Patroni.
    • Original (default): The header will expose the original behaviour and display the BaseHTTP and Python versions, e.g. BaseHTTP/0.6 Python/3.12.3.

Here is an example of both http_extra_headers and https_extra_headers:

restapi:
  listen: <listen>
  connect_address: <connect_address>
  authentication:
    username: <username>
    password: <password>
  http_extra_headers:
    'X-Frame-Options': 'SAMEORIGIN'
    'X-XSS-Protection': '1; mode=block'
    'X-Content-Type-Options': 'nosniff'
  cafile: <ca file>
  certfile: <cert>
  keyfile: <key>
  https_extra_headers:
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'

CTL

• ctl: (optional)
  • authentication:
    • username: Basic-auth username for accessing protected REST API endpoints. If not provided patronictl will use the value provided for REST API “username” parameter.
    • password: Basic-auth password for accessing protected REST API endpoints. If not provided patronictl will use the value provided for REST API “password” parameter.
  • insecure: Allow connections to REST API without verifying SSL certs.
  • cacert: CA_BUNDLE file or directory with trusted CAs for REST API SSL verification. If absent, patronictl uses the REST API “cafile” value.
  • certfile: Specifies the file with the client certificate in the PEM format.
  • keyfile: Specifies the file with the client secret key in the PEM format.
  • keyfile_password: Specifies a password for decrypting the client keyfile.

Watchdog

• mode: off, automatic, or required. off disables the watchdog. automatic uses it when available and otherwise ignores it. required prevents leadership unless watchdog activation succeeds.
• device: Path to watchdog device. Defaults to /dev/watchdog.
• safety_margin: Number of seconds of safety margin between watchdog triggering and leader key expiration.

Tags

• clonefrom: true or false. If true, other nodes may prefer this node as their bootstrap pg_basebackup source. With multiple nodes tagged clonefrom, selection is random. Default: false.
• noloadbalance: true or false. If set to true the node will return HTTP Status Code 503 for the GET /replica REST API health-check and therefore will be excluded from the load-balancing. Defaults to false.
• replicatefrom: The name of another replica to replicate from. Used to support cascading replication.
• nosync: true or false. If set to true the node will never be selected as a synchronous replica.
• sync_priority: integer priority for synchronous standby selection with synchronous_mode set to on. Higher values are preferred. Values of 0 or less exclude the node from synchronous_standby_names, like nosync: true. This is the opposite of sync_priority in pg_stat_replication.
• nofailover: true or false, controls whether this node is allowed to participate in the leader race and become a leader. Defaults to false, meaning this node can_ participate in leader races.
• failover_priority: integer failover priority. Higher values are preferred when nodes have received/replayed the same WAL amount. A higher receive/replay LSN takes precedence over priority. Values of 0 or less prevent leader election participation and promotion, like nofailover: true. Currently, failover_priority does not work with quorum-based synchronous replication.
• nostream: true or false. If true, disable WAL streaming through the replication protocol. Use archive recovery, if restore_command is configured, and pg_wal/pg_xlog polling instead. Also disable permanent logical slot copying and synchronization on this node and its cascading replicas. This tag has no effect on a primary.

In addition to these predefined tags, you can also add your own ones:

• key1: true
• key2: false
• key3: 1.4
• key4: "RandomString"

Tags appear in the REST API and patronictl_list. Use them in instance health checks. An undefined tag or a value different from the query value returns HTTP 503.

3 - Environment Configuration Settings

Source: https://patroni.readthedocs.io/en/latest/ENVIRONMENT.html

System environment variables can override some Patroni configuration file parameters. This page lists all supported variables. Environment values always take precedence over file values.

Global/Universal

• PATRONI_CONFIGURATION: sets the complete Patroni configuration through PATRONI_CONFIGURATION. Patroni then ignores all other environment variables.
• PATRONI_THREAD_POOL_SIZE: thread pool size for asynchronous tasks and REST API communication with other members during leader races or failsafe checks. Minimum: 5. Default: 5.
• PATRONI_THREAD_STACK_SIZE: stack size for Patroni threads. Use a multiple of 64kB. Minimum: 64kB. Patroni default: 512kB.
• PATRONI_NAME: name of the node where the current instance of Patroni is running. Must be unique for the cluster. The value __patroni_strict_sync_replica_placeholder__ is reserved for internal use by Patroni and cannot be used as a node name.
• PATRONI_NAMESPACE: path within the configuration store where Patroni will keep information about the cluster. Default value: “/service”
• PATRONI_SCOPE: cluster name
• PG_MALLOC_ARENA_MAX: custom value for MALLOC_ARENA_MAX environment variable for postmaster process. If not set, postmaster will inherit MALLOC_ARENA_MAX value.

Log

• PATRONI_LOG_TYPE: sets the format of logs. Can be either plain or json. To use json format, you must have the jsonlogger installed. The default value is plain.
• PATRONI_LOG_LEVEL: sets the general logging level. Default value is INFO (see the docs for Python logging)
• PATRONI_LOG_TRACEBACK_LEVEL: sets the level where tracebacks will be visible. Default value is ERROR. Set it to DEBUG if you want to see tracebacks only if you enable PATRONI_LOG_LEVEL=DEBUG.
• PATRONI_LOG_FORMAT: log format. For plain logs, use a string. For json, use a string or a list of LogRecord attributes. In lists, use field names without %( and ). To rename a field, use a dictionary with the original field as key and the output name as value. Default: %(asctime)s %(levelname)s: %(message)s.
• PATRONI_LOG_DATEFORMAT: sets the datetime formatting string. (see the formatTime() documentation)
• PATRONI_LOG_STATIC_FIELDS: add additional fields to the log. This option is only available when the log type is set to json. Example PATRONI_LOG_STATIC_FIELDS="{app: patroni}"
• PATRONI_LOG_MAX_QUEUE_SIZE: maximum internal log queue size. Patroni writes records to an in-memory queue. A separate thread reads them and writes to stderr or a file. The default 1000 records retain approximately 1h20m of logs.
• PATRONI_LOG_DIR: application log directory. It must exist and be writable by the Patroni user. By default, Patroni retains four 25MB files. Adjust retention with PATRONI_LOG_FILE_NUM and PATRONI_LOG_FILE_SIZE.
• PATRONI_LOG_MODE: Permissions for log files (for example, 0644). If not specified, permissions will be set based on the current umask value.
• PATRONI_LOG_FILE_NUM: The number of application logs to retain.
• PATRONI_LOG_FILE_SIZE: Size of patroni.log file (in bytes) that triggers a log rolling.
• PATRONI_LOG_LOGGERS: Redefine logging level per python module. Example PATRONI_LOG_LOGGERS="{patroni.postmaster: WARNING, urllib3: DEBUG}"
• PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS: suppresses consecutive identical heartbeat messages when true. Default: false.

Citus

Enable Citus integration. Patroni then registers workers on the coordinator. See Citus support.

• PATRONI_CITUS_GROUP: the Citus group id, integer. Use 0 for coordinator and 1, 2, etc… for workers
• PATRONI_CITUS_DATABASE: database for the citus extension. Use the same database on the coordinator and all workers. Currently, only one database is supported.

Consul

• PATRONI_CONSUL_HOST: the host:port for the Consul local agent.
• PATRONI_CONSUL_URL: url for the Consul local agent, in format: http(s)://host:port
• PATRONI_CONSUL_PORT: (optional) Consul port
• PATRONI_CONSUL_SCHEME: (optional) http or https, defaults to http
• PATRONI_CONSUL_TOKEN: (optional) ACL token
• PATRONI_CONSUL_VERIFY: (optional) whether to verify the SSL certificate for HTTPS requests
• PATRONI_CONSUL_CACERT: (optional) The ca certificate. If present it will enable validation.
• PATRONI_CONSUL_CERT: (optional) File with the client certificate
• PATRONI_CONSUL_KEY: (optional) File with the client key. Can be empty if the key is part of certificate.
• PATRONI_CONSUL_DC: (optional) Datacenter to communicate with. By default the datacenter of the host is used.
• PATRONI_CONSUL_CONSISTENCY: (optional) Select consul consistency mode. Possible values are default, consistent, or stale (more details in consul API reference)
• PATRONI_CONSUL_CHECKS: (optional) list of Consul health checks used for the session. By default an empty list is used.
• PATRONI_CONSUL_REGISTER_SERVICE: (optional) registers a service named by scope. Its role tag is master, primary, replica, or standby-leader. Default: false.
• PATRONI_CONSUL_SERVICE_TAGS: (optional) additional static tags to add to the Consul service apart from the role (primary/replica/standby-leader). By default an empty list is used.
• PATRONI_CONSUL_SERVICE_CHECK_INTERVAL: (optional) how often to perform health check against registered url
• PATRONI_CONSUL_SERVICE_CHECK_TLS_SERVER_NAME: (optional) override SNI host when connecting via TLS, see also consul agent check API reference.

Etcd

• PATRONI_ETCD_PROXY: proxy url for the etcd. If you are connecting to the etcd using proxy, use this parameter instead of PATRONI_ETCD_URL
• PATRONI_ETCD_URL: url for the etcd, in format: http(s)://(username:password@)host:port
• PATRONI_ETCD_HOSTS: list of etcd endpoints in format ‘host1:port1’,‘host2:port2’,etc…
• PATRONI_ETCD_USE_PROXIES: if true, treats hosts as a fixed proxy list. Patroni does not discover etcd topology.
• PATRONI_ETCD_PROTOCOL: http or https, if not specified http is used. If the url or proxy is specified - will take protocol from them.
• PATRONI_ETCD_HOST: the host:port for the etcd endpoint.
• PATRONI_ETCD_SRV: domain for SRV-based cluster discovery. Patroni queries these services in order until one succeeds: _etcd-client-ssl, _etcd-client, _etcd-ssl, _etcd, _etcd-server-ssl, _etcd-server. For _etcd-server-ssl or _etcd-server, it queries available members through the ETCD peer protocol. Otherwise, it uses hosts from the SRV records.
• PATRONI_ETCD_SRV_SUFFIX: suffix for discovery SRV names. Requires PATRONI_ETCD_SRV. Use it to distinguish etcd clusters in one domain. For example, PATRONI_ETCD_SRV_SUFFIX=foo and PATRONI_ETCD_SRV=example.org produce _etcd-client-ssl-foo._tcp.example.com. Patroni applies this suffix to each possible ETCD SRV service name.
• PATRONI_ETCD_USERNAME: username for etcd authentication.
• PATRONI_ETCD_PASSWORD: password for etcd authentication.
• PATRONI_ETCD_CACERT: The ca certificate. If present it will enable validation.
• PATRONI_ETCD_CERT: File with the client certificate.
• PATRONI_ETCD_KEY: File with the client key. Can be empty if the key is part of certificate.

Etcdv3

For Etcdv3, replace ETCD with ETCD3 in Etcd variable names. Examples include PATRONI_ETCD3_HOST and PATRONI_ETCD3_CACERT.

ZooKeeper

• PATRONI_ZOOKEEPER_HOSTS: Comma separated list of ZooKeeper cluster members: “‘host1:port1’,‘host2:port2’,’etc…’”. It is important to quote every single entity!
• PATRONI_ZOOKEEPER_USE_SSL: (optional) Whether SSL is used or not. Defaults to false. If set to false, all SSL specific parameters are ignored.
• PATRONI_ZOOKEEPER_CACERT: (optional) The CA certificate. If present it will enable validation.
• PATRONI_ZOOKEEPER_CERT: (optional) File with the client certificate.
• PATRONI_ZOOKEEPER_KEY: (optional) File with the client key.
• PATRONI_ZOOKEEPER_KEY_PASSWORD: (optional) The client key password.
• PATRONI_ZOOKEEPER_VERIFY: (optional) Whether to verify certificate or not. Defaults to true.
• PATRONI_ZOOKEEPER_SET_ACLS: (optional) default ACL that Kazoo applies to each new ZNode. Use x509 (default) or another supported ZooKeeper scheme, such as digest. Supply a dictionary: each key is the full principal, optionally prefixed with its scheme. Each value lists one or more permissions: CREATE, READ, WRITE, DELETE, ADMIN, or ALL. Example: set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]}.
• PATRONI_ZOOKEEPER_AUTH_DATA: (optional) connection authentication dictionary. Use scheme as the key and credential as the value. Default: empty dictionary.

Exhibitor

• PATRONI_EXHIBITOR_HOSTS: initial list of Exhibitor (ZooKeeper) nodes in format: ‘host1,host2,etc…’. This list updates automatically whenever the Exhibitor (ZooKeeper) cluster topology changes.
• PATRONI_EXHIBITOR_PORT: Exhibitor port.

Kubernetes

• PATRONI_KUBERNETES_BYPASS_API_SERVICE: (optional) normally, Patroni contacts the kubernetes service at KUBERNETES_SERVICE_HOST. With PATRONI_KUBERNETES_BYPASS_API_SERVICE set to true, it discovers the API nodes behind the service and contacts them directly.
• PATRONI_KUBERNETES_NAMESPACE: (optional) Kubernetes namespace where the Patroni pod is running. Default value is default.
• PATRONI_KUBERNETES_LABELS: labels in {label1: value1, label2: value2} format. Patroni uses them to find cluster Pods and Endpoints or ConfigMaps. It also adds them to each Endpoint or ConfigMap it creates.
• PATRONI_KUBERNETES_SCOPE_LABEL: (optional) name of the label containing cluster name. Default value is cluster-name.
• PATRONI_KUBERNETES_BOOTSTRAP_LABELS: (optional) labels in {label1: value1, label2: value2} format. Patroni assigns them to pods in these states: initializing new cluster, running custom bootstrap script, starting after custom bootstrap, or creating replica.
• PATRONI_KUBERNETES_ROLE_LABEL: (optional) name of the label containing role (primary, replica or other custom value). Patroni will set this label on the pod it runs in. Default value is role.
• PATRONI_KUBERNETES_LEADER_LABEL_VALUE: (optional) value of the pod label when Postgres role is primary. Default value is primary.
• PATRONI_KUBERNETES_FOLLOWER_LABEL_VALUE: (optional) value of the pod label when Postgres role is replica. Default value is replica.
• PATRONI_KUBERNETES_STANDBY_LEADER_LABEL_VALUE: (optional) value of the pod label when Postgres role is standby_leader. Default value is primary.
• PATRONI_KUBERNETES_TMP_ROLE_LABEL: (optional) name of the temporary label containing role (primary or replica). Value of this label will always use the default of corresponding role. Set only when necessary.
• PATRONI_KUBERNETES_USE_ENDPOINTS: (optional) if set to true, Patroni will use Endpoints instead of ConfigMaps to run leader elections and keep cluster state.
• PATRONI_KUBERNETES_POD_IP: (optional) Patroni pod IP address. Required when PATRONI_KUBERNETES_USE_ENDPOINTS is enabled. On promotion, Patroni uses this value to populate leader endpoint subsets.
• PATRONI_KUBERNETES_PORTS: (optional) named Service ports require identical Endpoint port names. Otherwise, the service cannot work. For {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}}, set PATRONI_KUBERNETES_PORTS='[{"name": "postgresql", "port": 5432}]'. Patroni uses this value to update leader Endpoint subsets. Applies only with PATRONI_KUBERNETES_USE_ENDPOINTS.
• PATRONI_KUBERNETES_CACERT: (optional) CA_BUNDLE file with trusted CA certificates for Kubernetes API SSL verification. Defaults to the ServiceAccount secret value.
• PATRONI_RETRIABLE_HTTP_CODES: (optional) Kubernetes API status codes to retry. By default, Patroni retries 500, 503, and 504, and responses with a retry-after HTTP header.

Raft (deprecated)

• PATRONI_RAFT_SELF_ADDR: ip:port to listen on for Raft connections. The self_addr must be accessible from other nodes of the cluster. If not set, the node will not participate in consensus.
• PATRONI_RAFT_BIND_ADDR: (optional) ip:port to listen on for Raft connections. If not specified the self_addr will be used.
• PATRONI_RAFT_PARTNER_ADDRS: list of other Patroni nodes in the cluster in format "'ip1:port1','ip2:port2'". It is important to quote every single entity!
• PATRONI_RAFT_DATA_DIR: directory where to store Raft log and snapshot. If not specified the current working directory is used.
• PATRONI_RAFT_PASSWORD: (optional) Encrypt Raft traffic with a specified password, requires cryptography python module.
• PATRONI_RAFT_MIN_TIMEOUT: (optional) minimum election timeout in seconds for the underlying pysyncobj Raft implementation. Must be greater than 3 * PATRONI_RAFT_APPEND_ENTRIES_PERIOD. Default: 0.4.
• PATRONI_RAFT_MAX_TIMEOUT: (optional) maximum election timeout in seconds for the underlying pysyncobj Raft implementation. Must be greater than PATRONI_RAFT_MIN_TIMEOUT. Default: 1.4.
• PATRONI_RAFT_CONNECTION_TIMEOUT: (optional) time in seconds after which a connection with no data received is considered dead. Must be greater than or equal to PATRONI_RAFT_MAX_TIMEOUT. Default: 3.5.
• PATRONI_RAFT_APPEND_ENTRIES_PERIOD: (optional) interval in seconds for sending heartbeat commands. Must be less than one-third of PATRONI_RAFT_MIN_TIMEOUT. Default: 0.1.
• PATRONI_RAFT_CONNECTION_RETRY_TIME: (optional) interval in seconds between reconnection attempts to offline nodes. Default: 5.0.
• PATRONI_RAFT_LEADER_FALLBACK_TIMEOUT: (optional) time in seconds after which a leader with no response from the majority falls back to follower state. Must be greater than PATRONI_RAFT_APPEND_ENTRIES_PERIOD. Default: 30.0.

PostgreSQL

• PATRONI_POSTGRESQL_LISTEN: Postgres listen addresses and port. Separate multiple addresses with commas and append the port after the last address: listen: 127.0.0.1,127.0.0.2:5432. Patroni uses the first address for local PostgreSQL connections.
• PATRONI_POSTGRESQL_CONNECT_ADDRESS: IP address + port through which Postgres is accessible from other nodes and applications.
• PATRONI_POSTGRESQL_PROXY_ADDRESS: address and port of the connection pool beside Postgres, such as pgbouncer. Patroni stores it as proxy_url in the DCS member key for service discovery.
• PATRONI_POSTGRESQL_DATA_DIR: The location of the Postgres data directory, either existing or to be initialized by Patroni.
• PATRONI_POSTGRESQL_CONFIG_DIR: The location of the Postgres configuration directory, defaults to the data directory. Must be writable by Patroni.
• PATRONI_POSTGRESQL_BIN_DIR: PostgreSQL binary directory: pg_ctl, initdb, pg_controldata, pg_basebackup, postgres, pg_isready, and pg_rewind. The default empty string uses PATH to find executables.
• PATRONI_POSTGRESQL_BIN_PG_CTL: (optional) Custom name for pg_ctl binary.
• PATRONI_POSTGRESQL_BIN_INITDB: (optional) Custom name for initdb binary.
• PATRONI_POSTGRESQL_BIN_PG_CONTROLDATA: (optional) Custom name for pg_controldata binary.
• PATRONI_POSTGRESQL_BIN_PG_BASEBACKUP: (optional) Custom name for pg_basebackup binary.
• PATRONI_POSTGRESQL_BIN_POSTGRES: (optional) Custom name for postgres binary.
• PATRONI_POSTGRESQL_BIN_IS_READY: (optional) Custom name for pg_isready binary.
• PATRONI_POSTGRESQL_BIN_PG_REWIND: (optional) Custom name for pg_rewind binary.
• PATRONI_POSTGRESQL_PGPASS: path to the .pgpass password file. Patroni creates this file before executing pg_basebackup and under some other circumstances. The location must be writable by Patroni.
• PATRONI_REPLICATION_USERNAME: replication username; the user will be created during initialization. Replicas will use this user to access the replication source via streaming replication
• PATRONI_REPLICATION_PASSWORD: replication password; the user will be created during initialization.
• PATRONI_REPLICATION_SSLMODE: (optional) maps to sslmode. Specifies the TLS negotiation mode. See the PostgreSQL documentation for each mode. Default: prefer.
• PATRONI_REPLICATION_SSLKEY: (optional) maps to sslkey. Path to the secret key for the client certificate.
• PATRONI_REPLICATION_SSLPASSWORD: (optional) maps to sslpassword. Password for the secret key in PATRONI_REPLICATION_SSLKEY.
• PATRONI_REPLICATION_SSLCERT: (optional) maps to sslcert. Path to the client certificate.
• PATRONI_REPLICATION_SSLROOTCERT: (optional) maps to sslrootcert. File containing one or more trusted CA certificates. The client uses them to verify the server certificate.
• PATRONI_REPLICATION_SSLCRL: (optional) maps to sslcrl. Certificate revocation list file. The client rejects servers whose certificates appear in the list.
• PATRONI_REPLICATION_SSLCRLDIR: (optional) maps to sslcrldir. Directory containing certificate revocation list files. The client rejects servers whose certificates appear in these lists.
• PATRONI_REPLICATION_SSLNEGOTIATION: (optional) maps to sslnegotiation. Controls server SSL negotiation when SSL is used.
• PATRONI_REPLICATION_GSSENCMODE: (optional) maps to gssencmode. Controls whether to negotiate secure GSS TCP/IP and its priority.
• PATRONI_REPLICATION_CHANNEL_BINDING: (optional) maps to channel_binding. Controls client channel binding.
• PATRONI_SUPERUSER_USERNAME: name for the superuser, set during initialization (initdb) and later used by Patroni to connect to the postgres. Also this user is used by pg_rewind.
• PATRONI_SUPERUSER_PASSWORD: password for the superuser, set during initialization (initdb).
• PATRONI_SUPERUSER_SSLMODE: (optional) maps to sslmode. Specifies the TLS negotiation mode. See the PostgreSQL documentation for each mode. Default: prefer.
• PATRONI_SUPERUSER_SSLKEY: (optional) maps to sslkey. Path to the secret key for the client certificate.
• PATRONI_SUPERUSER_SSLPASSWORD: (optional) maps to sslpassword. Password for the secret key in PATRONI_SUPERUSER_SSLKEY.
• PATRONI_SUPERUSER_SSLCERT: (optional) maps to sslcert. Path to the client certificate.
• PATRONI_SUPERUSER_SSLROOTCERT: (optional) maps to sslrootcert. File containing one or more trusted CA certificates. The client uses them to verify the server certificate.
• PATRONI_SUPERUSER_SSLCRL: (optional) maps to sslcrl. Certificate revocation list file. The client rejects servers whose certificates appear in the list.
• PATRONI_SUPERUSER_SSLCRLDIR: (optional) maps to sslcrldir. Directory containing certificate revocation list files. The client rejects servers whose certificates appear in these lists.
• PATRONI_SUPERUSER_SSLNEGOTIATION: (optional) maps to sslnegotiation. Controls server SSL negotiation when SSL is used.
• PATRONI_SUPERUSER_GSSENCMODE: (optional) maps to gssencmode. Controls whether to negotiate secure GSS TCP/IP and its priority.
• PATRONI_SUPERUSER_CHANNEL_BINDING: (optional) maps to channel_binding. Controls client channel binding.
• PATRONI_REWIND_USERNAME: (optional) name for the user for pg_rewind; the user will be created during initialization of postgres 11+ and all necessary permissions will be granted.
• PATRONI_REWIND_PASSWORD: (optional) password for the user for pg_rewind; the user will be created during initialization.
• PATRONI_REWIND_SSLMODE: (optional) maps to sslmode. Specifies the TLS negotiation mode. See the PostgreSQL documentation for each mode. Default: prefer.
• PATRONI_REWIND_SSLKEY: (optional) maps to sslkey. Path to the secret key for the client certificate.
• PATRONI_REWIND_SSLPASSWORD: (optional) maps to sslpassword. Password for the secret key in PATRONI_REWIND_SSLKEY.
• PATRONI_REWIND_SSLCERT: (optional) maps to sslcert. Path to the client certificate.
• PATRONI_REWIND_SSLROOTCERT: (optional) maps to sslrootcert. File containing one or more trusted CA certificates. The client uses them to verify the server certificate.
• PATRONI_REWIND_SSLCRL: (optional) maps to sslcrl. Certificate revocation list file. The client rejects servers whose certificates appear in the list.
• PATRONI_REWIND_SSLCRLDIR: (optional) maps to sslcrldir. Directory containing certificate revocation list files. The client rejects servers whose certificates appear in these lists.
• PATRONI_REWIND_SSLNEGOTIATION: (optional) maps to sslnegotiation. Controls server SSL negotiation when SSL is used.
• PATRONI_REWIND_GSSENCMODE: (optional) maps to gssencmode. Controls whether to negotiate secure GSS TCP/IP and its priority.
• PATRONI_REWIND_CHANNEL_BINDING: (optional) maps to channel_binding. Controls client channel binding.

REST API

• PATRONI_RESTAPI_THREAD_POOL_SIZE: size of thread pool used by Patroni to process REST API requests. Minimal value is 5, default value is 5.
• PATRONI_RESTAPI_CONNECT_ADDRESS: IP address and port to access the REST API.
• PATRONI_RESTAPI_LISTEN: IP address and port that Patroni will listen to, to provide health-check information for HAProxy.
• PATRONI_RESTAPI_USERNAME: Basic-auth username to protect unsafe REST API endpoints.
• PATRONI_RESTAPI_PASSWORD: Basic-auth password to protect unsafe REST API endpoints.
• PATRONI_RESTAPI_CERTFILE: Specifies the file with the certificate in the PEM format. If the certfile is not specified or is left empty, the API server will work without SSL.
• PATRONI_RESTAPI_KEYFILE: Specifies the file with the secret key in the PEM format.
• PATRONI_RESTAPI_KEYFILE_PASSWORD: Specifies a password for decrypting the keyfile.
• PATRONI_RESTAPI_CAFILE: Specifies the file with the CA_BUNDLE with certificates of trusted CAs to use while verifying client certs.
• PATRONI_RESTAPI_CIPHERS: (optional) Specifies the permitted cipher suites (e.g. “ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”)
• PATRONI_RESTAPI_VERIFY_CLIENT: (optional) client certificate verification mode: none (default), optional, or required. none disables verification. required requires certificates for all calls; successful signature verification authenticates the client. optional requires and checks certificates only for unsafe PUT, POST, PATCH, and DELETE requests.
• PATRONI_RESTAPI_ALLOWLIST: (optional) hosts permitted to call unsafe endpoints. Each entry can be a host name, IP address, or CIDR network. Default: allow all. With allowlist or allowlist_include_members set, all unlisted sources are rejected.
• PATRONI_RESTAPI_ALLOWLIST_INCLUDE_MEMBERS: (optional) if true, permits unsafe endpoint access from cluster members registered in the DCS. It uses each member’s api_url host name or IP address. The operating system may use a different address for outgoing connections.
• PATRONI_RESTAPI_HTTP_EXTRA_HEADERS: (optional) HTTP headers let the REST API server pass additional information with an HTTP response.
• PATRONI_RESTAPI_HTTPS_EXTRA_HEADERS: (optional) HTTPS headers let the REST API server pass additional information with an HTTP response when TLS is enabled. This will also pass additional information set in http_extra_headers.
• PATRONI_RESTAPI_REQUEST_QUEUE_SIZE: (optional): Sets request queue size for TCP socket used by Patroni REST API. Once the queue is full, further requests get a “Connection denied” error. The default value is 5.
• PATRONI_RESTAPI_SERVER_TOKENS: (optional) Configures the value of the Server HTTP header. Original (default) will expose the original behaviour and display the BaseHTTP and Python versions, e.g. BaseHTTP/0.6 Python/3.12.3. Minimal: The header will contain only the Patroni version, e.g. Patroni/4.0.0. ProductOnly: The header will contain only the product name, e.g. Patroni.

CTL

• PATRONICTL_CONFIG_FILE: (optional) location of the configuration file.
• PATRONI_CTL_USERNAME: (optional) Basic-auth username for accessing protected REST API endpoints. If not provided patronictl will use the value provided for REST API “username” parameter.
• PATRONI_CTL_PASSWORD: (optional) Basic-auth password for accessing protected REST API endpoints. If not provided patronictl will use the value provided for REST API “password” parameter.
• PATRONI_CTL_INSECURE: (optional) Allow connections to REST API without verifying SSL certs.
• PATRONI_CTL_CACERT: (optional) CA_BUNDLE file or directory with trusted CAs for REST API SSL verification. If absent, patronictl uses the REST API “cafile” value.
• PATRONI_CTL_CERTFILE: (optional) Specifies the file with the client certificate in the PEM format.
• PATRONI_CTL_KEYFILE: (optional) Specifies the file with the client secret key in the PEM format.
• PATRONI_CTL_KEYFILE_PASSWORD: (optional) Specifies a password for decrypting the client keyfile.