A VM-VM affinity rule applies to two or more virtual machines and specifies whether they should be deployed on the same host or on separate hosts. VM-VM affinity rules are properties of an organization VDC, and apply to virtual machines deployed on the hosts that back that VDC.

VM-VM affinity rules are user-specified constraints that the system considers during the deployment process. There are two types, or polarities, of VM-VM affinity rules:

■

A rule with a Polarity value of Affinity specifies two or more virtual machines that the system should deploy on the same host. This kind of rule is commonly applied in cases where virtual machines can realize performance benefits from being placed on a single host and are running workloads where failure of that host can be tolerated.

■

A rule with a Polarity value of Anti-Affinity specifies two or more virtual machines that the system should deploy on separate hosts. This kind of rule is commonly applied in cases where virtual machines are intended to support redundancy, availability, and similar uses that must not be affected by the failure of one host.

You can make an affinity rule mandatory to provide a hint to the system that the deployment should fail unless the specified placement objective can be achieved. When a virtual machine is the subject of a mandatory affinity rule, placement requirements dictated by the rule override any placement changes that might be initiated by vSphere services such as High Availability and Storage DRS.

When you create a VM-VM affinity rule in an organization VDC, vCloud Director creates a corresponding rule in the vCenter server that provides resources to that organization VDC. This rule has several differences compared with a VM-VM affinity rule created directly in vCenter:

■

A virtual machine can be referenced in no more than one vCloud Director affinity rule.

■

A virtual machine can be referenced in no more than one vCloud Director anti-affinity rule.

When you create a vCloud Director affinity rule, the system validates that it does not reference a virtual machine that is already referenced by an existing rule of the same polarity. Requests that attempt to create a rule that would violate this constraint are rejected.

Prerequisites
■

This operation requires the rights included in the predefined vApp Author role or an equivalent set of rights.

■

To create an affinity rule, you must be the owner of all virtual machines specified in the rule.

Procedure
1

Retrieve the XML representation of the organization VDC to which you want to add the affinity rule.

This request retrieves the user view of an organization VDC. 

GET https://vcloud.example.com/api/vdc/44
2

Examine the response to locate the Link element that contains the URL for adding affinity rules to the VDC.

This element has a rel attribute value of add and a type attribute value of application/vnd.vmware.vcloud.vmaffinityrule+xml, as shown here: 

<Link
      rel="add"
      href="https://vcloud.example.com/api/vdc/44/vmAffinityRules/"
      type="application/vnd.vmware.vcloud.vmaffinityrule+xml" />
3

Retrieve references to the virtual machines that will be subject to the rule.

The references must be to virtual machines that have been instantiated in the same VDC. You can use a query like this one to list references to all the virtual machines instantiated in a VDC whose URL is vdc-reference. 

GET https://vcloud.example.com/api/query?\
type=vm&format=references&\
filter=isVAppTemplate==false&vdc==vdc-reference

For example: 

GET https://vcloud.example.com/api/query?\
type=vm&format=references&\
filter=isVAppTemplate==false&vdc==https://vcloud.example.com/api/vdc/44
4

Create a VmAffinityRule request body.

The name element cannot contain more that 40 characters. See Example: Create a VM-VM Affinity Rule.

5

POST the VmAffinityRule element you created in Step 4 to the URL for adding affinity rules the organization VDC.

See the request portion of Example: Create a VM-VM Affinity Rule.

Example: Create a VM-VM Affinity Rule

This request creates an affinity rule for two virtual machines.

Request: 

POST https://vcloud.example.com/api/vdc/44/vmAffinityRules
Content-Type: application/vnd.vmware.vcloud.vmaffinityrule+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<VmAffinityRule xmlns="http://www.vmware.com/vcloud/v1.5">
   <Name>example-affinity-rule</Name>
   <IsEnabled>true</IsEnabled>
   <IsMandatory>false</IsMandatory>
   <Polarity>Affinity</Polarity>
   <Scope>Host</Scope>
   <VmReferences>
      <VmReference href="https://vcloud.example.com/api/vApp/vm-44" />
      <VmReference href="https://vcloud.example.com/api/vApp/vm-200" />
   </VmReferences>
</VmAffinityRule>

If either of the referenced virtual machines is already the subject of an affinity rule, the request fails with an error message indicating the reason for the failure.

The response is a Task. Note the href of the Owner element in the returned Task. This is the ID of the rule. You must use it when you delete or update the rule.

Response: 

<?xml version="1.0" encoding="UTF-8"?>
<Task
   ...
   operationName="affinityRuleCreate"
   ... >
   <Owner  
      href="https://vcloud.example.com/api/vmAffinityRule/edf7c456-a69c-48b1-89a8-4e9674448e01"  
      name="example_name"  
      type="application/vnd.vmware.vcloud.vmaffinityrule+xml" />
   ...    
</Task>

Note

When you create or update an anti-affinity rule, the system might need to create a place-holder virtual machine to satisfy the vCenter requirement that such rules include at least two virtual machines. This place-holder is visible to vCenter administrators, but is not visible in vCloud Director. It is never powered on.

Subtopics