Документация Patroni 4.1.5 on PIG.CENTER

Введение

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

Patroni — шаблон решений высокой доступности (HA) PostgreSQL на Python. Patroni возник как ответвление проекта Governor от Compose и содержит множество новых возможностей.

Дополнительные вводные материалы:

PostgreSQL HA with Kubernetes and Patroni — доклад Джоша Беркуса на KubeCon 2016 (видео)
Публикация в техническом блоге Zalando за февраль 2016 года

Состояние разработки

Patroni активно разрабатывается и принимает вклады сообщества. Подробнее см. раздел Участие в разработке ниже.

Сведения о новых выпусках публикуются здесь .

Установка

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

Предварительные требования для Mac OS

Чтобы установить необходимые компоненты на Mac, выполните:

brew install postgresql etcd haproxy libyaml python

Psycopg

Начиная с psycopg2-2.8 двоичная версия psycopg2 больше не устанавливается по умолчанию. Для установки из исходного кода необходим компилятор C и пакеты разработки postgres и python. Поскольку в экосистеме Python нельзя указать зависимость как psycopg2 OR psycopg2-binary, способ установки нужно выбрать самостоятельно.

Patroni REST API

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

Patroni предоставляет обширный REST API. Сам Patroni использует его во время выбора лидера, инструмент patronictl — для аварийных и плановых переключений, повторной инициализации, перезапусков и перезагрузки конфигурации, а HAProxy и другие балансировщики — для проверок работоспособности HTTP. API также можно применять для мониторинга. Ниже перечислены конечные точки REST API Patroni.

Конечные точки проверки работоспособности

На все запросы проверки GET Patroni возвращает документ JSON с состоянием узла и код состояния HTTP. Если документ JSON не нужен, вместо GET можно использовать метод HEAD или OPTIONS.

patronictl

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

Patroni предоставляет интерфейс командной строки patronictl , предназначенный главным образом для взаимодействия с REST API Patroni и DCS. Он упрощает операции с кластером и удобен как людям, так и сценариям.

Конфигурация

patronictl использует 3 раздела конфигурации:

ctl: способ аутентификации в REST API Patroni и проверки подлинности сервера. Подробнее см. параметры ctl ;
restapi: способ аутентификации в REST API Patroni и проверки подлинности сервера. Используется, только если конфигурации ctl недостаточно. patronictl в основном использует раздел restapi.authentication, если отсутствует ctl.authentication, и параметр restapi.cafile, если отсутствует ctl.cacert. Подробнее см. параметры REST API ;
DCS, например etcd: способ подключения и аутентификации в DCS, используемом Patroni.

Эти параметры можно получить из переменных окружения или файла конфигурации. Способы их задания описаны в соответствующих разделах Параметров конфигурации окружения и Параметров конфигурации YAML .

Создание образов реплик и начальная инициализация

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

Patroni позволяет настраивать создание новой реплики и определять действия при начальной инициализации нового пустого кластера. Различие строго определено: Patroni создаёт реплики, только если для кластера в DCS присутствует ключ initialize. Если ключа initialize нет, Patroni выполняет начальную инициализацию исключительно на первом узле, получившем блокировку ключа initialize.

Начальная инициализация

PostgreSQL предоставляет команду initdb для инициализации нового кластера, и Patroni вызывает её по умолчанию. В некоторых случаях, особенно при создании нового кластера как копии существующего, встроенный метод необходимо заменить пользовательскими действиями. Patroni поддерживает сценарии пользователя для начальной инициализации новых кластеров и передаёт им обязательные аргументы, например имя кластера и путь к каталогу данных. Это настраивается в разделе bootstrap конфигурации Patroni. Например:

Режимы репликации

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

Patroni использует потоковую репликацию PostgreSQL. Подробнее см. документацию Postgres . По умолчанию Patroni настраивает PostgreSQL на асинхронную репликацию. Выбор схемы репликации зависит от требований бизнеса. Изучите асинхронную и синхронную репликацию, а также другие решения HA, чтобы выбрать подходящий вариант.

Долговечность в асинхронном режиме

В асинхронном режиме ради доступности кластер может потерять часть зафиксированных транзакций. При отказе или недоступности первичного сервера Patroni автоматически повышает достаточно исправный резервный сервер до первичного. Транзакции, не реплицированные на этот резервный сервер, остаются в «ответвившейся временной шкале» первичного и фактически невосстановимы¹.

Резервный кластер

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

Patroni также поддерживает настройку каскадной репликации на удалённый центр обработки данных (регион) с использованием функции, называемой «резервный кластер». Такие кластеры обладают следующими характеристиками:

