Describe Subnets operation
The Describe Subnets operation enables you to retrieve information about your subnets.
You can filter the results to return information only about those subnets that match the criteria that you specify. For example, you could get information only about those subnets whose state is available. Also, you can specify multiple values for the filter. For example, the subnet is in a particular virtual private cloud (VPC), and the state of the subnet is available. However, at least one of the specified values must match a subnet to obtain results.
The result includes information for a particular subnet only if it matches all the specified filters. If there is no match, no special message is returned; the response is empty.
You can use wildcard characters with the filters:
- Use the asterisk (*) to match any number of characters.
- Use the question mark (?) to match a single character.
To escape a special character or metacharacter that has a special meaning in searches, precede the special character with a backslash (\ ).
The following table shows the available filters.
Filter Name | Description |
---|---|
availability-zone | Specifies the Availability Zone in which the subnet resides |
available-ip-address-count | Specifies the number of IP addresses that are available in the subnet |
cidr | Specifies the Classless Inter-Domain Routing (CIDR) block of the subnet |
state | Specifies the state of the subnet |
subnet-id | Specifies the ID of the subnet |
tag-key | Species the key assigned to a resource |
tag-value | Specifies the value of the tag assigned to the resource |
tag:key | Filters the results based on a specific tag-value combination |
vpc-id | Specifies the ID of the VPC that the subnet is in |
The following figure shows a sample <items> XML element for the Describe Subnets operation.
Sample <items> XML element for the Describe Subnets operation
<item>
<parameters>
<subnet-set>
<!--Zero or more repetition-->
<item>
<subnet-id></subnet-id>
</item>
</subnet-set>
<!--Optional:-->
<filter-set>
<!--Zero or more repetition-->
<item>
<name></name>
<value-set>
<!--Zero or more repetition-->
<item>
<value></value>
</item>
</value-set>
</item>
</filter-set>
</parameters>
</item>
</items>
The following table describes the elements for this adapter request.
Adapter request elements for the Describe Subnets operation
Element | Definition | Required |
---|---|---|
<wsdl-location> | Specifies the target Web Service Description Language (WSDL) URL for Amazon EC2 | Conditional:
|
<endpoint-address> | Specifies the web service endpoint for the adapter to use while performing operations on Amazon EC2 instances across different regions | No |
<signature-properties> | Specifies the mode for signing the adapter request | Conditional:
|
<operation-name> | Contains the name of the operation: describe-subnets | Yes |
<parameters> | Contains the elements required to execute the operation | Yes |
<subnet-set> | Contains the list of subnets | No |
<item> | Contains information about an individual subnet | No |
<subnet-id> | Specifies the ID of the subnet whose information you want to retrieve | No |
<filter-set> | Specifies the details of the filter with the filterName and filterValue that are used to retrieve specific information about the subnet | No |
The following figure shows a sample adapter request for the Describe Subnets operation using vpc-id as a filter.
Sample adapter request for the Describe Subnets operation using vpc-id as a filter
<wsdl-location>http://ec2.amazonaws.com/doc/2011-02-28/</wsdl-location>
<endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address>
<signature-properties mode = "key-files">
<private-key-file>C:\Security\
pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file>
<certificate-file>C:\Security\
cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file>
</signature-properties>
<operation-name>describe-subnets</operation-name>
<parameters>
<subnet-set>
<!--Zero or more repetition-->
<item>
<subnet-id>subnet-ab7b41c2</subnet-id>
</item>
</subnet-set>
<!--Optional:-->
<filter-set>
<!--Zero or more repetition-->
<item>
<name>vpc-id</name>
<value-set>
<!--Zero or more repetition-->
<item>
<value>vpc-f87b4191</value>
</item>
</value-set>
</item>
</filter-set>
</parameters>
</amazon-ec2-request>
The following figure shows the response for the sample Describe Subnets operation using vpc-idas a filter.
Sample adapter response for the Describe Subnets operation using vpc-id as a filter
<metadata>
<status>success</status>
</metadata>
<DescribeSubnetsResponse>
<requestId>edfd87f1-ca5e-4d5b-bd25-039cc1c36d45</requestId>
<subnetSet>
<item>
<subnetId>subnet-ab7b41c2</subnetId>
<state>available</state>
<vpcId>vpc-f87b4191</vpcId>
<cidrBlock>10.0.0.0/24</cidrBlock>
<availableIpAddressCount>251</availableIpAddressCount>
<availabilityZone>us-east-1a</availabilityZone>
</item>
</subnetSet>
</DescribeSubnetsResponse>
</amazon-ec2-response>
The following figure shows a sample adapter request for the Describe Subnets operation using cidr as a filter.
Sample adapter request for the Describe Subnets operation using cidr as a filter
<wsdl-location>http://ec2.amazonaws.com/doc/2011-02-28/</wsdl-location>
<endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address>
<signature-properties mode = "key-files">
<private-key-file>C:\Security\
pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file>
<certificate-file>C:\Security\
cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file>
</signature-properties>
<operation-name>describe-subnets</operation-name>
<parameters>
<subnet-set/>
<filter-set>
<item>
<name>cidr</name>
<value-set>
<item>
<value>10.0.0.0/24</value>
</item>
<item>
<value>10.0.0.0/22</value>
</item>
</value-set>
</item>
</filter-set>
</parameters>
</amazon-ec2-request>
The following figure shows the response for the sample Describe VPCs operation using cidr as a filter.
Sample adapter response for the Describe Subnets operation using cidr as a filter
<metadata>
<status>success</status>
</metadata>
<DescribeSubnetsResponse>
<requestId>0b42e898-4e65-4468-a9fa-d5cab83de314</requestId>
<subnetSet>
<item>
<subnetId>subnet-ab7b41c2</subnetId>
<state>available</state>
<vpcId>vpc-f87b4191</vpcId>
<cidrBlock>10.0.0.0/24</cidrBlock>
<availableIpAddressCount>251</availableIpAddressCount>
<availabilityZone>us-east-1a</availabilityZone>
</item>
<item>
<subnetId>subnet-097f4560</subnetId>
<state>available</state>
<vpcId>vpc-317f4558</vpcId>
<cidrBlock>10.0.0.0/22</cidrBlock>
<availableIpAddressCount>1019</availableIpAddressCount>
<availabilityZone>us-east-1c</availabilityZone>
</item>
</subnetSet>
</DescribeSubnetsResponse>
</amazon-ec2-response>
The following figure shows a sample adapter request for the Describe VPCs operation using cidr, available-ip-address-count, state, and availability-zone as filters.
Sample adapter request for the Describe Subnets operation using cidr, available-ip-address-count, state, and availability-zone as filters
<wsdl-location>http://ec2.amazonaws.com/doc/2011-02-28/</wsdl-location>
<endpoint-address>http://us-east-1.ec2.amazonaws.com/</endpoint-address>
<signature-properties mode = "key-files">
<private-key-file>C:\Security\
pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</private-key-file>
<certificate-file>C:\Security\
cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM</certificate-file>
</signature-properties>
<operation-name>describe-vpcs</operation-name>
<parameters>
<subnet-set/>
<filter-set>
<item>
<name>cidr</name>
<value-set>
<item>
<value>10.0.0.0/24</value>
</item>
</value-set>
</item>
<item>
<name>available-ip-address-count</name>
<value-set>
<item>
<value>251</value>
</item>
</value-set>
</item>
<item>
<name>state</name>
<value-set>
<item>
<value>available</value>
</item>
</value-set>
</item>
<item>
<name>availability-zone</name>
<value-set>
<item>
<value>us-east-1a</value>
</item>
</value-set>
</item>
</filter-set>
</parameters>
</amazon-ec2-request>
The following figure shows the response for the sample Describe VPCs operation using cidr, available-ip-address-count, state, and availability-zone as filters.
Sample adapter response for the Describe Subnets operation using cidr, available-ip-address-count, state, and availability-zone as filters
<metadata>
<status>success</status>
</metadata>
<DescribeSubnetsResponse>
<requestId>f1b852ca-8371-4fc6-bcfe-dfc310b77f7d</requestId>
<subnetSet>
<item>
<subnetId>subnet-ab7b41c2</subnetId>
<state>available</state>
<vpcId>vpc-f87b4191</vpcId>
<cidrBlock>10.0.0.0/24</cidrBlock>
<availableIpAddressCount>251</availableIpAddressCount>
<availabilityZone>us-east-1a</availabilityZone>
</item>
</subnetSet>
</DescribeSubnetsResponse>
</amazon-ec2-response>