CmdID

CmdID / aws / aws ec2

aws ec2 describe-instances

Describes the specified instances or all instances. AWS CLI reference

13 examples 6 options Its page in the AWS CLI reference

Opens CmdID with your command. It is read in your browser and sent nowhere.

Examples

from aws-cli, each command read by CmdID

Example 1: To describe an instance

The following describe-instances example describes the specified instance.

aws ec2 describe-instances --instance-ids i-1234567890abcdef0Identify
--instance-idsThe instance IDs.
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-1234567890abcdef0",
                    "InstanceType": "t3.nano",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2a",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-0-157.us-west-2.compute.internal",
                    "PrivateIpAddress": "10-0-0-157",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-34-253-223-13.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "34.253.223.13",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 124 more lines

Example 2: To filter for instances with the specified type

The following describe-instances example uses filters to scope the results to instances of the specified type.

aws ec2 describe-instances --filters Name=instance-type,Values=m5.largeIdentify
--filtersThe filters.
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-0abcdef1234567890",
                    "InstanceType": "m5.large",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2a",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-0-158.us-west-2.compute.internal",
                    "PrivateIpAddress": "10.0.0.158",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-203-0-113-18.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "203.0.113.18",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 124 more lines

For more information, see List and filter using the CLI in the Amazon EC2 User Guide.

Example 3: To filter for instances with the specified type and Availability Zone

The following describe-instances example uses multiple filters to scope the results to instances with the specified type that are also in the specified Availability Zone.

aws ec2 describe-instances --filters Name=instance-type,Values=t2.micro,t3.micro Name=availability-zone,Values=us-west-2cIdentify
--filtersThe filters.
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-0598c7d356eba48d7",
                    "InstanceType": "t3.micro",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2c",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-2-45.us-west-2.compute.internal",
                    "PrivateIpAddress": "10.0.2.45",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-203-0-113-27.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "203.0.113.27",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 124 more lines

Example 4: To filter for instances with the specified type and Availability Zone using a JSON file

The following describe-instances example uses a JSON input file to perform the same filtering as the previous example. When filters get more complicated, they can be easier to specify in a JSON file.

aws ec2 describe-instances --filters file://filters.jsonIdentify
--filtersThe filters.

Contents of filters.json:

[
    {
        "Name": "instance-type",
        "Values": ["t2.micro", "t3.micro"]
    },
    {
        "Name": "availability-zone",
        "Values": ["us-west-2c"]
    }
]
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-0598c7d356eba48d7",
                    "InstanceType": "t3.micro",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2c",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-2-45.us-west-2.compute.internal",
                    "PrivateIpAddress": "10.0.2.45",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-203-0-113-27.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "203.0.113.27",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 124 more lines

Example 5: To filter for instances with the specified Owner tag

The following describe-instances example uses tag filters to scope the results to instances that have a tag with the specified tag key (Owner), regardless of the tag value.

aws ec2 describe-instances --filters "Name=tag-key,Values=Owner"Identify
--filtersThe filters.
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-1234567890abcdef0",
                    "InstanceType": "t3.nano",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2a",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-0-157.us-west-2.compute.internal",
                    "PrivateIpAddress": "10-0-0-157",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-34-253-223-13.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "34.253.223.13",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 128 more lines

Example 6: To filter for instances with the specified my-team tag value

The following describe-instances example uses tag filters to scope the results to instances that have a tag with the specified tag value (my-team), regardless of the tag key.

aws ec2 describe-instances --filters "Name=tag-value,Values=my-team"Identify
--filtersThe filters.
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-1234567890abcdef0",
                    "InstanceType": "t3.nano",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2a",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-0-157.us-west-2.compute.internal",
                    "PrivateIpAddress": "10-0-0-157",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-34-253-223-13.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "34.253.223.13",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 128 more lines

Example 7: To filter for instances with the specified Owner tag and my-team value

The following describe-instances example uses tag filters to scope the results to instances that have the specified tag (Owner=my-team).

