Roman Vanicek
38c6b9324a
All checks were successful
continuous-integration/drone/push Build is passing
60 lines
4.2 KiB
Markdown
60 lines
4.2 KiB
Markdown
Postgres image with PostGIS and pg_auto_failover extensions that allows running a high-availability Postgres cluster with query load-balancing.
|
|
|
|
# How to use this image
|
|
|
|
The expected configuration is at least two `worker` nodes with one `monitor` node. The container is expected to have one or more peer configuration containers that implement query load balancing (activated using `AUTOCONFIG_LOCAL_PEER` and/or `AUTOCONFIG_REMOTE_PEERS`). One of such implementations is [docker-pgpool](/SW/docker-pgpool) that implements read-only/read-write splitting and load balancing using `pgpool`. Another is [docker-pgtraefik](/SW/docker-pgtraefik) that load balances all traffic to the primary node.
|
|
|
|
The configuration peers act as servers and this image connects to them. They can run either locally communicating over a socket or remotely over HTTP.
|
|
|
|
# Environmental variables
|
|
|
|
## General
|
|
|
|
- `AUTOCONFIG_LOG_LEVEL` Log level of the application that manages the execution (one of `trace`, `debug`, `info`, `warn`, `error`, `fatal`). Default `info`. Optional.
|
|
- `AUTOCONFIG_MODE` Determines the role of the container. Either
|
|
- empty/not set to get the behaviour of plain Postgres image
|
|
- `monitor` this container becomes a monitor (only one container should have this set)
|
|
- `postgres` this container becomes a worker (usually at least two containers have this)
|
|
|
|
No default. Required
|
|
- `AUTOCONFIG_FORMATION` Name of the pg_auto_failover formation. Default `default`. Optional
|
|
- `AUTOCONFIG_MONITOR_HOST` Hostname of the monitor node. Default none. Required.
|
|
- `AUTOCONFIG_MONITOR_PORT` Postgres port on the monitor node. Default `PGPORT` and if not set `5432`. Optional.
|
|
- `AUTOCONFIG_LOCAL_PEER` True if configuration peer container is running locally and is reachable over a socket. Default `false`. Optional.
|
|
- `AUTOCONFIG_SOCKET` Path to the socket of the locally run peer configuration container. Default `/var/run/pg_autoconfig.sock`. Optional.
|
|
- `AUTOCONFIG_REMOTE_PEERS` Hostnames with remote configuration peers separated by comma. Each hostname has format `hostname[:port]` (default port 5420). Default none. Optional.
|
|
|
|
## Security
|
|
|
|
- `AUTOCONFIG_MONITOR_PASSWORD` or `AUTOCONFIG_MONITOR_PASSWORD_FILE` password (resp. path to file with the password) that is set on the monitor node for the user `autoctl_node` and worker nodes use it to report their status in pg_auto_failover. Default none. Required.
|
|
- `AUTOCONFIG_REPLICATION_PASSWORD` or `AUTOCONFIG_REPLICATION_PASSWORD_FILE` password (resp. path to file with the password) that is set on the worker nodes for the user `pgautofailover_replicator` that allows other nodes to fetch state from the currently primary node
|
|
- `POSTGRES_USERNAME` Postgres admin user name
|
|
- `POSTGRES_PASSWORD` or `POSTGRES_PASSWORD_FILE` password (resp. path to file with the password) that is set for the user Postgres admin user
|
|
- `AUTOCONFIG_LINK_HBA_CONF` path to `pg_hba.conf` file that shall be linked to after the Postgres storage gets initialized (Postgres refuses to initialize non-empty directory with `pg_hba.conf` volume-binded from docker host). Default none. Optional.
|
|
|
|
This image does optionally deploy but does not modify the Postgres file `pg_hba.conf` using `AUTOCONFIG_LINK_HBA_CONF`. If you do not provide one then `pg_auto_failover` modifies the one you already have. However following rules are required for `pg_auto_failure` to work on monitor:
|
|
- `local all all`
|
|
- `host pg_auto_failover autoctl_node <worker ip address> scram-sha-256` (for each worker)
|
|
|
|
on worker:
|
|
- `local all all`
|
|
- `host all pgautofailover_monitor <monitor ip address> trust`
|
|
- `host replication pgautofailover_replicator <worker ip address> scram-sha-256` (for each oher worker)
|
|
|
|
## pg_auto_failover
|
|
- `XDG_CONFIG_HOME` Persistent storage for pg_auto_failover configuration
|
|
- `XDG_DATA_HOME` Persistent state of pg_auto_failover
|
|
|
|
See others in the pg_auto_failover documentation.
|
|
|
|
## Postgres
|
|
- `PGDATA` path to Postgres persistent storage.
|
|
- `PGPORT` port for Postgres to listen on. Default 5432. Optional.
|
|
- `POSTGRES_USERNAME` (see above)
|
|
- `POSTGRES_PASSWORD` or `POSTGRES_PASSWORD_FILE` (see above)
|
|
|
|
See others in postgres docker image documentation.
|
|
|
|
# Runtime status
|
|
|
|
You can check the state of the cluster by executing `pg_autoctl show state --formation <formation name ie. default>` in the container. |