From 7ce48d1161a41c298c521a81958d3f6a290035f8 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 2 Nov 2023 17:57:32 +0000 Subject: [PATCH] docs: Add documentation on server groups That's one giant hole in our docs. Whoops. Change-Id: I8ac6f204dd3ebe424dfe4335a491b8c9df7d0cc4 Signed-off-by: Stephen Finucane --- doc/source/admin/scheduling.rst | 8 ++- doc/source/user/availability-zones.rst | 6 ++ doc/source/user/index.rst | 1 + doc/source/user/server-groups.rst | 79 ++++++++++++++++++++++++++ 4 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 doc/source/user/server-groups.rst diff --git a/doc/source/admin/scheduling.rst b/doc/source/admin/scheduling.rst index d599a047ef..1f060936fd 100644 --- a/doc/source/admin/scheduling.rst +++ b/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`` diff --git a/doc/source/user/availability-zones.rst b/doc/source/user/availability-zones.rst index 889da64968..2d54a8e0f8 100644 --- a/doc/source/user/availability-zones.rst +++ b/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 ----- diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 0ecf4344e4..104da8f070 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -19,6 +19,7 @@ End user guide availability-zones launch-instances + server-groups metadata manage-ip-addresses certificate-validation diff --git a/doc/source/user/server-groups.rst b/doc/source/user/server-groups.rst new file mode 100644 index 0000000000..a17ec1e6de --- /dev/null +++ b/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.