Documentation Patroni 4.1.5 on PIG.CENTER

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Patroni est un modèle de solutions PostgreSQL à haute disponibilité (HA) basé sur Python. Patroni a été initialement développé à partir d’une branche de Governor , le projet de Compose. Il intègre de nombreuses fonctionnalités nouvelles.

Pour plus d’informations de contexte, voir :

Haute disponibilité PostgreSQL avec Kubernetes et Patroni , conférence de Josh Berkus à KubeCon 2016 (vidéo)
Article du blog technique Zalando, février 2016

Statut de développement

Patroni est en développement actif et accepte les contributions. Consultez notre section Contributing ci-dessous pour plus de détails.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Prérequis pour Mac OS

Pour installer les prérequis sur un Mac, exécutez la commande suivante :

brew install postgresql etcd haproxy libyaml python

Psycopg

À compter de psycopg2-2.8 , la version binaire de psycopg2 ne sera plus installée par défaut. Son installation à partir du code source nécessite un compilateur C ainsi que les paquets de développement postgres+python. Étant donné qu’environnement Python ne permet pas de spécifier la dépendance comme psycopg2 OR psycopg2-binary, vous devrez déterminer vous-même la méthode d’installation.

API REST Patroni

Mon, 01 Jan 0001 00:00:00 +0000

Patroni dispose d’une API REST riche, utilisée par Patroni lui-même lors de la course au leader, par l’outil patronictl afin d’effectuer des basculements, des basculements planifiés, des réinitialisations, des redémarrages ou des rechargements, par HAProxy ou tout autre équilibreur de charge pour effectuer des vérifications de santé HTTP, et bien entendu également utilisée pour la surveillance. Ci-dessous figure la liste des points d’accès de l’API REST de Patroni.

Points de terminaison de vérification de santé

Pour toutes les requêtes de vérification de santé GET, Patroni renvoie un document JSON indiquant l’état du nœud, accompagné du code d’état HTTP. Si vous ne souhaitez pas ou n’avez pas besoin du document JSON, vous pouvez envisager d’utiliser la méthode HEAD ou OPTIONS au lieu de GET.

patronictl

Mon, 01 Jan 0001 00:00:00 +0000

Patroni dispose d’une interface en ligne de commande nommée patronictl , utilisée principalement pour interagir avec l’API REST de Patroni et avec le DCS. Elle vise à simplifier l’exécution d’opérations au sein du cluster et peut être facilement utilisée par des humains ou des scripts.

Configuration

patronictl utilise trois sections de la configuration :

ctl : comment s’authentifier contre l’API REST de Patroni, et comment valider l’identité du serveur. Consulter paramètres ctl pour plus de détails ;
restapi : comment s’authentifier contre l’API REST de Patroni, et comment valider l’identité du serveur. N’est utilisé que si la configuration ctl est insuffisante. patronictl s’intéresse principalement à la section restapi.authentication (en cas de non-présence de ctl.authentication) et au paramètre restapi.cafile (en cas de non-présence de ctl.cacert). Consulter paramètres de l’API REST pour plus de détails ;
DCS (par exemple etcd) : comment contacter et s’authentifier contre le DCS utilisé par Patroni.

Ces options de configuration peuvent provenir soit de variables d’environnement, soit d’un fichier de configuration. Consultez les sections ci-dessus dans Paramètres de configuration par environnement ou Paramètres de configuration YAML pour comprendre comment définir ces options via des variables d’environnement ou un fichier de configuration.

Imagerie de réplique et amorçage

Mon, 01 Jan 0001 00:00:00 +0000

Patroni permet de personnaliser la création d’une nouvelle réplique. Il prend également en charge la définition des actions à effectuer lors de l’amorçage d’un nouveau cluster vide. La distinction entre les deux est clairement établie : Patroni crée des répliques uniquement si la clé initialize est présente dans le DCS pour le cluster. Si la clé initialize est absente, Patroni lance l’amorçage exclusivement sur le premier nœud qui obtient le verrou de la clé initialize.

Modes de réplication

Mon, 01 Jan 0001 00:00:00 +0000

Patroni utilise la réplication en streaming de PostgreSQL. Pour en savoir plus sur la réplication en streaming, consultez la documentation Postgres . Par défaut, Patroni configure PostgreSQL pour une réplication asynchrone. Le choix de votre schéma de réplication dépend de vos considérations métier. Étudiez à la fois la réplication asynchrone et synchrone, ainsi que d’autres solutions de haute disponibilité, afin de déterminer la solution la mieux adaptée à votre situation.

cluster de secours

Mon, 01 Jan 0001 00:00:00 +0000

