备份/恢复存储插件API（Beta版）

本主题介绍如何使用Greenplum数据库备份/还原存储插件API开发自定义存储插件。

Note: 只有备份/还原存储插件API才是Beta功能。存储插件是受支持的功能。

备份/恢复存储插件API提供了一个框架，您可以使用该框架开发自定义备份存储系统并将其与Greenplum数据库gpbackup和gprestore工具集成。

备份/恢复存储插件API定义了插件必须支持的一组接口。 API还指定插件的配置文件的格式和内容。

使用备份/还原存储插件API时，您将创建Greenplum数据库管理员部署到Greenplum数据库集群的插件。部署后，该插件可用于某些备份和还原操作。

本主题包含如下子主题：

插件配置文件
插件API
插件命令
实现一个备份/恢复存储插件
验证备份/还原存储插件
打包和部署备份/还原存储插件

插件配置文件

指定gpbackup和gprestore命令的--plugin-config选项会指示工具使用配置文件中指定的插件进行操作。

插件配置文件提供Greenplum数据库和插件的信息。备份/恢复存储插件API定义插件配置文件的格式和某些关键字。

插件的配置文件是一个如下格式的YAML文件：

executablepath: path_to_plugin_executable
options:
  keyword1: value1
  keyword2: value2
  ...
  keywordN: valueN

gpbackup和gprestore使用executablepath值来确定插件可执行程序的文件系统位置。

插件配置文件还可以包括特定于插件实例的关键字和值。备份/恢复存储插件可以使用文件中指定的选项块来从用户获取执行其任务所需的信息。例如，该信息可以包括位置，连接或认证信息。插件应该在keyword:value语法中指定和使用此信息的内容。

Greenplum数据库S3备份/恢复存储插件的示例插件配置文件如下：

executablepath: $GPHOME/bin/gpbackup_s3_plugin
options:
  region: us-west-2
  aws_access_key_id: notarealID
  aws_secret_access_key: notarealkey
  bucket: gp_backup_bucket
  folder: greenplum_backups

插件API

您使用备份/恢复存储插件API时实现的插件是一个可执行程序，它支持gpbackup和gprestore在各自生命周期操作中定义的点调用的特定命令：

Greenplum数据库备份/恢复存储插件API，提供在初始化、备份和清理/退出时挂载到gpbackup生命周期的钩子。
API在初始化、恢复期间以及清理/退出时提供到gprestore生命周期的钩子。
API提供了参数，用于指定插件设置或清除命令的执行范围（master主机，segment主机或segment实例）。范围可以是这些值之一。
- master - 在master主机上执行一次插件。
- segment_host - 在每个segment主机上执行一次插件。
- segment - 对运行segment实例的主机上的每个活着的segment实例执行一次插件。
备份开始时，Greenplum数据库master和segment实例基于Greenplum数据库配置。值segment_host和segment是作为segment主机提供的，可以托管多个segment实例。与每个segment实例相比，segment主机级别可能需要一些设置或清理。

备份/恢复存储插件API为备份/恢复存储插件可执行程序定义以下调用语法：

plugin_executable command config_file args

其中：

plugin_executable - 备份/恢复存储插件可执行程序的绝对路径。此路径由插件的配置YAML文件中配置的executablepath属性值确定。
command - 备份/恢复存储插件API命令的名称，用于标识gpbackup或gprestore生命周期操作的特定入口点。
config_file - 插件的配置YAML文件的绝对路径。
args - 命令参数; 实际参数因指定的command而异。

插件命令

Greenplum数据库备份/恢复存储插件API定义以下命令：

Table 1. 备份/恢复存储插件API命令
命令名称	描述
plugin_api_version	返回插件支持的备份/恢复存储插件API的版本。唯一支持的版本是0.3.0。
setup_plugin_for_backup	初始化插件以进行备份操作。
backup_file	将备份文件移动到远程存储系统。
backup_data	将流数据从`stdin`移动到远程存储系统上的文件。
cleanup_plugin_for_backup	备份操作后清理。
setup_plugin_for_restore	初始化插件以进行还原操作。
restore_file	将备份文件从远程存储系统移动到本地主机上的指定位置。
restore_data	从远程存储系统移动备份文件，将数据流式传输到`stdout`。
cleanup_plugin_for_restore	还原操作后清理。

备份/恢复存储插件必须支持上面标识的每个命令，即使它是无操作。

实现一个备份/恢复存储插件

