Managing placement groups

With placement groups for IBM Cloud® Virtual Private Cloud, you can create policies for managing high availability workloads. You can specify a choice of placement policies for a group of provisioned instances. You can use these policies to influence the physical placement of select VPC virtual servers to meet certain workload demands.

After the placement group is created, you can assign a selected virtual server instance or a group of virtual server instances to the placement group. When you provision these instances, the instance is then placed on a computer host in the designated zone for the instance based on the placement group strategy. You can use the same placement group for instances across multiple VPCs.

Placement groups can be managed with the UI, CLI, API, or Terraform. You can create extra placement groups, delete resources, and display the details of the placement groups, which are helpful when you assign placement groups to instances. Additionally, all existing placement groups can be listed and renamed if needed.

Managing the placement group in the UI

You can manage a placement group in your IBM Cloud VPC by using the IBM Cloud console.

To complete management tasks on your placement groups, complete the following steps.

In the IBM Cloud console, go to **Navigation Menu icon > Infrastructure > Compute > Placement Groups.
On the Placement groups for VPC page, click the Actions icon for the placement that you want to manage. You can select from the following actions:

Actions available for placement groups
Action	Description
Create	Create a placement group
Delete	If you no longer need the placement group, you can delete it to permanently remove it from your account. Before you can delete the placement group, you must first delete any virtual server instances that are assigned to the placement group.
Rename	Update the placement group name with a new name.

The VPC must exist before you create a placement group. If the VPC is not created first, you receive an error when you create the placement group and the placement group is not created.

Creating the placement group in the UI

You can create a placement group in your IBM Cloud VPC by using the IBM Cloud console. A placement group must be created first before an instance can use it. After a placement group is created, an instance can be attached to it during provisioning.

Use the following steps to create a placement group:

In the IBM Cloud console, go to **Navigation Menu icon > Infrastructure > Compute > Placement Groups.
Click Create and enter the information in Table 1 on the New placement for VPC page.

Fields required to create a placement group
Field	Value
Placement group name	A unique resource name within the region is required for your placement group. If you don't specify a name, a name is generated and assigned to your placement group.
Resource group	Select the resource group that contains the account resources and users that you want to be able to access the placement group. For more information about resource groups, see Managing resource groups.
Region	The region of the placement group.
User tags	Keywords that are used for profile management.
Placement strategy	Host spread - All provisioned instances are placed on separate hosts that might be in the same rack. Power spread - All provisioned instances are placed on different racks with separate power and network supplies. Each rack also contains dual power supplies from different sources.

Creating a placement group from the CLI

A placement group must be created first before an instance can use it. After a placement group is created, an instance can be attached to it during provisioning.

Before you begin

Make sure that you download, install, and initialize the following CLI plug-ins. For more information, see CLI prerequisites.
- IBM Cloud CLI
- The vpc-infrastructure plug-in
Create an IBM Cloud VPC.

Gathering information to create a placement group in the CLI

Ready to create a placement group? Before you can run the ibmcloud is placement-group-create command, you need to know the following information.

Gather the following required information:

Information required to create a placement group using the CLI
Field	Value
Placement group details	Options
Strategy	The placement group strategy. Either `host_spread` or `power_spread`
Name	The placement group name
Resource group ID	The ID of the resource group
Resource group name	The name of the resource group

Creating the placement group from the CLI

You can create a placement group in your IBM Cloud VPC by using the command-line interface (CLI).

To create a placement group by using the CLI, use the ibmcloud is placement-group-create command. Specify the placement group strategy for the placement group, the name of the placement group, the resource group ID, and the name of the resource group.

The following example creates a placement group with a host spread strategy, named MyPlacementGroup, with resource group ID RESOURCE_GROUP_ID, and a resource group name of RESOURCE_GROUP_NAME.

ibmcloud is placement-group-create --strategy host_spread --name MyPlacementGroup --resource-group-id RESOURCE_GROUP_ID --resource-group-name RESOURCE_GROUP_NAME

