Work with placement groups - Amazon Elastic Compute Cloud
Create a placement groupView placement group informationTag a placement groupLaunch instances in a placement groupDescribe instances in a placement groupChange the placement group for an instanceRemove an instance from a placement groupDelete a placement group
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Work with placement groups

Create a placement group

You can create a placement group using one of the following methods.

Console
To create a placement group using the console

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Placement Groups.

  3. Choose Create placement group.

  4. Specify a name for the group.

  5. Choose the placement strategy for the group.

    • If you choose Spread, choose the spread level.

      • Rack - no restrictions

      • Host - only for Outposts

    • If you choose Partition, choose the number of partitions within the group.

  6. To tag the placement group, choose Add tag, and then enter a key and value. Choose Add tag for each tag that you want to add.

  7. Choose Create group.

Amazon CLI
To create a placement group using the Amazon CLI

Use the create-placement-group command. The following example creates a placement group named my-cluster that uses the cluster placement strategy, and it applies a tag with a key of purpose and a value of production.

aws ec2 create-placement-group \
    --group-name my-cluster \
    --strategy cluster \
    --tag-specifications 'ResourceType=placement-group,Tags={Key=purpose,Value=production}'
To create a partition placement group using the Amazon CLI

Use the create-placement-group command. Specify the --strategy parameter with the value partition, and specify the --partition-count parameter with the desired number of partitions. In this example, the partition placement group is named HDFS-Group-A and is created with five partitions.

aws ec2 create-placement-group \
    --group-name HDFS-Group-A \
    --strategy partition \
    --partition-count 5
PowerShell
To create a placement group using the Amazon Tools for Windows PowerShell

Use the New-EC2PlacementGroup command.

View placement group information

You can view all your placement groups and the information about them using one of the following methods.

Console
To view information about one or more placement groups

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, under Network & Security, choose Placement Groups.

  3. In the Placement groups table, for each placement group, you can view the following information:

    • Group name – The name that you gave to the placement group.

    • Group Id – The ID of the placement group.

    • Strategy – The placement strategy for the placement group.

    • State – The state of the placement group.

    • Partition – The number of partitions. Valid only if the strategy is partition.

    • Group ARN – The Amazon Resource Name (ARN) of the placement group.

Amazon CLI
To describe all your placement groups

Use the describe-placement-groups Amazon CLI command.

aws ec2 describe-placement-groups

Example response

{
    "PlacementGroups": [
        {
            "GroupName": "my-cluster-pg",
            "State": "available",
            "Strategy": "cluster",
            "GroupId": "pg-0123456789example",
            "GroupArn": "arn:aws:ec2:eu-west-1:111111111111:placement-group/my-cluster-pg"
        },
            ...
     ]
}
To describe a specified placement group

Use the describe-placement-groups Amazon CLI command. You can specify either the --group-id or the --group-name parameter.

Specify placement group ID:

aws ec2 describe-placement-groups --group-id pg-0123456789example

Specify placement group name:

aws ec2 describe-placement-groups --group-name my-cluster-pg

Example response

{
    "PlacementGroups": [
        {
            "GroupName": "my-cluster-pg",
            "State": "available",
            "Strategy": "cluster",
            "GroupId": "pg-0123456789example",
            "GroupArn": "arn:aws:ec2:eu-west-1:111111111111:placement-group/my-cluster-pg"
        }
    ]
}

Tag a placement group

To help categorize and manage your existing placement groups, you can tag them with custom metadata. For more information about how tags work, see Tag your Amazon EC2 resources.

When you tag a placement group, the instances that are launched into the placement group are not automatically tagged. You need to explicitly tag the instances that are launched into the placement group. For more information, see Add a tag when you launch an instance.

You can view, add, and delete tags using one of the following methods.

Console
To view, add, or delete a tag for an existing placement group

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Placement Groups.

  3. Select a placement group, and then choose Actions, Manage tags.

  4. The Manage tags screen displays any tags that are assigned to the placement group.

    • To add a tag, choose Add tag, and then enter the tag key and value. You can add up to 50 tags per placement group. For more information, see Tag restrictions.

    • To delete a tag, choose Remove next to the tag that you want to delete.

  5. Choose Save.

Amazon CLI
To view placement group tags

Use the describe-tags command to view the tags for the specified resource. In the following example, you describe the tags for all of your placement groups.

