This is an automated email from the ASF dual-hosted git repository.
harikrishna pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new 90b35546 cks: add affinity group support for CKS cluster nodes (#620)
90b35546 is described below
commit 90b355463da82f347241034646296e20ebed8f0a
Author: Daman Arora <[email protected]>
AuthorDate: Fri Mar 13 06:11:03 2026 -0400
cks: add affinity group support for CKS cluster nodes (#620)
* add affinity group support for CKS cluster nodes
* simplify notes
* Add screenshot for affinity groups in CKS cluster creation
---------
Co-authored-by: Daman Arora <[email protected]>
---
.../images/cks-create-cluster-affinity-groups.png | Bin 0 -> 26989 bytes
source/plugins/cloudstack-kubernetes-service.rst | 41 +++++++++++++++++++++
2 files changed, 41 insertions(+)
diff --git a/source/_static/images/cks-create-cluster-affinity-groups.png
b/source/_static/images/cks-create-cluster-affinity-groups.png
new file mode 100644
index 00000000..469e7a25
Binary files /dev/null and
b/source/_static/images/cks-create-cluster-affinity-groups.png differ
diff --git a/source/plugins/cloudstack-kubernetes-service.rst
b/source/plugins/cloudstack-kubernetes-service.rst
index 06821623..12921f30 100644
--- a/source/plugins/cloudstack-kubernetes-service.rst
+++ b/source/plugins/cloudstack-kubernetes-service.rst
@@ -653,6 +653,45 @@ Administrators are able to dedicate hosts to a domain or
account. CloudStack wil
.. note::
By design the hosts dedication does not consider the deployment of
system VMs on the dedicated hosts (SSVM, CPVM and Virtual Routers). In case the
Kubernetes cluster is created on an unimplemented network then the Virtual
Router of the network will not be deployed on the dedicated hosts.
+Affinity groups for CKS cluster nodes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From 4.23.0 onwards, users can specify host affinity or anti-affinity groups
for different types of Kubernetes cluster nodes (control, worker, etcd) during
cluster creation. This provides control over VM placement on hosts for high
availability requirements.
+
+|cks-create-cluster-affinity-groups.png|
+
+To use affinity groups with CKS clusters:
+
+1. Create the desired affinity groups (host affinity or host anti-affinity)
beforehand using the CloudStack UI or API.
+
+2. When creating a Kubernetes cluster, specify the affinity group mapping
using the **nodeaffinitygroups** parameter. This parameter accepts a mapping of
node types to affinity group UUIDs with two fields per entry:
+
+ - ``node``: The node type (permitted values: ``worker``, ``control``,
``etcd``)
+ - ``affinitygroup``: The UUID of the desired affinity group
+
+Example using the API:
+
+.. code-block:: bash
+
+ cmk create kubernetescluster name=MyCluster zoneid=<zone-uuid>
kubernetesversionid=<version-uuid> serviceofferingid=<offering-uuid> size=3
nodeaffinitygroups[0].node=worker
nodeaffinitygroups[0].affinitygroup=<affinity-group-uuid>
+
+Multiple affinity groups can be assigned to a single node type by providing
comma-separated UUIDs:
+
+.. code-block:: bash
+
+ nodeaffinitygroups[0].affinitygroup=<uuid1>,<uuid2>
+
+Different node types can have different affinity group configurations:
+
+.. code-block:: bash
+
+ nodeaffinitygroups[0].node=control
nodeaffinitygroups[0].affinitygroup=<control-ag-uuid>
nodeaffinitygroups[1].node=worker
nodeaffinitygroups[1].affinitygroup=<worker-ag-uuid>
+
+The affinity group configuration is persisted and automatically applied when
scaling the cluster - new worker nodes inherit the affinity group settings
without requiring additional parameters.
+
+.. note::
+ - When adding external worker nodes to an existing cluster using
``addNodesToKubernetesCluster``, the nodes are validated against any worker
affinity groups configured for the cluster.
+
Use diverse CNI plugins (Calico, Cilium, etc)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -809,6 +848,8 @@ kubectl delete pod --all -A
:alt: Create Kubernetes Cluster form.
.. |cks-create-cluster-additional-settings.png| image::
/_static/images/cks-create-cluster-additional-settings.png
:alt: Create Kubernetes Cluster form with Advanced Settings.
+.. |cks-create-cluster-affinity-groups.png| image::
/_static/images/cks-create-cluster-affinity-groups.png
+ :alt: Affinity groups selection in Create Kubernetes Cluster Advanced
Settings.
.. |cks-delete-action.png| image:: /_static/images/cks-delete-action.png
:alt: Delete action icon.
.. |cks-kube-config-action.png| image::
/_static/images/cks-kube-config-action.png
