How to use Antiaffinity

You are here:
< All Topics


Anti-Affinity allows you to add more robustness to your VMs for High Availability applications. This is done by specifying labels for your Virtual Machines; these labels are used to figure out where VMs get deployed. Anti-Affinity ensures that no 2 VMs with the same label on the same cloudspace will end up on the same physical node, if no Anti-Affinity group is set (more details on Anti-Affinity groups later). That being said, in the very unlikely scenario of a cloud failure, rest assured that one of the two machines will still be up and running.


  • Access to one of the G8 accounts

You must be able to use Machine API from the end user portal of a G8.

Prepare the environment in your shell.

  • Export your JWT as $JWT in the environment variables of your shell

  • Export the url to the G8 you are importing to into the $URL environment variable. In my case this is:

    export URL=""
  • Install the jq cli utility for parsing JSON output from the API. See

Getting the cloudspace ID

Before you can start creating machines, you need to know the ID of your cloudspace. You can list the cloudspaces to which your JWT has access using the following command:

$ curl --silent -X POST -H "Authorization: bearer ${JWT}" -F "includedeleted=False" "${URL}/restmachine/cloudapi/cloudspaces/list" | jq -r '.[] | "\(.id)\t\(.accountName)/\(.name)"'
1040    my-cloudspace

Note Try the previous command without piping the output of the curl command to the jq cli utility. It will show you the complete output of the API result.

Let's also discuss the parameters we passed to the curl command in our shell:

  • --silent to omit curl to output any progress or other non important information
  • -X POST to make curl do a http POST request
  • -H "Authorization: bearer ${JWT}" passes an authentication header using our JWT
  • -F "includedeleted=False" passes the includedeleted argument to the API call

All these arguments are then POSTed to the URI of the API resource to list cloudspaces, which is "${URL}/restmachine/cloudapi/cloudspaces/list"

Getting the image ID

You will also need to know the IDs of the images your account has access to. This will be used to specify an image for your VM to boot from. To list the images, you can use the following command:

$ curl --silent -X POST -H "Authorization: bearer ${JWT}" "${URL}/restmachine/cloudapi/images/list" | jq -r '.[] | "\(.id)\t/\(.name)"'
239 /Alpine-NBD
231 /CentOS 7.6 - x86_64
232 /Debian 10 - x86_64
233 /Debian 9 - x86_64
234 /Open SUSE Leap 15.1 - x86_64
235 /Ubuntu Server 16.04 - x86_64
236 /Ubuntu Server 18.04 - x86_64   

Your output for the previous 2 commands might be slightly different depending on your G8

Steps (without setting Anti-Affinity Group)

Step 1

Go to your end user portal on your G8 and find your way to the Machine API page

Step 2

Find your way to the endpoint cloudapi/machines/create under cloudapi__machines


The above image only contains the required parameters. We will skip optional parameters since they hold no value to the purposes of this tutorial

Step 3

Enter the following parameters for the new VM you'll create:

cloudspaceId: Id of a cloudspace belonging to your account or one that your user has access to. You can use any cloudspace from the ones listed in the prerequisite section above. (required)

name: name of your machine. (required)

labels: could be a list of labels to be assigned to this VM or just 1 single label. In this case we will use, for example, "db server". Although this is optional, this must be set in order to use the Anti-Affinity feature. (required for this tutorial)

imageId: could be any image id from the ones listed in the prerequisite section above. (required)

vcpus: number of vcpus assigned to this VM. (required)

disksize: boot disk size. must be >= minimum size specified by the image. (required)

memory: amount of memory to be attached to this VM in Mb. (required)

description: some information about this virtual machine. (required)

Step 4

Click execute and repeat the same process again for another machine. New machines should have the same cloudspaceID and the same label, but different names. You can create as many machines with the same labels as there are cpu nodes on your G8.

Important Notes

Anti-Affinity rules are set on cloudspace level

This means that 2 machines with the same label but belonging to 2 different cloudspaces might still end up on the same physical node.

You can limit the outspread of machines to a specific number of physical nodes

Since your G8 doesn't have an infinite number of physical machines, we provide a mechanism to specify a limit on Anti-Affinity. To better understand this, let's go through a simple use case.

Consider the case when your G8 only has 5 physical nodes. Without specifying a limit on your Anti-Affinity, you'll only be able to deploy 5 machines with the same label on the same cloudspace. However, sometimes you might still want to leverage the Anti-Affinity feature on 3 nodes only while being able to deploy more than 3 Virtual Machines. In that case you can take advantage of setting Anti-Affinity groups on your cloudspace with a specific spread value. So, for example, if you set Anti-Affinity group on your cloudspace with spread value = 2 and you deploy 10 machines with the same label, then you can be sure that your 10 VMs will be distributed on at least 2 nodes. The following steps show how to do that.

Steps (with setAntiAffinityGroup)

Step 1

Go to Machine API and find your way to the cloudapi__cloudspaces section

Step 2

find your way to the API endpoint /cloudapi/cloudspaces/setAntiAffinityGroup and enter the following values


This will result in the desired effect discussed in the Important notes section above.

Delete an Anti-Affinity Group

In order to delete an Anti-Affinity rule, you can do so via the API endpoint /cloudapi/cloudspaces/deleteAntiAffinityGroup


Previous How to add your own vm image to your G8
Next How to use your own ISO’s on the G8
Table of Contents