Subnet_Operations for the Amazon EC2 REST adapter

This topic illustrates the adapter requests and responses for Subnet operations.

Create Subnet operation

The Create Subnet operation enables you create a subnet in an existing virtual private cloud (VPC). You can create up to 20 subnets in a VPC. If you add more than one subnet to a VPC, they are set up in a star topology with a logical router in the middle. The smallest subnet (and VPC) that you can create uses a /28 netmask (16 IP addresses) and the largest uses a /16 netmask (65,536 IP addresses).

The following figure shows a sample <items> XML element for the Create Subnet operation. 

Sample <items> XML element for the Create Subnet operation

<items>
 <item>
   <parameters>
     <vpc-id></vpc-id>
       <cidr-block></cidr-block>
       <!--Optional:-->
       <availability-zone></availability-zone>
   </parameters>
 </item>
</items>

The following table describes the elements for this adapter request. 

Adapter request elements for the Create Subnet operation 

Element

Definition

Required

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation: create-subnet

Yes

<parameters>

Contains the elements required to execute the operation

Yes

<vpc-id>

Specifies the ID of the VPC where you want to create the subnet

Yes

<cidr-block>

Specifies the Classless Inter-Domain Routing (CIDR) block that you want the subnet to cover (for example, 10.0.0.0/24)

Yes

<availability-zone>

Specifies the Availability Zone in which the subnet should reside

No

The following figure shows a sample adapter request for the Create Subnet operation.

Sample adapter request for the Create Subnet operation

<amazon-ec2-rest-request>
   <operation-name>create-subnet</operation-name>    
   <access-key>AKIA***********8BT2Q</access-key>
   <secret-key>WQisk8Irh********************8AiJx3VQVd</secret-key>
   <region>us-east-1</region>
   <parameters>
       <vpc-id>vpc-ad9d70c8</vpc-id>
         <cidr-block>10.0.0.0/28</cidr-block>
         <!-Optional:->
         <availability-zone></availability-zone>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample Create Subnet operation.

Sample adapter response for the Create Subnet operation 

<amazon-ec2-rest-response>
   <metadata>
       <status>success</status>
   </metadata>
   <CreateSubnetResponse>
       <subnet>
           <subnetId>subnet-ff5776b9</subnetId>
           <state>pending</state>
           <vpcId>vpc-ad9d70c8</vpcId>
           <cidrBlock>10.0.0.0/28</cidrBlock>
           <availableIpAddressCount>11</availableIpAddressCount>
           <availabilityZone>us-east-1c</availabilityZone>
       </subnet>
   </CreateSubnetResponse>
</amazon-ec2-rest-response>

Back to top 

Delete Subnet operation

The Delete Subnet operation enables you delete a subnet from a virtual private cloud (VPC). You must terminate all running instances in the subnet before deleting it; otherwise, Amazon VPC returns an error.

The following figure shows a sample <items> XML element for the Delete Subnet operation. 

Sample <items> XML element for the Delete Subnet operation

<items>
 <item>
   <parameters>
     <subnet-id></subnet-id>
   </parameters>
 </item>
</items>

The following table describes the elements for this adapter request. 

Adapter request elements for the Delete Subnet operation 

Element

Definition

Required

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation:delete-subnet

Yes

<parameters>

Contains the <subnet-id> element required to execute the operation

Yes

<subnet-id>

Specifies the ID of the subnet that you want to delete

Yes

The following figure shows a sample adapter request for the Delete Subnet operation.

Sample adapter request for the Delete Subnet operation

<amazon-ec2-rest-request>
   <operation-name>delete-subnet</operation-name>    
   <access-key>AKIA***********8BT2Q</access-key>
   <secret-key>WQisk8Irh********************8AiJx3VQVd</secret-key>
   <region>us-east-1</region>
   <parameters>
         <subnet-id>subnet-ff5776b9</subnet-id>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the sample response for the Delete Subnet operation.

Sample adapter response for the Delete Subnet operation

