Skip to content

Configuration Reference

The pgEdge Control Plane server can be configured with a JSON-formatted configuration file, environment variables, or a combination of both. If you're using a configuration file, you can provide it to the pgEdge Control Plane server command with the -c or --config parameter.

This reference uses a JSON-path like syntax to denote a nested property; for example:

property.sub_property.

Use a comma-separated string to specify string array properties, such as client_addresses, via an environment variable, e.g.:

PGEDGE_CLIENT_ADDRESSES='192.168.1.2,my-host.internal'

Required Settings

Property Environment variable Type Description Constraints
data_dir PGEDGE_DATA_DIR string A directory path where the Control Plane application data will be stored. This includes the server's internal database and configuration files as well as the data and configuration files for each Postgres database instance managed by this Control Plane server.

Optional Settings

Property Environment variable Type Default Description Constraints
host_id PGEDGE_HOST_ID string Defaults to the short hostname (hostname -s) A logical identifier for the host that the Control Plane server is running on. This ID must be stable and unique to each Control Plane server instance. Must be 1-63 characters long and contain only lower-cased letters, numbers, and hyphens (-). It must also start and end with either a lower-cased letter or number.
peer_addresses PGEDGE_PEER_ADDRESSES string array IP address of the first non-loopback interface The addresses that are advertised to other hosts in the Cluster. These addresses are used for inter-host communication, such as Etcd and database replication traffic. These can be IP addresses and/or DNS names.
client_addresses PGEDGE_CLIENT_ADDRESSES string array IP address of the first non-loopback interface The addresses that are advertised to API clients in the connection_info field for instances running on this host. These can be IP addresses and/or DNS names.
stop_grace_period_seconds PGEDGE_STOP_GRACE_PERIOD_SECONDS int 30 Controls the graceful shutdown period of the Control Plane server.
etcd_mode PGEDGE_ETCD_MODE string server Determines whether this Control Plane server acts as an Etcd server or as a client only. Must be one of: server or client.
mqtt.enabled PGEDGE_MQTT__ENABLED boolean false Exposes the Control Plane API over MQTT in addition to the default HTTP server.
mqtt.broker_url PGEDGE_MQTT__BROKER_URL string URL to an MQTT broker for the MQTT integration.
mqtt.topic PGEDGE_MQTT__TOPIC string The MQTT topic that the Control Plane server will subscribe to.
mqtt.client_id PGEDGE_MQTT__CLIENT_ID string The client ID that the Control Plane uses when connecting to the MQTT broker.
mqtt.username PGEDGE_MQTT__USERNAME string The username that the Control Plane uses when connecting to the MQTT broker.
mqtt.password PGEDGE_MQTT__PASSWORD string The password that the Control Plane uses when connecting to the MQTT broker.
http.bind_addr PGEDGE_HTTP__BIND_ADDR string 0.0.0.0 The address that the Control Plane HTTP server will listen on. Defaults to 0.0.0.0 to listen on all interfaces. Must be accessible by other Control Plane server instances in this cluster.
http.port PGEDGE_HTTP__PORT int 3000 The port that the Control Plane HTTP server will listen on.
logging.level PGEDGE_LOGGING__LEVEL string info The log level for the Control Plane server. Must be one of: trace, debug, info, warn, error, fatal, or panic
logging.pretty PGEDGE_LOGGING__PRETTY boolean false Enables human-readable logs and colorization.
logging.component_levels.<component_name> PGEDGE_LOGGING__COMPONENT_LEVELS_<COMPONENT_NAME> string Enables you to set per-component log levels. The list of components are available in Components. Must be one of: trace, debug, info, warn, error, fatal, or panic
etcd_server.log_level PGEDGE_ETCD_SERVER__LOG_LEVEL string fatal The log level for the embedded Etcd server.
etcd_server.peer_port PGEDGE_ETCD_SERVER__PEER_PORT int 2380 The port that the embedded Etcd server will listen on for peer connections.
etcd_server.client_port PGEDGE_ETCD_SERVER__CLIENT_PORT int 2379 The port that the embedded Etcd server will listen on for client connections.
etcd_client.log_level PGEDGE_ETCD_CLIENT__LOG_LEVEL string fatal The log level for Etcd client operations performed by this Control Plane server.
docker_swarm.image_repository_host PGEDGE_DOCKER_SWARM__IMAGE_REPOSITORY_HOST string ghcr.io/pgedge The base URL of pgEdge Docker images.
docker_swarm.manifest_url PGEDGE_DOCKER_SWARM__MANIFEST_URL string pgEdge hosted manifest URL Overrides the default version manifest URL. Set to an internal endpoint for air-gapped deployments or a staging URL for pre-release image testing. When set to a custom URL, the Control Plane falls back to the disk cache if the URL is unreachable, but does not fall back to the embedded manifest - an error is returned if both sources fail.
docker_swarm.manifest_path PGEDGE_DOCKER_SWARM__MANIFEST_PATH string Path to a local version manifest file. When set, all remote URL fetching is skipped and the manifest is loaded exclusively from this file. Intended for air-gapped deployments where no outbound network access is available. See Container Image Management.
docker_swarm.database_networks_cidr PGEDGE_DOCKER_SWARM__DATABASE_NETWORKS_CIDR string 10.128.128.0/18 (Docker Swarm only) The CIDR used to allocate per-database networks. Must not be changed after creating databases.
docker_swarm.database_networks_subnet_bits PGEDGE_DOCKER_SWARM__DATABASE_NETWORKS_SUBNET_BITS int 26 (Docker Swarm only) The subnet size for per-database networks. Must not be changed after creating databases.
systemd.instance_data_dir PGEDGE_SYSTEMD__INSTANCE_DATA_DIR string /var/lib/pgsql (RHEL-like) or /var/lib/postgresql (Debian-based) (systemd only) The base directory for Postgres instance data directories.
systemd.pgbackrest_path PGEDGE_SYSTEMD__PGBACKREST_PATH string /usr/bin/pgbackrest (systemd only) The path to the pgbackrest binary. Must not be empty.
systemd.patroni_path PGEDGE_SYSTEMD__PATRONI_PATH string /usr/bin/patroni (systemd only) The path to the patroni binary. Must not be empty.
database_owner_uid PGEDGE_DATABASE_OWNER_UID int Defaults to the postgres user's UID The UID to use for database configuration and data. Must match the UID that owns the Postgres server processes.
database_owner_gid PGEDGE_DATABASE_OWNER_GID int Defaults to the postgres user's GID The GID to use for database configuration and data. Must match the GID that owns the Postgres server processes.
databases_monitor_interval_seconds PGEDGE_DATABASES_MONITOR_INTERVAL_SECONDS uint 30 The refresh interval for the 'databases' monitor. This monitor watches for database version changes that happen outside of the Control Plane API, such as through a system package update. Set to 0 to disable this monitor.

Components

This is the current list of components that can be configured in the logging.component_levels setting:

  • api_server
  • database_service
  • election_candidate
  • embedded_etcd
  • migration
  • migration_runner
  • ports_service
  • remote_etcd
  • scheduler_service
  • workflows_backend
  • workflows_worker