«резервный лидер», который ведёт себя примерно как обычный лидер кластера, за исключением того, что реплицирует данные с удалённого узла.
каскадные реплики, которые реплицируют данные с резервного сервера.

Резервный сервер-лидер удерживает и обновляет блокировку лидера в DCS. Если блокировка лидера истекает, каскадные реплики выполнят голосование для выбора другого лидера из резервных серверов.

Поддержка сторожевого таймера

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

Запуск нескольких серверов PostgreSQL в качестве первичных может привести к потере транзакций из-за расхождения временных шкал. Такая ситуация также называется проблемой расщепленного мозга. Чтобы избежать проблемы расщепленного мозга, Patroni должен обеспечить, чтобы PostgreSQL не принимал никаких подтверждений транзакций после истечения срока действия ключа лидера в DCS. В нормальных условиях Patroni пытается достичь этого, останавливая PostgreSQL при неудаче обновления блокировки лидера по любой причине. Однако это может не произойти по различным причинам:

Режим приостановки/возобновления для кластера

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

Цель

В некоторых случаях Patroni должен временно прекратить управление кластером, сохраняя при этом состояние кластера в DCS. Возможные сценарии использования — редкие операции с кластером, такие как обновление до новой версии или восстановление после повреждения. В ходе таких операций узлы часто запускаются и останавливаются по причинам, неизвестным Patroni, некоторые узлы могут даже временно повышаться до статуса первичного сервера, что нарушает предположение о наличии только одного первичного сервера. Поэтому Patroni должен уметь «отключаться» от работающего кластера, реализуя эквивалент режима обслуживания, как в Pacemaker.

DCS Отказоустойчивый режим

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

Проблема

Patroni активно использует распределённое хранилище конфигурации (DCS) для решения задачи выбора лидера и обнаружения сетевых разделений. Узел может запускать PostgreSQL как первичный сервер только в том случае, если ему удаётся обновить блокировку лидера в DCS. В случае неудачи обновления блокировки лидера PostgreSQL немедленно понижается до режима только для чтения. Вероятность возникновения «проблемы» зависит от используемого DCS. Например, при использовании etcd, который применяется исключительно для Patroni, вероятность близка к нулю, тогда как при использовании K8s API (основанного на etcd) такая ситуация может возникать чаще.

Использование Patroni с Kubernetes

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

Patroni может использовать объекты Kubernetes для хранения состояния кластера и управления ключом лидера. Это позволяет работать с Postgres в среде Kubernetes без дополнительного хранилища согласованности, то есть не требуется запуск отдельного развёртывания etcd. Patroni может использовать два различных типа объектов Kubernetes для хранения ключей лидера и конфигурации, которые настраиваются с помощью переменной среды kubernetes.use_endpoints или PATRONI_KUBERNETES_USE_ENDPOINTS.

Используйте конечные точки

Несмотря на то что этот режим рекомендуется, по соображениям совместимости он отключён по умолчанию. Когда он включён, Patroni хранит конфигурацию кластера и ключ лидера в полях metadata: annotations соответствующих Endpoints, которые он создаёт. Смена лидера безопаснее, чем при использовании ConfigMaps, поскольку одновременно обновляются и аннотации, содержащие информацию о лидере, и фактические адреса, указывающие на запущенный под-лидер.

Поддержка Citus

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

Patroni делает развертывание кластеров Multi-Node Citus чрезвычайно простым.

TL;DR

Существует лишь несколько простых правил, которым необходимо следовать:

Расширение базы данных Citus для PostgreSQL должно быть доступно на всех узлах. Абсолютно минимальная поддерживаемая версия Citus — 10.0, но для использования всех преимуществ прозрачных плановых переключений и перезапусков рабочих узлов рекомендуется как минимум Citus 11.2.
Имя кластера (scope) должно быть одинаковым для всех узлов Citus!
Учётные данные суперпользователя должны быть одинаковыми на координаторе и всех рабочих узлах, а pg_hba.conf должен разрешать доступ суперпользователя между всеми узлами.
REST API доступ должен быть разрешён с узлов-работников к координатору. E.g, учётные данные должны быть одинаковыми, и, если настроены, клиентские сертификаты с узлов-работников должны быть приняты координатором.
Добавьте следующий раздел в patroni.yaml:

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

После этого вам нужно просто запустить Patroni, и он сам займётся остальным:

Преобразование отдельного экземпляра в кластер Patroni

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

В этом разделе описано преобразование отдельного экземпляра PostgreSQL в кластер Patroni.

Чтобы развернуть кластер Patroni без существующего экземпляра PostgreSQL, обратитесь к разделу Запуск и настройка .

Процедура