aws ec2 describe-tags \
    --filters Name=resource-type,Values=placement-group			
{
    "Tags": [
        {
            "Key": "Environment",
            "ResourceId": "pg-0123456789EXAMPLE",
            "ResourceType": "placement-group",
            "Value": "Production"
        },
        {
            "Key": "Environment",
            "ResourceId": "pg-9876543210EXAMPLE",
            "ResourceType": "placement-group",
            "Value": "Production"
        }
    ]
}

You can also use the describe-tags command to view the tags for a placement group by specifying its ID. In the following example, you describe the tags for pg-0123456789EXAMPLE.

aws ec2 describe-tags \

    --filters Name=resource-id,Values=pg-0123456789EXAMPLE
{
    "Tags": [
        {
            "Key": "Environment",
            "ResourceId": "pg-0123456789EXAMPLE",
            "ResourceType": "placement-group",
            "Value": "Production"
        }
    ]
}

You can also view the tags of a placement group by describing the placement group.

Use the describe-placement-groups command to view the configuration of the specified placement group, which includes any tags that were specified for the placement group.

aws ec2 describe-placement-groups \
    --group-name my-cluster
{
    "PlacementGroups": [
        {
            "GroupName": "my-cluster",
            "State": "available",
            "Strategy": "cluster",
            "GroupId": "pg-0123456789EXAMPLE",
            "Tags": [
                {
                    "Key": "Environment",
                    "Value": "Production"
                }
            ]
        }
    ]
}
To tag an existing placement group using the Amazon CLI

You can use the create-tags command to tag existing resources. In the following example, the existing placement group is tagged with Key=Cost-Center and Value=CC-123.

aws ec2 create-tags \
    --resources pg-0123456789EXAMPLE \
    --tags Key=Cost-Center,Value=CC-123
To delete a tag from a placement group using the Amazon CLI

You can use the delete-tags command to delete tags from existing resources. For examples, see Examples in the Amazon CLI Command Reference.

PowerShell
To view placement group tags

Use the Get-EC2Tag command.

To describe the tags for a specific placement group

Use the Get-EC2PlacementGroup command.

To tag an existing placement group

Use the New-EC2Tag command.

To delete a tag from a placement group

Use the Remove-EC2Tag command.

Launch instances in a placement group

You can launch an instance into a placement group if the placement group rules and limitations are met using one of the following methods.

Console
To launch instances into a placement group

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. From the EC2 console dashboard, in the Launch instance box, choose Launch instance. Complete the form as directed, taking care to do the following:

    • Under Instance type, select an instance type that can be launched into a placement group.

    • In the Summary box, under Number of instances, enter the total number of instances that you need in this placement group, because you might not be able to add instances to the placement group later.

    • Under Advanced details, for Placement group name, you can choose to add the instances to a new or existing placement group. If you choose a placement group with a partition strategy, for Target partition, choose the partition in which to launch the instances.

Amazon CLI
To launch instances into a placement group

Use the run-instances command and specify the placement group name using the --placement "GroupName = my-cluster" parameter. In this example, the placement group is named my-cluster.

aws ec2 run-instances --placement "GroupName = my-cluster"
To launch instances into a specific partition of a partition placement group using the Amazon CLI

Use the run-instances command and specify the placement group name and partition using the --placement "GroupName = HDFS-Group-A, PartitionNumber = 3" parameter. In this example, the placement group is named HDFS-Group-A and the partition number is 3.

aws ec2 run-instances --placement "GroupName = HDFS-Group-A, PartitionNumber = 3"
PowerShell
To launch instances into a placement group using Amazon Tools for Windows PowerShell

Use the New-EC2Instance command and specify the placement group name using the -Placement_GroupName parameter.

Describe instances in a placement group

You can view the placement information of your instances using one of the following methods. You can also filter partition placement groups by the partition number using the Amazon CLI.

Console
To view the placement group and partition number of an instance

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance.

  4. On the Details tab, under Host and placement group, find Placement group. If the instance is not in a placement group, the field is empty. Otherwise, it contains the name of the placement group name. If the placement group is a partition placement group, Partition number contains the partition number for the instance.

Amazon CLI
To view the partition number for an instance in a partition placement group

Use the describe-instances command and specify the --instance-id parameter.

aws ec2 describe-instances --instance-id i-0123a456700123456

