docs - add content for backup storage plugin api (#4901)

* docs - add content for backup storage plugin api * some edits requested by david * comments from mel; remove diagram placeholder * address some requested edits from karen * gpbackup creates the local directory * include restore more * remove bold styling from command * clarify streaming backup * address some review comments * add backup/restore plugin api cmds to subnav * remove the on-page toc entries for cmds * wrap up the edits from karen

docs - add content for backup storage plugin api (#4901)
* docs - add content for backup storage plugin api * some edits requested by david * comments from mel; remove diagram placeholder * address some requested edits from karen * gpbackup creates the local directory * include restore more * remove bold styling from command * clarify streaming backup * address some review comments * add backup/restore plugin api cmds to subnav * remove the on-page toc entries for cmds * wrap up the edits from karen
5c81bbe7 · Lisa Owen · David Yozie · dcc208fb · 5c81bbe7 · 5c81bbe7
11 changed file
--- a/gpdb-doc/dita/admin_guide/managing/backup-plugin-api.xml
+++ b/gpdb-doc/dita/admin_guide/managing/backup-plugin-api.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="backup-plugin-api" xml:lang="en">
+  <title id="kk1598353">Backup/Restore Storage Plugin API</title>
+  <body>
+  <p>This topic describes how to develop a custom storage plugin with the Greenplum Database Backup/Restore Storage Plugin API.</p>
+    <note type="warning">The Greenplum Database Backup/Restore Storage Plugin API
+      is an experimental feature and is not intended for use in a production
+      environment. Experimental features are subject to change without notice
+      in future releases.</note>
+    <p>The Backup/Restore Storage Plugin API provides a framework that you can use to develop and integrate a custom backup storage system with the Greenplum Database <xref href="../../utility_guide/admin_utilities/gpbackup.xml"><codeph>gpbackup</codeph></xref> and <xref href="../../utility_guide/admin_utilities/gprestore.xml"><codeph>gprestore</codeph></xref> utilities.</p>
+    <p>The Backup/Restore Storage Plugin API defines a set of interfaces that a plugin must support.  The API also specifies the format and content of a configuration file for a plugin.</p>
+    <p>When you use the Backup/Restore Storage Plugin API, you create a plugin that the Greenplum Database administrator deploys to the Greenplum Database cluster. Once deployed, the plugin is available for use in certain backup and restore operations.</p>
+    <note>Greenplum Database supports using a custom storage plugin on a backup operation only when <codeph>gpbackup</codeph> is run with the <codeph>--single-data-file</codeph> or <codeph>--metadata-only</codeph> options.</note>
+
+    <p>This topic includes the following subtopics:</p>
+    <ul id="ul_wjf_1wy_sp">
+      <li id="im168064">
+        <xref href="#topic9339" type="topic" format="dita"/>
+      </li>
+      <li id="im16806a">
+        <xref href="#topic_api" type="topic" format="dita"/>
+      </li>
+      <li id="im16806b">
+        <xref href="#topic_commands" type="topic" format="dita"/>
+      </li>
+      <li id="im16806c">
+        <xref href="#topic9337" type="topic" format="dita"/>
+      </li>
+      <li id="im16806d">
+        <xref href="#topic9339a" type="topic" format="dita"/>
+      </li>
+      <li id="im16806e">
+        <xref href="#topic9339b" type="topic" format="dita"/>
+      </li>
+    </ul>
+
+    </body>
+
+  <topic id="topic9339" xml:lang="en">
+    <title>Plugin Configuration File</title>
+    <body>
+      <p>Specifying the <codeph>--plugin-config</codeph> option to the <codeph>gpbackup</codeph> and <codeph>gprestore</codeph> commands instructs the utilities to use the plugin specified in the configuration file for the operation.</p>
+      <p>The plugin configuration file provides information for both Greenplum Database and the plugin. The Backup/Restore Storage Plugin API defines the format of, and certain keywords used in, the plugin configuration file.</p>
+      <p>A plugin configuration file is a YAML file in the following format: <codeblock><b>executablepath</b>: <varname>path_to_plugin_executable</varname>
+<b>options</b>:
+  <varname>keyword1</varname>: <varname>value1</varname>
+  <varname>keyword2</varname>: <varname>value2</varname>
+  ...
+  <varname>keywordN</varname>: <varname>valueN</varname></codeblock></p>
+      <p><codeph>gpbackup</codeph> and <codeph>gprestore</codeph> use the <codeph><b>executablepath</b></codeph> value to determine the file system location of the plugin executable program.</p>
+      <p>The plugin configuration file may also include keywords and values specific to a plugin instance. A backup/restore storage plugin can use the <codeph><b>options</b></codeph> block specified in the file to obtain information from the user that may be required to perform its tasks. This information may include location, connection, or authentication information, for example. The plugin should both specify and consume the content of this information in <codeph><varname>keyword</varname>:<varname>value</varname></codeph> syntax.</p>
+
+      <p>A sample plugin configuration file for the Greenplum Database S3 backup/restore storage plugin follows:<codeblock>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
+  backupdir: greenplum_backups</codeblock></p> 
+    </body>
+  </topic>
+
+  <topic id="topic_api" xml:lang="en">
+    <title>Plugin API</title>
+    <body>
+      <p>The plugin that you implement when you use the Backup/Restore Storage Plugin API is an executable program that supports specific <varname>command</varname>s invoked by <codeph>gpbackup</codeph> and <codeph>gprestore</codeph> at defined points in their respective life cycle operations:</p><ul>
+        <li>The Greenplum Database Backup/Restore Storage Plugin API provides hooks into the <codeph>gpbackup</codeph> lifecycle at initialization, during backup, and at cleanup/exit time.</li>
+        <li>The API provides hooks into the <codeph>gprestore</codeph> lifecycle at initialization, during restore, and at cleanup/exit time.</li></ul>
+
+      <p>The Backup/Restore Storage Plugin API defines the following call syntax for a backup/restore storage plugin executable program:<codeblock><varname>plugin_executable</varname> <varname>command</varname> <varname>config_file</varname> <varname>arg</varname></codeblock></p>
+
+      <p>where:</p><ul>
+        <li><codeph><varname>plugin_executable</varname></codeph> - The absolute path of the backup/restore storage plugin executable program. This path is determined by the <codeph>executablepath</codeph> property value configured in the plugin's configuration YAML file.</li>
+        <li><codeph><varname>command</varname></codeph> - The name of a Backup/Restore Storage Plugin API command that identifies a specific entry point to a <codeph>gpbackup</codeph> or <codeph>gprestore</codeph> lifecycle operation.</li>
+        <li><codeph><varname>config_file</varname></codeph> - The absolute path of the plugin's configuration YAML file.</li>
+        <li><codeph><varname>arg</varname></codeph> - The command argument; the actual argument differs depending upon the <codeph><varname>command</varname></codeph> specified.</li>
+      </ul>
+
+    </body>
+  <topic id="topic_commands" xml:lang="en">
+    <title>Plugin Commands</title>
+    <body>
+      <p>The Greenplum Database Backup/Restore Storage Plugin API defines the following commands:
+  <table class="- topic/table " id="table_b1q_m2h_zz">
+    <title class="- topic/title ">Backup/Restore Storage Plugin API Commands</title>
+    <tgroup cols="2" class="- topic/tgroup ">
+      <colspec colnum="1" colname="col1" colwidth="100pt" class="- topic/colspec "/>
+      <colspec colnum="2" colname="col3" colwidth="300pt" class="- topic/colspec "/>
+      <thead class="- topic/thead ">
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry ">Command Name</entry>
+          <entry colname="col3" class="- topic/entry ">Description</entry>
+        </row>
+      </thead>
+      <tbody class="- topic/tbody ">
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/plugin_api_version.xml#topic1"
+            type="topic" format="dita">plugin_api_version</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Return the version of the Backup/Restore Storage Plugin API supported by the plugin. The only supported version is 0.1.0.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/setup_plugin_for_backup.xml#topic1"
+            type="topic" format="dita">setup_plugin_for_backup</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Initialize the plugin for a backup operation.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/backup_file.xml#topic1"
+            type="topic" format="dita">backup_file</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Move a backup file to the remote storage system.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/backup_data.xml#topic1"
+            type="topic" format="dita">backup_data</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Move streaming data from <codeph>stdin</codeph> to a file on the remote storage system.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/cleanup_plugin_for_backup.xml#topic1"
+            type="topic" format="dita">cleanup_plugin_for_backup</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Clean up after a backup operation.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/setup_plugin_for_restore.xml#topic1"
+            type="topic" format="dita">setup_plugin_for_restore</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Initialize the plugin for a restore operation.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/restore_file.xml#topic1"
+            type="topic" format="dita">restore_file</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Move a backup file from the remote storage system to a designated location on the local host.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/restore_data.xml#topic1"
+            type="topic" format="dita">restore_data</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Move a backup file from the remote storage system, streaming the data to <codeph>stdout</codeph>.</entry>
+        </row>
+        <row class="- topic/row ">
+          <entry colname="col1" class="- topic/entry "><xref href="plugin_api/cleanup_plugin_for_restore.xml#topic1"
+            type="topic" format="dita">cleanup_plugin_for_restore</xref></entry>
+          <entry colname="col3" class="- topic/entry ">Clean up after a restore operation.</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+</p>
+    <p>A backup/restore storage plugin must support every command identified above, even if it is a no-op.</p>
+  </body>
+  </topic>
+  </topic>
+
+  <topic id="topic9337" xml:lang="en">
+    <title>Implementing a Backup/Restore Storage Plugin</title>
+    <body>
+      <p>You can implement a backup/restore storage plugin executable in any programming or scripting language.</p>
+      <p>The tasks performed by a backup/restore storage plugin will be very specific to the remote storage system. As you design the plugin implementation, you will want to:</p><ul>
+        <li>Examine the connection and data transfer interface to the remote storage system.</li>
+        <li>Identify the storage path specifics of the remote system.</li>
+        <li>Identify configuration information required from the user.</li>
+        <li>Define the keywords and value syntax for information required in the plugin configuration file.</li>
+        <li>Determine if, and how, the plugin will modify (compress, etc.) the data en route to/from the remote storage system.</li>
+        <li>Define a mapping between a <codeph>gpbackup</codeph> file path and the remote storage system.</li>
+        <li>Identify how <codeph>gpbackup</codeph> options affect the plugin, as well as which are required and/or not applicable. For example, if the plugin performs its own compression, <codeph>gpbackup</codeph> must be invoked with the <codeph>--no-compression</codeph> option to prevent the utility from compressing the data.</li>
+      </ul>
+      <p>A backup/restore storage plugin that you implement must:</p><ul>
+        <li>Support all plugin commands identified in <xref href="#topic_commands" type="topic" format="dita"/>. Each command must exit with the values identified on the command reference page.</li>
+      </ul>
+      <p>Refer to the <xref href="https://github.com/greenplum-db/gpbackup-s3-plugin" format="html" scope="external">gpbackup-s3-plugin</xref> github repository for an example plugin implementation.</p>
+    </body>
+  </topic>
+
+  <topic id="topic9339a" xml:lang="en">
+    <title>Verifying a Backup/Restore Storage Plugin</title>
+    <body>
+      <p>The Backup/Restore Storage Plugin API includes a test bench that you can run to ensure that a plugin is well integrated with <codeph>gpbackup</codeph> and <codeph>gprestore</codeph>.</p>
+      <p>The test bench is a <codeph>bash</codeph> script that you run in a Greenplum Database installation. The script generates a small (&lt;1MB) data set in a Greenplum Database table, explicitly tests each command, and runs a backup and restore of the data (file and streaming). The test bench invokes <codeph>gpbackup</codeph> and <codeph>gprestore</codeph>, which in turn individually call/test each Backup/Restore Storage Plugin API command implemented in the plugin.</p>
+      <p>The test bench program calling syntax is: <codeblock><b>plugin_test_bench.sh</b> <varname>plugin_executable plugin_config</varname></codeblock></p>
+    <section id="topic8339191" xml:lang="en">
+      <title>Procedure</title>
+      <p>To run the Backup/Restore Storage Plugin API test bench against a plugin:</p><ol>
+        <li>Log in to the Greenplum Database master host and set up your environment. For example:<codeblock>$ ssh gpadmin@&lt;gpmaster&gt;
+gpadmin@gpmaster$ . /usr/local/greenplum-db/greenplum_path.sh</codeblock></li>
+        <li>Obtain a copy of the test bench from the <codeph>gpbackup</codeph> github repository. For example:<codeblock>$ git clone git@github.com:greenplum-db/gpbackup.git</codeblock>The clone operation creates a directory named <codeph>gpbackup/</codeph> in the current working directory.</li>
+        <li>Locate the test bench program in the <codeph>gpbackup/master/plugins</codeph> directory. For example:<codeblock>$ ls gpbackup/master/plugins/plugin_test_bench.sh</codeblock></li>
+        <li>Copy the plugin executable program and the plugin configuration YAML file from your development system to the Greenplum Database master host. Note the file system location to which you copied the files.</li>
+        <li>Copy the plugin executable program from the Greenplum Database master host to the same file system location on each segment host.</li>
+        <li>If required, edit the plugin configuration YAML file to specify the absolute path of the plugin executable program that you just copied to the Greenplum segments.</li>
+        <li>Run the test bench program against the plugin. For example:<codeblock>$ gpbackup/master/plugins/plugin_test_bench.sh /path/to/pluginexec /path/to/plugincfg.yaml</codeblock></li>
+        <li>Examine the test bench output. Your plugin passed the test bench if all output messages specify <codeph>RUNNING</codeph> and <codeph>PASSED</codeph>. For example:<codeblock># ----------------------------------------------
+# 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
+# ----------------------------------------------</codeblock></li></ol>
+    </section>
+    </body>
+  </topic>
+  <topic id="topic9339b" xml:lang="en">
+    <title>Packaging and Deploying a Backup/Restore Storage Plugin</title>
+    <body>
+      <p>Your backup/restore storage plugin is ready to be deployed to a Greenplum Database installation after the plugin passes your testing and the test bench verification. When you package the backup/restore storage plugin, consider the following:</p><ul>
+        <li>The backup/restore storage plugin must be installed in the same file system location on every host in the Greenplum Database cluster. Provide installation instructions for the plugin indentifying the same.</li>
+        <li>The <codeph>gpadmin</codeph> user must have permission to traverse the file system path to the backup/restore plugin executable program.</li>
+        <li>Include a template configuration file with the plugin.</li>
+        <li>Document the valid plugin configuration keywords, making sure to include the syntax of expected values.</li>
+        <li>Document required <codeph>gpbackup</codeph> options and how they affect plugin processing.</li>
+      </ul>
+    </body>
+  </topic>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/backup.ditamap
+++ b/gpdb-doc/dita/admin_guide/managing/backup.ditamap
@@ -30,6 +30,17 @@
        <topicref href="backup-boostfs.xml#topic_t4z_tvv_bdb"/>
      </topicref>
      <topicref href="backup-s3-plugin.xml"/>
+      <topicref href="backup-plugin-api.xml">
+        <topicref href="plugin_api/backup_data.xml" linking="none"/>
+        <topicref href="plugin_api/backup_file.xml" linking="none"/>
+        <topicref href="plugin_api/cleanup_plugin_for_backup.xml" linking="none"/>
+        <topicref href="plugin_api/cleanup_plugin_for_restore.xml" linking="none"/>
+        <topicref href="plugin_api/plugin_api_version.xml" linking="none"/>
+        <topicref href="plugin_api/restore_data.xml" linking="none"/>
+        <topicref href="plugin_api/restore_file.xml" linking="none"/>
+        <topicref href="plugin_api/setup_plugin_for_backup.xml" linking="none"/>
+        <topicref href="plugin_api/setup_plugin_for_restore.xml" linking="none"/>
+      </topicref>
    </topicref>
  </topicref>
 </map>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/backup_data.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/backup_data.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">backup_data</title>
+  <body>
+    <p>Plugin command to move streaming data from <codeph>stdin</codeph> to the remote storage system.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>backup_data</b> <varname>plugin_config_file</varname> <varname>data_filenamekey</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gpbackup</codeph> invokes the <codeph>backup_data</codeph> plugin command on each segment host during a streaming backup.</p>
+      <p>The <codeph>backup_data</codeph> implementation should read a potentially large stream of data from <codeph>stdin</codeph> and write the data to a single file on the remote storage system. The data is sent to the command as a single continuous stream per Greenplum Database segment. If <codeph>backup_data</codeph> modifies the data in any manner (i.e. compresses), <codeph>restore_data</codeph> must perform the reverse operation.</p>
+      <p>Name or maintain a mapping from the destination file to <codeph>data_filenamekey</codeph>. This will be the file key used for the restore operation.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>data_filenamekey</varname></pt>
+          <pd>The mapping key for a specially-named backup file for streamed data.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>backup_data</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gpbackup</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/backup_file.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/backup_file.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">backup_file</title>
+  <body>
+    <p>Plugin command to move a backup file to the remote storage system.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>backup_file</b> <varname>plugin_config_file</varname> <varname>file_to_backup</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gpbackup</codeph> invokes the <codeph>backup_file</codeph> plugin command on the master and each segment host for the file that <codeph>gpbackup</codeph> writes to a backup directory on local disk.</p>
+      <p>The <codeph>backup_file</codeph> implementation should process and move the file to the remote storage system. <codeph>gpbackup</codeph> does not remove the <varname>file_to_backup</varname> from the local system. Remove the file in the <codeph>backup_file</codeph> command, if appropriate.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>file_to_backup</varname></pt>
+          <pd>The absolute path to a local backup file generated by <codeph>gpbackup</codeph>.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>backup_file</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gpbackup</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/cleanup_plugin_for_backup.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/cleanup_plugin_for_backup.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">cleanup_plugin_for_backup</title>
+  <body>
+    <p>Plugin command to clean up a storage plugin after backup.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>cleanup_plugin_for_backup</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gpbackup</codeph> invokes the <codeph>cleanup_plugin_for_backup</codeph> plugin command on the master and all segment hosts when a <codeph>gpbackup</codeph> operation completes, both in success and failure cases.</p>
+      <p>The <codeph>cleanup_plugin_for_backup</codeph> command should perform the actions necessary to clean up the remote storage system after a backup. Clean up activities may include removing remote directories or temporary files created during the backup, disconnecting from the backup service, etc.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>local_backup_dir</varname></pt>
+          <pd>The local directory on the Greenplum Database host (master and segments) to which <codeph>gpbackup</codeph> wrote backup files.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>cleanup_plugin_for_backup</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gpbackup</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/cleanup_plugin_for_restore.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/cleanup_plugin_for_restore.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">cleanup_plugin_for_restore</title>
+  <body>
+    <p>Plugin command to clean up a storage plugin after restore.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>cleanup_plugin_for_restore</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gprestore</codeph> invokes the <codeph>cleanup_plugin_for_restore</codeph> plugin command on the master and all segment hosts when a <codeph>gprestore</codeph> operation completes, both in success and failure cases.</p>
+      <p>The <codeph>cleanup_plugin_for_restore</codeph> implementation should perform the actions necessary to clean up the remote storage system after a restore. Clean up activities may include removing remote directories or temporary files created during the restore, disconnecting from the backup service, etc.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>local_backup_dir</varname></pt>
+          <pd>The local directory on the Greenplum Database host (master and segments) from which <codeph>gprestore</codeph> reads backup files.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>cleanup_plugin_for_restore</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gprestore</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/plugin_api_version.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/plugin_api_version.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">plugin_api_version</title>
+  <body>
+    <p>Plugin command to display the supported Backup Storage Plugin API version.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>plugin_api_version</b></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gpbackup</codeph> and <codeph>gprestore</codeph> invoke the <codeph>plugin_api_version</codeph> plugin command before a backup or restore operation to determine Backup Storage Plugin API version compatibility.</p>
+    </section>
+    <section id="section5"><title>Return Value</title>
+      <p>The <codeph>plugin_api_version</codeph> command must return the Backup Storage Plugin API version number supported by the storage plugin, "0.1.0".</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/restore_data.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/restore_data.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">restore_data</title>
+  <body>
+    <p>Plugin command to stream data from the remote storage system to <codeph>stdout</codeph>.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>restore_data</b> <varname>plugin_config_file</varname> <varname>data_filenamekey</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gprestore</codeph> invokes the <codeph>restore_data</codeph> plugin command on each segment host when a restoring a streaming backup.</p>
+      <p>The <codeph>restore_data</codeph> implementation should read a potentially large data file named or mapped to <codeph>data_filenamekey</codeph> from the remote storage system and write the contents to <codeph>stdout</codeph>. If the <codeph>backup_data</codeph> command modified the data in any way (i.e. compressed), <codeph>restore_data</codeph> should perform the reverse operation.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>data_filenamekey</varname></pt>
+          <pd>The mapping key to a backup file on the remote storage system. <varname>data_filenamekey</varname> is the same key provided to the <codeph>backup_data</codeph> command.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>restore_data</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gprestore</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/restore_file.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/restore_file.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">restore_file</title>
+  <body>
+    <p>Plugin command to move a backup file from the remote storage system.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>restore_file</b> <varname>plugin_config_file</varname> <varname>file_to_restore</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gprestore</codeph> invokes the <codeph>restore_file</codeph> plugin command on the master and each segment host for the file that <codeph>gprestore</codeph> will read from a backup directory on local disk.</p>
+      <p>The <codeph>restore_file</codeph> command should process and move the file from the remote storage system to <codeph><varname>file_to_restore</varname></codeph> on the local host.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>file_to_restore</varname></pt>
+          <pd>The absolute path to which to move a backup file from the remote storage system.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>restore_file</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gprestore</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/setup_plugin_for_backup.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/setup_plugin_for_backup.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">setup_plugin_for_backup</title>
+  <body>
+    <p>Plugin command to initialize a storage plugin for the backup operation.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>setup_plugin_for_backup</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gpbackup</codeph> invokes the <codeph>setup_plugin_for_backup</codeph> plugin command on the master and all segment hosts during <codeph>gpbackup</codeph> initialization phase.</p>
+      <p>The <codeph>setup_plugin_for_backup</codeph> command should perform the activities necessary to initialize the remote storage system before backup begins. Set up activities may include creating remote directories, validating connectivity to the remote storage system, checking disks, and so forth.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>local_backup_dir</varname></pt>
+          <pd>The local directory on the Greenplum Database host (master and segments) to which <codeph>gpbackup</codeph> will write backup files. <codeph>gpbackup</codeph> creates this local directory.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>setup_plugin_for_backup</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gpbackup</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>
--- a/gpdb-doc/dita/admin_guide/managing/plugin_api/setup_plugin_for_restore.xml
+++ b/gpdb-doc/dita/admin_guide/managing/plugin_api/setup_plugin_for_restore.xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<topic id="topic1">
+  <title id="pa137116">setup_plugin_for_restore</title>
+  <body>
+    <p>Plugin command to initialize a storage plugin for the restore operation.</p>
+    <section id="section2">
+      <title>Synopsis</title>
+      <codeblock><varname>plugin_executable</varname> <b>setup_plugin_for_restore</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname></codeblock>
+    </section>
+    <section id="section3">
+      <title>Description</title>
+      <p><codeph>gprestore</codeph> invokes the <codeph>setup_plugin_for_restore</codeph> plugin command on the master and all segment hosts during <codeph>gprestore</codeph> initialization phase.</p>
+      <p>The <codeph>setup_plugin_for_restore</codeph> command should perform the activities necessary to initialize the remote storage system before a restore operation begins. Set up activities may include creating remote directories, validating connectivity to the remote storage system, etc.</p>
+    </section>
+    <section id="section4"><title>Arguments</title><parml>
+        <plentry>
+          <pt><varname>plugin_config_file</varname></pt>
+          <pd>The absolute path to the plugin configuration YAML file.</pd>
+        </plentry>
+        <plentry>
+          <pt><varname>local_backup_dir</varname></pt>
+          <pd>The local directory on the Greenplum Database host (master and segments) from which <codeph>gprestore</codeph> reads backup files. <codeph>setup_plugin_for_restore</codeph> must create this directory if it does not already exist.</pd>
+        </plentry>
+        </parml>
+    </section>
+    <section id="section5"><title>Exit Code</title>
+      <p>The <codeph>setup_plugin_for_restore</codeph> command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, <codeph>gprestore</codeph> displays the contents of <codeph>stderr</codeph> to the user.</p>
+    </section>
+  </body>
+</topic>