.. _pg_autoctl_node: pg_autoctl node =============== pg_autoctl node - Declarative node lifecycle from a single configuration file Synopsis -------- ``pg_autoctl node`` manages the full lifecycle of a pg_auto_failover node — creation, startup, and live reconfiguration — driven by a single ``pg_autoctl_node.ini`` file rather than long sequences of command-line flags:: pg_autoctl node run Create (if needed) and run a node described by a pg_autoctl_node.ini file apply Apply mutable settings from a pg_autoctl_node.ini to a running node start Start a node waiting in launch=deferred mode (idempotent) show Dump current node configuration as a pg_autoctl_node.ini file check Validate a pg_autoctl_node.ini file without creating anything .. toctree:: :maxdepth: 1 pg_autoctl_node_run pg_autoctl_node_apply pg_autoctl_node_start pg_autoctl_node_show pg_autoctl_node_check Description ----------- ``pg_autoctl node run `` is the recommended entry-point for container and Kubernetes deployments. The complete node description lives in one ini file that can be version-controlled, templated, and bind-mounted into a container. The same image and the same entry-point work for every node type (monitor, primary, standby, Citus coordinator, Citus worker); per-node differences live entirely in the mounted ini file. The ``pg_autoctl_node.ini`` File -------------------------------- The file uses ``.ini`` sections. A typical data node:: [node] kind = postgres name = node1 hostname = node1.internal port = 5432 [postgresql] pgdata = /var/lib/postgresql/data [monitor] pguri = postgres://autoctl_node@monitor:5432/pg_auto_failover [formation] name = default [settings] candidate_priority = 50 replication_quorum = true [options] ssl = self-signed auth = trust pg_hba_lan = true A monitor node omits ``[monitor]`` entirely:: [node] kind = monitor hostname = monitor.internal port = 5432 [postgresql] pgdata = /var/lib/postgresql/monitor [formation default] kind = pgsql Section and Property Reference ------------------------------- The following sections and properties are supported in ``pg_autoctl_node.ini``. Properties marked *mutable* can be changed on a running node by editing the file; the supervisor converges the change without restarting Postgres. Immutable properties take effect only the next time the node is created or started from scratch. ``[node]`` ^^^^^^^^^^ ``kind`` Node role. One of ``postgres``, ``monitor``, ``coordinator``, or ``worker``. Required; immutable. ``name`` Human-readable node name shown in ``pg_autoctl show state``. Defaults to the value of ``hostname`` when not set. Immutable. ``hostname`` Address that other nodes (including the monitor) use to reach this node. Defaults to the auto-detected FQDN of the host. Immutable. ``port`` Postgres port number. Defaults to ``5432``. Immutable. ``[postgresql]`` ^^^^^^^^^^^^^^^^ ``pgdata`` Path to the Postgres data directory. Required; immutable. ``[monitor]`` ^^^^^^^^^^^^^ ``pguri`` Connection string to the pg_auto_failover monitor. Omit for monitor nodes. **Mutable**: changing this value re-registers the node to the new monitor without restarting Postgres (``pg_autoctl disable monitor --force`` followed by ``pg_autoctl enable monitor ``). ``no_monitor`` Set to ``true`` to run in :ref:`pg_autoctl_disable_monitor` (standalone) mode. Immutable. ``node_id`` Node identifier to use when ``no_monitor = true``. Immutable. ``[formation]`` ^^^^^^^^^^^^^^^ ``name`` Formation name. Defaults to ``default``. Immutable. ``group`` Citus group identifier. ``0`` means coordinator. Defaults to ``0``. Immutable. ``[settings]`` ^^^^^^^^^^^^^^ Settings in this section are applied live without restarting the node. ``candidate_priority`` Failover weight, an integer from 0 to 100. A value of ``0`` means this node is never promoted to primary. Defaults to ``50``. **Mutable**. ``replication_quorum`` Whether this node participates in the synchronous replication quorum. Boolean, defaults to ``true``. **Mutable**. ``[options]`` ^^^^^^^^^^^^^ ``ssl`` SSL mode. One of ``self-signed``, ``verify-ca``, ``verify-full``, or ``off``. Defaults to ``self-signed``. **Mutable**: changes are applied via ``pg_autoctl enable ssl``; Postgres reloads SSL without a full restart. ``auth`` Authentication method written into ``pg_hba.conf`` at create time. One of ``trust``, ``md5``, ``scram``, or ``cert``. Defaults to ``trust``. Immutable (create-time only). ``pg_hba_lan`` When ``true``, add LAN-range entries to ``pg_hba.conf`` at create time. Defaults to ``true``. Immutable (create-time only). ``[ssl]`` ^^^^^^^^^ Certificate paths for ``verify-ca`` and ``verify-full`` SSL modes. All three are **mutable**: editing them and saving the file reconfigures Postgres SSL live via ``pg_autoctl enable ssl``. ``ca_file`` Path to the CA certificate file (``ssl_ca_file`` in ``postgresql.conf``). ``cert_file`` Path to the server certificate file (``ssl_cert_file``). ``key_file`` Path to the server private key file (``ssl_key_file``). ``[launch]`` ^^^^^^^^^^^^ ``mode`` When set to ``deferred``, the node starts a polling loop and waits instead of creating or starting Postgres immediately. Call ``pg_autoctl node start`` to release it. Defaults to ``immediate``. See :ref:`pg_autoctl_node_start`. ``[formation ]`` ^^^^^^^^^^^^^^^^^^^^^^ Repeat this section for each non-default formation to create. Applies to monitor nodes only. ``kind`` Formation kind. One of ``pgsql`` or ``citus``. Defaults to ``pgsql``. Immutable. Password sections ^^^^^^^^^^^^^^^^^ These sections hold credentials that are kept out of the main ini file where possible. ``[pg_auto_failover]`` ``autoctl_node_password`` — password for the ``pgautofailover_monitor`` role (monitor nodes) or the ``autoctl_node`` role (data nodes). ``[replication]`` ``replication_password`` — password for the ``pgautofailover_replicator`` role. ``[citus]`` ``role = secondary`` and ``cluster_name`` for Citus secondary clusters. Live Reconfiguration -------------------- The supervisor that ``pg_autoctl node run`` exec's into watches the ini file for changes. When it detects a write it re-reads the file and converges any **mutable** fields without restarting the node or interrupting replication: ``candidate_priority`` and ``replication_quorum`` Applied by calling ``pg_autoctl set node`` against the running node. ``ssl``, ``ca_file``, ``cert_file``, ``key_file`` Applied by calling ``pg_autoctl enable ssl`` with the appropriate flags. Postgres reloads its SSL configuration without a full restart. ``monitor.pguri`` Applied by calling ``pg_autoctl disable monitor --force`` (which removes the node from the old monitor) followed by ``pg_autoctl enable monitor `` (which registers the node to the new monitor). Postgres keeps running throughout; only the monitoring relationship changes. Changing an **immutable** field (``kind``, ``pgdata``, ``hostname``, ``port``, ``auth``, ``pg_hba_lan``) while the node is running is logged as a warning; the value takes effect the next time the node is started. The ``launch = deferred`` Pattern ---------------------------------- :: [launch] mode = deferred A node configured with ``mode = deferred`` starts a polling loop and waits. A sidecar container or init script then calls:: pg_autoctl node start /etc/pgaf/node.ini which rewrites the ini file with ``mode = immediate``. The waiting node detects the change within the poll interval and proceeds to create or run. This enables ordered startup without an external orchestrator: the monitor container can be given ``mode = immediate`` while all data nodes start with ``mode = deferred``, and each data node is released with ``node start`` only after the monitor is confirmed ready. See Also -------- :ref:`pg_autoctl_node_run`, :ref:`pg_autoctl_create_postgres`, :ref:`pg_autoctl_run`, :ref:`pg_autoctl_set`