Create a placement group

post

https://api.linode.com/{apiVersion}/placement/groups

Creates a placement group on your account. Placement groups disperse your Linodes across physical machines (hosts) in one of our compute regions. Depending on your workload requirements, you may need your Linodes to follow specific strategies:

Grouped-together model. You may want them placed close together to reduce latency between Linodes that are used for an application or workload. Affinity placement groups follow this model.
Spread-apart model. You may want to disperse them across several hosts to support high availability, for example when required for failover. Anti-affinity placement groups follow this model.

To run this operation, your user needs the add_linodes grant. Talk to your local account administrator about grant management for your user.

👍
There's a tutorial
We offer an example API workflow you can follow to create a placement group and add Linodes to it.

Permissions and scopes

To call this operation, you need permissions, based on the model you're using:

OAuth scopes. Your user needs these scopes assigned. Learn more.
- Scopes: linodes:read_write

CLI

linode-cli placement group-create \
  --label PG_Miami_failover \
  --region us-mia \
  --placement_group_type "anti_affinity:local" \
  --placement_group_policy strict

Learn more

Path Params

apiVersion

string

enum

required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Allowed:

Body Params

Common properties for creating and rebuilding placement groups.

label

string

required

length ≥ 1

A unique name for the placement group. A placement group label has the following constraints:

It needs to begin and end with an alphanumeric character.
It can only consist of alphanumeric characters, hyphens (-), underscores (_), or periods (.).

placement_group_policy

string

enum

required

How requests to add future Linodes to your placement group are handled:

strict: Ensures the placement group stays compliant with your selected model. If a target Linode breaks the grouped-together or spread-apart model set by your placement group type, it won't be added. For example, with anti_affinity:local as your placement_group_type, assume it already has three qualifying Linodes on separate hosts, to support the spread-apart model. If a fourth Linode is assigned that's on the same host as one of the existing three, an error occurs and the system won't add it.
flexible. A target Linode will be added even if it breaks the grouped-together or spread-apart model set by your placement group type. Breaking the model makes the placement group non-compliant. 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.

📘
Once you create a placement group, you can't change its placement_group_policy setting.

Allowed:

placement_group_type

string

enum

required

How Linodes are distributed in your placement group. A placement_group_type using anti-affinity (anti_affinity:local) places Linodes in separate hosts, but still in the same region. This best supports the spread-apart model for high availability. A placement_group_type using affinity places Linodes physically close together, possibly on the same host. This supports the grouped-together model for low-latency.

📘
Currently, only anti_affinity:local is available for placement_group_type.

Allowed:

region

string

required

The data center that houses the Linodes you want to add to your placement group. Run the List Linodes operation to view your Linodes and store the region identifier.

Responses

200A new placement group is being created.

defaultSee Errors for the range of possible error response codes.