When you deploy several Linodes in one of our compute regions, they’re allocated to physical machines (“hosts”) with available resources. However, depending on your workload requirements, you may need your Linodes to follow specific strategies:

Grouped-together. You may want them placed close together to reduce latency between Linodes that are used for an application or workload.
Spread apart. You may want to disperse them across several hosts to support high-availability, for example when required for fail-over.

Placement groups distribute your Linodes across hosts in a region to meet either of these models.

Overview

Setting up a placement group is a simple process using Cloud Manager, the Linode API, or our CLI. Create a new group in a supported region and add new or existing Linodes from that region to your group. When assigning Linodes to the placement group, we physically place them, based on your desired model.

Availability

Placement Groups is available in all core compute regions that support Linodes, but is not available in distributed compute regions.

Placement groups and compliance

Review these sections for an understanding of the placement groups concept.

Placement group type

To distribute your Linodes in a placement group, we use specific placement strategies. When creating a new group, you select from one of two placement group types:

Affinity. When you assign Linodes to the group, we place them physically close together, possibly on the same host. This supports the grouped-together model and is best for applications that require low-latency.
Anti-affinity. When you assign Linodes to the group, we place them in separate hosts, but keep them in the same region. This supports the spread-apart model for high-availability.

📘
Currently, only the Anti-affinity Placement Group Type is supported.

Compliance

Your placement group is in compliance if all of the Linodes in it currently meet your grouped-together or spread-apart model, based on your selected placement group type.

When you create a new placement group and assign Linodes to it, we'll place them as necessary to make sure the group is compliant with your selected placement group type. There's nothing you need to do to apply compliance at this phase.
Compliance comes into play when you add more Linodes to your placement group in the future. For example, assume you've set Anti-affinity as your placement group type. Your group already has three qualifying Linodes in separate hosts, to support the spread-apart model. If a fourth Linode is added that's on the same host as one of the existing three, this would make the placement group non-compliant. Compliance at this stage is enforced by your selected placement group policy.
Compliance can also come into play when we need to perform emergency maintenance. For example, if we need to apply an essential security patch to a host, this can affect the compliance of a placement group that uses Linodes on that host.

Placement group policy

This determines how we handle requests to add Linodes to your placement group in the future, and whether or not it stays compliant.

Strict (Best practice). If a target Linode breaks the grouped-together or spread-apart model set by your placement group type, it won't be added. Use this to ensure the placement group stays compliant.
Flexible. A target Linode will be added even if it breaks the grouped-together or spread-apart model set by your placement group type. This makes the placement group non-compliant. Use this if you need more flexibility to add future Linodes and compliance isn't an immediate concern.

Fix non-compliance

We're alerted if a placement group becomes non-compliant, regardless of the cause. We'll move an out-of-compliance Linode for you to fix the issue. Non-compliance can only be fixed by Akamai staff.

Based on your selected placement group policy, here are the ways a placement group can become non-compliant:

Strict. There are rare cases when we may need to perform emergency maintenance on a host that contains the Linodes that make up your placement group. In this case, we need to migrate these Linodes to other hosts, which could make the placement group non-compliant.
Flexible. A placement group using this policy can become non-compliant if a Linode is included that doesn't meet the placement group type's grouped-together or spread-apart model.

📘
Fixing non-compliance for Strict placement groups is prioritized over Flexible groups.

Create a placement group

Here are a some workflows to create a new placement group and add existing Linodes to it.

Use Cloud Manager

Review these sections to create a new group using Cloud Manager.

Before you begin

Review Placement groups and compliance to understand the placement group concept.
Review the Technical specifications for details on what's supported.

Creation process

Navigate to the Placement Groups page in Cloud Manager and click Create Placement Groups. The Create Placement Group form opens.
Fill out the form with your desired settings:
- Label. Give your placement group an easily recognizable name.
- Region. Select the compute region that includes the Linodes you want to add.
- Placement Group Type. Select the affinity that meets your model.
- Placement Group Policy. Pick how you want to enforce compliance for your placement group, when adding Linodes to it in the future.

📘

Currently, only Anti-affinity is available for Placement Group Type.

Once you create your placement group, you can't change its Placement Group Policy.

Click the Label for your new group. A summary of it is revealed.
Click Assign Linode to Placement Group. The Assign Linodes form opens.
The Linodes in <Region> drop-down is auto-populated with eligible Linodes in that region. Pick one and click Assign Linode.
Review the Linode limit for this placement group, and repeat steps 5-6 to add more Linodes, as necessary.

📘
Currently, you’re limited to a maximum of 5 Linodes in a placement group.

With all your Linodes added, we begin provisioning by moving them into the placement group to meet your selected Placement Group Type.

Use the API

Here, we combine API operations to create a new placement group and add existing Linodes to it.

Before you begin

Review Placement groups and compliance to understand the placement group concept.
Review the Technical specifications for details on what's supported.

List regions

Run this API curl request, making sure to properly paste in or reference your API token. Store the id and label values for the region where your target Linodes live.

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/regions

📘
During the limited availability phase, only specific regions support placement groups.

Identify the maximum number of Linodes

Run this request, using the stored region id. Store the maximum_linodes_per_pg value. This represents the maximum number of Linodes you can add to a placement group for that region.

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/regions/us-east

📘
Currently, you can have a maximum of 5 Linodes in a placement group.

List Linodes

Run this request using the stored region id to filter the response. Identify the specific Linodes you want to include -- up to the maximum_linodes_per_pg value -- and store the id value for each.

curl -H "Authorization: Bearer $TOKEN"
    -H 'X-Filter: { "region": "us-east" }'
    https://api.linode.com/v4/networking/ips

Create the new placement group

Run this request to create a new placement group. Store the id value that's generated for it.

label. Give your placement group an easily recognizable name.
region. Set this to the label you stored for your region.
placement_group_type. Set this to the affinity that meets your model.
placement_group_policy. Define how to enforce compliance for your placement group, when adding Linodes to it in the future. Set to strict for strict enforcement or flexible for flexible enforcement.

📘

Currently, only anti-affinity (anti-affinity:local) is available for placement_group_type.

Once you create your placement group, you can't change its placement_group_policy enforcement setting.

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "label": "new-placement-group",
      "region": "us-east",
      "placement_group_type": "anti_affinity:local",
      "placement_group_policy": "strict"
    }' \
    https://api.linode.com/v4/placement/groups

Add Linodes to the group

In this request, populate the linodes array with a comma-separated data center list of stored id values for the Linodes. In the URL, target the new placement group using its stored id.

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "linodes": [
        123, 456, 789
      ]
    }' \
    https://api.linode.com/v4/placement/groups/12/assign

With all your Linodes added, we begin provisioning by placing them into the placement group to meet your selected placement_group_type.

More with the placement groups API

There are several other operations in the Linode API you can use to interact with placement groups.

Technical specifications

Placement groups support dedicated, premium, and shared Linode plans. You can mix dedicated and shared plan Linodes in the same placement group, but you can't mix premium plans with any other type.
Specialty hardware, such as GPUs aren't supported.
A Linode can only exist in one placement group.
The maximum number of Linodes in a placement group is currently five. This quantity is reflected in Cloud Manager when reviewing your placement group. With the API, the GET /v4/regions/{regionid} operation contains the maximum_linodes_per_pg element that displays this maximum.
Placement groups can be renamed or deleted. To delete a placement group, you need to remove all Linodes from it.
When you remove a Linode from a placement group, it continues to function as-is, but the placement decisions are no longer guided by the group's Placement Group Type.
Entry points to create a placement group are also available when creating a new Linode or editing an existing one.