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

> Создание образов реплик, начальная инициализация и пользовательские процессы создания реплик.

---

Индекс LLMS: [llms.txt](/ru/llms.txt)

---

<a id="replica_imaging_and_bootstrap"></a>
Patroni позволяет настраивать создание новой реплики и определять действия при начальной инициализации нового пустого кластера. Различие строго определено: Patroni создаёт реплики, только если для кластера в DCS присутствует ключ `initialize`. Если ключа `initialize` нет, Patroni выполняет начальную инициализацию исключительно на первом узле, получившем блокировку ключа initialize.

<a id="custom_bootstrap"></a>

--------

## Начальная инициализация {#bootstrap}

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

```yaml
bootstrap:
    method: <custom_bootstrap_method_name>
    <custom_bootstrap_method_name>:
        command: <path_to_custom_bootstrap_script> [param1 [, ...]]
        keep_existing_recovery_conf: False
        no_params: False
        recovery_conf:
            recovery_target_action: promote
            recovery_target_timeline: latest
            restore_command: <method_specific_restore_command>
```

Каждый метод начальной инициализации должен определить как минимум `name` и `command`. Специальный метод `initdb` запускает поведение по умолчанию; в этом случае параметр `method` можно полностью опустить. `command` задаётся абсолютным путём либо путём относительно расположения команды `patroni`. Помимо фиксированных параметров файла конфигурации Patroni передаёт два параметра конкретного кластера:

`--scope`  
Имя инициализируемого кластера

`--datadir`  
Путь к каталогу данных инициализируемого экземпляра кластера

Передачу этих двух дополнительных флагов можно отключить, задав специальному параметру `no_params` значение `True`.

Если сценарий начальной инициализации возвращает `0`, Patroni пытается настроить и запустить созданный им экземпляр PostgreSQL. Если промежуточный шаг завершается ошибкой либо сценарий возвращает ненулевое значение, Patroni считает инициализацию неудачной, очищает созданные данные и освобождает блокировку initialize, позволяя другому узлу выполнить инициализацию.

Если в том же разделе, что и пользовательский метод, определён блок `recovery_conf`, Patroni перед запуском нового экземпляра создаёт `recovery.conf` либо задаёт параметры восстановления в конфигурации Postgres для PostgreSQL \>= 12. Обычно такая конфигурация должна содержать хотя бы один параметр `recovery_target_*` вместе с `recovery_target_action`, равным `promote`.

Если `keep_existing_recovery_conf` определён и равен `True`, Patroni не удаляет существующий `recovery.conf` в PostgreSQL \<= 11. Аналогично, Patroni не удаляет существующие `recovery.signal` или `standby.signal` и не переопределяет настроенные параметры восстановления в PostgreSQL \>= 12. Это полезно при начальной инициализации из резервной копии инструментом наподобие pgBackRest, который самостоятельно создаёт подходящую конфигурацию восстановления.

Кроме того, дополнительные пары «ключ — значение» из конфигурации пользовательского метода передаются как аргументы `command` в формате `--name=value`. Например:

```yaml
bootstrap:
    method: <custom_bootstrap_method_name>
    <custom_bootstrap_method_name>:
        command: <path_to_custom_bootstrap_script>
        arg1: value1
        arg2: value2
```

Настроенная `command` будет дополнительно вызвана с аргументами командной строки `--arg1=value1 --arg2=value2`.

> > [!NOTE]
> > Методы начальной инициализации не объединяются в цепочку, и при ошибке основного метода возврат к методу по умолчанию не выполняется

Например, новый кластер Patroni можно инициализировать из резервной копии Barman со следующей конфигурацией:

```yaml
bootstrap:
    method: barman
    barman:
        keep_existing_recovery_conf: true
        command: patroni_barman --api-url https://barman-host:7480 recover
        barman-server: my_server
        ssh-command: ssh postgres@patroni-host
```

> [!NOTE]
> Для `patroni_barman recover` на узле Barman должны быть настроены Barman и `pg-backup-api`, чтобы удалённо выполнять `barman recover` через API резервного копирования. В примере выше используется часть доступных параметров. Дополнительные сведения выводит команда `patroni_barman recover --help`.

<a id="custom_replica_creation"></a>

--------

## Создание реплик {#building-replicas}

Для создания новых реплик Patroni использует проверенный `pg_basebackup`. Его недостатки — необходимость работающего узла-лидера, отсутствие сжатия резервных данных «на лету» и встроенной очистки устаревших файлов копий. Некоторые предпочитают другие решения, например `WAL-E`, `pgBackRest`, `Barman`, либо собственные сценарии. Для этих случаев Patroni поддерживает пользовательские сценарии клонирования новой реплики. Они настраиваются в блоке `postgresql`:

