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>
This commit is contained in:
Stephen Finucane 2023-11-02 17:57:32 +00:00
parent ee9ed0f7c6
commit 7ce48d1161
4 changed files with 92 additions and 2 deletions

View File

@ -747,6 +747,8 @@ For example, when using the :command:`openstack server create` command, use the
$ openstack server create --image IMAGE_ID --flavor 1 \
--hint group=SERVER_GROUP_UUID server-1
For more information on server groups, refer to :doc:`/user/server-groups`.
.. _ServerGroupAntiAffinityFilter:
@ -767,6 +769,8 @@ For example, when using the :command:`openstack server create` command, use the
$ openstack server create --image IMAGE_ID --flavor 1 \
--hint group=SERVER_GROUP_UUID server-1
For more information on server groups, refer to :doc:`/user/server-groups`.
``SimpleCIDRAffinityFilter``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

View File

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

View File

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

View File

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