diff --git a/doc/common/section_cli_nova_host_aggregates.xml b/doc/common/section_cli_nova_host_aggregates.xml
index 06531d84b7..e25b8182ea 100644
--- a/doc/common/section_cli_nova_host_aggregates.xml
+++ b/doc/common/section_cli_nova_host_aggregates.xml
@@ -8,18 +8,31 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="host-aggregates">
-
Host aggregates
- Host aggregates are a mechanism to further partition an
- availability zone; while availability zones are visible to
- users, host aggregates are only visible to administrators.
- Host Aggregates provide a mechanism to allow administrators to
- assign key-value pairs to groups of machines. Each node can
- have multiple aggregates, each aggregate can have multiple
- key-value pairs, and the same key-value pair can be assigned
- to multiple aggregates. This information can be used in the
- scheduler to enable advanced scheduling, to set up hypervisor
- resource pools or to define logical groups for
- migration.
+ Host aggregates and availability zones
+
+ Host aggregates are a mechanism for partitioning hosts in an OpenStack
+ cloud, or a region of an OpenStack cloud, based on arbitrary
+ characteristics. Examples where an administrator may want to do this
+ include where a group of hosts have additional hardware or performance
+ characteristics.
+
+
+ Host aggregates are not explicitly exposed to users.
+ Instead administrators map flavors to host aggregates. Administrators
+ do this by setting metadata on a host aggregate, and matching flavor
+ extra specifications. The scheduler then endeavors to match user
+ requests for instance of the given flavor to a host aggregate with the
+ same key-value pair in its metadata. Compute nodes can be in more than
+ one host aggregate.
+
+
+ Administrators are able to optionally expose a host aggregate as an
+ availability zone. Availability zones are different to host aggregates
+ in that they are explicitly exposed to the user, and hosts can only be
+ in a single availability zone. Administrators can configure a default
+ availability zone where instances will be scheduled when the user
+ fails to specify one.
+
Command-line interface
The nova command-line tool supports
@@ -34,19 +47,18 @@
nova aggregate-create
<name>
- <availability-zone>
+ [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
+ <name>, and
+ optionally in availability zone
+ [availability-zone]
+ if specified. The command returns the ID of the
+ newly created aggregate. Hosts can be made
+ available to multiple host aggregates. Be careful
+ when adding a host to an additional host
+ aggregate when the host is also in an availability
+ zone. Pay attention when using the
aggregate-set-metadata
and aggregate-update
commands to avoid user confusion when they