aws ec2 describe-instances --filters "Name=tag:Owner,Values=my-team"Identify
--filtersThe filters.
Its output, shortened
{
    "Reservations": [
        {
            "Groups": [],
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "ami-0abcdef1234567890",
                    "InstanceId": "i-1234567890abcdef0",
                    "InstanceType": "t3.nano",
                    "KeyName": "my-key-pair",
                    "LaunchTime": "2022-11-15T10:48:59+00:00",
                    "Monitoring": {
                        "State": "disabled"
                    },
                    "Placement": {
                        "AvailabilityZone": "us-west-2a",
                        "GroupName": "",
                        "Tenancy": "default"
                    },
                    "PrivateDnsName": "ip-10-0-0-157.us-west-2.compute.internal",
                    "PrivateIpAddress": "10-0-0-157",
                    "ProductCodes": [],
                    "PublicDnsName": "ec2-34-253-223-13.us-west-2.compute.amazonaws.com",
                    "PublicIpAddress": "34.253.223.13",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "StateTransitionReason": "",
… 128 more lines

Example 8: To display only instance and subnet IDs for all instances

The following describe-instances examples use the --query parameter to display only the instance and subnet IDs for all instances, in JSON format.

For Linux and macOS, use the following command.

aws ec2 describe-instances --query 'Reservations[*].Instances[*].{Instance:InstanceId,Subnet:SubnetId}'Identify
--queryA JMESPath query to use in filtering the response data.

For Windows, use the following command.

aws ec2 describe-instances ^Identify
--query "Reservations[*].Instances[*].{Instance:InstanceId,Subnet:SubnetId}"
Its output
[
    {
        "Instance": "i-057750d42936e468a",
        "Subnet": "subnet-069beee9b12030077"
    },
    {
        "Instance": "i-001efd250faaa6ffa",
        "Subnet": "subnet-0b715c6b7db68927a"
    },
    {
        "Instance": "i-027552a73f021f3bd",
        "Subnet": "subnet-0250c25a1f4e15235"
    }
]

Example 9: To filter instances of the specified type and only display their instance IDs

The following describe-instances example uses filters to scope the results to instances of the specified type and the --query parameter to display only the instance IDs.

aws ec2 describe-instances --filters "Name=instance-type,Values=t2.micro" --query "Reservations[*].Instances[*].[InstanceId]" --output textIdentify
--filtersThe filters.
--queryA JMESPath query to use in filtering the response data.
--outputThe formatting style for command output.
Its output
i-031c0dc19de2fb70c
i-00d8bff789a736b75
i-0b715c6b7db68927a
i-0626d4edd54f1286d
i-00b8ae04f9f99908e
i-0fc71c25d2374130c

Example 10: To filter instances of the specified type and only display their instance IDs, Availability Zone, and the specified tag value

The following describe-instances examples display the instance ID, Availability Zone, and the value of the Name tag for instances that have a tag with the name tag-key, in table format.

For Linux and macOS, use the following command.

aws ec2 describe-instances --filters Name=tag-key,Values=Name --query 'Reservations[*].Instances[*].{Instance:InstanceId,AZ:Placement.AvailabilityZone,Name:Tags[?Key==`"Name"`]|[0].Value}' --output tableIdentify
--filtersThe filters.
--queryA JMESPath query to use in filtering the response data.
--outputThe formatting style for command output.

For Windows, use the following command.

aws ec2 describe-instances ^Identify
--filters Name=tag-key,Values=Name ^
--query "Reservations[*].Instances[*].{Instance:InstanceId,AZ:Placement.AvailabilityZone,Name:Tags[?Key=='Name']|[0].Value}" ^
--output table
Its output
-------------------------------------------------------------
|                     DescribeInstances                     |
+--------------+-----------------------+--------------------+
|      AZ      |       Instance        |        Name        |
+--------------+-----------------------+--------------------+
|  us-west-2b  |  i-057750d42936e468a  |  my-prod-server    |
|  us-west-2a  |  i-001efd250faaa6ffa  |  test-server-1     |
|  us-west-2a  |  i-027552a73f021f3bd  |  test-server-2     |
+--------------+-----------------------+--------------------+

Example 11: To describe instances in a partition placement group

The following describe-instances example describes the specified instance. The output includes the placement information for the instance, which contains the placement group name and the partition number for the instance.

aws ec2 describe-instances --instance-ids i-0123a4567abcd1234 --query "Reservations[*].Instances[*].Placement"Identify
--instance-idsThe instance IDs.
--queryA JMESPath query to use in filtering the response data.
Its output
[
    [
        {
            "AvailabilityZone": "us-west-2c",
            "GroupName": "HDFS-Group-A",
            "PartitionNumber": 3,
            "Tenancy": "default"
        }

    ]
]

For more information, see Describing instances in a placement group in the Amazon EC2 User Guide.

Example 12: To filter to instances with the specified placement group and partition number

The following describe-instances example filters the results to only those instances with the specified placement group and partition number.

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

The following example output shows only the relevant information.

Its output
{
    "Reservations": [
        {
            "Instances": [
                {
                    "InstanceId": "i-0123a4567abcd1234",
                    "InstanceType": "r4.large",
                    "Placement": {
                        "AvailabilityZone": "us-west-2c",
                        "GroupName": "HDFS-Group-A",
                        "PartitionNumber": 7,
                        "Tenancy": "default"
                    }
                },
                {
                    "InstanceId": "i-9876a5432abcd9876",
                    "InstanceType": "r4.large",
                    "Placement": {
                        "AvailabilityZone": "us-west-2c",
                        "GroupName": "HDFS-Group-A",
                        "PartitionNumber": 7,
                        "Tenancy": "default"
                    }
                }
            ]
        }
    ]
}

For more information, see Describing instances in a placement group in the Amazon EC2 User Guide.

Example 13: To filter to instances that are configured to allow access to tags from instance metadata

The following describe-instances example filters the results to only those instances that are configured to allow access to instance tags from instance metadata.

aws ec2 describe-instances --filters "Name=metadata-options.instance-metadata-tags,Values=enabled" --query "Reservations[*].Instances[*].InstanceId" --output textIdentify
--filtersThe filters.
--queryA JMESPath query to use in filtering the response data.
--outputThe formatting style for command output.
Its output
i-1234567890abcdefg
i-abcdefg1234567890
i-11111111aaaaaaaaa
i-aaaaaaaa111111111

For more information, see Work with instance tags in instance metadata in the Amazon EC2 User Guide.

Options

6 in the AWS CLI reference
--dry-runChecks whether you have the required permissions for the operation, without actually making the request, and provides an error response.
--filtersThe filters.
--include-managed-resourcesIndicates whether to include managed resources in the output.
--instance-idsThe instance IDs.
--max-resultsThe maximum number of items to return for this request.
--next-tokenThe token returned from a previous paginated request.