The response contains the placement information, which includes the placement group name and the partition number for the instance.

"Placement": {
     "AvailabilityZone": "us-east-1c",
     "GroupName": "HDFS-Group-A",
     "PartitionNumber": 3,
     "Tenancy": "default"
}
To filter instances for a specific partition placement group and partition number

Use the describe-instances command and specify the --filters parameter with the placement-group-name and placement-partition-number filters. In this example, the placement group is named HDFS-Group-A and the partition number is 7.

aws ec2 describe-instances --filters "Name = placement-group-name, Values = HDFS-Group-A" "Name = placement-partition-number, Values = 7"

The response lists all the instances that are in the specified partition within the specified placement group. The following is example output showing only the instance ID, instance type, and placement information for the returned instances.

"Instances": [
                {   
                    "InstanceId": "i-0a1bc23d4567e8f90",
                    "InstanceType": "r4.large",
                    },
                  
                    "Placement": {
                        "AvailabilityZone": "us-east-1c",
                        "GroupName": "HDFS-Group-A",
                        "PartitionNumber": 7,
                        "Tenancy": "default"
                    }

                {   
                    "InstanceId": "i-0a9b876cd5d4ef321",
                    "InstanceType": "r4.large",
                    },

                    "Placement": {
                        "AvailabilityZone": "us-east-1c",
                        "GroupName": "HDFS-Group-A",
                        "PartitionNumber": 7,
                        "Tenancy": "default"
                    }
              ],

Change the placement group for an instance

You can change the placement group for an instance as follows:

  • Move an existing instance to a placement group

  • Move an instance from one placement group to another

Before you can move the instance, the instance must be in the stopped state.

Console
To move an instance to a placement group

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance, and then choose Instance state, Stop instance.

  4. With the instance selected, choose Actions, Instance settings, Modify instance placement.

  5. For Placement group, choose the placement group to move the instance to.

  6. Choose Save.

Amazon CLI
To move an instance to a placement group

  1. Stop the instance using the stop-instances command.

  2. Use the modify-instance-placement command and specify the name of the placement group to move the instance to.

    aws ec2 modify-instance-placement \
    --instance-id i-0123a456700123456 \
    --group-name MySpreadGroup

  3. Start the instance using the start-instances command.

PowerShell
To move an instance to a placement group using the Amazon Tools for Windows PowerShell

  1. Stop the instance using the Stop-EC2Instance command.

  2. Use the Edit-EC2InstancePlacement command and specify the name of the placement group to which to move the instance.

  3. Start the instance using the Start-EC2Instance command.

Remove an instance from a placement group

You can remove an instance from a placement group using one of the following methods.

Before you can remove an instance from a placement group, the instance must be in the stopped state.

Console
To remove an instance from a placement group

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance, and then choose Instance state, Stop instance.

  4. With the instance selected, choose Actions, Instance settings, Modify instance placement.

  5. For Placement group, choose None.

  6. Choose Save.

Amazon CLI
To remove an instance from a placement group

  1. Stop the instance using the stop-instances command.

  2. Use the modify-instance-placement command and specify an empty string for the placement group name.

    aws ec2 modify-instance-placement \
    --instance-id i-0123a456700123456 \
    --group-name ""

  3. Start the instance using the start-instances command.

PowerShell
To remove an instance from a placement group using the Amazon Tools for Windows PowerShell

  1. Stop the instance using the Stop-EC2Instance command.

  2. Use the Edit-EC2InstancePlacement command and specify an empty string for the placement group name.

  3. Start the instance using the Start-EC2Instance command.

Delete a placement group

If you need to replace a placement group or no longer need one, you can delete it. You can delete a placement group using one of the following methods.

Prerequisite

Before you can delete a placement group, it must contain no instances. You can terminate all instances that you launched in the placement group, move instances to another placement group, or remove instances from the placement group.

Console
To delete a placement group

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Placement Groups.

  3. Select the placement group and choose Actions, Delete.

  4. When prompted for confirmation, enter Delete and then choose Delete.

Amazon CLI
To delete a placement group

Use the delete-placement-group command and specify the placement group name to delete the placement group. In this example, the placement group name is my-cluster.

aws ec2 delete-placement-group --group-name my-cluster
PowerShell
To delete a placement group using the Amazon Tools for Windows PowerShell

Use the Remove-EC2PlacementGroup command to delete the placement group.