<amazon-ec2-rest-response>
   <metadata>
       <status>success</status>
   </metadata>
   <DeleteSubnetResponse>
       <return>true</return>
   </DeleteSubnetResponse>
</amazon-ec2-rest-response>

Back to top

Describe Subnet 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 

Valid value: Any string

available-ip-address-count

Specifies the number of IP addresses that are available in the subnet 

Valid value: Any string

cidr

Specifies the Classless Inter-Domain Routing (CIDR) block of the subnet 

The CIDR block that you specify must exactly match the CIDR block of the to obtain results. Include a forward slash followed by one or two digits (for example, /28) before the CIDR block. 

Valid value: Any string

state

Specifies the state of the subnet 

Valid values: pending, available

subnet-id

Specifies the ID of the subnet 

Valid value: Any string

tag-key

Species the key assigned to a resource 

The tag-key filter is independent of the tag-value filter.

To list all the resources assigned the Purpose tag key (regardless of the value of the tag), and the X tag value (regardless of the value of the tag key), specify:

tag-key=Purpose
tag-value=X 

Valid value: Any string

tag-value

Specifies the value of the tag assigned to the resource 

The tag-value filter is independent of the <tag-key> filter. 

Valid value: Any string

Filters the results based on a specific tag-value combination 

To list the resources assigned the Purpose=X tag, specify: 
name=tag:Purpose 
value=X 

To list the resources assigned the Purpose=X or Purpose=Y tag, specify: 
name=tag:Purpose 
value1=X 
value2=Y

vpc-id

Specifies the ID of the VPC that the subnet is in 

Valid value: Any string

The following figure shows a sample <items> XML element for the Describe Subnets operation. 

Sample <items> XML element for the Describe Subnets operation

<items>
 <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

<access-key>

Specifies the Amazon Web Services (AWS) access key

You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Access Key is specified, the adapter ignores the value.
<secret-key>

Specifies the AWS secret access key

You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.

Conditional;

  • You must specify the Access Key and theSecret Key together in the configuration or the adapter request.
  • If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration.
  • If only the Secret Access Key is specified, the adapter ignores the value.
<region>

Specifies the region with which you want the adapter to communicate

Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions.

Valid values:

  • us-east-1
  • us-west-2 (default)
  • us-west-1
  • eu-west-1
  • ap-southeast-1
  • ap-northeast-1
  • ap-southeast-2
  • sa-east-1

No

<operation-name>

Contains the name of the operation:describe-subnets

Yes

<parameters>

Contains the elements required to execute the operation 

This element can be empty.

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 thefilterName 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. 

Sample adapter request for the Describe Subnets operation

<amazon-ec2-rest-request>
   <access-key>AKIAI**********GROKA</access-key>
   <secret-key>6hXjoZZDvWx**********1y2Yte/jZfnY6WgKCdC</secret-key>
   <region>us-west-2</region>
   <operation-name>describe-subnets</operation-name>
   <parameters>
     <subnet-set>
       <item>
         <subnet-id>subnet-b2376bf4</subnet-id>
       </item>
     </subnet-set>
     <filter-set>
       <item>
         <name>availability-zone</name>
         <value-set>
           <item>
             <value>us-west-2c</value>
             <value>vpc-ff1f0f9d1</value>
           </item>
         </value-set>
       </item>
     </filter-set>
   </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample Describe Subnets operation.

Sample adapter response for the Describe Subnets operation

<amazon-ec2-rest-response>
 <metadata>
   <status>success</status>
 </metadata>
 <DescribeSubnetsResponse>
   <subnetSet>
     <item>
       <subnetId>subnet-b2376bf4</subnetId>
       <state>available</state>
       <vpcId>vpc-ff1f0f9d</vpcId>
       <cidrBlock>10.0.0.0/25</cidrBlock>
       <availableIpAddressCount>123</availableIpAddressCount>
       <availabilityZone>us-west-2c</availabilityZone>
     </item>
   </subnetSet>
 </DescribeSubnetsResponse>
</amazon-ec2-rest-response>


Back to top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*