Bug in documentation for host aggregates and availability zones

[Chris Friesen]

The docs at "http://docs.openstack.org/trunk/config-reference/content/section_compute-scheduler.html#host-aggregates" contain this:

nova aggregate-create <name> <availability-zone>

    Create a new aggregate named <name> in availability zone <availability-zone>. Returns the ID of the newly created aggregate. Hosts can be made available to multiple availability zones, but administrators should be careful when adding the host to a different host aggregate within the same availability zone and pay attention when using the aggregate-set-metadata and aggregate-update commands to avoid user confusion when they boot instances in different availability zones. An error occurs if you cannot add a particular host to an aggregate zone for which it is not intended.

I'm pretty sure that there are multiple errors in there:

1) This command creates a new aggregate that is *exposed as* an availability zone. It doesn't create a new aggregate within an availability zone. [1] Because of that the idea of a "different host aggregate within the same availability zone" doesn't make any sense.

2) Hosts can be part of multiple host aggregates, they cannot be part of multiple availability zones. [2]

References:
[1] http://blog.russellbryant.net/2013/05/21/availability-zones-and-host-aggregates-in-openstack-compute-nova/

[2] See the check in nova.compute.api.AggregateAPI._check_az_for_host()

[Stephen Gordon (sgordon)]

Pretty much needs a re-write as the inconsistencies exist throughout this little section, I also have some images/examples from http://www.slideshare.net/sgordon2/divide-and-conquer2 (slides 25 onwards) which I am happy to contribute and I think might help flesh this out.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/184916

[Stephen Gordon (sgordon)]

First attempt at cleaning this up, feedback welcome.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/184916
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=9752012c439a151d38a72d774b4d82ebec80f67b
Submitter: Jenkins
Branch: master

commit 9752012c439a151d38a72d774b4d82ebec80f67b
Author: Stephen Gordon <email address hidden>
Date: Thu May 21 17:01:03 2015 -0700

    Correct host aggregate and availability zone info

    The documentation around the creation of host aggregates and
    availability zones. In particular indicating that a host could be in
    multiple availability zones.

    Change-Id: I56ea99cfe004b58ed903702b20896c479fa43644
    Closes-Bug: #1433673

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/openstack-manuals 15.0.0 release.