How to enable Anti-affinity with the UpCloud API

Running your application on more than one Cloud Server gives it redundancy. Those servers can still end up on the same physical host, where a single hardware failure could stop all of them. Server Groups with anti-affinity reduce that risk.

Server Groups let you bundle your Cloud Servers for easier organization and management. A group can also have an anti-affinity policy, which places the servers in the group on separate physical hosts. The policy decides what happens when that isn't possible.

Creating a new Server Group

The Server Group and anti-affinity features are provided via the UpCloud API at no cost to the customer. If you are new to UpCloud API, check out our getting started with UpCloud API guide to get up to speed.

Begin by calling the endpoint shown below and creating a new Server Group. Include the following parameters in the body of your API request.

1. Name your Server Group by setting a title.

2. You can also already add existing servers to the Server Group by including each Cloud Server’s UUID.

3. To enable anti-affinity, include the anti_affinity parameter. Set it to strict to keep the servers on separate hosts, or to yes to place them on separate hosts when possible. With yes, a server still starts if anti-affinity can't be met, so it can share a host with another server in the group. The default is no. See Anti-affinity for how each policy works.

POST /1.3/server-group

{
  "server_group": {
    "title": "App servers",
    "anti_affinity": "strict",
    "servers": {
      "server": [
        "<server-uuid>"
      ]
    }
  }
}

A normal response will look similar to the example below.

HTTP/1.1 200 OK

{
    "server_group": {
        "anti_affinity": "strict",
        "anti_affinity_status": [
            {
                "status": "met",
                "uuid": "00dd7d47-da91-44f0-9898-73d7a4de5ad2"
            }
        ],
        "labels": {
            "label": []
        },
        "servers": {
            "server": [
                "00dd7d47-da91-44f0-9898-73d7a4de5ad2"
            ]
        },
        "title": "App servers",
        "uuid": "0ba3e07d-3733-4e43-8230-183d708e6055"
    }
}

Notice that just adding Cloud Servers to a group will not automatically distribute them between different hosts. You can see the status of the anti-affinity conditions like in the response example above, or by querying the Server Group endpoint with your group UUID.

The status of the server’s anti-affinity can be checked via group info or group list endpoints. If the status is met, the server is the only one on that physical host. If the status is unmet, the server shares the same host machine with another Cloud Server from the same anti-affinity group.

Adding Cloud Servers to an existing server group

Including Cloud Servers in a Server Group with anti-affinity enabled allows you to increase the redundancy of your cloud services. The anti-affinity conditions are observed during the Cloud Server creation and start-up phases by allocating the Cloud Server to a host without any other members of the same Server Group.

You need the group's UUID. It's in the uuid field of the response when you create the group. To find it later, list your Server Groups and look for the group's title.

GET /1.3/server-group

{
  "server_groups": {
    "server_group": [
      {
        "anti_affinity": "strict",
        "anti_affinity_status": [ ... ],
        "labels": {
          "label": []
        },
        "servers": {
          "server": [ ... ]
        },
        "title": "App servers",
        "uuid": "0ba3e07d-3733-4e43-8230-183d708e6055"
      }
    ]
  }
}

Cloud Servers can be added to the Server Group already at creation by including the Server Group UUID in the server creation API query.

POST /1.3/server/

{
   ...
  "server" : {
    "server_group": "<server-group-uuid>"
  }
   ...
}

To add a Cloud Server that already exists, add it to the group's servers.

POST /1.3/server-group/{server_group_uuid}/servers

{
  "server": {
    "uuid": "<server-uuid>"
  }
}

Alternatively, you can call the Server Group API endpoint to include multiple Cloud Servers in the same group in one go.

PATCH /1.3/server-group/{server_group_uuid}

{
  "server_group": {
    "title": "App servers",
    "anti_affinity": "strict",
    "servers": {
      "server": [
        "<server-uuid>",
        "<second-server-uuid>"
      ]
    }
  }
}

The servers list replaces the group's current members, so include every server that should stay in the group.

If the group's policy is strict, the API refuses to add a running server that shares a host with another server in the group, with the error STRICT_ANTI_AFFINITY_NOT_MET. To add it, stop the server first, add it to the group, and then start it.

Grouped servers avoid physical hosts that already have members from the same group. A server in a group with yes still starts if anti-affinity can't be met. See Anti-affinity for how each policy works.

A server can belong to only one group. To be able to move a Cloud Server to another group, it must first be removed from its current group.

Meeting the anti-affinity conditions

Adding new Cloud Servers to a Server Group already at creation helps to have the server allocated on a host that meets the anti-affinity conditions. However, adding already running servers to a group has the possibility of finding multiple Cloud Servers running on the same host, and therefore, not meeting the anti-affinity conditions. In a group with yes, such servers are added and listed as unmet.

If your Server Group has Cloud Servers that are listed as anti-affinity “status unmet”, you will need to restart at least one of the servers. The anti-affinity conditions are then observed during the start-up phases and the Cloud Server is started on a new host.

You can issue a restart command to a Cloud Server using the following API request. Notice that the stop type needs to be set to hard to have the server perform a full power cycle.

POST /1.3/server/{uuid}/restart

{
  "restart_server": {
    "stop_type": "hard"
  }
}

After sending the restart command, wait a moment for the server to reboot. Then check your Server Group to see the status of the anti-affinity conditions.

GET /1.3/server-group/{server_group_uuid}

A normal response with anti-affinity conditions satisfied will look similar to the example below.

HTTP/1.1 200 OK

{
    "server_group": {
        "anti_affinity": "yes",
        "anti_affinity_status": [
            {
                "status": "met",
                "uuid": "0038c967-0713-4ba2-a9da-9c532023849f"
            },
            {
                "status": "met",
                "uuid": "00dd7d47-da91-44f0-9898-73d7a4de5ad2"
            }
        ],
        "labels": {
            "label": []
        },
        "servers": {
            "server": [
                "0038c967-0713-4ba2-a9da-9c532023849f",
                "00dd7d47-da91-44f0-9898-73d7a4de5ad2"
            ]
        },
        "title": "App servers",
        "uuid": "0ba3e07d-3733-4e43-8230-183d708e6055"
    }
}

When every server in the group shows met, your Cloud Servers are running on separate hosts, and a single hardware failure is less likely to stop all of them.

Conclusions

Server Groups and anti-affinity help you build redundant services by placing your Cloud Servers on separate physical hosts. These features are made available through the UpCloud API and their usage is entirely free of charge.