Creating a placement group with the API

You can create a placement group in your IBM Cloud VPC by using the API.

A placement group must be created first before an instance can use it. After a placement group is created, an instance can be attached to it during provisioning.

The following example creates a placement group that uses the host spread placement group strategy.

curl -X POST "$vpc_api_endpoint/v1/placement_groups?version=2021-04-20&generation=2" -H "Authorization: $iam_token" -d '{
      "name": "my-placement-group"
      "strategy": "host_spread"
    }'

For more information about the host_spread and power_spread strategy variables, see Create a placement group in the Virtual Private Cloud API documentation.

Creating the placement group with Terraform

You can create a placement group in your IBM Cloud VPC by using Terraform.

A placement group must be created first before an instance can use it. After a placement group is created, an instance can be attached to it during provisioning.

Before you begin

Make sure that you set up Terraform for VPC.

The following example creates a placement group with a host spread strategy that is named my-placement-group, and a resource group that is named data.ibm_resource_group.default.id.

resource "ibm_is_placement_group" "is_placement_group" {
  strategy = "host_spread"
  name = "my-placement-group"
  resource_group = data.ibm_resource_group.default.id
}

For more information about the host_spread and power_spread strategy variables, see Create a placement group in the Virtual Private Cloud API documentation.

Changing the placement group name in the UI

You can update the name of a placement group in your IBM Cloud VPC by using the IBM Cloud console.

To rename a placement group:

In the IBM Cloud console, go to **Navigation Menu icon > Infrastructure > Compute > Placement Groups.
Select the placement group and click Rename.
Change the placement group name.

Changing the placement group name from the CLI

You can update the name of a placement group in your IBM Cloud VPC by using the command-line interface (CLI).

To update the placement group name by using the CLI, use the ibmcloud is placement-group-update command. Specify the placement group ID and the new name of the placement group.

The following example updates the placement group with the ID 72251a2e-d6c5-42b4-97b0-b5f8e8d1f479 to the name of NEW_NAME.

ibmcloud is placement-group-update 72251a2e-d6c5-42b4-97b0-b5f8e8d1f479 --name NEW_NAME

Changing the placement group name with the API

You can update the name of a placement group in your IBM Cloud VPC by using the API. The following example updates the placement group name with the new name my-updated=placement-group.

curl -X PATCH "$vpc_api_endpoint/v1/placement_groups/$id?version=2021-05-04&generation=2" -H "Authorization: $iam_token" -d '{
      "name": "my-updated-placement-group",
    }'

Changing the placement group name with Terraform

You can update the name of a placement group in your IBM Cloud VPC by using Terraform.

The following example updates the placement group with the ID is_placement_group to the name of my-placement-group-modified.

resource "ibm_is_placement_group" "is_placement_group" {
  strategy = "host_spread"
  name = "my-placement-group-modified"
  resource_group = data.ibm_resource_group.default.id
}

Deleting a placement group with the UI

You can delete a placement group in your IBM Cloud VPC by using the IBM Cloud console. A placement group can't be deleted if instances are attached to it. All instances must be removed first. For more information about deleting a virtual private cloud instance and its associated resources, see Deleting a VPC.

Use the following steps to delete a placement group:

In the IBM Cloud console, go to **Navigation Menu icon > Infrastructure > Compute > Placement Groups.
Select the placement group and click Delete.
A confirmation message is displayed. Click Delete.

Deleting a placement group with the CLI

You can delete a placement group in your IBM Cloud VPC by using the command-line interface (CLI). A placement group can't be deleted if instances are attached to it. All instances must be removed first. For more information about deleting a virtual private cloud instance and its associated resources, see Deleting a VPC.

To delete placement group by using the CLI, use the ibmcloud is placement-group-delete command. Specify the placement group ID.

The following example deletes a placement group named PLACEMENT_GROUP.

