> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/virtualized-clusters/virtualmachine/vm-affinity-anti-affinity-rules.md).

# VM Affinity Anti-Affinity Rules

This document describes how to create affinity and anti-affinity rules for your virtual machines, the placement behavior each rule produces, and how those rules interact with other <code class="expression">space.vars.product\_name</code> operations such as Dynamic Resource Rebalancing (DRR), VM High Availability (VM HA), maintenance mode, and migration.

## Overview

Server groups are the mechanism <code class="expression">space.vars.product\_name</code> uses to apply affinity and anti-affinity rules. A server group is a logical group of virtual machines that shares a single placement policy. Membership in a server group controls how the member VMs are placed across the hypervisor hosts in your virtualized cluster.

<code class="expression">space.vars.product\_name</code> supports four policies. Two are strict ("hard") and two are best effort ("soft").

| Policy             | Rule strength | Placement goal                                 | If the goal cannot be met            |
| ------------------ | ------------- | ---------------------------------------------- | ------------------------------------ |
| Affinity           | Strict (hard) | All VMs in the group run on the same host      | The operation fails                  |
| Soft affinity      | Best effort   | Keep all VMs in the group on the same host     | VMs may be placed on different hosts |
| Anti-affinity      | Strict (hard) | No two VMs in the group run on the same host   | The operation fails                  |
| Soft anti-affinity | Best effort   | Spread VMs in the group across different hosts | Two or more VMs may share a host     |

* **Affinity (hard).** Restricts all VMs in the group to the same hypervisor host. If no single host can hold every member, the operation fails.
* **Soft affinity.** Attempts to keep all VMs in the group on the same host, but allows them to run on different hosts when that is not possible.
* **Anti-affinity (hard).** Restricts the VMs in the group to separate hosts, so that no two members run on the same host. If there are not enough eligible hosts, the operation fails.
* **Soft anti-affinity.** Attempts to keep the VMs in the group on separate hosts, but allows two or more of them to share a host when that is not possible.

A server group has exactly one policy. You cannot combine affinity and anti-affinity, or hard and soft, within the same group.

## Prerequisites

* A virtualized cluster with one or more hosts that have the hypervisor role.
* Enough host capacity for the policy you choose. A hard affinity group needs a single host with enough capacity for every member. A hard anti-affinity group needs at least as many eligible hosts as it has VMs. Anti-affinity and soft anti-affinity are only meaningful when the cluster has more than one hypervisor host.
* The server group must exist before you create the VMs that will belong to it.
* The appropriate role. Administrators and self-service users can create and delete server groups. Read-only users cannot.

## Create a Server Group

To create a server group from the UI:

