placement_groups

Creates, updates, deletes, gets or lists a placement_groups resource.

Overview

Name	placement_groups
Type	Resource
Id	linode.placement.placement_groups

Fields

The following fields are returned by SELECT queries:

get_placement_group

Returns a single placement group object.

Name	Datatype	Description
id	integer	The placement group's ID. You need to provide it for all operations that affect it.
is_compliant	boolean	Whether all of the compute instances in your placement group are compliant. If true, all compute instances meet either the grouped-together or spread-apart model, which you determine through your selected placement_group_type. If false, a compute instance is out of this compliance. For example, assume you've set anti-affinity:local as your placement_group_type and your group already has three qualifying compute instances on separate hosts, to support the spread-apart model. If a fourth compute instance is assigned that's on the same host as one of the existing three, the placement group is non-compliant. Enforce compliance in your group by setting a placement_group_policy. > 📘 > > Fixing compliance is not self-service. You need to wait for our assistance to physically move compute instances to make the group compliant again.
label	string	Filterable The unique name set for the placement group. A label has these constraints: - It needs to begin and end with an alphanumeric character. - It can only consist of alphanumeric characters, hyphens (-), underscores (_) or periods (.). (example: PG_Miami_failover)
members	array	An array of compute instances included in the placement group.
migrations	object	Any compute instances that are being migrated to or from the placement group. Returned as null if no migrations are taking place.
placement_group_policy	string	How requests to add future compute instances to your placement group are handled, and whether it remains compliant: - strict. Don't assign a new compute instance if it breaks the grouped-together or spread-apart model set by the placement_group_type. Use this to ensure the placement group stays compliant (is_compliant: true). - flexible. Assign a new compute instance, even if it breaks the grouped-together or spread-apart model set by the placement_group_type. This makes the group non-compliant (is_compliant: false). You need to wait for Akamai to move the offending compute instance to make it compliant again, once the necessary capacity is available in the region. Offers flexibility to add future compute instances if compliance isn't an immediate concern. <<LB>> > 📘 > > In rare cases, non-compliance can occur with a strict placement group if Akamai needs to failover or migrate your compute instances for maintenance. Fixing non-compliance for a strict placement group is prioritized over a flexible group. (example: strict)
placement_group_type	string	Filterable, Read-only How compute instances are distributed in your placement group. A placement_group_type using anti-affinity (anti-affinity:local) places compute instances 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 compute instances 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. (example: anti-affinity:local)
region	string	Filterable, Read-only The region where the placement group was deployed. (example: us-mia)

get_placement_groups

Returns an array of all placement groups on your Account.

Name	Datatype	Description
data	array
page	integer	Read-only The current page.
pages	integer	Read-only The total number of pages.
results	integer	Read-only The total number of results.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_placement_group	select			View a specific placement group by ID. > 📘 > > Your user needs at least read-only permission to all Linodes included in a placement group to view it. If you don't have this access and call this operation, the API returns a 403 error. Talk to your local account administrator about managing permissions. Learn more... Learn more...
get_placement_groups	select		page, page_size	Returns a paginated list of placement groups you have permission to view. > 📘 > > Your user needs at least read-only permission to all Linodes included in a placement group to view it. Placement groups that contain Linodes that you don't have this permission for are left out of the response. If all placement groups contain Linodes that lack this permission, the API returns a 403 error. Talk to your local account administrator about managing permissions. Learn more... Learn more...
post_placement_group	insert	data__placement_group_type, data__placement_group_policy, data__label, data__region		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. 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 failover. We offer an example API workflow you can follow to create a placement group. > 📘 > > To run this operation, your user needs the add_linodes grant. Talk to your local account administrator about grant management for your user. Learn more... Learn more...
put_placement_group	replace			Change the label for a specific placement group. This is the only value you can update. However, you can add more Linodes or remove existing ones. > 📘 > > To update a placement group, your user grants need to include read_write permission to all of the Linodes in the group. Talk to your local account administrator about grant management for your user. Learn more... Learn more...
delete_placement_group	delete			Deletes a placement group you have permission to read_write. - Deleting a placement group can't be undone. - All Linodes need to be removed before you can delete a placement group. - If your placement group is non-compliant, you can't delete it. You need to wait for our help to bring it compliant. <<LB>> > 📘 > > To run this operation, your user needs the add_linodes grant. Talk to your local account administrator about grant management for your user. Learn more... Learn more...
post_group_add_linode	exec			Add a Linode to your placement group. Check out our example API workflow to create a placement group and add Linodes. > 📘 > > To run this operation, your user needs the add_linodes grant and read-write permission to the Linodes you want to add to the group. Talk to your local account administrator about grant and permissions management. Learn more... Learn more...
post_group_unassign	exec			Remove a Linode from your placement group. > 📘 > > To run this operation, your user needs the add_linodes grant and read-write permission to the Linodes you want to remove from the group. Talk to your local account administrator about grant and permissions management. Learn more... Learn more...

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
page	integer	The page of a collection to return.
page_size	integer	The number of items to return per page.

