Work with placement groups

When you deploy several Compute Instances 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 Compute Instances to follow specific strategies:

  • Grouped-together. You may want them placed close together to reduce latency between Compute Instances 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 Compute Instances 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 Compute Instances from that region to your group. When assigning Compute Instances 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 Compute Instances, 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 Compute Instances 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 Compute Instances 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 Compute Instances 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 Compute Instances 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 Compute Instances 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 Compute Instances 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 Compute Instances in separate hosts, to support the spread-apart model. If a fourth Compute Instance 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 Compute Instances on that host.

Placement group policy

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

  • Strict (Best practice). If a target Compute Instance 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 Compute Instance 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 Compute Instances 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 Compute Instance 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 Compute Instances that make up your placement group. In this case, we need to migrate these Compute Instances to other hosts, which could make the placement group non-compliant.

  • Flexible. A placement group using this policy can become non-compliant if a Compute Instance 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 Compute Instances to it.

Use Cloud Manager

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

Before you begin

Creation process

  1. Navigate to the Placement Groups page in Cloud Manager and click Create Placement Groups. The Create Placement Group form opens.

  2. 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 Compute Instances 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 Compute Instances 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.
  1. When you're ready, click Create Placement Group. A summary of your group is revealed.

  2. Select the Linodes (0) tab.

  3. Click Assign Linode to Placement Group. The Assign Linodes form opens.

  4. The Linodes in <Region> drop-down is auto-populated with eligible Compute Instances in that region. Pick one and click Assign Linode.

  5. Review the Linode limit for this placement group, and repeat steps 5-6 to add more Compute Instances, as necessary.

📘

Currently, you’re limited to a maximum of 5 Compute Instances in a placement group.

With all your Compute Instances 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 Compute Instances to it.

Before you begin

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 Compute Instances 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 Compute Instances

Run this request, using the stored region id. Store the maximum_linodes_per_pg value. This represents the maximum number of Compute Instances 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 Compute Instances in a placement group.

List Compute Instances

Run this request using the stored region id to filter the response. Identify the specific Compute Instances 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 Compute Instances 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 Compute Instances to the group

In this request, populate the linodes array with a comma-separated data center list of stored id values for the Compute Instances. 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 Compute Instances 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 Compute Instance plans. You can mix dedicated and shared plan Compute Instances 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 Compute Instance can only exist in one placement group.

  • The maximum number of Compute Instances 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 Compute Instances from it.

  • When you remove a Compute Instance 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 Compute Instance or editing an existing one.