Конфигурирование Patroni

примечание

Эта страница переведена при помощи нейросети GigaChat.

Существует 3 типа конфигурации Patroni:

• Глобальная динамическая конфигурация. Эти параметры хранятся в DCS (распределенном хранилище конфигурации) и применяются на всех узлах кластера. Динамическую конфигурацию можно установить в любое время с помощью инструмента patronictl edit-config или через интерфейс Patroni REST API. Если измененные параметры не являются частью конфигурации запуска, они применяются асинхронно (при следующем цикле пробуждения) для каждого узла, который затем перезагружается. Если узел требует перезапуска для применения конфигурации (для параметров PostgreSQL с контекстом postmaster, если их значения были изменены), специальный флаг pending_restart указывающий на это, устанавливается в файле members.data JSON. Кроме того, статус узла указывает на это, отображая "restart_pending": true.
• Локальный файл конфигурации (patroni.yml). Эти параметры определены в файле конфигурации и имеют приоритет над динамической конфигурацией. patroni.yml может быть изменен и перезагружен во время выполнения (без перезапуска Patroni), отправив сигнал SIGHUP процессу Patroni, выполнив запрос POST /reload к REST-API или выполнив команду patronictl reload. Локальная конфигурация может быть либо одним файлом YAML, либо каталогом. Когда это каталог, все файлы YAML в этом каталоге загружаются по одному в отсортированном порядке. В случае, если ключ определен в нескольких файлах, предпочтение отдается последнему файлу.
• Конфигурация окружения. Позволяет установить/заменить некоторые из параметров локальной конфигурации с помощью переменных окружения. Конфигурация среды полезна, когда работа происходит в динамической среде и нет определенности по некоторым из параметров заранее (например, внешний IP-адрес может быть неизвестен при запуске внутри docker).

Важные правила

Параметры PostgreSQL, управляемые Patroni

Некоторые параметры PostgreSQL должны иметь одинаковые значения на первичном узле и репликах. Для них значения, заданные либо в локальных файлах конфигурации patroni, либо через переменные окружения, не действуют. Чтобы изменить или задать их значения, необходимо изменить общую конфигурацию в DCS. Ниже приведен актуальный список таких параметров вместе со значениями по умолчанию и минимальными значениями:

Параметр	Значение по умолчанию	Минимальное значение
max_connections	100	25
max_locks_per_transaction	64	32
max_worker_processes	8	2
max_prepared_transactions	0	0
wal_level	hot_standby	hot_standby, replica, logical
track_commit_timestamp	off	—

Для параметров ниже PostgreSQL не требует равных значений между первичным узлом и всеми репликами. Однако, учитывая возможность того, что реплика в любой момент может стать первичной, не имеет смысла задавать их по-разному; поэтому Patroni ограничивает установку их значений через динамическую конфигурацию.

Параметр	Значение по умолчанию	Минимальное значение
max_wal_senders	10	3
max_replication_slots	10	4
wal_keep_segments	8	1
wal_keep_size	128MB	16MB
wal_log_hints	on	—

Эти параметры проверяются на корректность и соответствие минимальному значению.

Есть и другие параметры Postgres, управляемые Patroni:

• listen_addresses — задается либо из postgresql.listen, либо из переменной окружения PATRONI_POSTGRESQL_LISTEN
• port — задается либо из postgresql.listen, либо из переменной окружения PATRONI_POSTGRESQL_LISTEN
• cluster_name — задается либо из scope, либо из переменной окружения PATRONI_SCOPE
• hot_standby: on

Для безопасности параметры из приведенных выше списков записываются в postgresql.conf и передаются в виде списка аргументов в postgres, что придает им наивысший приоритет (кроме wal_keep_segments и wal_keep_size), даже выше, чем ALTER SYSTEM.

Также есть параметры, такие как postgresql.listen, postgresql.data_dir, которые могут быть заданы только локально, то есть в файле конфигурации Patroni или через переменную окружения. В большинстве случаев локальная конфигурация переопределит динамическую.

При применении опций локальной или динамической конфигурации выполняются следующие действия:

