Environment Configuration Settings

It is possible to override some of the configuration parameters defined in the Patroni configuration file using the system environment variables. This document lists all environment variables handled by Patroni. The values set via those variables always take precedence over the ones set in the Patroni configuration file.

Global/Universal

  • PATRONI_CONFIGURATION: it is possible to set the entire configuration for the Patroni via PATRONI_CONFIGURATION environment variable. In this case any other environment variables will not be considered!
  • PATRONI_NAME: name of the node where the current instance of Patroni is running. Must be unique for the cluster.
  • PATRONI_NAMESPACE: path within the configuration store where Patroni will keep information about the cluster. Default value: “/service”
  • PATRONI_SCOPE: cluster name
  • PATRONI_LOGLEVEL: sets the general logging level (see the docs for Python logging)
  • PATRONI_REQUESTS_LOGLEVEL: sets the logging level for all HTTP requests e.g. Kubernetes API calls (see the docs for Python logging)

Bootstrap configuration

It is possible to create new database users right after the successful initialization of a new cluster. This process is defined by the following variables:

  • PATRONI_<username>_PASSWORD=’<password>’
  • PATRONI_<username>_OPTIONS=’list,of,options’

Example: defining PATRONI_admin_PASSWORD=strongpasswd and PATRONI_admin_OPTIONS='createrole,createdb' will cause creation of the user admin with the password strongpasswd that is allowed to create other users and databases.

Consul

  • PATRONI_CONSUL_HOST: the host:port for the Consul endpoint.
  • PATRONI_CONSUL_URL: url for the Consul, 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_CHECKS: (optional) list of Consul health checks used for the session. If not specified Consul will use “serfHealth” in additional to the TTL based check created by Patroni. Additional checks, in particular the “serfHealth”, may cause the leader lock to expire faster than in ttl seconds when the leader instance becomes unavailable.

Etcd

  • PATRONI_ETCD_HOST: the host:port for the etcd endpoint.
  • PATRONI_ETCD_HOSTS: list of etcd endpoints in format host1:port1,host2:port2,etc…
  • PATRONI_ETCD_URL: url for the etcd, in format: http(s)://(username:password@)host:port
  • 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_SRV: Domain to search the SRV record(s) for cluster autodiscovery.
  • 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.

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_NAMESPACE: (optional) Kubernetes namespace where the Patroni pod is running. Default value is default.
  • PATRONI_KUBERNETES_LABELS: Labels in format {label1: value1, label2: value2}. These labels will be used to find existing objects (Pods and either Endpoints or ConfigMaps) associated with the current cluster. Also Patroni will set them on every object (Endpoint or ConfigMap) it creates.
  • PATRONI_KUBERNETES_SCOPE_LABEL: (optional) name of the label containing cluster name. Default value is cluster-name.
  • PATRONI_KUBERNETES_ROLE_LABEL: (optional) name of the label containing Postgres role (master or replica). Patroni will set this label on the pod it is running in. Default value is role.
  • 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) IP address of the pod Patroni is running in. This value is required when PATRONI_KUBERNETES_USE_ENDPOINTS is enabled and is used to populate the leader endpoint subsets when the pod’s PostgreSQL is promoted.
  • PATRONI_KUBERNETES_PORTS: (optional) if the Service object has the name for the port, the same name must appear in the Endpoint object, otherwise service won’t work. For example, if your service is defined as {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}}, then you have to set PATRONI_KUBERNETES_PORTS='{[{"name": "postgresql", "port": 5432}]}' and Patroni will use it for updating subsets of the leader Endpoint. This parameter is used only if PATRONI_KUBERNETES_USE_ENDPOINTS is set.

PostgreSQL

  • PATRONI_POSTGRESQL_LISTEN: IP address + port that Postgres listens to. Multiple comma-separated addresses are permitted, as long as the port component is appended after to the last one with a colon, i.e. listen: 127.0.0.1,127.0.0.2:5432. Patroni will use the first address from this list to establish local connections to the PostgreSQL node.
  • PATRONI_POSTGRESQL_CONNECT_ADDRESS: IP address + port through which Postgres is accessible from other nodes and applications.
  • 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: Path to PostgreSQL binaries. (pg_ctl, pg_rewind, pg_basebackup, postgres) The default value is an empty string meaning that PATH environment variable will be used to find the executables.
  • 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 master via streaming replication
  • PATRONI_REPLICATION_PASSWORD: replication password; the user will be created during initialization.
  • 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).

REST API

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

ZooKeeper

  • PATRONI_ZOOKEEPER_HOSTS: comma separated list of ZooKeeper cluster members: “‘host1:port1’,’host2:port2’,’etc…’”. It is important to quote every single entity!