Использование плагина для хранения в S3

Павел Семёнов

Contents

Доступ к S3-хранилищу
Установка S3-плагина
- Предварительные требования
- Сборка и установка
Подготовка конфигурации плагина
Создание бэкапа в S3-хранилище
Восстановление данных из S3-хранилища
Параметры конфигурации S3-плагина

Этот раздел описывает, как использовать плагин для хранения бэкапов в S3-хранилище (S3-плагин, S3 storage plugin) с утилитами gpbackup и gprestore в Greengage DB.

Плагин для хранения в S3 расширяет возможности gpbackup и gprestore, позволяя использовать любое S3-совместимое хранилище для бэкапов. С его помощью gpbackup может автоматически выгружать бэкапы СУБД Greengage в Amazon S3 или любое другое хранилище, поддерживающее протокол S3 (Simple Storage Service). Это может быть публичное хранилище от облачного провайдера, например AWS S3, Wasabi или Google Cloud Storage в режиме совместимости с S3, или собственное хранилище.

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

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

Для использования S3-плагина необходимо иметь доступ к S3-совместимому хранилищу данных. Требуются следующие права доступа:

Загрузка и удаление объектов для операций бэкапа.
Чтение (просмотр, открытие и скачивание) объектов для операций восстановления.

Учетные данные доступа указываются в конфигурационном файле плагина, который используется при запуске gpbackup или gprestore. В зависимости от хранилища это могут быть пара AWS-ключей доступа или временный токен доступа.

Чтобы использовать S3-плагин, необходимо собрать его из исходного кода и разместить полученный бинарный файл на всех хостах кластера. Исходный код плагина доступен в репозитории gpbackup-s3-plugin.

Плагин написан на языке Go. Для его сборки на мастер-хосте должен быть установлен Go версии 1.19 или выше, а также определена переменная окружения GOPATH.

Чтобы проверить эти условия, выполните команды от имени пользователя gpadmin:

$ go version
$ echo $GOPATH

Вывод может выглядеть так:

go version go1.25.1 linux/amd64
/home/gpadmin/go

Инструкции по установке Go доступны на официальном сайте Go.

Чтобы собрать и установить S3-плагин для gpbackup и gprestore:

Убедитесь, что вы вошли в систему на мастер-хосте как gpadmin и находитесь в домашнем каталоге.

Клонируйте репозиторий gpbackup-s3-plugin:

$ git clone https://github.com/arenadata/gpbackup-s3-plugin.git

Перейдите в каталог gpbackup-s3-plugin:
```
$ cd gpbackup-s3-plugin
```
(Опционально) Переключитесь на тег для сборки и установки конкретной версии:
```
$ git checkout <tag_name>
```
где <tag_name> совпадает с номером версии.
Соберите плагин:
```
$ make build
```
Установите бинарный файл плагина на все хосты кластера:
```
$ make install
```
Эта команда копирует gpbackup_s3_plugin в каталог $GPHOME/bin на всех хостах кластера. В случае успеха вывод включает строку следующего вида:
```
Successfully copied gpbackup_s3_plugin to /usr/local/gpdb on all segments
```

В результате gpbackup_s3_plugin становится доступным на мастер-хосте и сегмент-хостах:

$ gpbackup_s3_plugin --version

Пример вывода:

gpbackup_s3_plugin version 1.10.0+dev.1.gd9993be

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

Файл конфигурации плагина имеет формат YAML. Пример конфигурации:

executablepath: $GPHOME/bin/gpbackup_s3_plugin
options:
  region: garage
  endpoint: http://10.92.40.164:3900
  aws_access_key_id: GK8bbdf080f0717c03add3e461
  aws_secret_access_key: 28efc14dfa24b7965e74a69b7a3a619e2b49e090875c883377b5a61ba0b48f05
  bucket: test-backup-bucket
  folder: test/ggbackup

В этой конфигурации заданы следующие параметры:

executablepath — абсолютный путь к исполняемому файлу S3-плагина. Обычно это $GPHOME/bin/gpbackup_s3_plugin.
options — верхнеуровневый раздел конфигурации, содержащий параметры плагина.
region — регион AWS или логический идентификатор вашего S3-совместимого хранилища.
endpoint — HTTP-эндпойнт S3-сервиса. Если не указан, плагин автоматически определяет эндпойнт на основе region при подключении к Amazon S3.
aws_access_key_id и aws_secret_access_key — учетные данные для аутентификации в хранилище.
bucket — имя S3-бакета для хранения бэкапов. Бакет должен существовать и быть доступен для указанных учетных данных.
folder — префикс пути внутри бакета, в котором будут храниться файлы бэкапа. Каждый бэкап сохраняется в подкаталоге вида <folder>/backups/YYYYMMDD/YYYYMMDDHHMMSS.

