Amazon EC2 instance topology examples - Amazon Elastic Compute Cloud
Example 1 - No parameters or filtersExample 2 – instance-type filterExample 3 – zone-id filterExample 4 – Combined instance-type and zone-id filtersExample 5 – Placement group name parameterExample 6 – Instance IDs
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).

Amazon EC2 instance topology examples

You can use the describe-instance-topology CLI command to describe the instance topology for your EC2 instances.

When you use the describe-instance-topology command without parameters or filters, the response includes all your instances that match the supported instance types for this command in the specified Region. You can specify the Region by including the --region parameter, or by setting a default Region. For more information about setting a default Region, see Specify the Region for a resource.

You can include parameters to return instances that match specified instance IDs or placement group names. You can also include filters to return instances that match a specified instance type or instance family, or instances in a specified Availability Zone or Local Zone. You can include a single parameter or filter, or a combination of parameters and filters.

The output is paginated, with up to 20 instances per page by default. You can specify up to 100 instances per page using the --max-results parameter.

For more information, see describe-instance-topology in the Amazon CLI Command Reference.

Required permissions

The following permission is required to describe instance topology:

  • ec2:DescribeInstanceTopology

Example 1 - No parameters or filters

To describe the instance topology of all your instances

Use the describe-instance-topology CLI command without specifying any parameters or filters.

aws ec2 describe-instance-topology --region us-west-2

