feat: pg_autoctl node — declarative node lifecycle from a single ini file - #1131
Merged
Conversation
…de.ini
Adds a new pg_autoctl node sub-command tree and a NodeSpec file format
designed as the recommended entry-point for container and Kubernetes
deployments.
## pg_autoctl_node.ini sections
[node] kind (postgres|monitor|coordinator|worker), name, hostname, port
[postgresql] pgdata
[monitor] pguri (empty for monitor nodes), no_monitor, node_id
[formation] name, group
[settings] candidate_priority, replication_quorum ← mutable, applied live
[options] ssl, auth, pg_hba_lan ← create-time only
[ssl] ssl_ca_file, ssl_cert_file, ssl_key_file
[launch] mode=deferred: wait for pg_autoctl node start
[formation N] monitor only: additional named formations
## pg_autoctl node sub-commands
run <file> Read ini, create node if absent, exec() into supervisor.
Sets PG_AUTOCTL_NODESPEC so the supervisor watches for
live [settings] changes via inotify (Linux) or mtime poll.
apply <file> Converge mutable settings on an already-running node.
start [<file>] Clear launch=deferred so a waiting node run proceeds.
show Dump live config as pg_autoctl_node.ini on stdout.
check <file> Parse-only validate; print resolved fields.
## Supervisor file watcher (nodespec_watcher)
The supervisor initialises a NodeSpecWatcher when PG_AUTOCTL_NODESPEC is
set. Every tick it checks for file changes:
- Linux: drain inotify IN_CLOSE_WRITE / IN_MOVED_TO events
- Others: stat() every NODESPEC_WATCH_INTERVAL_SECS (10 s)
On change, re-parse [settings] and call nodespec_apply() to converge
mutable fields without restarting the node.
## Files
src/bin/pg_autoctl/cli_node.c / cli_node.h
src/bin/pg_autoctl/nodespec.c / nodespec.h
src/bin/pg_autoctl/supervisor.c / supervisor.h (watcher integration)
docs/ref/pg_autoctl_node.rst
docs/ref/pg_autoctl_node_run.rst
- pg_autoctl_node.rst: replace prose property list with a structured table (section/property/type/mutable/default/description), each property on its own row; fix 'disabled-monitor' label → actual ref - nodespec_apply: add ssl apply block — when [options].ssl or any [ssl] cert path changes, call 'pg_autoctl enable ssl' with the appropriate flags (--ssl-self-signed, --no-ssl, or --ssl-mode + cert paths); update nodespec_apply comment to list ssl as mutable - docs/index.rst: remove 'Container and Kubernetes' as a top-level toctree caption; the manual page is still reachable via Manual Pages - docs/operations.rst: add 'Container and Kubernetes Deployments' section describing pg_autoctl node run, live reconfiguration, and the launch=deferred pattern; cross-refs to pg_autoctl_node for details - docs/ref/configuration.rst: add 'Declarative Node Configuration' section covering pg_autoctl_node.ini sections and their relationship to pg_autoctl.cfg; cross-ref to pg_autoctl_node
When the [monitor] pguri changes in pg_autoctl_node.ini, nodespec_apply now re-registers the node to the new monitor without stopping Postgres: pg_autoctl disable monitor --force --pgdata <dir> pg_autoctl enable monitor <new_uri> --pgdata <dir> The disable step removes the node from the old monitor (--force allows this even if the old monitor is temporarily unreachable). The enable step registers the node to the new monitor and signals the running supervisor to start using the new monitor_pguri for node_active calls. Document the change in the property table and Live Reconfiguration section of pg_autoctl_node.rst.
…ction Follow the pg_autoctl_create pattern: each pg_autoctl node sub-command now has its own manual page, all listed in pg_autoctl_node.rst's toctree: pg_autoctl node run (existing) pg_autoctl node apply (new) pg_autoctl node start (new) pg_autoctl node show (new) pg_autoctl node check (new) Remove the redundant 'Container and Kubernetes Deployments' section from operations.rst. The full documentation for this feature lives in the pg_autoctl_node manual page (ref/pg_autoctl_node.rst) and its sub-pages.
The list-table rendered poorly in the Sphinx HTML theme. Replace it with the same definition-list style used throughout the other manual pages (e.g. pg_autoctl_create_postgres Options section): each property is a bare term followed by indented description paragraphs, grouped under ini-section sub-headings.
…ioning Re-add the 'Container and Kubernetes Deployments' section at the end of operations.rst with a named anchor so it can be referenced from elsewhere. Add a short note in the Provisioning section pointing to pg_autoctl node run as the declarative alternative for container and Kubernetes deployments, with a cross-reference down to the new section.
Add references to pg_autoctl node / pg_autoctl node run in all the places identified by the documentation audit: Reference pages (new See Also section): - pg_autoctl_create_postgres.rst - pg_autoctl_create_monitor.rst - pg_autoctl_create_coordinator.rst - pg_autoctl_create_worker.rst - pg_autoctl_run.rst Narrative docs (short note pointing to the declarative alternative): - how-to.rst — after the pg_autoctl run step in Quick Start - tutorial.rst — after the docker-compose.yml literalinclude - citus-quickstart.rst — after the docker-compose-scale.yml literalinclude - install.rst — after the systemd unit section
Replace the imperative pg_autoctl create postgres / pg_autoctl create monitor commands with the declarative pg_autoctl node run approach: - Add tutorial/ini/monitor.ini and tutorial/ini/postgres.ini — two small ini files that describe the monitor and every data node respectively. Data nodes share one ini file; hostname and name default to the container hostname set by Docker Compose. - Rewrite tutorial/docker-compose.yml: all PG_AUTOCTL_* environment variables are gone; each service bind-mounts its ini file at /etc/pgaf/node.ini and runs 'pg_autoctl node run'. The x-node anchor is now clean — no env vars, single command. - Update tutorial.rst to introduce the ini files before the compose file, explain that pg_autoctl node run handles both create and run, and show that live reconfiguration (candidate_priority change for node3) is done by editing the ini file rather than calling pg_autoctl set. - Replace the stale pg_autoctl_do_tmux_compose_session reference in Next steps with a pointer to the pg_autoctl_node reference and the Container and Kubernetes Deployments section.
… paths Show both approaches side by side: - Direct command (pg_autoctl set candidate-priority): immediate, no restart - Declarative ini file: explain that changing docker-compose.yml volumes requires 'docker compose up -d node3' to recreate the container, that pg_autoctl node run applies the ini diff on startup before exec'ing into the supervisor, and that once the dedicated ini file is mounted any subsequent edits to it are picked up live by the running supervisor.
Replace all pg_autoctl create coordinator/worker/monitor commands with
the declarative pg_autoctl node run approach:
New ini files:
citus/ini/monitor.ini — kind = monitor
citus/ini/coordinator.ini — kind = coordinator, shared by coord0a/coord0b
citus/ini/worker.ini — kind = worker, no group (monitor auto-assigns)
citus/ini/worker1.ini — kind = worker, group = 1
citus/ini/worker2.ini — kind = worker, group = 2
citus/ini/worker3.ini — kind = worker, group = 3
Rewritten compose files:
docker-compose-scale.yml — three services (monitor/coord/worker), each
bind-mounts its ini file; all PG_AUTOCTL_* env vars removed
docker-compose.yml — named services with per-group worker ini files;
YAML anchors kept for coord and per-group worker templates
Updated citus-quickstart.rst:
- Show all ini files with literalinclude captions before each compose file
- Explain that worker.ini without [formation] group triggers monitor
auto-assignment (right for --scale), while workerN.ini with group = N
pins the pair to a specific shard group (right for named services)
- Explain that pg_autoctl node run uses the container hostname as the
node name when name is not set in the ini file
- Replace stale pg_autoctl_do_tmux_compose_session reference in Next
steps with pointer to pg_autoctl_node and container deployments guide
This was referenced Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
pg_autoctl node, a new sub-command tree that manages the full lifecycle of a pg_auto_failover node — creation, startup, and live reconfiguration — from a singlepg_autoctl_node.inifile. This is the recommended entry-point for container and Kubernetes deployments.Motivation
The existing
pg_autoctl create ... && pg_autoctl runworkflow is flag-heavy and hard to parameterise in containers.pg_autoctl node run /etc/pgaf/node.inireplaces the per-nodecommand:lines in Docker Compose with a single image and a single entry-point; all per-node differences live in a mounted ini file.pg_autoctl_node.ini
Sections:
[node],[postgresql],[monitor],[formation],[settings](mutable),[options](create-time only),[ssl],[launch],[formation <name>](monitor: extra formations),[pg_auto_failover],[replication],[citus].Sub-commands
node run [<file>]PG_AUTOCTL_NODESPECfor live watchingnode apply <file>node start [<file>]launch=deferredso a waitingnode runproceedsnode shownode check <file>Live Reconfiguration
The supervisor watches
PG_AUTOCTL_NODESPECvia inotify (Linux) or mtime polling (macOS/others). Editing[settings]and saving the file is sufficient to convergecandidate_priorityorreplication_quorumon a running node — no restart required.Deferred Launch
A node with
mode = deferredwaits in a poll loop. A sidecar or init container callspg_autoctl node startto release it. Enables ordered startup without an external orchestrator.Container Usage
Same image, same entry-point for every node type:
Per-node differences are a bind-mount (Docker) or ConfigMap volume (Kubernetes).
Files
src/bin/pg_autoctl/cli_node.c/.h— command treesrc/bin/pg_autoctl/nodespec.c/.h— ini parser, create-argv builder, apply logicsrc/bin/pg_autoctl/supervisor.c/.h— NodeSpecWatcher integrationdocs/ref/pg_autoctl_node.rst— full reference with Docker Compose and Kubernetes examplesdocs/ref/pg_autoctl_node_run.rst— run sub-command detailRelationship to existing commands
pg_autoctl node runtranslates the ini file into the same flags and exec's into the same supervisor thatpg_autoctl create ... --runwould start. No hidden API. Existing nodes can adopt the ini-based workflow viapg_autoctl node show --pgdata <dir>.