Полный список параметров с описаниями приведен в разделе Параметры конфигурации S3-плагина.

Чтобы сохранить бэкап базы данных в S3-хранилище, выполните gpbackup с опцией --plugin-config. В качестве значения укажите абсолютный путь к конфигурационному файлу плагина:

$ gpbackup --dbname marketplace --plugin-config /home/gpadmin/s3-config.yaml

После успешного завершения операции в выводе появится сообщение:

[INFO]:-Backup completed successfully

В результате gpbackup создает бэкап в локальных каталогах по умолчанию на узлах кластера и загружает его в S3-хранилище, указанное в конфигурации плагина. Проверить наличие загруженных файлов можно с помощью инструмента AWS CLI или любого другого клиента S3.

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

Чтобы выполнить приведенные ниже примеры команд AWS CLI, настройте следующие переменные окружения:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION
AWS_ENDPOINT_URL

Например:

$ export AWS_ACCESS_KEY_ID=GK8bbdf080f0717c03add3e461
$ export AWS_SECRET_ACCESS_KEY=28efc14dfa24b7965e74a69b7a3a619e2b49e090875c883377b5a61ba0b48f05
$ export AWS_DEFAULT_REGION='garage'
$ export AWS_ENDPOINT_URL='http://10.92.40.164:3900'

Проверить содержимое бэкапа в S3-хранилище можно командой aws s3 ls:

$ aws s3 ls test-backup-bucket/test/ggbackup/backups/20251021/20251021053010/

Вывод покажет список файлов бэкапа со всех узлов кластера:

2025-10-21 05:30:13      39724 gpbackup_0_20251021053010_19450.gz
2025-10-21 05:30:13       1123 gpbackup_0_20251021053010_19460.gz
2025-10-21 05:30:13      22351 gpbackup_0_20251021053010_19463.gz
2025-10-21 05:30:13      40713 gpbackup_1_20251021053010_19450.gz
2025-10-21 05:30:13       1050 gpbackup_1_20251021053010_19460.gz
2025-10-21 05:30:13      22524 gpbackup_1_20251021053010_19463.gz
2025-10-21 05:30:14        800 gpbackup_20251021053010_config.yaml
2025-10-21 05:30:13       2751 gpbackup_20251021053010_metadata.sql
2025-10-21 05:30:13        354 gpbackup_20251021053010_plugin_config.yaml
2025-10-21 05:30:14       1869 gpbackup_20251021053010_report
2025-10-21 05:30:13       4446 gpbackup_20251021053010_toc.yaml
2025-10-21 05:30:13      40610 gpbackup_2_20251021053010_19450.gz
2025-10-21 05:30:13       1076 gpbackup_2_20251021053010_19460.gz
2025-10-21 05:30:13      21971 gpbackup_2_20251021053010_19463.gz
2025-10-21 05:30:13      39901 gpbackup_3_20251021053010_19450.gz
2025-10-21 05:30:13       1025 gpbackup_3_20251021053010_19460.gz
2025-10-21 05:30:13      21655 gpbackup_3_20251021053010_19463.gz

ПРИМЕЧАНИЕ

Метаданные бэкапов, созданных с использованием S3-плагина, также сохраняются локально на мастер-хосте. Кроме обычных файлов метаданных, такие бэкапы включают файл gpbackup_<timestamp>_plugin_config.yaml, который содержит конфигурацию плагина, использованную при выполнении операции. Его можно использовать для последующего восстановления данных.

S3-плагин можно использовать с большинством стандартных опций настройки бэкапов, поддерживаемых gpbackup, например:

Частичное резервное копирование с фильтрацией схем и таблиц:
```
$ gpbackup --dbname marketplace --plugin-config /home/gpadmin/s3-config.yaml --include-table public.customers
```
Инкрементальное резервное копирование:
```
$ gpbackup --dbname marketplace --plugin-config /home/gpadmin/s3-config.yaml --incremental --leaf-partition-data
```
Для создания инкрементальных бэкапов нужен полный бэкап, созданный с опцией --leaf-partition-data, в том же расположении в S3-хранилище.
Однофайловые бэкапы, в которых все данные каждого сегмента хранятся в одном файле вместо нескольких:
```
$ gpbackup --dbname marketplace --plugin-config /home/gpadmin/s3-config.yaml --single-data-file
```

ВАЖНО

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

Чтобы восстановить данные из бэкапа в S3-хранилище, выполните gprestore с той же конфигурацией плагина, которая использовалась для создания бэкапа:

$ gprestore --timestamp 20251021054129 --plugin-config /home/gpadmin/s3-config.yaml

После успешного восстановления в выводе появится сообщение:

20251021:05:43:42 gprestore:gpadmin:spn-greengage24:003827-[INFO]:-Restore completed successfully