Patroni prend également en charge l’exécution d’une réplication en cascade vers un centre de données distant (région) à l’aide d’une fonctionnalité appelée « stand-by cluster ». Ce type de cluster présente les caractéristiques suivantes :

« leader en veille », qui se comporte presque comme un leader de cluster régulier, à ceci près qu’il effectue la réplication à partir d’un nœud distant.
répliques en cascade, qui effectuent la réplication à partir d’un leader en veille.

Le leader de secours détient et met à jour un verrou de leader dans le DCS. Si le verrou de leader expire, les répliques en cascade effectueront une élection afin de choisir un autre leader parmi les serveurs de secours.

Prise en charge du watchdog

Mon, 01 Jan 0001 00:00:00 +0000

L’exécution de plusieurs serveurs PostgreSQL en tant que primaires peut entraîner la perte de transactions en raison de lignes temporelles divergentes. Ce cas est également appelé problème de split-brain. Pour éviter le split-brain, Patroni doit s’assurer que PostgreSQL n’accepte aucune validation de transaction après l’expiration de la clé leader dans le DCS. Dans des conditions normales, Patroni tente d’atteindre cet objectif en arrêtant PostgreSQL lorsque la mise à jour du verrou leader échoue pour quelque raison que ce soit. Toutefois, cette action peut échouer pour diverses raisons :

Mode Pause/Reprise pour le cluster

Mon, 01 Jan 0001 00:00:00 +0000

Objectif

Dans certains cas, Patroni doit pouvoir se retirer temporairement de la gestion du cluster tout en conservant l’état du cluster dans le DCS. Les cas d’utilisation possibles concernent des activités inhabituelles sur le cluster, telles que les mises à jour majeures de version ou la récupération après corruption. Pendant ces opérations, les nœuds sont souvent démarrés et arrêtés pour des raisons inconnues de Patroni, certains nœuds pouvant même être temporairement promus, ce qui contrevient à l’hypothèse d’un seul nœud primaire en cours d’exécution. Par conséquent, Patroni doit pouvoir se « déconnecter » du cluster en cours, en implémentant une fonctionnalité équivalente au mode maintenance de Pacemaker.

Mode de secours DCS

Mon, 01 Jan 0001 00:00:00 +0000

Le problème

Patroni s’appuie fortement sur le magasin de configuration distribué (DCS) pour résoudre les élections de leader et détecter les partitions réseau. Un nœud ne peut exécuter PostgreSQL en tant que primaire que s’il parvient à mettre à jour le verrou de leader dans le DCS. En cas d’échec de mise à jour du verrou de leader, PostgreSQL est immédiatement rétrogradé et lancé en lecture seule. Selon le DCS utilisé, les chances de rencontrer ce problème varient. Par exemple, avec etcd, utilisé exclusivement par Patroni, les chances sont quasi nulles, tandis qu’avec l’API Kubernetes (appuyée sur etcd), ce problème peut être observé plus fréquemment.

Utilisation de Patroni avec Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Patroni peut utiliser des objets Kubernetes afin de stocker l’état du cluster et gérer la clé du leader. Cela lui permet de fonctionner avec PostgreSQL dans un environnement Kubernetes sans nécessiter de magasin de cohérence, c’est-à-dire qu’il n’est pas nécessaire de déployer un Étcd supplémentaire. Patroni peut utiliser deux types d’objets Kubernetes pour stocker la clé du leader et les clés de configuration, configurés via les variables d’environnement kubernetes.use_endpoints ou PATRONI_KUBERNETES_USE_ENDPOINTS.

Prise en charge Citus

Mon, 01 Jan 0001 00:00:00 +0000

Patroni permet de déployer très facilement des clusters Multi-Node Citus .

TL;DR

Il n’existe que quelques règles simples à suivre :

Extension Citus pour PostgreSQL doit être disponible sur tous les nœuds. La version minimale prise en charge est 10.0, mais pour bénéficier pleinement des basculements planifiés transparents et des redémarrages des workers, nous recommandons d’utiliser au moins la version Citus 11.2.
Le nom du cluster (scope) doit être identique sur tous les nœuds Citus !
Les identifiants de superutilisateur doivent être identiques sur le nœud coordinateur et sur tous les nœuds workers, et pg_hba.conf doit autoriser l’accès en tant que superutilisateur entre tous les nœuds.
API REST doit être accessible depuis les nœuds workers vers le coordinateur. Par exemple, les identifiants doivent être identiques, et si configurés, les certificats clients émis par les nœuds workers doivent être acceptés par le coordinateur.
Ajoutez la section suivante au patroni.yaml :

