Using placement groups with the API

Placement groups allow you to group Instances into groups.

Placement groups have two operating modes. The first one is called max_availability. It ensures that all the Instances that belong to the same group will not run on the same underlying hardware. The second one is called low_latency and does the exact opposite: it brings Instances closer together to achieve higher network throughput.

If you prefer managing your placement groups in a visual environment, discover our documentation about managing placement groups from the Scaleway console.

Understanding placement groups

Placement groups work for all instance ranges in the same availability zone without any architecture or type distinction. It means that GP1, DEV1, ARM64, or all the future virtualized ranges can be part of the same placement group. Unfortunately, they will not work on Elastic Metal servers.

A placement group is composed of three mandatory fields:

• a name
• a policy type
• a policy mode

Name is a free text field but let us explain what are the two others in more details.

Policy types

The policy type enables the choice of placement behavior for underlying Instances. It can be set to either low_latency or to max_availability.

The low latency policy regroups your Instances on the nearest hardware. It will limit network latency and allows for the highest network throughput between servers. At best, Instances will be placed on the same hypervisor.

The maximum availability policy spreads the Instances on far-away hypervisors as much as possible. It will limit the impact in case of hardware failure. For this policy, the Instances may be placed anywhere in the same availability zone.

Policy modes

The policy mode selects the instance’s allocation behavior if the placement constraint cannot be respected. Policy mode can be set to either optional or enforced.

When the policy mode is set to optional then failing to respect the placement policy still allocates the server. When the policy mode is set to enforced then failing to respect the placement policy results in not allocating the server.

Checking a group status

When several Instances are part of the same placement group, it is possible to query the full group status and then to check the field policy_respected. This field indicates if the selected policy is respected or not. It returns true if the policy is respected, false otherwise.

To get the placement information for a single server, query its server object. In the result, check the field placement_group. Likewise, it will be true if the placement is respected or false if it is not.

Creating a placement group

As a practical application, we will see how to setup two Instances that should never run on the same hardware. To do so, we will create a max_availabilitytype placement group with the enforced policy.

First, let us create the placement group with the appropriate policy_type and policy_mode fields:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	-X POST \
	-d '{"name": "cc-test", "policy_mode": "optional", "policy_type": "max_availability", "organization": "c2d2fe22-6b5a-4f09-abae-cb1d633f1533"}' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/Copy

A query to the placement group prints the current operation mode of the group:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json'  \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4
{
  "placement_group": {
    "name": "cc-test",
    "policy_mode": "enforced",
    "policy_type": "max_availability",
    "organization": "c2d2fe22-6b5a-4f09-abae-cb1d633f1533",
    "policy_respected": true,
    "id": "ae5c1189-f421-4285-988b-80d29267ddc4"
  }Copy

The policy_respected field is set to true as there is no server in the group at the moment.

To list Instances that belong to the group, use the /placement_groups/*/servers API endpoint:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4/servers
{
  "servers": []
}Copy

Our group is empty at the moment so this is perfectly normal.

Adding multiple existing Instances to a placement group

Once a placement group is created, you can add existing Instances in it. To do so, just call a PUT method on the /placement_groups/*/servers endpoint.

Before adding Instances to a group, ensure that they are all powered off. The placement procedure cannot work with a running server.

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json'  \
	-X PUT \
	-d '{"servers": ["a3505194-b875-4bda-87c0-058466a6ea6d", "dab279bc-aa4d-4ba1-841c-ba04cc23eb00"]}' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4
{
  "servers": [
    {
      "policy_respected": true,
      "id": "a3505194-b875-4bda-87c0-058466a6ea6d",
      "name": "elated-lamport"
    },
    {
      "policy_respected": true,
      "id": "dab279bc-aa4d-4ba1-841c-ba04cc23eb00",
      "name": "elegant-brown"
    }
  ]
}Copy

The group now contains the two servers. If one of the servers was running, the API would have returned the error:

{
  "message": "One or more servers are invalid",
  "type": "invalid_request_error"
}Copy

Adding a single Instance to a placement group

A single instance can also be directly added to a placement group. Again, the server must be off before doing so:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	-X PATCH -d '{"placement_group": "ae5c1189-f421-4285-988b-80d29267ddc4"}'
	\
	https://api.scaleway.com/instance/v1/zones/fr-par-1/servers/a3505194-b875-4bda-87c0-058466a6ea6dCopy

In addition, an instance can be created directly into a placement group by filing the placement_group field in the server creation API call.

Removing an Instance from a placement group

An instance, running or stopped, can be removed at any time from a placement group by setting its placement_group property to null:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json'  \
	-X PATCH -d '{"placement_group": null}' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/servers/dab279bc-aa4d-4ba1-841c-ba04cc23eb00Copy

Remember that the instance must be archived to be made part of a group so be careful!

After that call, we only have one server left in our group:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4/servers
{
  "servers": [
    {
      "policy_respected": true,
      "id": "a3505194-b875-4bda-87c0-058466a6ea6d",
      "name": "elated-lamport"
    }
  ]
}Copy

It is also possible to remove all Instances from a placement group with a DELETE call on the API endpoint /placement_groups/*/servers:

$ curl -q \
	-H "X-Auth-Token: $SCW_SECRET_KEY" \
	-H 'Content-Type: application/json' \
	-X DELETE \
	https://api.scaleway.com/instance/v1/zones/fr-par-1/placement_groups/ae5c1189-f421-4285-988b-80d29267ddc4/servers
Copy

We hope that placement groups will help you build more performant and more reliable systems with Scaleway’s products.

For more information and to see the full capabilities of placement groups, refer to the full API documentation.

Remember that a placement group will work only according to the following rules:

• Instances must be in the same availability zone
• an Instance can be in only one group at a time
• Instances must be VM only (Elastic Metal servers are not supported yet)
• a running Instance cannot be modified and should be archived