From 268190b252aef91d9309f30b2f5db3be7bdecf01 Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Fri, 1 Mar 2019 12:36:42 -0500
Subject: [PATCH] api-ref: explain aggregate set_metadata semantics

This came up as a source of confusion while reviewing
change Ic27195e46502067c87ee9c71a811a3ca3f610b73 because
I thought that the "metadata" key in the
POST /os-aggregates/{aggregate_id}/action (set_metadata)
API was an overwrite of the existing metadata rather than
an update.

The way the Aggregate.update_metadata() method works is that
new entries are added, existing metadata is updated if the
value is not None, otherwise existing entries are removed
if the value is None.

And because of the AggregateAPI.is_safe_to_update_az() method
the special "availability_zone" metadata cannot be unset to None
once it is set. So the only way to remove an AZ is to delete the
aggregate altogether.

This updates the API reference description of the "metadata"
parameter in the "set_metadata" action API.

Change-Id: I6fa9f9691b945b5212b7f951ab0a26b4d3049df9
Related-Bug: #1378904
---
 api-ref/source/parameters.yaml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index a5ee4f369d95..46faa7df50f9 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1644,7 +1644,12 @@ aggregate_metadata_request:
     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
+    New keys will be added to existing aggregate metadata. For existing
+    keys, if the value is ``null`` the entry is removed, otherwise the
+    value is updated. Note that the special ``availability_zone`` metadata
+    entry cannot be unset to ``null``.
+
+    .. warning:: You should not change 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.