api-ref: warn about changing/unsetting AZ name with instances

It is currently possible to rename or unset the availability_zone
metadata value on a host aggregate which can adversely impact
instances that were created in that specific AZ since later
attempts to migrate or unshelve those instances will fail if the
AZ with the original name no longer exists.

This adds a warning to the API reference for updating the AZ
name and also fixes a grammar typo in the 'metadata' response
parameter description.

Change-Id: Ie9d4a1ff1a23827490fe51350c11292c6efc4eb2
Related-Bug: #1378904

2 files changed, 38 insertions, 12 deletions

diff --git a/api-ref/source/os-aggregates.inc b/api-ref/source/os-aggregates.inc
index ecfefe59ac..a8ff9df9c9 100644
--- a/api-ref/source/os-aggregates.inc
+++ b/api-ref/source/os-aggregates.inc
@@ -31,7 +31,7 @@ Response
   - deleted: deleted
   - hosts: aggregate_host_list
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -60,7 +60,7 @@ Request
 
   - aggregate: aggregate
   - name: aggregate_name
-  - availability_zone: aggregate_az_optional
+  - availability_zone: aggregate_az_optional_create
 
 **Example Create Aggregate: JSON request**
 
@@ -117,7 +117,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -149,7 +149,7 @@ Request
   - aggregate_id: aggregate_id
   - aggregate: aggregate
   - name: aggregate_name_optional
-  - availability_zone: aggregate_az_optional
+  - availability_zone: aggregate_az_optional_update
 
 **Example Update Aggregate: JSON request**
 
@@ -168,7 +168,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -241,7 +241,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -291,7 +291,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
@@ -322,7 +322,7 @@ Request
 
   - aggregate_id: aggregate_id
   - set_metadata: set_metadata
-  - metadata: metadata_object 
+  - metadata: aggregate_metadata_request
 
 **Example Create Or Update Aggregate Metadata: JSON request**
 
@@ -341,7 +341,7 @@ Response
   - deleted: deleted
   - hosts: hosts
   - id: aggregate_id_body
-  - metadata: aggregate_metadata
+  - metadata: aggregate_metadata_response
   - name: aggregate_name
   - updated_at: updated_consider_null
   - uuid: aggregate_uuid
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index ed6ce9bac2..258d7f7a31 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1604,7 +1604,7 @@ aggregate_az:
   in: body
   required: true
   type: string
-aggregate_az_optional:
+aggregate_az_optional_create:
   description: |
     The availability zone of the host aggregate. You should use a custom
     availability zone rather than the default returned by the
@@ -1613,6 +1613,20 @@ aggregate_az_optional:
   in: body
   required: false
   type: string
+aggregate_az_optional_update:
+  description: |
+    The availability zone of the host aggregate. You should use a custom
+    availability zone rather than the default returned by the
+    os-availability-zone API. The availability zone must not include ':'
+    in its name.
+
+    .. warning:: You should not change or unset the availability zone of an
+      aggregate when that aggregate has hosts which contain servers in it
+      since that may impact the ability for those servers to move to another
+      host.
+  in: body
+  required: false
+  type: string
 aggregate_host_list:
   description: |
     A list of host ids in this aggregate.
@@ -1625,9 +1639,21 @@ aggregate_id_body:
   in: body
   required: true
   type: integer
-aggregate_metadata:
+aggregate_metadata_request:
+  description: |
+    Metadata key and value pairs associated with the aggregate.
+    The maximum size for each metadata key and value pair is 255 bytes.
+
+    .. warning:: You should not change or unset the availability zone of an
+      aggregate when that aggregate has hosts which contain servers in it
+      since that may impact the ability for those servers to move to another
+      host.
+  in: body
+  required: true
+  type: object
+aggregate_metadata_response:
   description: |
-    Metadata key and value pairs associate with the aggregate.
+    Metadata key and value pairs associated with the aggregate.
   in: body
   required: true
   type: object