Browse Source

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
Matt Riedemann 2 years ago
1 changed files with 6 additions and 1 deletions
  1. +6

+ 6
- 1
api-ref/source/parameters.yaml View File

@ -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