SELECT examples

get_placement_group

View a specific placement group by ID.

> 📘
>
> Your user needs at least read-only permission to all Linodes included in a placement group to view it. If you don't have this access and call this operation, the API returns a 403 error. Talk to your local account administrator about managing permissions.

Learn more...

Learn more...

SELECT
id,
is_compliant,
label,
members,
migrations,
placement_group_policy,
placement_group_type,
region
FROM linode.placement.placement_groups;

get_placement_groups

Returns a paginated list of placement groups you have permission to view.

> 📘
>
> Your user needs at least read-only permission to all Linodes included in a placement group to view it. Placement groups that contain Linodes that you don't have this permission for are left out of the response. If all placement groups contain Linodes that lack this permission, the API returns a 403 error. Talk to your local account administrator about managing permissions.

Learn more...

Learn more...

SELECT
data,
page,
pages,
results
FROM linode.placement.placement_groups
WHERE page = '{{ page }}'
AND page_size = '{{ page_size }}';

INSERT examples

post_placement_group

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. 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 failover.

We offer an example API workflow you can follow to create a placement group.

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

Learn more...

Learn more...

INSERT INTO linode.placement.placement_groups (
data__label,
data__placement_group_policy,
data__placement_group_type,
data__region
)
SELECT 
'{{ label }}' --required,
'{{ placement_group_policy }}' --required,
'{{ placement_group_type }}' --required,
'{{ region }}' --required
RETURNING
id,
is_compliant,
label,
members,
placement_group_policy,
placement_group_type,
region
;

Manifest

# Description fields are for documentation purposes
- name: placement_groups
  props:
    - name: label
      value: string
      description: >
        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 (`.`).
        
    - name: placement_group_policy
      value: string
      description: >
        How requests to add future compute instances to your placement group are handled:

- `strict`. Don't add a compute instance if it breaks the grouped-together or spread-apart model set by your `placement_group_type`. For example, with `anti-affinity:local` as your `placement_group_type`, assume it already has three qualifying compute instances on separate hosts, to support the spread-apart model. If a fourth compute instance is assigned that's on the same host as one of the existing three, an error is thrown and the system won't add it. Ensures the placement group stays compliant with your selected model.
- `flexible`. Add a new compute instance, 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. You need to wait for Akamai to move the offending compute instances to make the group compliant again, once the necessary capacity is available in the region. Offers flexibility to add future compute instances if compliance isn't an immediate concern.

> 📘
>
> Once you create a placement group, you can't change its `placement_group_policy` setting.
        
      valid_values: ['strict', 'flexible']
    - name: placement_group_type
      value: string
      description: >
        How compute instances are distributed in your placement group. A `placement_group_type` using anti-affinity (`anti-affinity:local`) places compute instances 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 compute instances 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`.
        
      valid_values: ['anti_affinity:local']
    - name: region
      value: string
      description: >
        The data center that houses the compute instances you want to add to your placement group. Run the [List Linodes](https://techdocs.akamai.com/linode-api/reference/get-linode-instances) operation to view your compute instances and store the `region` identifier.
        

REPLACE examples

put_placement_group

Change the label for a specific placement group. This is the only value you can update. However, you can add more Linodes or remove existing ones.

> 📘
>
> To update a placement group, your user grants need to include read_write permission to all of the Linodes in the group. Talk to your local account administrator about grant management for your user.

Learn more...

Learn more...

REPLACE linode.placement.placement_groups
SET 
data__label = '{{ label }}'
WHERE 

RETURNING
id,
is_compliant,
label,
members,
placement_group_policy,
placement_group_type,
region;

DELETE examples

delete_placement_group

Deletes a placement group you have permission to read_write.

- Deleting a placement group can't be undone.

- All Linodes need to be removed before you can delete a placement group.

- If your placement group is non-compliant, you can't delete it. You need to wait for our help to bring it compliant.

<<LB>>

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

Learn more...

Learn more...

DELETE FROM linode.placement.placement_groups;

Lifecycle Methods

post_group_add_linode

Add a Linode to your placement group. Check out our example API workflow to create a placement group and add Linodes.

> 📘
>
> To run this operation, your user needs the add_linodes grant and read-write permission to the Linodes you want to add to the group. Talk to your local account administrator about grant and permissions management.

Learn more...

Learn more...

EXEC linode.placement.placement_groups.post_group_add_linode 
@@json=
'{
"linodes": "{{ linodes }}"
}';

post_group_unassign

Remove a Linode from your placement group.

> 📘
>
> To run this operation, your user needs the add_linodes grant and read-write permission to the Linodes you want to remove from the group. Talk to your local account administrator about grant and permissions management.

Learn more...

Learn more...

EXEC linode.placement.placement_groups.post_group_unassign 
@@json=
'{
"linodes": "{{ linodes }}"
}';