.. SPDX-FileCopyrightText: 2021 Dalibo
..
.. SPDX-License-Identifier: GPL-3.0-or-later

Patroni
=======

PostgreSQL high availability is achieved by using the `patroni` plugin of
pglift. This needs to be set up through a non-``null`` value for the
``patroni`` key in site settings:

.. code-block:: yaml
   :caption: settings.yaml

    patroni: {}

With the above settings, pglift assumes that an *open* etcd server is
available at ``127.0.0.1:2379``. It may be required to configure the etcd
hosts address:

.. code-block:: yaml
   :caption: settings.yaml

    patroni:
      etcd:
        hosts:
        - 192.168.60.21:2379
        - 192.168.60.21:2380

Settings and Patroni configuration
----------------------------------

The Patroni configuration file is generated from configuration
managed by pglift (based on settings and arguments) and from a
template which may be :ref:`overridden<configuration_templates>`.

The ``patroni.yaml`` template contains this configuration by
default:

.. literalinclude:: ../../../lib/src/pglift/patroni/patroni.yaml
   :language: yaml
   :caption: patroni/patroni.yaml

The configuration managed by pglift always takes precedence to ensure
proper functionality, while additional user inputs enrich the
configuration.

Security
--------

Protecting Etcd
~~~~~~~~~~~~~~~

Through site settings, it is possible to secure communication between Patroni
and etcd via TLS.

The settings would look like the following:

.. code-block:: yaml
   :caption: settings.yaml

    patroni:
      […]
      etcd:
        protocol: https
        cacert: /path/to/cacert.crt
        cert: /path/to/client.crt
        key: /path/to/client.key

Those settings are actually copied to the etcd section in Patroni YAML
configuration file that pglift generates at instance creation.

At least the ``protocol: https`` should be specified to require TLS encryption
from Patroni to Etcd. Unless the root certificate for the authority is
available in system's store, the ``cacert`` should be specified as well.

Then, client certificates ``cert`` and ``key`` can be specified to enable TLS
authentication provided that the etcd server runs with client certificate
authentication enabled (``--client-cert-auth`` and ``--trusted-ca-file``
command-line options for etcd); this configuration provides a global
authentication, but no role-based security.

For role-based authorization, the etcd server must have roles and users
defined and authentication enabled. Then, at instance setup, the
``--patroni-etcd-{username,password}`` command-line options of ``pglift
instance create`` should be used to configure the connection user to etcd.

.. warning::
   Basic authentication works by writing Etcd username and password to the
   Patroni YAML configuration; pglift generates the file with owner-read
   permission ``600`` though.

.. note::
   Basic authentication takes precedence on the client certificates method so
   both methods should not be used together.

Protecting the REST API
~~~~~~~~~~~~~~~~~~~~~~~

To secure the patroni's REST API, the following parameters can be set:

.. code-block:: yaml
   :caption: settings.yaml

    patroni:
      […]
      restapi:
        cafile: /path/to/cacert.crt
        certfile: /path/to/client.crt
        keyfile: /path/to/client.key
        verify_client: optional

``verify_client`` must be set to either ``required`` or ``optional`` if
certificates are set. Please refer to `patroni' s official documentation
<https://patroni.readthedocs.io/en/latest/yaml_configuration.html#rest-api>`_.

Basic authentication can be configured when creating an instance with
the ``pglift instance create`` command. To enable such authentication the
``--patroni-restapi-authentication-{username,password}`` options should be
used.

Those parameters are actually copied to the ``restapi.authentication`` section
in Patroni YAML configuration file that pglift generates at instance creation.

.. warning::
   Basic authentication should be used with transport-level encryption for proper security. It
   is strongly recommended to configure TLS certificates when using those
   authentication options.

Watchdog support
----------------

One can activate watchdog devices support via site settings. Please refer to
patroni `configuration
<https://patroni.readthedocs.io/en/latest/yaml_configuration.html#watchdog>`_
and `watchdog <https://patroni.readthedocs.io/en/latest/watchdog.html>`_
documentation.

Here's an example of settings for watchdog:

.. code-block:: yaml
   :caption: settings.yaml

    patroni:
      […]
      watchdog:
        mode: required
        device: /dev/watchdog
        safety_margin: 5

pg_rewind support
-----------------

``pg_rewind`` can be activated by adding the following settings:

.. code-block:: yaml
   :caption: settings.yaml

    patroni:
      […]
      postgresql:
        use_pg_rewind: true

The corresponding setting will go in the `patroni.postgresql
<https://patroni.readthedocs.io/en/latest/yaml_configuration.html#postgresql>`_
section in patroni configuration file.

Dynamic mode
------------

When configuring Patroni through pglift, users can control
how authentication (``pg_hba``) and PostgreSQL parameters are
managed.

.. code-block:: yaml
   :caption: settings.yaml

    patroni:
      […]
      configuration_mode:
        auth: dynamic
        parameters: dynamic

With that configuration, the authentication (``pg_hba`` entries)
and PostgreSQL ``parameters`` are managed dynamically by pglift
via the Patroni API and stored into the DCS. During instance creation,
upgrade, or conversion, the Patroni bootstrap system is responsible of
populating the DCS with the initial configuration. For subsequent
changes, such as changing parameters, the updates are sent directly to the DCS
through the Patroni API, without rewriting local configuration files
on each node.

When using the ``local`` mode, the corresponding sections
are written directly into Patroni’s configuration file on
each node.