Skip to content

Commit d20e7da

Browse files
DimCitusDimCitus
authored
Improve documentation thanks to user feedback. (#909)
1 parent efcfb73 commit d20e7da

42 files changed

Lines changed: 1314 additions & 44 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# pg_auto_failover
22

3-
[![Slack Status](http://slack.citusdata.com/badge.svg)](https://slack.citusdata.com)
43
[![Documentation Status](https://readthedocs.org/projects/pg-auto-failover/badge/?version=master)](https://pg-auto-failover.readthedocs.io/en/master/?badge=master)
54

65
pg_auto_failover is an extension and service for PostgreSQL that monitors
@@ -64,6 +63,17 @@ the packages from there.
6463

6564
### Ubuntu or Debian:
6665

66+
Binary packages for debian and derivatives (ubuntu) are available from
67+
`apt.postgresql.org`__ repository, install by following the linked
68+
documentation and then::
69+
70+
```bash
71+
$ sudo apt-get install pg-auto-failover-cli
72+
$ sudo apt-get install postgresql-14-auto-failover
73+
```
74+
75+
__ https://wiki.postgresql.org/wiki/Apt
76+
6777
When using debian, two packages are provided for pg_auto_failover: the
6878
monitor Postgres extension is packaged separately and depends on the
6979
Postgres version you want to run for the monitor itself. The monitor's
@@ -74,15 +84,17 @@ Then another package is prepared that contains the `pg_autoctl` command, and
7484
the name of the package is `pg-auto-failover-cli`. That's the package that
7585
is needed for the Postgres nodes.
7686

77-
```bash
78-
# Add the repository to your system
79-
curl https://install.citusdata.com/community/deb.sh | sudo bash
87+
To avoid debian creating a default Postgres data directory and service,
88+
follow these steps before installing the previous packages.
8089

81-
# Install pg_auto_failover
82-
sudo apt-get install postgresql-11-auto-failover
90+
```bash
91+
$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
92+
$ echo "deb http://apt.postgresql.org/pub/repos/apt buster-pgdg main" > /etc/apt/sources.list.d/pgdg.list
8393

84-
# Confirm installation
85-
/usr/bin/pg_autoctl --version
94+
# bypass initdb of a "main" cluster
95+
$ echo 'create_main_cluster = false' | sudo tee -a /etc/postgresql-common/createcluster.conf
96+
$ apt-get update
97+
$ apt-get install -y --no-install-recommends postgresql-14
8698
```
8799

88100
### Fedora, CentOS, or Red Hat:
@@ -193,6 +205,8 @@ Once the building and installation is done, follow those steps:
193205
4. See the state of the new system:
194206
195207
~~~ bash
208+
$ export PGDATA=./monitor
209+
$ export PGPORT=5000
196210
$ pg_autoctl show state
197211
Name | Node | Host:Port | LSN | Reachable | Current State | Assigned State
198212
-------+-------+----------------+-----------+-----------+---------------------+--------------------

‎docs/failover-state-machine.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _failover_state_machine:
2+
13
Failover State Machine
24
======================
35

‎docs/faq.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,33 @@ When things are not obvious, the next step is to go read the logs. Both the
9696
output of the ``pg_autoctl`` command and the Postgres logs are relevant. See
9797
the :ref:`logs` question for details.
9898

99+
Impossible / unresolveable state after crash - How to recover?
100+
--------------------------------------------------------------
101+
102+
The pg_auto_failover :ref:`failover_state_machine` is great to simplify node
103+
management and orchestrate multi-nodes operations such as a switchover or a
104+
failover. That said, it might happen that the FSM is unable to proceed in
105+
some cases, usually after a hard crash of some components of the system, and
106+
mostly due to bugs.
107+
108+
Even if we have an extensive test suite to prevent such bugs from happening,
109+
you might have to deal with a situation that the monitor doesn't know how to
110+
solve.
111+
112+
The FSM has been designed with a last resort operation mode. It is always
113+
possible to unregister a node from the monitor with the
114+
:ref:`pg_autoctl_drop_node` command. This helps the FSM getting back to a
115+
simpler situation, the simplest possible one being when only one node is
116+
left registered in a given formation and group (state is then SINGLE).
117+
118+
When the monitor is back on its feet again, then you may add your nodes
119+
again with the :ref:`pg_autoctl_create_postgres` command. The command
120+
understands that a Postgres service is running and will recover from where
121+
you left.
122+
123+
In some cases you might have to also delete the local pg_autoctl state file,
124+
error messages will instruct you about the situation.
125+
99126
The monitor is a SPOF in pg_auto_failover design, how should we handle that?
100127
----------------------------------------------------------------------------
101128

‎docs/index.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,40 @@
66
Welcome to pg_auto_failover's documentation!
77
============================================
88

9+
The pg_auto_failover project is an Open Source Software project. The
10+
development happens at `https://github.com/citusdata/pg_auto_failover`__ and
11+
is public: everyone is welcome to participate by opening issues or pull
12+
requests, giving feedback, etc.
13+
14+
Remember that the first steps are to actually play with the pg_autoctl
15+
command, then read the entire available documentation (after all, I took the
16+
time to write it), and then to address the community in a kind and polite
17+
way — the same way you would expect people to use when addressing you.
18+
19+
__ https://github.com/citusdata
20+
21+
.. note::
22+
23+
The development of pg_auto_failover has been driven by Citus Data, since
24+
then a team at Microsoft. The Citus Data team at Microsoft generously
25+
maintains the pg_auto_failover Open Source Software so that its users may
26+
continue using it in production.
27+
28+
The pg_auto_failover Open Source project does not include support for the
29+
Citus extension. Citus support in pg_auto_failover has not been Open
30+
Sourced at this time.
31+
32+
For enhancements, improvements, and new features, consider contributing
33+
to the project. Pull Requests are reviewed as part of the offered
34+
maintenance.
35+
36+
.. note::
37+
38+
Assistance is provided as usual with Open Source projects, on a voluntary
39+
basis. If you need help to cook a patch, enhance the documentation, or
40+
even to use the software, you're welcome to ask questions and expect some
41+
level of free guidance.
42+
943
.. toctree::
1044
:maxdepth: 4
1145
:caption: Contents:

‎docs/install.rst‎

Lines changed: 35 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
Installing pg_auto_failover
44
===========================
55

6-
We provide native system packages for pg_auto_failover on most popular Linux distributions.
6+
We provide native system packages for pg_auto_failover on most popular Linux
7+
distributions.
78

89
Use the steps below to install pg_auto_failover on PostgreSQL 11. At the
910
current time pg_auto_failover is compatible with both PostgreSQL 10 and
@@ -12,50 +13,48 @@ PostgreSQL 11.
1213
Ubuntu or Debian
1314
----------------
1415

15-
Quick install
16-
~~~~~~~~~~~~~
17-
18-
The following installation method downloads a bash script that automates
19-
several steps. The full script is available for review at our `package cloud
20-
installation instructions`__ page.
21-
22-
__ https://packagecloud.io/citusdata/community/install#bash
23-
24-
.. code-block:: bash
25-
26-
# add the required packages to your system
27-
curl https://install.citusdata.com/community/deb.sh | sudo bash
28-
29-
# install pg_auto_failover
30-
sudo apt-get install postgresql-11-auto-failover
31-
32-
# confirm installation
33-
/usr/bin/pg_autoctl --version
16+
Postgres apt repository
17+
~~~~~~~~~~~~~~~~~~~~~~~
3418

35-
Manual Installation
36-
~~~~~~~~~~~~~~~~~~~
19+
Binary packages for debian and derivatives (ubuntu) are available from
20+
`apt.postgresql.org`__ repository, install by following the linked
21+
documentation and then::
3722

38-
If you'd prefer to install your repo on your system manually, follow the
39-
instructions from `package cloud manual installation`__ page. This page will
40-
guide you with the specific details to achieve the 3 steps:
23+
$ sudo apt-get install pg-auto-failover-cli
24+
$ sudo apt-get install postgresql-14-auto-failover
4125

42-
__ https://packagecloud.io/citusdata/community/install#manual
26+
__ https://wiki.postgresql.org/wiki/Apt
4327

44-
1. install CitusData GnuPG key for its package repository
45-
2. install a new apt source for CitusData packages
46-
3. update your available package list
28+
The Postgres extension named "pgautofailover" is only necessary on the
29+
monitor node. To install that extension, you can install the
30+
``postgresql-14-auto-failover`` package when using Postgres 14. It's
31+
available for other Postgres versions too.
4732

48-
Then when that's done, you can proceed with installing pg_auto_failover
49-
itself as in the previous case:
33+
Avoiding the default Postgres service
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5035

51-
.. code-block:: bash
36+
When installing the debian Postgres package, the installation script will
37+
initialize a Postgres data directory automatically, and register it to the
38+
systemd services. When using pg_auto_failover, it is best to avoid that step.
5239

53-
# install pg_auto_failover
54-
sudo apt-get install postgresql-11-auto-failover
40+
To avoid automated creation of a Postgres data directory when installing the
41+
debian package, follow those steps:
5542

56-
# confirm installation
57-
/usr/bin/pg_autoctl --version
43+
::
44+
45+
$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
46+
$ echo "deb http://apt.postgresql.org/pub/repos/apt buster-pgdg main" > /etc/apt/sources.list.d/pgdg.list
47+
48+
# bypass initdb of a "main" cluster
49+
$ echo 'create_main_cluster = false' | sudo tee -a /etc/postgresql-common/createcluster.conf
50+
$ apt-get update
51+
$ apt-get install -y --no-install-recommends postgresql-14
5852

53+
That way when it's time to :ref:`pg_autoctl_create_monitor` or
54+
:ref:`pg_autoctl_create_postgres` there is no confusion about how to handle
55+
the default Postgres service created by debian: it has not been created at
56+
all.
57+
5958
Fedora, CentOS, or Red Hat
6059
--------------------------
6160

‎docs/operations.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,23 @@ pg_auto_failover monitor. The ``pg_autoctl create`` command honors the
1919
running. If Postgres is detected, the new node is registered in SINGLE mode,
2020
bypassing the monitor's role assignment policy.
2121

22+
Postgres configuration management
23+
---------------------------------
24+
25+
The :ref:`pg_autoctl_create_postgres` command edits the default Postgres
26+
configuration file (``postgresql.conf``) to include pg_auto_failover
27+
settings.
28+
29+
The include directive is placed on the top of the ``postgresql.conf`` file
30+
in a way that you may override any setting by editing it later in the file.
31+
32+
Unless using the ``--skip-pg-hba`` option then pg_autoctl edits a minimal
33+
set of HBA rules for you, in order for the pg_auto_failover nodes to be able
34+
to connect to each other. The HBA rules that are needed for your application
35+
to connect to your Postgres nodes still need to be added. As pg_autoctl
36+
knows nothing about your applications, then you are responsible for editing
37+
the HBA file.
38+
2239
Upgrading pg_auto_failover, from versions 1.4 onward
2340
-----------------------------------------------------
2441

‎docs/ref/pg_autoctl.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,3 +140,13 @@ A typical JSON output would be::
140140
This is for version 1.4.2 of pg_auto_failover. This particular version of
141141
the pg_autoctl client tool has been compiled using ``libpq`` for PostgreSQL
142142
12.3 and is compatible with Postgres 10, 11, 12, and 13.
143+
144+
Environment
145+
-----------
146+
147+
PG_AUTOCTL_DEBUG
148+
149+
When this environment variable is set (to anything) then ``pg_autoctl``
150+
allows more commands. Use with care, this opens abilities to destroy your
151+
production clusters.
152+

‎docs/ref/pg_autoctl_config_check.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,35 @@ Options
3030

3131
Output JSON formatted data.
3232

33+
34+
Environment
35+
-----------
36+
37+
PGDATA
38+
39+
Postgres directory location. Can be used instead of the ``--pgdata``
40+
option.
41+
42+
PG_AUTOCTL_MONITOR
43+
44+
Postgres URI to connect to the monitor node, can be used instead of the
45+
``--monitor`` option.
46+
47+
XDG_CONFIG_HOME
48+
49+
The pg_autoctl command stores its configuration files in the standard
50+
place XDG_CONFIG_HOME. See the `XDG Base Directory Specification`__.
51+
52+
__ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
53+
54+
XDG_DATA_HOME
55+
56+
The pg_autoctl command stores its internal states files in the standard
57+
place XDG_DATA_HOME, which defaults to ``~/.local/share``. See the `XDG
58+
Base Directory Specification`__.
59+
60+
__ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
61+
3362
Examples
3463
--------
3564

‎docs/ref/pg_autoctl_config_get.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,34 @@ Options
2828

2929
Output JSON formatted data.
3030

31+
Environment
32+
-----------
33+
34+
PGDATA
35+
36+
Postgres directory location. Can be used instead of the ``--pgdata``
37+
option.
38+
39+
PG_AUTOCTL_MONITOR
40+
41+
Postgres URI to connect to the monitor node, can be used instead of the
42+
``--monitor`` option.
43+
44+
XDG_CONFIG_HOME
45+
46+
The pg_autoctl command stores its configuration files in the standard
47+
place XDG_CONFIG_HOME. See the `XDG Base Directory Specification`__.
48+
49+
__ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
50+
51+
XDG_DATA_HOME
52+
53+
The pg_autoctl command stores its internal states files in the standard
54+
place XDG_DATA_HOME, which defaults to ``~/.local/share``. See the `XDG
55+
Base Directory Specification`__.
56+
57+
__ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
58+
3159
Description
3260
-----------
3361

‎docs/ref/pg_autoctl_config_set.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,34 @@ Options
2828

2929
Output JSON formatted data.
3030

31+
Environment
32+
-----------
33+
34+
PGDATA
35+
36+
Postgres directory location. Can be used instead of the ``--pgdata``
37+
option.
38+
39+
PG_AUTOCTL_MONITOR
40+
41+
Postgres URI to connect to the monitor node, can be used instead of the
42+
``--monitor`` option.
43+
44+
XDG_CONFIG_HOME
45+
46+
The pg_autoctl command stores its configuration files in the standard
47+
place XDG_CONFIG_HOME. See the `XDG Base Directory Specification`__.
48+
49+
__ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
50+
51+
XDG_DATA_HOME
52+
53+
The pg_autoctl command stores its internal states files in the standard
54+
place XDG_DATA_HOME, which defaults to ``~/.local/share``. See the `XDG
55+
Base Directory Specification`__.
56+
57+
__ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
58+
3159
Description
3260
-----------
3361

0 commit comments

Comments
 (0)