1. Navigate to **Virtual Machines** > **Server Groups** and click the **Create Server Group** button.
2. In the **Name** field, enter a descriptive name for the server group.
3. From the **Policy** dropdown, select one of **Affinity**, **Soft Affinity**, **Anti-Affinity**, or **Soft Anti-Affinity**. See [Overview](#overview) for what each policy does.
4. Click the **Create Server Group** button.

You can now add a VM to this server group as part of the VM creation wizard.

## Add a VM to a Server Group

A VM's server group is selected when the VM is created, in the VM creation wizard.

You cannot add an existing VM to a server group, and you cannot move a VM from one server group to another, after the VM has been created. To change membership, recreate the VM in the desired group. You can create the new VM from an image of the original VM to preserve its disk contents.

## How Affinity Rules Interact With <code class="expression">space.vars.product\_name</code> Operations

After a server group is created and its VMs are running, the group's policy continues to govern placement during automated and administrative operations. The table below summarizes the behavior for powered-on VMs.

| Policy                   | DRR                                                                                                                                                                                     | VM HA                                                                                                                                                                                                                                                                                       | Maintenance mode                                                                                                                                                                                     | Live and cold migration                                                                                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Affinity** (hard)      | DRR does not rebalance members of a hard affinity group. The Compute Service cannot find a valid target for a single member without breaking the rule, so the VM is skipped.            | On host failure, VM HA looks for a single host with enough capacity for the entire group and restarts all members there together. If no such host exists, HA fails for the group and the UI reports the failure.                                                                            | Entering maintenance mode fails if any powered-on member of a hard affinity group is on the host. The UI reports the policy violation.                                                               | Migration fails. The platform cannot move every member together in a single operation, so a single member cannot be relocated without breaking the rule. See [Limitations](#limitations). |
| **Soft affinity**        | DRR may rebalance members. A member with no explicit migration priority is treated as low priority for rebalancing; a member with a set migration priority is honored at that priority. | VM HA tries to restart all members together on a single host with enough capacity. If none is available, it restarts the members individually, which may place them on different hosts, and the UI reports an affinity policy violation.                                                    | Best effort. <code class="expression">space.vars.product\_name</code> keeps members together where capacity allows and places the remainder on other hosts. The group may end up split across hosts. | Allowed. The UI warns that the move may violate the soft affinity policy but does not block it.                                                                                           |
| **Anti-affinity** (hard) | When choosing a migration target, DRR excludes any host that already runs another member of the group.                                                                                  | On host failure, VM HA restarts each VM on a host that is not running another member VM. If no compliant host is available, HA fails for that VM and the UI reports the failure. A member on an offline host is shown as disconnected.                                                      | Entering maintenance mode fails if no target host preserves the anti-affinity rule.                                                                                                                  | Migration fails when the selected target host already runs another member of the group. The UI filters out non-compliant hosts.                                                           |
| **Soft anti-affinity**   | Same rebalancing behavior as soft affinity. Members are honored at their set migration priority, or treated as low priority when none is set.                                           | VM HA tries to restart each member on a host that is not running another member. If none is available, it may restart on a host that already runs a member and reports an anti-affinity policy violation. If it cannot restart the VM at all, HA fails and the VM is shown as disconnected. | Best effort. Members may be co-located on a host when capacity requires it.                                                                                                                          | Allowed even when the target host runs another member. The UI warns of the membership but does not block the move.                                                                        |

{% hint style="info" %}
**Hot add of CPU or memory does not affect affinity rules.** A hot add operation does not move a VM to a different host, so a hot-added VM keeps the same placement and never violates an affinity or anti-affinity rule, regardless of the policy type.
{% endhint %}

## Limitations

* <code class="expression">space.vars.product\_name</code> cannot move all members of a server group together in a single, atomic operation. As a result:
  * Live or cold migration of a VM in a **hard affinity** group fails. Moving one member VM on its own would break the rule that all members share a host, and the platform cannot relocate the entire group in one step.
  * Live or cold migration of a VM in a **hard anti-affinity** group fails when the selected target host already runs another member of the group.
  * Soft affinity and soft anti-affinity groups are not affected, because their rules are best effort and the platform is allowed to break them when necessary.
* **Group membership is set at VM creation only.** You select a VM's server group when you create the VM. You cannot add an existing VM to a group, or move a VM between groups, afterward.
* **One policy per group.** A server group enforces a single policy. Affinity and anti-affinity, or hard and soft, cannot be mixed in the same group.
* **Capacity and host count govern strict policies.** A hard affinity group needs one host with enough capacity for every member, and a hard anti-affinity group needs at least as many eligible hosts as it has members. When these conditions are not met, VM creation, an HA restart, or a maintenance-mode evacuation can fail because no valid host is available.

## VMware Equivalents

If you are coming from VMware, <code class="expression">space.vars.product\_name</code> affinity rules map to vSphere DRS affinity rules as follows.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Private Cloud Director policy</th><th>Closest VMware DRS rule</th></tr></thead><tbody><tr><td>Affinity</td><td>"Keep Virtual Machines Together", or a VM-Host "Must run on hosts in group" rule</td></tr><tr><td>Soft affinity</td><td>A preferential "should run" affinity rule</td></tr><tr><td>Anti-affinity</td><td>"Separate Virtual Machines", or a VM-Host "Must not run on hosts in group" rule</td></tr><tr><td>Soft anti-affinity</td><td>A preferential "should not run" separation rule</td></tr></tbody></table>

As in vSphere, a hard rule blocks an HA restart that would violate it, while a soft rule lets HA restore availability first, even if that temporarily breaks the rule, and rebalances toward compliance afterward.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/virtualized-clusters/virtualmachine/vm-affinity-anti-affinity-rules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.