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:
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.
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 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. |
This request creates an affinity rule for two virtual machines.
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> <Polarity>Affinity</Polarity> <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.
<?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>
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.