docs: Add documentation on server groups

That's one giant hole in our docs. Whoops.

Change-Id: I8ac6f204dd3ebe424dfe4335a491b8c9df7d0cc4
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

doc/source/admin/scheduling.rst

@@ -745,7 +745,9 @@ For example, when using the :command:`openstack server create` command, use the
 
    $ openstack server group create --policy affinity group-1
    $ openstack server create --image IMAGE_ID --flavor 1 \
-     --hint group=SERVER_GROUP_UUID server-1
+       --hint group=SERVER_GROUP_UUID server-1
+
+For more information on server groups, refer to :doc:`/user/server-groups`.
 
 
 .. _ServerGroupAntiAffinityFilter:
@@ -765,7 +767,9 @@ For example, when using the :command:`openstack server create` command, use the
 
    $ openstack server group create --policy anti-affinity group-1
    $ openstack server create --image IMAGE_ID --flavor 1 \
-     --hint group=SERVER_GROUP_UUID server-1
+       --hint group=SERVER_GROUP_UUID server-1
+
+For more information on server groups, refer to :doc:`/user/server-groups`.
 
 
 ``SimpleCIDRAffinityFilter``

doc/source/user/availability-zones.rst

@@ -15,6 +15,12 @@ zone feature. However, the implementation of these features differs vastly
 between these different services. Consult the documentation for these other
 services for more information on their implementation of this feature.
 
+.. tip::
+
+    Server Groups provide another mechanism for configuring the colocation of
+    instances during scheduling. For more information, refer to
+    :doc:`/user/server-groups`.
+
 
 Usage
 -----

doc/source/user/index.rst

@@ -19,6 +19,7 @@ End user guide
 
    availability-zones
    launch-instances
+   server-groups
    metadata
    manage-ip-addresses
    certificate-validation

doc/source/user/server-groups.rst

@@ -0,0 +1,79 @@
+=============
+Server Groups
+=============
+
+Server groups provide a mechanism for indicating the locality of servers
+relative to other servers. They allow you to indicate whether servers should
+run on the same host (affinity) or different hosts (anti-affinity). Affinity is
+advantageous if you wish to minimise network latency, while anti-affinity can
+improve fault-tolerance and load distribution.
+
+.. note::
+
+    Server groups are useful for separating or grouping workloads but should
+    not generally be relied on to provide HA. Instead, consider using
+    availability zones. Unlike server groups, availability zones can only be
+    configured by admins but they are often used to model failure domains,
+    particularly in larger deployments. For more information, refer to
+    :doc:`/user/availability-zones`.
+
+Server groups can be configured with a policy and rules. There are currently
+four policies supported:
+
+``affinity``
+  Restricts instances belonging to the server group to the same host.
+
+``anti-affinity``
+  Restricts instances belonging to the server group to separate hosts.
+
+``soft-affinity``
+  Attempts to restrict instances belonging to the server group to the same
+  host. Where it is not possible to schedule all instances on one host,
+  they will be scheduled together on as few hosts as possible.
+
+  .. note::
+
+      Requires API microversion 2.15 or later.
+
+``soft-anti-affinity``
+  Attempts to restrict instances belonging to the server group to separate
+  hosts. Where it is not possible to schedule all instances to separate hosts,
+  they will be scheduled on as many separate hosts as possible.
+
+  .. note::
+
+      Requires API microversion 2.15 or later.
+
+There is currently one rule supported:
+
+``max_server_per_host``
+  Indicates the max number of instances that can be scheduled to any given
+  host when using the ``anti-affinity`` policy. This rule is not compatible
+  with other policies.
+
+  .. note::
+
+      Requires API microversion 2.64 or later.
+
+
+Usage
+-----
+
+Server groups can be configured and used by end-users. For example:
+
+.. code-block:: console
+
+    $ openstack --os-compute-api-version 2.64 server group create \
+        --policy POLICY --rule RULE NAME
+
+Once a server group has been created, you can use it when creating a server.
+This is achieved using the ``--hint`` option. For example:
+
+.. code-block:: console
+
+    $ openstack server create \
+        --hint group=SERVER_GROUP_UUID ... NAME
+
+Once created, a server group cannot be modified. In addition, a server cannot
+move between server groups. In both cases, this is because doing so would
+require potentially moving the server to satisfy the server group policy.