citus:
 group: X  # 0 for coordinator and 1, 2, 3, etc for workers
 database: citus  # must be the same on all nodes

Ensuite, il vous suffit de démarrer Patroni, qui s’occupera du reste :

Convertir un nœud autonome en cluster Patroni

Mon, 01 Jan 0001 00:00:00 +0000

Cette section décrit le processus de conversion d’une instance PostgreSQL autonome en cluster Patroni.

Pour déployer un cluster Patroni sans utiliser d’instance PostgreSQL préexistante, consultez plutôt Exécution et configuration .

Procédure

Vous trouverez ci-dessous un aperçu des étapes permettant de convertir un cluster Postgres existant en cluster géré par Patroni. Dans ces étapes, nous supposons que tous les nœuds faisant partie du cluster existant sont actuellement en fonctionnement, et que vous ne prévoyez pas de modifier la configuration de Postgres pendant la migration. Les étapes :

Intégration avec d'autres outils

Mon, 01 Jan 0001 00:00:00 +0000

Patroni est capable d’intégrer d’autres outils de votre infrastructure. Dans cette section, vous trouverez une liste d’exemples, qui, bien qu’elle ne soit pas exhaustive, peut vous inspirer sur les façons dont Patroni peut s’intégrer à d’autres outils.

Barman

Patroni fournit une application nommée patroni_barman qui intègre la logique de communication avec pg-backup-api, vous permettant ainsi d’effectuer des opérations Barman à distance.

Cette application possède actuellement plusieurs sous-commandes : recover et config-switch.

Considérations de sécurité

Mon, 01 Jan 0001 00:00:00 +0000

Un cluster Patroni dispose de deux interfaces à protéger contre l’accès non autorisé : le stockage de configuration distribué (DCS) et l’API REST Patroni.

Protection du SCD

Patroni et patronictl stockent et récupèrent des données auprès du DCS.

Bien que le DCS ne contienne aucune information sensible, il permet de modifier certaines configurations de Patroni/PostgreSQL. Par conséquent, la première mesure à prendre est de protéger le DCS lui-même.

Haute disponibilité multi-centre de données

Mon, 01 Jan 0001 00:00:00 +0000

La haute disponibilité d’un cluster PostgreSQL déployé dans plusieurs centres de données repose sur la réplication, qui peut être synchrone ou asynchrone (voir modes de réplication ).

Dans les deux cas, il est important de bien comprendre les concepts suivants :

PostgreSQL peut fonctionner en tant que leader primaire ou en mode standby uniquement lorsqu’il détient la clé de leadership et peut mettre à jour cette clé.
Vous devez exécuter un nombre impair de nœuds etcd, ZooKeeper ou Consul : 3 ou 5 !

Réplication synchrone

Pour disposer d’un cluster multi-DC pouvant tolérer automatiquement la perte d’une zone, un minimum de 3 est requis.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Dans cette section, vous trouverez les réponses aux questions les plus fréquemment posées concernant Patroni. Chaque sous-section s’efforce de se concentrer sur des types de questions différents.

Nous espérons que cela vous aidera à clarifier la majeure partie de vos questions. Si vous avez encore des interrogations ou rencontrez un problème imprévu, veuillez vous référer à chatting et reporting_bugs pour obtenir des instructions sur la manière de demander de l’aide ou de signaler des anomalies.

Notes de version

Mon, 01 Jan 0001 00:00:00 +0000

Version 4.1.5

Libéré le 2026-08-12

Améliorations de compatibilité

Compatibilité avec PostgreSQL 14.24, 15.19, 16.15, 17.11, 18.6 (Alexander Kukushkin)

Ajoutez le nouveau paramètre GUC output_plugin_libraries, qui restreint les plugins de décodage logique.

Améliorations

Réinitialisations de connexion de l’API REST à DEBUG au lieu de WARNING (Kyle McLaren)

Assurez-vous que les variantes courantes de « client est parti au milieu de l’écriture » sont désactivées sans affecter le traitement des erreurs réelles (non liées à la connexion).

Guidelines pour les contributions

Mon, 01 Jan 0001 00:00:00 +0000

Discussion

Si vous avez une question, recherchez une aide interactive pour dépanner ou souhaitez discuter avec d’autres utilisateurs Patroni, rejoignez-nous sur le canal #patroni dans PostgreSQL Slack .

Signalement de bogues

Avant de signaler un bogue, assurez-vous d’en reproduire l’incident avec la dernière version de Patroni ! Veuillez également vérifier soigneusement si le problème n’existe pas déjà dans notre Suivi des problèmes .