Плагин можно использовать совместно с различными опциями gprestore, например:

Частичное восстановление:

$ gprestore --timestamp 20251027040114 --plugin-config /home/gpadmin/s3-config.yaml --include-table public.customers

Восстановление только данных:

$ gprestore --timestamp 20251027040114 --plugin-config /home/gpadmin/s3-config.yaml --data-only

Восстановление в другую базу данных:
```
$ createdb marketplace_restore
$ gprestore --timestamp 20251027040114 --plugin-config /home/gpadmin/s3-config.yaml --redirect-db marketplace_restore
```
Такой сценарий полезен для проверки бэкапов без перезаписи данных в production-кластере.

S3-плагин использует конфигурационный файл в формате YAML, в котором задаются параметры плагина. В этом файле указываются путь к исполняемому файлу плагина, учетные данные для подключения к хранилищу, место размещения бэкапов и другие параметры.

Общая структура конфигурационного файла выглядит следующим образом:

executablepath: <absolute-path-to-gpbackup_s3_plugin>
options:
  region: <aws-region>
  endpoint: <S3-endpoint>
  aws_access_key_id: <aws-access-key-id>
  aws_secret_access_key: <aws-access-secret-key>
  aws_session_token: <aws-session-token>
  bucket: <s3-bucket>
  folder: <s3-location>
  encryption: [on|off]
  backup_max_concurrent_requests: [int] # default 6
  backup_multipart_chunksize: [string] # default 500MB
  restore_max_concurrent_requests: [int] # default 6
  restore_multipart_chunksize: [string] # default 500MB
  http_proxy: <proxy-address>
  remove_duplicate_bucket: [true|false]

Ключ Описание

Ключ	Описание
executablepath	Абсолютный путь к исполняемому файлу плагина S3-хранилища, например /usr/local/gpdb/bin/gpbackup_s3_plugin или $GPHOME/bin/gpbackup_s3_plugin. Файл должен находиться на всех хостах кластера в одинаковом месте
options	Обязательный раздел файла, который содержит параметры, относящиеся к S3-хранилищу
region	AWS-регион, который используется при работе с Amazon S3. Если регион указан, параметр `endpoint` определяется автоматически. При использовании другого S3-совместимого хранилища этот параметр может быть необязательным в зависимости от конфигурации
endpoint	HTTP- или HTTPS-эндпойнт S3-совместимого хранилища. Обязателен для других S3-хранилищ кроме Amazon, включая развернутые в собственной среде. Для Amazon S3 эндпойнт определяется автоматически на основе параметра `region`
aws_access_key_id	Идентификатор ключа доступа, используемый для аутентификации в S3. Обязателен вместе с `aws_secret_access_key`, если используется доступ по ключу. ПРИМЕЧАНИЕ Если учетные данные не указаны в конфигурационном файле, плагин ищет их в следующем порядке: Переменные окружения `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` и `AWS_SESSION_TOKEN`. Учетные данные AWS CLI, заданные командой `aws configure`. Учетные данные IAM-роли (если операция выполняется на экземпляре EC2).
aws_secret_access_key	Секретный ключ для указанного идентификатором ключа доступа. Обязателен, если указан `aws_access_key_id`
aws_session_token	Временный AWS-токен доступа. Используется при аутентификации по токену
bucket	Имя S3-бакета, в котором будут храниться бэкапы. Бакет должен существовать в целевом хранилище
folder	Путь внутри бакета, где размещаются бэкапы. Если указанный путь отсутствует, плагин создаст его при первой загрузке бэкапа. Бэкапы сохраняются в подкаталогах следующего вида: <folder>/backups/YYYYMMDD/YYYYMMDDHHMMSS
encryption	Определяет, используется ли защищенное (SSL) подключение к хранилищу. Возможные значения: `on` (по умолчанию) и `off`
backup_max_concurrent_requests	Максимальное количество параллельных подключений для загрузки одного файла при создании бэкапа (по умолчанию `6`). Общее количество параллельных загрузок зависит также от числа сегментов и значения опции `--jobs` в вызове `gpbackup`. Например, в кластере с 8 сегментами при настройке по умолчанию каждый сегмент может выполнять до 6 одновременных загрузок (всего 48). Если параметр `--jobs` увеличен до `10`, каждая задача может загружать до 6 файлов параллельно. В результате может быть до 480 одновременных загрузок. Этот лимит применяется только к многосоставным (multipart) загрузкам, определяемым параметром `backup_multipart_chunksize`. Файлы меньшего размера передаются одной операцией
backup_multipart_chunksize	Размер части (chunk) при многосоставной загрузке. Можно задавать в байтах (`B`), мегабайтах (`MB`) или гигабайтах (`GB`). Значение по умолчанию — `500MB`, минимально допустимое — `5MB` (или `5242880B`). Части файла загружаются параллельно; уровень параллелизма определяется параметром `backup_max_concurrent_requests`
restore_max_concurrent_requests	Максимальное количество параллельных подключений при скачивании одного файла во время восстановления (по умолчанию `6`). Работает аналогично `backup_max_concurrent_requests`
restore_multipart_chunksize	Размер части файла при многосоставном скачивании во время восстановления. Работает аналогично `backup_multipart_chunksize`
http_proxy	Адрес HTTP-прокси, используемого для доступа к хранилищу. Может быть указан в виде URL с аутентификацией или без нее: http://<url>:<port> http://<username>:<password>@<url>:<port>
remove_duplicate_bucket	Возможные значения: `false` (по умолчанию) и `true`. Помогает избежать ошибок NoSuchBucket в некоторых S3-совместимых хранилищах

