docs: add explanatory comments to pgBackRest Ansible changes

Clarify the intent and rationale behind the less-obvious changes:
- adminapi.sudoers.conf: explain the two pgbackrest sudo chains
  (NewRunner vs NewRunnerAs) and the wrapper/real-binary split
- supabase-admin-agent.yml: explain why pgdata-chown is 0700 and
  pgdata-signal is 0755
- setup-pgbackrest.yml: explain the pgbackrest self-sudo entry,
  why conf.d needs setgid (02770), and why SAA log files must be
  pre-created before the agent runs
- pgbackrest.conf: explain expire-auto change and why the [supabase]
  stanza was removed (SAA owns it via conf.d to avoid error [031])

Author: Crispy1975

ansible/files/adminapi.sudoers.conf

@@ -15,10 +15,19 @@ Cmnd_Alias PGBOUNCER = /bin/systemctl start pgbouncer.service, /bin/systemctl st
 %adminapi ALL= NOPASSWD: /etc/adminapi/pg_upgrade_scripts/common.sh
 %adminapi ALL= NOPASSWD: /etc/adminapi/pg_upgrade_scripts/pgsodium_getkey.sh
 %adminapi ALL= NOPASSWD: /usr/bin/systemctl daemon-reload
+# pgBackRest wrapper scripts: constrained helpers called by supabase-admin-agent.
+# pgdata-chown runs as root (default); pgdata-signal runs as postgres so it can
+# create/remove signal files owned by that user.
 %adminapi ALL= NOPASSWD: /usr/local/lib/supabase-admin-agent/pgdata-chown
 %adminapi ALL=(postgres) NOPASSWD: /usr/local/lib/supabase-admin-agent/pgdata-signal
+# pgBackRest binary entries support two sudo chains used by supabase-admin-agent:
+# NewRunner()      — adminapi → /usr/bin/pgbackrest wrapper → sudo -u pgbackrest real_binary
+# NewRunnerAs()    — adminapi → sudo -u pgbackrest /usr/bin/pgbackrest → sudo -u pgbackrest real_binary
+# Both paths require the wrapper entry; NewRunner() additionally needs the real binary entry
+# because the wrapper itself calls sudo to drop privileges to the pgbackrest user.
 %adminapi ALL=(pgbackrest) NOPASSWD: /var/lib/pgbackrest/.nix-profile/bin/pgbackrest
 %adminapi ALL=(pgbackrest) NOPASSWD: /usr/bin/pgbackrest
+# pgBackRest restore stops PostgreSQL, restores PGDATA, then starts PostgreSQL.
 %adminapi ALL= NOPASSWD: /usr/bin/systemctl start postgresql.service
 %adminapi ALL= NOPASSWD: /usr/bin/systemctl stop postgresql.service
 %adminapi ALL= NOPASSWD: /usr/bin/systemctl reload postgresql.service

ansible/files/pgbackrest_config/pgbackrest.conf

@@ -4,10 +4,17 @@ archive-copy = y
 backup-standby = prefer
 compress-type = zst
 delta = y
+# expire-auto=y allows pgBackRest to expire old backups automatically after
+# each new backup completes, keeping retention in sync without a separate
+# expire command. Previously n; changed to work correctly with SAA-managed backups.
 expire-auto = y
 link-all = y
 log-level-console = info
 log-level-file = detail
 log-subprocess = y
 resume = n
 start-fast = y
+# Note: the [supabase] stanza (pg1-path, pg1-socket-path, pg1-user) has been
+# removed from this file. supabase-admin-agent owns that stanza and writes it
+# to /etc/pgbackrest/conf.d/ at enable time. Having the stanza in both places
+# causes pgBackRest error [031] (duplicate option).

ansible/tasks/internal/supabase-admin-agent.yml

@@ -45,6 +45,7 @@
     dest: /usr/local/lib/supabase-admin-agent/pgdata-chown
     owner: root
     group: root
+    # 0700: always invoked via "sudo" (as root); no other user needs execute.
     mode: "0700"
 
 - name: supabase-admin-agent - pgdata-signal script
@@ -53,6 +54,8 @@
     dest: /usr/local/lib/supabase-admin-agent/pgdata-signal
     owner: root
     group: root
+    # 0755: invoked via "sudo -u postgres"; the postgres OS user needs the
+    # world-execute bit since it is neither owner nor group member.
     mode: "0755"
 
 - name: Setting arch (amd64)

ansible/tasks/setup-pgbackrest.yml

@@ -30,6 +30,10 @@
     - 'postgres ALL=(pgbackrest) NOPASSWD: /usr/bin/bash'
     - 'postgres ALL=(pgbackrest) NOPASSWD: /usr/bin/nix'
     - 'pgbackrest ALL=(pgbackrest) NOPASSWD: /usr/bin/bash'
+    # Required for the NewRunnerAs() path: supabase-admin-agent runs the
+    # /usr/bin/pgbackrest wrapper as the pgbackrest user, but the wrapper
+    # internally calls "sudo -u pgbackrest <real_binary>". Without this entry
+    # that inner sudo fails even though the outer caller is already pgbackrest.
     - 'pgbackrest ALL=(pgbackrest) NOPASSWD: /var/lib/pgbackrest/.nix-profile/bin/pgbackrest'
 
 - name: Install pgBackRest
@@ -49,6 +53,9 @@
     path: "{{ backrest_dir['dir'] }}"
     state: directory
   loop:
+    # conf.d is setgid (02770) so files written by adminapi (postgres group)
+    # automatically inherit the postgres group. Without setgid, pgbackrest
+    # (running as the pgbackrest user) cannot read conf files created by adminapi.
     - {dir: /etc/pgbackrest/conf.d, mode: '02770'}
     - {dir: /var/lib/pgbackrest}
     - {dir: /var/spool/pgbackrest}
@@ -58,6 +65,10 @@
   when:
     - nixpkg_mode
 
+# supabase-admin-agent opens these log files with O_APPEND|O_WRONLY (no
+# O_CREATE). They must exist before SAA runs; a missing file causes the
+# pgBackRest enable command to fail before any backup work is attempted.
+# access_time/modification_time: preserve keeps this task idempotent.
 - name: Pre-create pgBackRest SAA log files
   ansible.builtin.file:
     access_time: preserve