From 9db41c5ee09f4b3d4d072282e32510f2d7fa09ab Mon Sep 17 00:00:00 2001
From: Hesam Chobanlou <hesamchobanlou@gmail.com>
Date: Sat, 26 Jan 2019 19:56:17 -0500
Subject: [PATCH] docs: ComputeDriver.update_provider_tree in nova

This change is an update to the nova reference documentation to reflect
changes to the ComputeDriver.update_provider_tree method in nova drivers.

Change-Id: Ifae98d888069477748ade7ef5e0a5cde5c88ffc2
Closes-Bug: #1800657
---
 doc/source/reference/update-provider-tree.rst | 34 ++++++++++++++++++-
 nova/virt/driver.py                           |  3 --
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/doc/source/reference/update-provider-tree.rst b/doc/source/reference/update-provider-tree.rst
index bdaa29d20b7b..4d786008a65d 100644
--- a/doc/source/reference/update-provider-tree.rst
+++ b/doc/source/reference/update-provider-tree.rst
@@ -38,7 +38,7 @@ the compute node and its associated providers.
 
 The Method
 ----------
-``update_provider_tree`` accepts two parameters:
+``update_provider_tree`` accepts the following parameters:
 
 * A ``nova.compute.provider_tree.ProviderTree`` object representing all the
   providers in the tree associated with the compute node, and any sharing
@@ -59,6 +59,38 @@ The Method
   use this to help identify the compute node provider in the ProviderTree.
   Drivers managing more than one node (e.g. ironic) may also use it as a cue to
   indicate which node is being processed by the caller.
+* Dictionary of ``allocations`` data of the form:
+
+  .. code::
+
+    { $CONSUMER_UUID: {
+          # The shape of each "allocations" dict below is identical
+          # to the return from GET /allocations/{consumer_uuid}
+          "allocations": {
+              $RP_UUID: {
+                  "generation": $RP_GEN,
+                  "resources": {
+                      $RESOURCE_CLASS: $AMOUNT,
+                      ...
+                  },
+              },
+              ...
+          },
+          "project_id": $PROJ_ID,
+          "user_id": $USER_ID,
+          "consumer_generation": $CONSUMER_GEN,
+      },
+      ...
+    }
+
+  If ``None``, and the method determines that any inventory needs to be moved
+  (from one provider to another and/or to a different resource class), the
+  ``ReshapeNeeded`` exception must be raised. Otherwise, this dict must be
+  edited in place to indicate the desired final state of allocations. Drivers
+  should *only* edit allocation records for providers whose inventories are
+  being affected by the reshape operation. For more information about the
+  reshape operation, refer to the `spec <http://specs.openstack.org/openstack/
+  nova-specs/specs/stein/approved/reshape-provider-tree.html>`_.
 
 The virt driver is expected to update the ProviderTree object with current
 resource provider and inventory information. When the method returns, the
diff --git a/nova/virt/driver.py b/nova/virt/driver.py
index 8625bd7abcc6..74569e16677f 100644
--- a/nova/virt/driver.py
+++ b/nova/virt/driver.py
@@ -975,9 +975,6 @@ class ComputeDriver(object):
             allocations. Drivers should *only* edit allocation records for
             providers whose inventories are being affected by the reshape
             operation.
-            TODO(efried): Doc reshaper in reference/update-provider-tree.html
-            Meanwhile, please refer to the spec for more details on reshaping:
-            http://specs.openstack.org/openstack/nova-specs/specs/stein/approved/reshape-provider-tree.html  # noqa
         :raises ReshapeNeeded: If allocations is None and any inventory needs
             to be moved from one provider to another and/or to a different
             resource class.