Comment 18 for bug 1378904

Reviewed: https://review.openstack.org/640460
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=268190b252aef91d9309f30b2f5db3be7bdecf01
Submitter: Zuul
Branch: master

commit 268190b252aef91d9309f30b2f5db3be7bdecf01
Author: Matt Riedemann <email address hidden>
Date: Fri Mar 1 12:36:42 2019 -0500

    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