The response returns only the instances that match the supported instance types for this API. The instances can be in different Availability Zones, Local Zones (ZoneId), and placement groups (GroupName). If an instance is not in a placement group, the GroupName field does not appear in the output. In the following example output, only one instance is in a placement group.

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "my-ml-cpg",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        },
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "p4d.24xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        },
        {
            "InstanceId": "i-3333333333example",
            "InstanceType": "trn1.32xlarge",
            "NetworkNodes": [
                "nn-1212121212example",
                "nn-1211122211example",
                "nn-1311133311example"
            ],
            "ZoneId": "usw2-az4",
            "AvailabilityZone": "us-west-2d"            
        },
        {
            "InstanceId": "i-444444444example",
            "InstanceType": "trn1.2xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-5434334334example",
                "nn-1235301234example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"          
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 2 – instance-type filter

You can filter by a specified instance type (exact match) or filter by an instance family (using a wildcard). You can also combine a specified instance type filter and instance family filter.

Example 2a – Exact match filter for a specified instance type

To describe the instance topology of all your instances that match a specified instance type

Use the describe-instance-topology CLI command with the instance-type filter. In this example, the output is filtered for trn1n.32xlarge instances. The response will return only the instances that match the specified instance type. 

aws ec2 describe-instance-topology \
    --region us-west-2 \
    --filters Name=instance-type,Values=trn1n.32xlarge

Example output

{
    "Instances": [
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 2b – Wild card filter for an instance family

To describe the instance topology of all your instances that match an instance family

Use the describe-instance-topology CLI command with the instance-type filter. In this example, the output is filtered for trn1* instances. The response will return only the instances that match the specified instance family. 

aws ec2 describe-instance-topology \
    --region us-west-2 \
    --filters Name=instance-type,Values=trn1*

Example output

{
    "Instances": [
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        },
        {
            "InstanceId": "i-3333333333example",
            "InstanceType": "trn1.32xlarge",
            "NetworkNodes": [
                "nn-1212121212example",
                "nn-1211122211example",
                "nn-1311133311example"
            ],
            "ZoneId": "usw2-az4",
            "AvailabilityZone": "us-west-2d"            
        },
        {
            "InstanceId": "i-444444444example",
            "InstanceType": "trn1.2xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-5434334334example",
                "nn-1235301234example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"          
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 2c – Combined instance family and exact match filters

To describe the instance topology of all your instances that match an instance family or specified instance type

Use the describe-instance-topology CLI command with the instance-type filter. In this example, the output is filtered for pd4d* or trn1n.32xlarge instances. The response will return the instances that match any of the specified filters. 

aws ec2 describe-instance-topology \
    --region us-west-2 \
    --filters "Name=instance-type,Values=p4d*,trn1n.32xlarge"

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "ML-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        },
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-4343434343example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 3 – zone-id filter

You can use the zone-id filter to filter by an Availability Zone or Local Zone. You can also combine an Availability Zone filter and Local Zone filter.

Example 3a – Availability Zone filter

To describe the instance topology of all your instances that match a specified Availability Zone

Use the describe-instance-topology CLI command with the zone-id filter. In this example, the output is filtered using the Availability Zone ID use1-az1. The response will return only the instances that match the specified Availability Zone. 

aws ec2 describe-instance-topology \
    --region us-east-1 \
    --filters Name=zone-id,Values=use1-az1

Example output

{
    "Instances": [
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3214313214example"
            ],
            "ZoneId": "use1-az1",
            "AvailabilityZone": "us-east-1a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 3b – Local Zone filter

To describe the instance topology of all your instances that match a specified Local Zone

Use the describe-instance-topology CLI command with the zone-id filter. In this example, the output is filtered using the Local Zone ID use1-atl2-az1. The response will return only the instances that match the specified Local Zone. 

aws ec2 describe-instance-topology \
    --region us-east-1 \
    --filters Name=zone-id,Values=use1-atl2-az1

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "ML-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "use1-atl2-az1",
            "AvailabilityZone": "us-east-1-atl-2a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 3c – Combined Availability Zone and Local Zone filters

To describe the instance topology of all your instances that match a specified Availability Zone or Local Zone

Use the describe-instance-topology CLI command with the zone-id filter. In this example, the output is filtered using the Availability Zone ID use1-az1 and the Local Zone ID use1-atl2-az1. The response will return the instances that match any of the specified filters. 

aws ec2 describe-instance-topology \
    --region us-east-1 \
    --filters Name=zone-id,Values=use1-az1,use1-atl2-az1

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "ML-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "use1-atl2-az1",
            "AvailabilityZone": "us-east-1-atl-2a"
        },
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3214313214example"
            ],
            "ZoneId": "use1-az1",
            "AvailabilityZone": "us-east-1a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 4 – Combined instance-type and zone-id filters

You can combine all the filters in a single command.

To describe the instance topology of all your instances that match a specified instance type, instance family, Availability Zone, or Local Zone

Use the describe-instance-topology CLI command with the instance-type and zone-id filters. In this example, the output is filtered for the p4d* instance family, trn1n.32xlarge instance type, use1-az1 Availability Zone ID, and use1-atl2-az1 Local Zone ID. The response will return the instances that match p4d* or trn1n.32xlarge instances in the us-east-1a or us-east-1-atl-2a zones. 

aws ec2 describe-instance-topology \
    --region us-east-1 \
    --filters "Name=instance-type,Values=p4d*,trn1n.32xlarge" "Name=zone-id,Values=use1-az1,use1-atl2-az1"

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "ML-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "use1-atl2-az1",
            "AvailabilityZone": "us-east-1-atl-2a"
        },
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3214313214example"
            ],
            "ZoneId": "use1-az1",
            "AvailabilityZone": "us-east-1a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 5 – Placement group name parameter

To describe the instance topology of all your instances in a specified placement group

Use the describe-instance-topology CLI command with the group-names parameter. In the following example, the instances can be in the ML-group or HPC-group placement group. The response will return instances that are in either of the placement groups. 

aws ec2 describe-instance-topology \
    --region us-west-2 \
    --group-names ML-group HPC-group

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "ML-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        },
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "GroupName": "HPC-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3214313214example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}

Example 6 – Instance IDs

To describe the instance topology of specified instances

Use the describe-instance-topology CLI command with the --instance-ids parameter. The response will return the instances that match the specified instance IDs.

aws ec2 describe-instance-topology \
    --region us-west-2 \
    --instance-ids i-1111111111example i-2222222222example

Example output

{
    "Instances": [
        {
            "InstanceId": "i-1111111111example",
            "InstanceType": "p4d.24xlarge",
            "GroupName": "ML-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3333333333example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        },
        {
            "InstanceId": "i-2222222222example",
            "InstanceType": "trn1n.32xlarge",
            "GroupName": "HPC-group",
            "NetworkNodes": [
                "nn-1111111111example",
                "nn-2222222222example",
                "nn-3214313214example"
            ],
            "ZoneId": "usw2-az2",
            "AvailabilityZone": "us-west-2a"
        }
    ],
    "NextToken": "SomeEncryptedToken"
}