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

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

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

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

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. Например:

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.

Примечание

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

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

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

Создание реплик

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

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

пример: wal_e

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

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

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'

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 примера:

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

и

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

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