Add locations to POST /v1/plans API

When determining placements for a related set of resources
via OpenStack Heat, there's no a priori knowledge of specific
location candidates. Thus the /v1/plans API never accounted
for them. However, when it comes to ad hoc placement of a
single resource (e.g., via OpenStack Nova), such knowledge
*does* exist. This is one piece of a three-part change (same
issue tracking ID).

Change-Id: I327b87a1a1104019239547d03600cdd849ea6501

doc/rest_api.md

@@ -504,6 +504,7 @@ This operation does not accept a request body.
 
 | Parameter   | Style | Type       | Description                                       |
 |-------------|-------|------------|---------------------------------------------------|
+| locations   | plain | xsd:list   | An optional list of placement location candidates. |
 | plan_name   | plain | xsd:string | The name of the plan.                             |
 | resources   | plain | xsd:dict   | A dictionary of resources to be planned. Each is keyed by an orchestration uuid. This is a UUID provided by an orchestration engine (e.g., heat-engine) prior to instantiation of a resource. The dictionary contains three keys: |
 |             |       |            | **name**: resource name                             |

valet/api/common/ostro_helper.py

@@ -245,6 +245,11 @@ class Ostro(object):
             "stack_id": self.args['stack_id'],
         }
 
+        # Only add locations if we have it (no need for an empty object)
+        locations = self.args.get('locations')
+        if locations:
+            self.request['locations'] = locations
+
         if resources_update:
             # If we get any status in the response, it's an error. Bail.
             self.response = self._prepare_resources(resources_update)

valet/api/v1/controllers/plans.py

@@ -27,6 +27,7 @@ from valet.api import LOG
 
 
 CREATE_SCHEMA = (
+    (decorators.optional('locations'), types.array),
     ('plan_name', types.string),
     ('resources', types.dictionary),
     ('stack_id', types.string),
@@ -237,7 +238,7 @@ class PlansController(object):
 
         kwargs = {
             'tenant_id': request.context['tenant_id'],
-            'args': args
+            'args': args,
         }
 
         # Prepare the request. If request prep fails,