Using placement groups with the API

Placement groups allow you to group your Instances.

You can choose between two operating modes: max_availability, which ensures that Instances of a group do not run on the same underlying hardware, and low_latency, which brings Instances closer together to achieve higher network throughput.

If you prefer a visual environment, discover how to manage placement groups from the Scaleway console.

Before you start

To complete the actions presented below, you must have:

• Owner status or IAM permissions allowing you to perform actions in the intended Organization

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. However, they are not compatible with Elastic Metal servers.

A placement group is composed of three mandatory fields:

• Name,
• Policy type,
• Policy mode.

Name is a free text field.

Policy types

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

The low latency policy groups your Instances on the nearest hardware and limits network latency, allowing 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 check the field policy_respected. This field indicates if the selected policy is respected or not. It returns true if the policy is respected, and 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 set up 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/

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"
  }

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": []
}

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"
    }
  ]
}

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"
}

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-058466a6ea6d

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-ba04cc23eb00

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"
    }
  ]
}

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

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,
• A running Instance cannot be modified and should be archived.