mirror of
https://github.com/outbackdingo/patroni.git
synced 2026-08-25 14:53:37 +00:00
Extend documentation with package installation and upgrade process (#2854)
This commit is contained in:
Matt Baker
+1
-76
@@ -25,82 +25,7 @@ We report new releases information :ref:`here <releases>`.
|
||||
Technical Requirements/Installation
|
||||
-----------------------------------
|
||||
|
||||
**Pre-requirements for Mac OS**
|
||||
|
||||
To install requirements on a Mac, run the following:
|
||||
|
||||
::
|
||||
|
||||
brew install postgresql etcd haproxy libyaml python
|
||||
|
||||
.. _psycopg2_install_options:
|
||||
|
||||
**Psycopg**
|
||||
|
||||
Starting from `psycopg2-2.8 <http://initd.org/psycopg/articles/2019/04/04/psycopg-28-released/>`__ the binary version of psycopg2 will no longer be installed by default. Installing it from the source code requires C compiler and postgres+python dev packages.
|
||||
Since in the python world it is not possible to specify dependency as ``psycopg2 OR psycopg2-binary`` you will have to decide how to install it.
|
||||
|
||||
There are a few options available:
|
||||
|
||||
1. Use the package manager from your distro
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install python3-psycopg2 # install psycopg2 module on Debian/Ubuntu
|
||||
sudo yum install python3-psycopg2 # install psycopg2 on RedHat/Fedora/CentOS
|
||||
|
||||
2. Install psycopg2 from the binary package
|
||||
|
||||
::
|
||||
|
||||
pip install psycopg2-binary
|
||||
|
||||
3. Install psycopg2 from source
|
||||
|
||||
::
|
||||
|
||||
pip install psycopg2>=2.5.4
|
||||
|
||||
4. Use psycopg 3.0 instead of psycopg2
|
||||
|
||||
::
|
||||
|
||||
pip install psycopg[binary]>=3.0.0
|
||||
|
||||
**General installation for pip**
|
||||
|
||||
Patroni can be installed with pip:
|
||||
|
||||
::
|
||||
|
||||
pip install patroni[dependencies]
|
||||
|
||||
where dependencies can be either empty, or consist of one or more of the following:
|
||||
|
||||
etcd or etcd3
|
||||
`python-etcd` module in order to use Etcd as Distributed Configuration Store (DCS)
|
||||
consul
|
||||
`python-consul` module in order to use Consul as DCS
|
||||
zookeeper
|
||||
`kazoo` module in order to use Zookeeper as DCS
|
||||
exhibitor
|
||||
`kazoo` module in order to use Exhibitor as DCS (same dependencies as for Zookeeper)
|
||||
kubernetes
|
||||
`kubernetes` module in order to use Kubernetes as DCS in Patroni
|
||||
raft
|
||||
`pysyncobj` module in order to use python Raft implementation as DCS
|
||||
aws
|
||||
`boto3` in order to use AWS callbacks
|
||||
|
||||
For example, the command in order to install Patroni together with dependencies for Etcd as a DCS and AWS callbacks is:
|
||||
|
||||
::
|
||||
|
||||
pip install patroni[etcd,aws]
|
||||
|
||||
Note that external tools to call in the replica creation or custom bootstrap scripts (i.e. WAL-E) should be installed
|
||||
independently of Patroni.
|
||||
|
||||
Go :ref:`here <installation>` for guidance on installing and upgrading Patroni on various platforms.
|
||||
|
||||
.. _running_configuring:
|
||||
|
||||
|
||||
@@ -22,6 +22,7 @@ Currently supported PostgreSQL versions: 9.3 to 15.
|
||||
:caption: Contents:
|
||||
|
||||
README
|
||||
installation
|
||||
patroni_configuration
|
||||
rest_api
|
||||
replica_bootstrap
|
||||
|
||||
@@ -0,0 +1,201 @@
|
||||
.. _installation:
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Pre-requirements for Mac OS
|
||||
---------------------------
|
||||
|
||||
To install requirements on a Mac, run the following:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
brew install postgresql etcd haproxy libyaml python
|
||||
|
||||
.. _psycopg2_install_options:
|
||||
|
||||
Psycopg
|
||||
-------
|
||||
|
||||
Starting from `psycopg2-2.8`_ the binary version of psycopg2 will no longer be installed by default. Installing it from
|
||||
the source code requires C compiler and postgres+python dev packages. Since in the python world it is not possible to
|
||||
specify dependency as ``psycopg2 OR psycopg2-binary`` you will have to decide how to install it.
|
||||
|
||||
There are a few options available:
|
||||
|
||||
1. Use the package manager from your distro
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt-get install python3-psycopg2 # install psycopg2 module on Debian/Ubuntu
|
||||
sudo yum install python3-psycopg2 # install psycopg2 on RedHat/Fedora/CentOS
|
||||
|
||||
2. Install psycopg2 from the binary package
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
pip install psycopg2-binary
|
||||
|
||||
3. Install psycopg2 from source
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
pip install psycopg2>=2.5.4
|
||||
|
||||
4. Use psycopg 3.0 instead of psycopg2
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
pip install psycopg[binary]>=3.0.0
|
||||
|
||||
General installation for pip
|
||||
----------------------------
|
||||
|
||||
Patroni can be installed with pip:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
pip install patroni[dependencies]
|
||||
|
||||
where ``dependencies`` can be either empty, or consist of one or more of the following:
|
||||
|
||||
etcd or etcd3
|
||||
`python-etcd` module in order to use Etcd as Distributed Configuration Store (DCS)
|
||||
consul
|
||||
`python-consul` module in order to use Consul as DCS
|
||||
zookeeper
|
||||
`kazoo` module in order to use Zookeeper as DCS
|
||||
exhibitor
|
||||
`kazoo` module in order to use Exhibitor as DCS (same dependencies as for Zookeeper)
|
||||
kubernetes
|
||||
`kubernetes` module in order to use Kubernetes as DCS in Patroni
|
||||
raft
|
||||
`pysyncobj` module in order to use python Raft implementation as DCS
|
||||
aws
|
||||
`boto3` in order to use AWS callbacks
|
||||
|
||||
For example, the command in order to install Patroni together with dependencies for Etcd as a DCS and AWS callbacks is:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
pip install patroni[etcd,aws]
|
||||
|
||||
Note that external tools to call in the replica creation or custom bootstrap scripts (i.e. WAL-E) should be installed
|
||||
independently of Patroni.
|
||||
|
||||
.. _package_installation:
|
||||
|
||||
Package installation on Linux
|
||||
-----------------------------
|
||||
|
||||
Patroni packages may be available for your operating system, produced by the Postgres community for:
|
||||
|
||||
* RHEL, RockyLinux, AlmaLinux;
|
||||
* Debian and Ubuntu;
|
||||
* SUSE Enterprise Linux.
|
||||
|
||||
You can also find packages for direct dependencies of Patroni, like python modules that might not be available in
|
||||
the official operating system repositories.
|
||||
|
||||
For more information see the `PGDG repository`_ documentation.
|
||||
|
||||
If you are on a RedHat Enterprise Linux derivative operating system you may also require packages from EPEL, see
|
||||
`EPEL repository`_ documentation.
|
||||
|
||||
Once you have installed the PGDG repository for your OS you can install patroni.
|
||||
|
||||
.. note::
|
||||
|
||||
Patroni packages are not maintained by the Patroni developers, but rather by the Postgres community. If you
|
||||
require support please first try connecting on `Postgres slack`_.
|
||||
|
||||
Installing on Debian derivatives
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
With PGDG repo installed, see :ref:`above <package_installation>`, install Patroni via apt run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
apt-get install patroni
|
||||
|
||||
Installing on RedHat derivatives
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
With PGDG repo installed, see :ref:`above <package_installation>`, install patroni with an etcd DCS via dnf on RHEL 9
|
||||
(and derivatives) run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
dnf install patroni patroni-etcd
|
||||
|
||||
You can install etcd from PGDG if your RedHat derivative distribution does not provide packages. On the nodes that will
|
||||
host the DCS run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
dnf install 'dnf-command(config-manager)'
|
||||
dnf config-manager --enable pgdg-rhel9-extras
|
||||
dnf install etcd
|
||||
|
||||
You can replace the version of RHEL with `8` in the repo to make `pgdg-rhel8-extras` if needed. The repo name is still
|
||||
`pgdg-rhelN-extras` on RockyLinux, AlmaLinux, Oracle Linux, etc...
|
||||
|
||||
Installing on SUSE Enterprise Linux
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You might need to enable the SUSE PackageHub repositories for some dependencies. see `SUSE PackageHub`_ documentation.
|
||||
|
||||
For SLES 15 with PGDG repo installed, see :ref:`above <package_installation>`, you can install patroni using:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
zypper install patroni patroni-etcd
|
||||
|
||||
With the SUSE PackageHub repo enabled you can also install etcd:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
SUSEConnect -p PackageHub/15.5/x86_64
|
||||
zypper install etcd
|
||||
|
||||
Upgrading
|
||||
---------
|
||||
|
||||
Upgrading patroni is a very simple process, just update the software installation and restart the Patroni daemon on
|
||||
each node in the cluster.
|
||||
|
||||
However, restarting the Patroni daemon will result in a Postgres database restart. In some situations this may cause
|
||||
a failover of the primary node in your cluster, therefore it is recommended to put the cluster into maintenance mode
|
||||
until the Patroni daemon restart has been completed.
|
||||
|
||||
To put the cluster in maintenance mode, run the following command on one of the patroni nodes:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
patronictl pause --wait
|
||||
|
||||
Then on each node in the cluster, perform the package upgrade required for your OS:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
apt-get update && apt-get install patroni patroni-etcd
|
||||
|
||||
Restart the patroni daemon process on each node:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
systemctl restart patroni
|
||||
|
||||
Then finally resume monitoring of Postgres with patroni to take it out of maintenance mode:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
patronictl resume --wait
|
||||
|
||||
The cluster will now be full operational with the new version of Patroni.
|
||||
|
||||
.. _psycopg2-2.8: http://initd.org/psycopg/articles/2019/04/04/psycopg-28-released/
|
||||
.. _PGDG repository: https://www.postgresql.org/download/linux/
|
||||
.. _EPEL repository: https://docs.fedoraproject.org/en-US/epel/
|
||||
.. _SUSE PackageHub: https://packagehub.suse.com/how-to-use/
|
||||
.. _Postgres slack: http://pgtreats.info/slack-invite
|
||||
Reference in New Issue
Block a user