# Patroni конфигурация
> Patroni модель конфигурации, правила приоритета и инструменты валидации.
---
Индекс LLMS: [llms.txt](/ru/llms.txt)
---
Существует 3 типов конфигурации Patroni:
- Глобальная [динамическая конфигурация](/ru/patroni/config/dynamic#dynamic).
Эти параметры хранятся в DCS (распределённое хранилище конфигурации) и применяются ко всем узлам кластера. Динамическая конфигурация может быть установлена в любой момент с помощью инструмента [patronictl_edit_config](/ru/patroni/patronictl#patronictl_edit_config) или Patroni [REST API](/ru/patroni/rest_api#rest_api). Если изменённые параметры не входят в начальную конфигурацию, они применяются асинхронно (при следующем цикле пробуждения) на каждом узле, после чего узел перезагружается. Если узлу требуется перезапуск для применения конфигурации (для параметров [PostgreSQL](https://www.postgresql.org/docs/current/view-pg-settings.html) с контекстом postmaster, если их значения изменились), в members.data JSON устанавливается специальный флаг `pending_restart`. Кроме того, состояние узла указывает на это, отображая `"restart_pending": true`.
- Локальный [файл конфигурации](/ru/patroni/config/yaml#yaml) (patroni.yml).
Эти параметры определяются в файле конфигурации и имеют приоритет перед динамической конфигурацией. `patroni.yml` можно изменить и повторно загрузить во время выполнения (без перезапуска Patroni), отправив SIGHUP процессу Patroni, выполнив запрос `POST /reload` REST-API или команду [patronictl_reload](/ru/patroni/patronictl#patronictl_reload). Локальная конфигурация может представлять собой один файл YAML или каталог. Если указан каталог, все файлы YAML в нём загружаются по одному в отсортированном порядке. Если ключ определён в нескольких файлах, приоритет имеет его значение в последнем файле.
- [Конфигурация среды](/ru/patroni/config/env#env).
Возможна установка/переопределение некоторых параметров конфигурации «Локальная» с помощью переменных среды. Конфигурация среды особенно полезна при работе в динамической среде, когда некоторые параметры заранее неизвестны (например, невозможно определить внешний IP-адрес при запуске внутри `docker`).
--------
## Важные правила {#important-rules}
### Параметры PostgreSQL, контролируемые Patroni {#postgresql-parameters-controlled-by-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, реплика, логическая
- **track_commit_timestamp**: значение по умолчанию off
Для параметров, указанных ниже, PostgreSQL не требует одинаковых значений между первичным сервером и всеми репликами. Однако с учётом возможности превращения реплики в первичный сервер в любой момент, установка различных значений не имеет смысла; следовательно, **Patroni ограничивает установку их значений в** [динамическую конфигурацию](/ru/patroni/config/dynamic#dynamic).
- **max_wal_senders**: значение по умолчанию 10, минимальное значение 3
- **max_replication_slots**: значение по умолчанию 10, минимальное значение 4
- **wal_keep_segments**: значение по умолчанию 8, минимальное значение 1
- **wal_keep_size**: значение по умолчанию 128MB, минимальное значение 16MB
- **wal_log_hints**: включено
Эти параметры проверяются на корректность или соответствие минимальному значению.
Существуют и другие параметры 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](https://www.postgresql.org/docs/current/static/sql-altersystem.html)
Существуют также некоторые параметры, такие как **postgresql.listen**, **postgresql.data_dir**, которые **можно задать только локально**, i.e. в файле конфигурации Patroni [config](/ru/patroni/config/yaml#yaml) или с помощью переменной окружения [configuration](/ru/patroni/config/env#env). В большинстве случаев локальная конфигурация переопределяет динамическую конфигурацию.
При применении параметров локальной или динамической конфигурации выполняются следующие действия:
- Узел сначала проверяет наличие файла `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` устанавливается включение базовой конфигурации (либо `postgresql.base.conf`, либо файл по пути `custom_conf`). Таким образом, можно применять новые параметры без повторного чтения файла конфигурации для проверки наличия включения.
- Некоторые параметры, необходимые для управления кластером 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-parameters-that-touch-shared-memory}
PostgreSQL имеет некоторые параметры, определяющие размер общей памяти, используемой ими:
- **max_connections**
- **max_prepared_transactions**
- **max_locks_per_transaction**
- **max_wal_senders**
- **max_worker_processes**
Изменение этих параметров требует перезапуска PostgreSQL для применения, и их структуры общей памяти не могут быть меньше на резервных серверах, чем на первичном сервере.
Как уже объяснялось ранее, Patroni ограничивает изменение их значений через [динамическую конфигурацию](/ru/patroni/config/dynamic#dynamic), которая обычно состоит из:
1. Применение изменений через [patronictl_edit_config](/ru/patroni/patronictl#patronictl_edit_config) (или через конечную точку REST API `/config`)
2. Перезапуск узлов через [patronictl_restart](/ru/patroni/patronictl#patronictl_restart) (или через конечную точку REST API `/restart`)
**Примечание:** имейте в виду, что перезапуск узлов PostgreSQL следует выполнять с помощью команды [patronictl_restart](/ru/patroni/patronictl#patronictl_restart) или через конечную точку REST API `/restart`. Попытка перезапуска PostgreSQL путём перезапуска демона Patroni, e.g. путём выполнения команды `systemctl restart patroni`, может привести к переключению при отказе в кластере, если перезапускается первичный сервер.
Однако, поскольку эти параметры управляют общей памятью, при перезапуске узлов следует проявлять дополнительную осторожность:
- Если вы хотите **увеличить** значение одного из этих параметров:
> 1. Сначала перезапустите все резервные серверы
> 2. Затем перезапустите первичный сервер
- Если вы хотите **уменьшить** значение одного из этих параметров:
> 1. Перезапустите первичный сервер сначала
> 2. Затем перезапустите все резервные серверы
**Примечание:** если вы попытаетесь перезапустить все узлы одновременно после **уменьшения** значения любого из этих параметров, Patroni проигнорирует изменение и перезапустит резервный сервер с исходным значением параметра, что потребует последующего повторного перезапуска резервных серверов. Patroni поступает так, чтобы предотвратить попадание резервного сервера в бесконечный цикл сбоев, поскольку PostgreSQL завершается с сообщением `FATAL`, если попытаться установить любой из этих параметров на значение ниже, чем то, что отображается в `pg_controldata` на узле резервного сервера. Иными словами, мы можем уменьшить значение параметра на резервном сервере только после того, как его `pg_controldata` будет синхронизировано с первичным сервером относительно этих изменений на первичном сервере.
Дополнительную информацию об этом можно найти в [Обзоре администратора PostgreSQL](https://www.postgresql.org/docs/current/hot-standby.html#HOT-STANDBY-ADMIN).
### Patroni параметры конфигурации {#patroni-configuration-parameters}
Также следующие параметры конфигурации Patroni **могут быть изменены только динамически**:
- **ttl**: 30
- **loop_wait**: 10
- **retry_timeout**: 10
- **maximum_lag_on_failover**: 1048576
- **max_timelines_history**: 0
- **check_timeline**: false
- **postgresql.use_slots**: true
При изменении этих параметров Patroni прочитает соответствующий раздел конфигурации, хранящийся в DCS, и изменит их значения в режиме выполнения.
Узлы Patroni сохраняют состояние параметров DCS на диск при каждом изменении конфигурации в файл `patroni.dynamic.json`, расположенном в каталоге данных PostgreSQL. Восстановление этих параметров из дампа на диске разрешено только лидеру, если они полностью отсутствуют в DCS или являются недопустимыми.
--------
## Генерация и проверка конфигурации {#configuration-generation-and-validation}
Patroni предоставляет интерфейсы командной строки для генерации и проверки локальной конфигурации Patroni [local configuration](/ru/patroni/config/yaml#yaml). С помощью исполняемого файла `patroni` вы можете:
- Создайте образец локальной конфигурации Patroni;
- Создайте файл конфигурации Patroni для локально запущенного экземпляра PostgreSQL (e.g в качестве подготовительного шага к интеграции с [Patroni](/ru/patroni/existing_data#existing_data));
- Проверьте заданный файл конфигурации Patroni.
### Пример конфигурации Patroni {#sample-patroni-configuration}
```text
patroni --generate-sample-config [configfile]
```
#### Описание {#description}
Создайте образец файла конфигурации Patroni в формате `yaml`. Значения параметров задаются с помощью конфигурации [Environment](/ru/patroni/config/env#env), в противном случае, если не заданы, используются значения по умолчанию в 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`.
#### Параметры {#parameters}
`configfile` — полный путь к файлу конфигурации, используемому для хранения результата. Если не указан, результат отправляется в `stdout`.
### Patroni конфигурация для работающего экземпляра {#patroni-configuration-for-a-running-instance}
```text
patroni --generate-config [--dsn DSN] [configfile]
```
#### Описание {#description-1}
Создайте конфигурацию Patroni в формате `yaml` для локально запущенного экземпляра PostgreSQL. Для соединения с PostgreSQL будет использоваться либо указанный DSN (он имеет приоритет), либо [переменные окружения](https://www.postgresql.org/docs/current/libpq-envars.html) PostgreSQL. Если пароль не указан, его следует ввести по запросу.
Все не внутренние параметры GUC, определённые в исходном экземпляре PostgreSQL, независимо от того, были ли они установлены через файл конфигурации, через командную строку postmaster или через переменные среды, будут использованы в качестве источника для следующих параметров конфигурации Patroni:
> - **scope**: `cluster_name` GUC значение;
> - **postgresql.listen**: `listen_addresses` и `port` GUC значения;
> - **postgresql.datadir**: `data_directory` GUC значение;
> - **postgresql.parameters**: `archive_command`, `restore_command`, `archive_cleanup_command`, `recovery_end_command`, `ssl_passphrase_command`, `hba_file`, `ident_file`, `config_file` GUC значения;
> - **bootstrap.dcs**: все остальные собранные параметры GUC PostgreSQL.
Если параметр `scope`, `postgresql.listen` или `postgresql.datadir` не задан через GUC PostgreSQL, используется соответствующее значение конфигурации [Environment](/ru/patroni/config/env#env).
Другие правила, применяемые для определения значений:
> - **name**: значение переменной среды `PATRONI_NAME`, если установлена, иначе имя хоста текущей машины.
> - **postgresql.bin_dir**: путь к бинарным файлам PostgreSQL, извлечённый из работающего экземпляра.
> - **postgresql.connect_address**: IP-адрес, возвращённый вызовом `gethostname` для имени хоста текущей машины, и порт, используемый для соединения с экземпляром, или значение `port` GUC.
> - **postgresql.authentication.superuser**: конфигурация, используемая для соединения с экземпляром;
> - **postgresql.pg_hba**: строки, извлечённые из `hba_file` исходного экземпляра.
> - **postgresql.pg_ident**: строки, извлечённые из `ident_file` исходного экземпляра.
> - **restapi.listen**: IP-адрес, возвращённый вызовом `gethostname` для имени хоста текущей машины, и стандартный порт `8008`.
> - **restapi.connect_address**: IP-адрес, возвращённый вызовом `gethostname` для имени хоста текущей машины, и стандартный порт `8008`.
Другие параметры, определённые с помощью [Конфигурация среды](/ru/patroni/config/env#env), также включаются в конфигурацию.
#### Параметры {#parameters-1}
`configfile`
Полный путь к файлу конфигурации, используемому для хранения результата. Если не указан, результат отправляется в `stdout`.
`dsn`
Необязательная строка DSN для локального экземпляра PostgreSQL, из которого будут получены значения GUC.
### Проверка конфигурации Patroni {#validate-patroni-configuration}
```text
patroni --validate-config [configfile] [--ignore-listen-port | -i]
```
#### Описание {#description-2}
Проверьте указанную конфигурацию Patroni и выведите сведения о неудавшихся проверках.
#### Параметры {#parameters-2}
`configfile`
Полный путь к файлу конфигурации для проверки. Если не указан или файл отсутствует, будет попытка прочитать из переменной среды `PATRONI_CONFIG_VARIABLE`, или, если она не установлена, из переменных среды [Patroni](/ru/patroni/config/env#env).
`--ignore-listen-port | -i`
Необязательный флаг для игнорирования ошибок привязки к портам `listen`, которые уже заняты при проверке `configfile`.
`--print | -p`
Необязательный флаг для вывода локальной конфигурации (включая переопределения конфигурации из переменных среды) после её успешной валидации.
---
Страницы раздела:
- [YAML Параметры конфигурации](/ru/patroni/config/yaml/): Полная справка по параметрам и разделам конфигурации Patroni YAML.
- [Настройки динамической конфигурации](/ru/patroni/config/dynamic/): Настройки динамической конфигурации, хранящиеся в DCS, применяются ко всему кластеру.
- [Настройки конфигурации среды](/ru/patroni/config/env/): Переменные среды для переопределения параметров конфигурации Patroni.
---
Backlinks:
- [Конфигурация среды](/ru/patroni/config/env/)
- [YAML Конфигурация](/ru/patroni/config/yaml/)
- [Преобразование существующего кластера](/ru/patroni/existing_data/)
- [Часто задаваемые вопросы](/ru/patroni/faq/)
- [Примечания к выпускам](/ru/patroni/releases/)