• Узел сначала проверяет, существует ли файл postgresql.base.conf или задан ли параметр custom_conf.
• Если задан параметр custom_conf, указанный им файл используется в качестве базовой конфигурации, игнорируя postgresql.base.conf и postgresql.conf.
• Если параметр custom_conf не задан и postgresql.base.conf существует, он содержит переименованную «оригинальную» конфигурацию и используется в качестве базовой конфигурации.
• Если нет ни custom_conf, ни postgresql.base.conf, оригинальный postgresql.conf переименовывается в postgresql.base.conf и используется в качестве базовой конфигурации.
• Динамические опции (за исключением вышеуказанных) выгружаются в postgresql.conf, и в postgresql.conf устанавливается include на базовую конфигурацию (либо postgresql.base.conf, либо файл, указанный в custom_conf). Таким образом, можно применять новые опции без перечитывания файла конфигурации для проверки наличия include.
• Некоторые параметры, важные для управления кластером Patroni, переопределяются с помощью командной строки.
• Если изменяется опция, требующая перезапуска (следует смотреть на контекст в pg_settings и на фактические значения этих опций), на этом узле устанавливается флаг pending_restart. Этот флаг сбрасывается при любом перезапуске.

Параметры будут применены в следующем порядке (параметры времени выполнения имеют наивысший приоритет):

1. загрузка параметров из файла postgresql.base.conf (или из файла custom_conf, если задан)
2. загрузка параметров из файла postgresql.conf
3. загрузка параметров из файла postgresql.auto.conf
4. параметр времени выполнения с использованием -o --name=value

Это позволяет конфигурировать все узлы (2), конфигурировать конкретный узел с помощью ALTER SYSTEM (3) и гарантирует, что параметры, важные для работы Patroni, будут применены (4), а также оставляет место для инструментов конфигурации, которые управляют postgresql.conf напрямую, без участия Patroni (1).

Параметры PostgreSQL, затрагивающие общую память

PostgreSQL имеет некоторые параметры, определяющие размер общей памяти, используемой ими:

• max_connections
• max_prepared_transactions
• max_locks_per_transaction
• max_wal_senders
• max_worker_processes

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

Как объяснялось ранее, Patroni ограничивает изменение их значений через динамическую конфигурацию, что обычно состоит из:

1. Применение изменений через patronictl edit-config (или через конечную точку REST API /config)
2. Перезапуск узлов через patronictl restart (или через конечную точку REST API /restart)

примечание

Пожалуйста, имейте в виду, что следует выполнять перезапуск узлов PostgreSQL через команду patronictl restart или через конечную точку REST API /restart. Попытка перезапустить PostgreSQL путем перезапуска демона Patroni, например, выполнив systemctl restart patroni, может привести к failover в кластере, если перезапускается первичный узел.

Однако, поскольку эти настройки управляют общей памятью, при перезапуске узлов следует проявлять особую осторожность:

• Если требуется увеличить значение любого из этих параметров:

  1. Сначала перезапустите все standby
  2. Затем перезапустите первичный узел

• Если требуется уменьшить значение любого из этих параметров:

  1. Сначала перезапустите первичный узел
  2. Затем перезапустите все standby

примечание

Если попытаются перезапустить все узлы сразу после уменьшения значения любого из этих параметров, Patroni проигнорирует изменение и перезапустит standby с исходным значением настройки, что потребует повторного перезапуска standby позже. Patroni делает это для предотвращения входа standby в бесконечный цикл аварийных завершений, поскольку PostgreSQL завершает работу с сообщением FATAL, если будет предпринята попытка установить любое из этих параметров на значение ниже, чем видно в pg_controldata на узле Standby. Другими словами, можно уменьшить настройку на standby только тогда, когда его pg_controldata актуален относительно первичного узла в отношении этих изменений на первичном узле.

Параметры конфигурации Patroni

Также следующие опции конфигурации Patroni могут быть изменены только динамически:

• ttl: 30
• loop_wait: 10
• retry_timeouts: 10
• maximum_lag_on_failover: 1048576
• max_timelines_history: 0
• check_timeline: false
• postgresql.use_slots: true

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

Узлы Patroni выгружают состояние опций DCS на диск при каждом изменении конфигурации в файл patroni.dynamic.json, расположенный в каталоге данных Postgres. Только лидеру разрешено восстанавливать эти опции из дампа на диске, если они полностью отсутствуют в DCS или если они недействительны.

Генерация и проверка конфигурации

Patroni предоставляет интерфейсы командной строки для генерации и валидации локальной конфигурации Patroni. С помощью исполняемого файла patroni можно:

• Создать пример локальной конфигурации Patroni;
• Создать файл конфигурации Patroni для локально запущенного экземпляра PostgreSQL (например, как подготовительный шаг для интеграции Patroni);
• Валидировать заданный файл конфигурации Patroni.

Пример конфигурации Patroni

patroni --generate-sample-config [configfile]

Описание

Сгенерировать пример файла конфигурации Patroni в формате yaml. Значения параметров определяются с помощью конфигурации через переменные окружения, в противном случае, если не заданы, используются значения по умолчанию в Patroni или строка #FIXME для значений, которые должны быть позже определены пользователем.

Некоторые значения по умолчанию определяются на основе локальной настройки:

• postgresql.listen: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и стандартный порт 5432.
• postgresql.connect_address: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и стандартный порт 5432.
• postgresql.authentication.rewind: определяется только если версия PostgreSQL может быть определена из бинарного файла и версия равна 11 или новее.
• restapi.listen: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и стандартный порт 8008.
• restapi.connect_address: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и стандартный порт 8008.

Параметры

configfile — полный путь к файлу конфигурации, используемому для сохранения результата. Если не предоставлен, результат отправляется в stdout.

Конфигурация Patroni для запущенного экземпляра

patroni --generate-config [--dsn DSN] [configfile]

Описание

Сгенерировать конфигурацию Patroni в формате yaml для локально запущенного экземпляра PostgreSQL. Для подключения к PostgreSQL будет использоваться либо предоставленный DSN (имеет приоритет), либо переменные окружения PostgreSQL. Если пароль не предоставлен, его следует ввести через приглашение.

Все не-внутренние GUC, определенные в исходном экземпляре Postgres, независимо от того, были ли они заданы через файл конфигурации, через командную строку postmaster или через переменные окружения, будут использованы в качестве источника для следующих параметров конфигурации Patroni:

• scope: значение GUC cluster_name;
• postgresql.listen: значения GUC listen_addresses и port;
• postgresql.datadir: значение GUC data_directory;
• postgresql.parameters: значения GUC archive_command, restore_command, archive_cleanup_command, recovery_end_command, ssl_passphrase_command, hba_file, ident_file, config_file;
• bootstrap.dcs: все остальные собранные GUC PostgreSQL.

Если scope, postgresql.listen или postgresql.datadir не заданы из GUC Postgres, используется соответствующее значение конфигурации через переменные окружения.

Другие правила, применяемые для определения значений:

• name: значение переменной окружения PATRONI_NAME, если задано, в противном случае — имя хоста текущей машины.
• postgresql.bin_dir: путь к бинарным файлам Postgres, полученный из запущенного экземпляра.
• postgresql.connect_address: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и порт, используемый для подключения к экземпляру, или значение GUC port.
• postgresql.authentication.superuser: конфигурация, используемая для подключения к экземпляру;
• postgresql.pg_hba: строки, собранные из hba_file исходного экземпляра.
• postgresql.pg_ident: строки, собранные из ident_file исходного экземпляра.
• restapi.listen: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и стандартный порт 8008.
• restapi.connect_address: IP-адрес, возвращенный вызовом gethostname для имени хоста текущей машины, и стандартный порт 8008.

Другие параметры, определенные с помощью конфигурации через переменные окружения, также включаются в конфигурацию.

Параметры

configfile

Полный путь к файлу конфигурации, используемому для сохранения результата. Если не предоставлен, результат отправляется в stdout.

dsn

Необязательная строка DSN для локального экземпляра PostgreSQL, из которого нужно получить значения GUC.

Валидация конфигурации Patroni

patroni --validate-config [configfile] [--ignore-listen-port | -i]

Описание

Валидировать заданную конфигурацию Patroni и вывести информацию о неудачных проверках.

Параметры

configfile Полный путь к файлу конфигурации для проверки. Если не задан или файл не существует, попытается прочитать из переменной окружения PATRONI_CONFIG_VARIABLE или, если не задана, из переменных окружения Patroni.

--ignore-listen-port | -i Необязательный флаг для игнорирования ошибок привязки для портов listen, которые уже используются, при валидации configfile.

--print | -p Необязательный флаг для вывода локальной конфигурации (включая переопределения конфигурации через переменные окружения) после успешной валидации.