```yaml
postgresql:
    create_replica_methods:
        - <method name>
    <method name>:
        command: <command name>
        keep_data: True
        no_params: True
        no_leader: 1
```

пример: wal_e

```yaml
postgresql:
    create_replica_methods:
        - wal_e
        - basebackup
    wal_e:
        command: patroni_wale_restore
        no_leader: 1
        envdir: '{{WALE_ENV_DIR}}'
        use_iam: 1
    basebackup:
        max-rate: '100M'
```

пример: pgbackrest

```yaml
postgresql:
    create_replica_methods:
        - pgbackrest
        - basebackup
    pgbackrest:
        command: /usr/bin/pgbackrest --stanza=<scope> --delta restore
        keep_data: True
        no_params: True
    basebackup:
        max-rate: '100M'
```

пример: Barman

```yaml
postgresql:
    create_replica_methods:
        - barman
        - basebackup
    barman:
        command: patroni_barman --api-url https://barman-host:7480 recover
        barman-server: my_server
        ssh-command: ssh postgres@patroni-host
    basebackup:
        max-rate: '100M'
```

> [!NOTE]
> Для `patroni_barman recover` на узле Barman должны быть настроены Barman и `pg-backup-api`, чтобы удалённо выполнять `barman recover` через API резервного копирования. В примере выше используется часть доступных параметров. Дополнительные сведения выводит команда `patroni_barman recover --help`.

`create_replica_methods` определяет доступные методы создания реплик и порядок их выполнения. Patroni останавливается на первом методе, вернувшем 0. Для каждого метода следует определить отдельный раздел файла конфигурации с выполняемой командой и передаваемыми ей пользовательскими параметрами. Все параметры передаются в формате `--name=value`. Помимо параметров пользователя Patroni передаёт несколько параметров конкретного кластера:

`--scope`  
Кластер, которому принадлежит реплика

`--datadir`  
Путь к каталогу данных реплики

`--role`  
Всегда 'replica'

`--connstring`  
Строка подключения к участнику кластера, с которого выполняется клонирование (первичному серверу или другой реплике). Пользователь из строки подключения может выполнять команды SQL и протокола репликации.

Специальный параметр `no_leader`, если он определён, позволяет Patroni вызывать метод создания реплики даже при отсутствии работающего лидера или реплик. В таком случае передаётся пустая строка подключения. Это полезно для восстановления ранее работавшего кластера из двоичной резервной копии.

Специальный параметр `keep_data`, если он определён, запрещает Patroni очищать каталог PGDATA перед вызовом восстановления.

Специальный параметр `no_params`, если он определён, запрещает передачу параметров пользовательской команде.

Метод `basebackup` — особый случай: он используется, если `create_replica_methods` пуст, хотя его можно явно перечислить среди методов `create_replica_methods`. Метод инициализирует новую реплику с помощью `pg_basebackup`. Базовая резервная копия берётся с лидера, если нет реплик с тегом `clonefrom`; в противном случае источником pg_basebackup служит одна из таких реплик. Метод работает без конфигурации, но можно определить раздел `basebackup`. Применяются те же правила, что и для других методов: следует указывать только длинные параметры с --. Не все параметры имеют смысл: если переопределить строку подключения или запросить архивированную tar либо сжатую базовую копию, Patroni не сможет создать из неё реплику. Имена и значения параметров раздела `basebackup` не проверяются. Если для каталога WAL используются символические ссылки, пользователь должен указать правильный путь `--waldir`, чтобы ссылка сохранилась после создания или повторной инициализации реплики. Этот параметр поддерживается только начиная с v10.

Параметры basebackup можно задать как отображение пар «ключ — значение» либо как список элементов, каждый из которых является парой или отдельным ключом для параметров без значений, например `--verbose`. Рассмотрим 2 примера:

```yaml
postgresql:
    basebackup:
        max-rate: '100M'
        checkpoint: 'fast'
```

и

```yaml
postgresql:
    basebackup:
        - verbose
        - max-rate: '100M'
        - waldir: /pg-wal-mount/external-waldir
```

Если все методы создания реплики завершаются ошибкой, Patroni повторяет их по порядку в следующем цикле обработки событий.

---

Обратные ссылки:

- [YAML Конфигурация](/ru/docs/patroni/config/yaml/)
- [Часто задаваемые вопросы](/ru/docs/patroni/faq/)
- [Примечания к выпускам](/ru/docs/patroni/releases/)
- [Patroni REST API](/ru/docs/patroni/rest_api/)
- [Резервный кластер](/ru/docs/patroni/standby_cluster/)
- [Интеграция инструментов](/ru/docs/patroni/tools_integration/)