Ниже приведён обзор преобразования существующего кластера Postgres в кластер под управлением Patroni. Предполагается, что все узлы существующего кластера работают и во время миграции вы не намерены менять конфигурацию Postgres. Выполните следующие действия:

Создайте пользователей Postgres, как описано в разделе аутентификации конфигурации Patroni. В блоке SQL ниже приведены примеры команд; замените имена пользователей и пароли в соответствии со своим окружением. Если необходимые пользователи уже существуют, пропустите этот шаг.

Интеграция с другими инструментами

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

Patroni способен интегрироваться с другими инструментами в вашем стеке. В этом разделе вы найдете список примеров, которые, хотя и не являются исчерпывающими, могут дать вам идеи о том, как Patroni может интегрироваться с другими инструментами.

Barman

Patroni предоставляет приложение с именем patroni_barman, в котором реализована логика взаимодействия с pg-backup-api, что позволяет выполнять операции Barman удалённо.

У данного приложения в настоящее время имеется несколько подкоманд: recover и config-switch.

Аспекты безопасности

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

Кластер Patroni имеет два интерфейса, которые необходимо защитить от несанкционированного доступа: хранилище распределённой конфигурации (DCS) и REST API Patroni (REST) (API).

Защита DCS

Patroni и patronictl хранят и извлекают данные из DCS.

Несмотря на то что DCS не содержит никакой конфиденциальной информации, он позволяет изменять часть конфигурации Patroni/Postgres. Поэтому первым делом необходимо защитить DCS.

Детали защиты зависят от типа DCS, используемого в системе. Параметры аутентификации и шифрования (токены/базовая аутентификация/сертификаты клиента) для поддерживаемых типов DCS описаны в настройки .

HA-кластер с несколькими центрами обработки данных

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

Высокая доступность кластера PostgreSQL, развернутого в нескольких центрах обработки данных, основана на репликации, которая может быть синхронной или асинхронной (см. режимы репликации ).

В обоих случаях важно четко понимать следующие понятия:

PostgreSQL может работать в качестве первичного сервера или резервного сервера-лидера только тогда, когда он владеет ключом лидера и может обновлять этот ключ.
Рекомендуется запускать нечётное количество узлов etcd, ZooKeeper или Consul: 3 или 5!

Синхронная репликация

Для создания кластера с несколькими ЦО, способного автоматически переживать отказ зоны, требуется как минимум 3.

Часто задаваемые вопросы

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

В этом разделе приведены ответы на самые частые вопросы о Patroni. Каждый подраздел посвящён отдельной категории вопросов.

Надеемся, это прояснит большинство вопросов. Если сомнения остаются или возникла неожиданная проблема, инструкции по получению помощи и сообщению об ошибке приведены в разделах общение и сообщение об ошибках .

Сравнение с другими решениями HA

Почему Patroni требует отдельный кластер узлов DCS, а другие решения наподобие repmgr — нет?
Решения HA можно реализовать разными способами, каждый со своими преимуществами и недостатками.

Примечания к выпускам

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

Версия 4.1.5

Выпущено 2026-08-12

Улучшения совместимости

Совместимость с PostgreSQL 14.24, 15.19, 16.15, 17.11, 18.6 (Alexander Kukushkin)

Добавьте новый output_plugin_libraries GUC, который ограничивает вывод плагинов логического декодирования.

Улучшения

Записывать REST предупреждения о сбросе API соединений в DEBUG вместо WARNING (Kyle McLaren)

Убедитесь, что распространенные варианты “клиент неожиданно завершил операцию записи” не влияют на обработку реальных (не связанных с соединением) ошибок.

Исправления ошибок

Исправить выравнивание при проверке thread_stack_size (Sundong Kim)

Документация Patroni 4.1.5 on PIG.CENTER

Введение

Состояние разработки

Установка

Предварительные требования для Mac OS

Psycopg

Patroni REST API

Конечные точки проверки работоспособности

patronictl

Конфигурация

Создание образов реплик и начальная инициализация

Начальная инициализация

Режимы репликации

Долговечность в асинхронном режиме

Резервный кластер

Поддержка сторожевого таймера

Режим приостановки/возобновления для кластера

Цель

DCS Отказоустойчивый режим

Проблема

Использование Patroni с Kubernetes

Используйте конечные точки

Поддержка Citus

TL;DR

Преобразование отдельного экземпляра в кластер Patroni

Процедура

Интеграция с другими инструментами

Barman

Аспекты безопасности

Защита DCS

HA-кластер с несколькими центрами обработки данных

Синхронная репликация

Часто задаваемые вопросы

Сравнение с другими решениями HA

Примечания к выпускам

Версия 4.1.5

Рекомендации по участию в разработке

Общение

Сообщение об ошибках

Запуск тестов