docs - update gpbackup API - add segment instance and update backup d… (#5285)

* docs - update gpbackup API - add segment instance and update backup directory information.

Also update API version to 0.3.0.

This will be ported to 5X_STABLE

* docs - gpbackup API - review updates and fixes for scope information

Also, cleanup edits.

* docs - gpbackup API - more review updates and fixes to scope information.

gpdb-doc/dita/admin_guide/managing/backup-plugin-api.xml

@@ -98,8 +98,9 @@ options:
           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>
-        <li>The API provides an argument that specifies the execution scope (master host, segment
-          host, or segment instance) for a plugin setup or cleanup command. <ul id="ul_rpk_tzt_k2b">
+        <li>The API provides arguments that specify the execution scope (master host, segment host,
+          or segment instance) for a plugin setup or cleanup command. The scope can be one of these
+            values.<ul id="ul_rpk_tzt_k2b">
             <li><codeph>master</codeph> - Execute the plugin once on the master host.</li>
             <li><codeph>segment_host</codeph> - Execute the plugin once on each of the segment
               hosts.</li>
@@ -154,7 +155,7 @@ options:
                       >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.2.0.</entry>
+                    version is 0.3.0.</entry>
                 </row>
                 <row class="- topic/row ">
                   <entry colname="col1" class="- topic/entry "><xref

gpdb-doc/dita/admin_guide/managing/plugin_api/cleanup_plugin_for_backup.xml

@@ -8,6 +8,7 @@
     <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> <varname>scope</varname></codeblock>
+      <codeblock><varname>plugin_executable</varname> <b>cleanup_plugin_for_backup</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname> <varname>scope</varname> <varname>contentID</varname></codeblock>
     </section>
     <section id="section3">
       <title>Description</title>
@@ -29,21 +30,44 @@
         <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>
+              <codeph>gpbackup</codeph> wrote backup files.<ul id="ul_rrs_vts_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of the Greenplum
+                Database master.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of a segment instance.
+                The <varname>contentID</varname> identifies the segment instance.</li>
+              <li>When the scope is <codeph>segment_host</codeph>, the
+                  <varname>local_backup_dir</varname> is an arbitrary backup directory on the
+                host.</li>
+            </ul></pd>
         </plentry>
         <plentry>
           <pt><varname>scope</varname></pt>
-          <pd>The execution scope (host and number of times the plugin is executed) for the plugin.
-              <ul id="ul_rpk_tzt_k2b">
-              <li><codeph>master</codeph> - Execute the plugin once on the master host.</li>
-              <li><codeph>segment_host</codeph> - Execute the plugin once on each of the segment
-                hosts.</li>
-              <li><codeph>segment</codeph> - Execute the plugin once for each active segment
-                instance on the host running the segment instance.</li>
+          <pd>The execution scope value indicates the host and number of times the plugin command is
+            executed. <varname>scope</varname> can be one of these values: <ul id="ul_rpk_tzt_k2b">
+              <li><codeph>master</codeph> - Execute the plugin command once on the master host.</li>
+              <li><codeph>segment_host</codeph> - Execute the plugin command once on each of the
+                segment hosts.</li>
+              <li><codeph>segment</codeph> - Execute the plugin command once for each active segment
+                instance on the host running the segment instance. The <varname>contentID</varname>
+                identifies the segment instance.</li>
             </ul></pd>
           <pd>The Greenplum Database hosts and segment instances are based on the Greenplum Database
             configuration when the back up was first initiated. </pd>
         </plentry>
+        <plentry>
+          <pt><varname>contentID</varname></pt>
+          <pd>The contentID of the Greenplum Database master or segment instance corresponding to
+            the scope. <varname>contentID</varname> is passed only when the <varname>scope</varname>
+            is <codeph>master</codeph> or <codeph>segment</codeph>.<ul id="ul_vqv_wly_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>contentID</varname> is <codeph>-1</codeph>.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>contentID</varname> is the content identifier of an active segment
+                instance. </li>
+            </ul></pd>
+        </plentry>
       </parml>
     </section>
     <section id="section5"><title>Exit Code</title>

gpdb-doc/dita/admin_guide/managing/plugin_api/cleanup_plugin_for_restore.xml

@@ -8,6 +8,7 @@
     <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> <varname>scope</varname></codeblock>
+      <codeblock><varname>plugin_executable</varname> <b>cleanup_plugin_for_restore</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname> <varname>scope</varname> <varname>contentID</varname></codeblock>
     </section>
     <section id="section3">
       <title>Description</title>
@@ -29,21 +30,44 @@
         <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>
+              <codeph>gprestore</codeph> reads backup files.<ul id="ul_rrs_vts_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of the Greenplum
+                Database master.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of a segment instance.
+                The <varname>contentID</varname> identifies the segment instance.</li>
+              <li>When the scope is <codeph>segment_host</codeph>, the
+                  <varname>local_backup_dir</varname> is an arbitrary backup directory on the
+                host.</li>
+            </ul></pd>
         </plentry>
         <plentry>
           <pt><varname>scope</varname></pt>
-          <pd>The execution scope (host and number of times the plugin is executed) for the plugin.
-              <ul id="ul_rpk_tzt_k2b">
-              <li><codeph>master</codeph> - Execute the plugin once on the master host.</li>
-              <li><codeph>segment_host</codeph> - Execute the plugin once on each of the segment
-                hosts.</li>
-              <li><codeph>segment</codeph> - Execute the plugin once for each active segment
-                instance on the host running the segment instance.</li>
+          <pd>The execution scope value indicates the host and number of times the plugin command is
+            executed. <varname>scope</varname> can be one of these values:<ul id="ul_rpk_tzt_k2b">
+              <li><codeph>master</codeph> - Execute the plugin command once on the master host.</li>
+              <li><codeph>segment_host</codeph> - Execute the plugin command once on each of the
+                segment hosts.</li>
+              <li><codeph>segment</codeph> - Execute the plugin command once for each active segment
+                instance on the host running the segment instance. The <varname>contentID</varname>
+                identifies the segment instance.</li>
             </ul></pd>
           <pd>The Greenplum Database hosts and segment instances are based on the Greenplum Database
             configuration when the back up was first initiated. </pd>
         </plentry>
+        <plentry>
+          <pt><varname>contentID</varname></pt>
+          <pd>The contentID of the Greenplum Database master or segment instance corresponding to
+            the scope. <varname>contentID</varname> is passed only when the <varname>scope</varname>
+            is <codeph>master</codeph> or <codeph>segment</codeph>.<ul id="ul_okg_2bs_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>contentID</varname> is <codeph>-1</codeph>.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>contentID</varname> is the content identifier of an active segment
+                instance.</li>
+            </ul></pd>
+        </plentry>
       </parml>
     </section>
     <section id="section5"><title>Exit Code</title>

gpdb-doc/dita/admin_guide/managing/plugin_api/setup_plugin_for_backup.xml

@@ -8,6 +8,7 @@
     <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> <varname>scope</varname></codeblock>
+      <codeblock><varname>plugin_executable</varname> <b>setup_plugin_for_backup</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname> <varname>scope</varname> <varname>contentID</varname></codeblock>
     </section>
     <section id="section3">
       <title>Description</title>
@@ -29,21 +30,44 @@
           <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>
+            this local directory.<ul id="ul_rrs_vts_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of the Greenplum
+                Database master.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of a segment instance.
+                The <varname>contentID</varname> identifies the segment instance.</li>
+              <li>When the scope is <codeph>segment_host</codeph>, the
+                  <varname>local_backup_dir</varname> is an arbitrary backup directory on the
+                host.</li>
+            </ul></pd>
         </plentry>
         <plentry>
           <pt><varname>scope</varname></pt>
-          <pd>The execution scope (host and number of times the plugin is executed) for the plugin.
-              <ul id="ul_rpk_tzt_k2b">
-              <li><codeph>master</codeph> - Execute the plugin once on the master host.</li>
-              <li><codeph>segment_host</codeph> - Execute the plugin once on each of the segment
-                hosts.</li>
-              <li><codeph>segment</codeph> - Execute the plugin once for each active segment
-                instance on the host running the segment instance.</li>
+          <pd>The execution scope value indicates the host and number of times the plugin command is
+            executed. <varname>scope</varname> can be one of these values:<ul id="ul_rpk_tzt_k2b">
+              <li><codeph>master</codeph> - Execute the plugin command once on the master host.</li>
+              <li><codeph>segment_host</codeph> - Execute the plugin command once on each of the
+                segment hosts.</li>
+              <li><codeph>segment</codeph> - Execute the plugin command once for each active segment
+                instance on the host running the segment instance. The <varname>contentID</varname>
+                identifies the segment instance.</li>
             </ul></pd>
           <pd>The Greenplum Database hosts and segment instances are based on the Greenplum Database
             configuration when the back up was first initiated. </pd>
         </plentry>
+        <plentry>
+          <pt><varname>contentID</varname></pt>
+          <pd>The contentID of the Greenplum Database master or segment instance corresponding to
+            the scope. <varname>contentID</varname> is passed only when the <varname>scope</varname>
+            is <codeph>master</codeph> or <codeph>segment</codeph>.<ul id="ul_okg_2bs_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>contentID</varname> is <codeph>-1</codeph>.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>contentID</varname> is the content identifier of an active segment
+                instance.</li>
+            </ul></pd>
+        </plentry>
       </parml>
     </section>
     <section id="section5"><title>Exit Code</title>

gpdb-doc/dita/admin_guide/managing/plugin_api/setup_plugin_for_restore.xml

@@ -8,6 +8,7 @@
     <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> <varname>scope</varname></codeblock>
+      <codeblock><varname>plugin_executable</varname> <b>setup_plugin_for_restore</b> <varname>plugin_config_file</varname> <varname>local_backup_dir</varname> <varname>scope</varname> <varname>contentID</varname></codeblock>
     </section>
     <section id="section3">
       <title>Description</title>
@@ -29,21 +30,44 @@
           <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>gprestore</codeph> creates this
-            local directory.</pd>
+            local directory.<ul id="ul_rrs_vts_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of the Greenplum
+                Database master.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>local_backup_dir</varname> is the backup directory of a segment instance.
+                The <varname>contentID</varname> identifies the segment instance.</li>
+              <li>When the scope is <codeph>segment_host</codeph>, the
+                  <varname>local_backup_dir</varname> is an arbitrary backup directory on the
+                host.</li>
+            </ul></pd>
         </plentry>
         <plentry>
           <pt><varname>scope</varname></pt>
-          <pd>The execution scope (host and number of times the plugin is executed) for the plugin.
-              <ul id="ul_rpk_tzt_k2b">
-              <li><codeph>master</codeph> - Execute the plugin once on the master host.</li>
-              <li><codeph>segment_host</codeph> - Execute the plugin once on each of the segment
-                hosts.</li>
-              <li><codeph>segment</codeph> - Execute the plugin once for each active segment
-                instance on the host running the segment instance.</li>
+          <pd>The execution scope value indicates the host and number of times the plugin command is
+            executed. <varname>scope</varname> can be one of these values:<ul id="ul_rpk_tzt_k2b">
+              <li><codeph>master</codeph> - Execute the plugin command once on the master host.</li>
+              <li><codeph>segment_host</codeph> - Execute the plugin command once on each of the
+                segment hosts.</li>
+              <li><codeph>segment</codeph> - Execute the plugin command once for each active segment
+                instance on the host running the segment instance. The <varname>contentID</varname>
+                identifies the segment instance.</li>
             </ul></pd>
           <pd>The Greenplum Database hosts and segment instances are based on the Greenplum Database
             configuration when the back up was first initiated. </pd>
         </plentry>
+        <plentry>
+          <pt><varname>contentID</varname></pt>
+          <pd>The contentID of the Greenplum Database master or segment instance corresponding to
+            the scope. <varname>contentID</varname> is passed only when the <varname>scope</varname>
+            is <codeph>master</codeph> or <codeph>segment</codeph>.<ul id="ul_okg_2bs_m2b">
+              <li>When <varname>scope</varname> is <codeph>master</codeph>, the
+                  <varname>contentID</varname> is <codeph>-1</codeph>.</li>
+              <li>When <varname>scope</varname> is <codeph>segment</codeph>, the
+                  <varname>contentID</varname> is the content identifier of an active segment
+                instance.</li>
+            </ul></pd>
+        </plentry>
       </parml>
     </section>
     <section id="section5"><title>Exit Code</title>