ibmcloud is placement-group-delete PLACEMENT_GROUP --output JSON

Deleting a placement group with the API

A placement group can't be deleted if instances are attached to it. All instances must be removed first. For more information about deleting a virtual private cloud instance and its associated resources, see Deleting a VPC.

The following example deletes the placement group.

curl -X DELETE "$vpc_api_endpoint/v1/placement_groups/$id?version=2021-04-20&generation=2" -H "Authorization: $iam_token"

Deleting a placement group with Terraform

You can delete a placement group in your IBM Cloud VPC by using Terraform. A placement group can't be deleted if instances are attached to it. All instances must be removed first. For more information about deleting a virtual private cloud instance and its associated resources, see Deleting a VPC.

The following example deletes a placement group named PLACEMENT_GROUP.

terraform destroy -target=ibm_is_placement_group.is_placement_group

Listing all placement groups with the UI

You can generate a list of placement groups for a region.

To display a list of all existing placement groups:

In the IBM Cloud console, go to **Navigation Menu icon > Infrastructure > Compute > Placement Groups.
All existing placement groups are displayed.

Listing all placement groups with the CLI

You can generate a list of placement groups for a region. You can list all the existing placement groups in your IBM Cloud VPC by using the command-line interface (CLI).

To list all the existing placement groups by using the CLI, use the ibmcloud is placement-groups command. Specify the name and ID of the resource group that you are listing placement groups.

The following example lists all the existing placement groups for the resource group ID RESOURCE_GROUP_ID and name RESOURCE_GROUP.

ibmcloud is placement-groups --resource-group-id RESOURCE_GROUP_ID --resource-group-name RESOURCE_GROUP_NAME --all-resource-groups --output JSON

Listing all placement groups with the API

You can generate a list of placement groups for a region. The following example generates a list of all placement groups.

curl -X GET "$vpc_api_endpoint/v1/placement_groups?version=2021-04-20&generation=2" -H "Authorization: $iam_token"

Listing all placement groups with Terraform

You can generate a list of placement groups for a region. You can list all the existing placement groups in your IBM Cloud VPC by using Terraform.

The following example lists all the existing placement groups.

data "ibm_is_placement_groups" "is_placement_groups" {
}

Viewing placement group details with the UI

You can view details about a placement group, such as the placement group name, assigned resource group, placement group ID, location, date that the placement group was created, and the specified placement group strategy.

To view details about a placement group, complete the following steps.

In the IBM Cloud console, go to **Navigation Menu icon > Infrastructure > Compute > Placement Groups.
Click the name of the placement group about which you want to view details.

Viewing placement group details with the CLI

You can retrieve the details of a placement group in your IBM Cloud VPC by using the command-line interface (CLI).

To retrieve the details of a placement group by using the CLI, use the ibmcloud is placement-group command. Specify the placement group ID.

The following example retrieves the details for a placement group named PLACEMENT_GROUP.

ibmcloud is placement-group PLACEMENT_GROUP --output JSON

Viewing placement group details with the API

The following example retrieves a single placement group that is specified by the identifier in the URL.

curl -X GET "$vpc_api_endpoint/v1/placement_groups/$id?version=2021-04-20&generation=2" -H "Authorization: $iam_token"

Viewing placement group details with Terraform

You can retrieve the details of a placement group in your IBM Cloud VPC by using Terraform.

The following example retrieves details for a single placement group with an ID of ibm_is_placement_group.is_placement_group.name.

data "ibm_is_placement_group" "d_is_placement_group" {
  name = ibm_is_placement_group.is_placement_group.name
}

Using placement groups with a reservation

Keep the following information in mind when you use a placement group with a reservation. For more information about reservations, see About Reservations for VPC.

Support for an instance with both a placement group and reservation target isn't supported yet.

Placement groups and reservations are mutually exclusive. Meaning, that an instance that is a member of a placement group can't be created or updated to also target a reservation. Such a POST or PATCH API request results in an error.