您可以使用任何编程语言或脚本语言实现可执行的备份/恢复存储插件。

备份/恢复存储插件执行的任务将非常特定于远程存储系统。在设计插件实现时，您需要：

检查远程存储系统的连接和数据传输接口。
确定远程系统的存储路径细节。
确定用户所需的配置信息。
为插件配置文件中所需的信息定义关键字和值语法。
确定插件是否以及如何修改（压缩等）到达/来自远程存储系统的数据。
定义gpbackup文件路径和远程存储系统之间的映射。
确定gpbackup选项如何影响插件，以及哪些是必需的和/或不适用的。例如，如果插件执行自己的压缩，则必须使用--no-compression选项调用gpbackup以防止工具压缩数据。

您实现的备份/恢复存储插件必须：

支持插件命令中标识的所有插件命令。每个命令都必须使用命令参考页面上标识的值退出。

插件实现的示例，请参考github仓库gpbackup-s3-plugin。

验证备份/还原存储插件

备份/恢复存储插件API包含一个测试平台，您可以运行该平台以确保插件与gpbackup和gprestore良好集成。

测试平台是您在Greenplum数据库安装中运行的bash脚本。该脚本在Greenplum数据库表中生成一个小（<1MB）数据集，显式测试每个命令，并运行数据的备份和恢复（文件和流）。测试平台调用gpbackup和gprestore，后者又单独调用/测试插件中实现的每个备份/还原存储插件API命令。

测试平台程序调用语法是：

plugin_test_bench.sh plugin_executable plugin_config

过程

针对插件运行备份/恢复存储插件API测试平台：

登录Greenplum数据库master主机并设置您的环境。例如：

$ ssh gpadmin@<gpmaster>
gpadmin@gpmaster$ . /usr/local/greenplum-db/greenplum_path.sh

从gpbackupgithub仓库获取测试平台的副本。例如：
```
$ git clone git@github.com:greenplum-db/gpbackup.git
```
克隆操作在当前工作目录中创建名为gpbackup/的目录。
在gpbackup/master/plugins目录中找到测试平台程序。例如：
```
$ ls gpbackup/master/plugins/plugin_test_bench.sh
```
将插件可执行程序和插件配置YAML文件从开发系统复制到Greenplum数据库master主机。记下复制文件的文件系统位置。
将插件可执行程序从Greenplum数据库master主机复制到每个segment主机上的相同文件系统位置。
如果需要，编辑插件配置YAML文件以指定刚刚复制到Greenplum segment的插件可执行程序的绝对路径。

针对插件运行测试平台程序。例如：

$ gpbackup/master/plugins/plugin_test_bench.sh /path/to/pluginexec /path/to/plugincfg.yaml

检查测试台输出。如果所有输出消息都显示RUNNING或PASSED，则您的插件会通过测试平台。例如：

# ----------------------------------------------
# Starting gpbackup plugin tests
# ----------------------------------------------
[RUNNING] plugin_api_version
[PASSED] plugin_api_version
[RUNNING] setup_plugin_for_backup
[RUNNING] backup_file
[RUNNING] setup_plugin_for_restore
[RUNNING] restore_file
[PASSED] setup_plugin_for_backup
[PASSED] backup_file
[PASSED] setup_plugin_for_restore
[PASSED] restore_file
[RUNNING] backup_data
[RUNNING] restore_data
[PASSED] backup_data
[PASSED] restore_data
[RUNNING] cleanup_plugin_for_backup
[PASSED] cleanup_plugin_for_backup
[RUNNING] cleanup_plugin_for_restore
[PASSED] cleanup_plugin_for_restore
[RUNNING] gpbackup with test database
[RUNNING] gprestore with test database
[PASSED] gpbackup and gprestore
# ----------------------------------------------
# Finished gpbackup plugin tests
# ----------------------------------------------

打包和部署备份/还原存储插件

在插件通过测试和测试台验证后，您的备份/恢复存储插件已准备好部署到Greenplum数据库安装。打包备份/还原存储插件时，请考虑以下事项：

备份/恢复存储插件必须安装在Greenplum数据库集群中每个主机上的相同位置。提供插件标识相同的安装说明。
gpadmin用户必须具有遍历备份/恢复插件可执行程序的文件系统路径的权限。
在插件中包含模板配置文件。
记录有效的插件配置关键字，确保包含期望值的语法。
记录gpbackup所需的选项以及它们如何影响插件处理。