executablepath

Абсолютный путь к исполняемому файлу плагина S3-хранилища, например /usr/local/gpdb/bin/gpbackup_s3_plugin или $GPHOME/bin/gpbackup_s3_plugin. Файл должен находиться на всех хостах кластера в одинаковом месте

options

Обязательный раздел файла, который содержит параметры, относящиеся к S3-хранилищу

region

AWS-регион, который используется при работе с Amazon S3. Если регион указан, параметр endpoint определяется автоматически.

При использовании другого S3-совместимого хранилища этот параметр может быть необязательным в зависимости от конфигурации

endpoint

HTTP- или HTTPS-эндпойнт S3-совместимого хранилища. Обязателен для других S3-хранилищ кроме Amazon, включая развернутые в собственной среде.

Для Amazon S3 эндпойнт определяется автоматически на основе параметра region

aws_access_key_id

Идентификатор ключа доступа, используемый для аутентификации в S3. Обязателен вместе с aws_secret_access_key, если используется доступ по ключу.

ПРИМЕЧАНИЕ

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

Переменные окружения AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY и AWS_SESSION_TOKEN.
Учетные данные AWS CLI, заданные командой aws configure.
Учетные данные IAM-роли (если операция выполняется на экземпляре EC2).

aws_secret_access_key

Секретный ключ для указанного идентификатором ключа доступа. Обязателен, если указан aws_access_key_id

aws_session_token

Временный AWS-токен доступа. Используется при аутентификации по токену

bucket

Имя S3-бакета, в котором будут храниться бэкапы. Бакет должен существовать в целевом хранилище

folder

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

Бэкапы сохраняются в подкаталогах следующего вида: <folder>/backups/YYYYMMDD/YYYYMMDDHHMMSS

encryption

Определяет, используется ли защищенное (SSL) подключение к хранилищу. Возможные значения: on (по умолчанию) и off

backup_max_concurrent_requests

Максимальное количество параллельных подключений для загрузки одного файла при создании бэкапа (по умолчанию 6).

Общее количество параллельных загрузок зависит также от числа сегментов и значения опции --jobs в вызове gpbackup. Например, в кластере с 8 сегментами при настройке по умолчанию каждый сегмент может выполнять до 6 одновременных загрузок (всего 48). Если параметр --jobs увеличен до 10, каждая задача может загружать до 6 файлов параллельно. В результате может быть до 480 одновременных загрузок.

Этот лимит применяется только к многосоставным (multipart) загрузкам, определяемым параметром backup_multipart_chunksize. Файлы меньшего размера передаются одной операцией

backup_multipart_chunksize

Размер части (chunk) при многосоставной загрузке. Можно задавать в байтах (B), мегабайтах (MB) или гигабайтах (GB). Значение по умолчанию — 500MB, минимально допустимое — 5MB (или 5242880B).

Части файла загружаются параллельно; уровень параллелизма определяется параметром backup_max_concurrent_requests

restore_max_concurrent_requests

Максимальное количество параллельных подключений при скачивании одного файла во время восстановления (по умолчанию 6). Работает аналогично backup_max_concurrent_requests

restore_multipart_chunksize

Размер части файла при многосоставном скачивании во время восстановления. Работает аналогично backup_multipart_chunksize

http_proxy

Адрес HTTP-прокси, используемого для доступа к хранилищу. Может быть указан в виде URL с аутентификацией или без нее:

http://<url>:<port>
http://<username>:<password>@<url>:<port>

remove_duplicate_bucket

Возможные значения: false (по умолчанию) и true. Помогает избежать ошибок NoSuchBucket в некоторых S3-совместимых хранилищах

Инкрементальное резервное копирование

gpbackup

Использование плагина для хранения в S3

Доступ к S3-хранилищу

Установка S3-плагина

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

Сборка и установка

Подготовка конфигурации плагина

Создание бэкапа в S3-хранилище

Восстановление данных из S3-хранилища

Параметры конфигурации S3-плагина