Amazon Elastic Compute Cloud

API Reference API Version 2012-05-01

Amazon Elastic Compute Cloud API Reference

Amazon Elastic Compute Cloud: API Reference

Copyright 2012 Amazon Web Services LLC or its affiliates. All rights reserved. The following are trademarks or registered trademarks of Amazon: Amazon, Amazon.com, Amazon.com Design, Amazon DevPay, Amazon EC2, Amazon Web Services Design, AWS, CloudFront, EC2, Elastic Compute Cloud, Kindle, and Mechanical Turk. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.

Amazon Elastic Compute Cloud API Reference

Welcome ................................................................................................................................................. 1 List of Actions by Function ...................................................................................................................... 3 Actions .................................................................................................................................................... 9 AllocateAddress .................................................................................................................................... 13 AssociateAddress ................................................................................................................................. 15 AssociateDhcpOptions ......................................................................................................................... 18 AssociateRouteTable ............................................................................................................................ 20 AttachInternetGateway ......................................................................................................................... 22 AttachNetworkInterface ........................................................................................................................ 24 AttachVolume ........................................................................................................................................ 26 AttachVpnGateway ............................................................................................................................... 29 AuthorizeSecurityGroupEgress ............................................................................................................ 31 AuthorizeSecurityGroupIngress ............................................................................................................ 34 BundleInstance ..................................................................................................................................... 38 CancelBundleTask ................................................................................................................................ 41 CancelConversionTask ......................................................................................................................... 43 CancelExportTask ................................................................................................................................. 45 CancelSpotInstanceRequests .............................................................................................................. 47 ConfirmProductInstance ....................................................................................................................... 49 CreateCustomerGateway ..................................................................................................................... 51 CreateDhcpOptions .............................................................................................................................. 53 CreateImage ......................................................................................................................................... 56 CreateInstanceExportTask ................................................................................................................... 58 CreateInternetGateway ......................................................................................................................... 61 CreateKeyPair ....................................................................................................................................... 63 CreateNetworkAcl ................................................................................................................................. 65 CreateNetworkAclEntry ........................................................................................................................ 67 CreateNetworkInterface ........................................................................................................................ 70 CreatePlacementGroup ........................................................................................................................ 72 CreateRoute ......................................................................................................................................... 74 CreateRouteTable ................................................................................................................................. 77 CreateSecurityGroup ............................................................................................................................ 79 CreateSnapshot .................................................................................................................................... 81 CreateSpotDatafeedSubscription ......................................................................................................... 84 CreateSubnet ........................................................................................................................................ 86 CreateTags ........................................................................................................................................... 88 CreateVolume ....................................................................................................................................... 90 CreateVpc ............................................................................................................................................. 92 CreateVpnConnection .......................................................................................................................... 94 CreateVpnGateway ............................................................................................................................... 98 DeleteCustomerGateway .................................................................................................................... 100 DeleteDhcpOptions ............................................................................................................................. 102 DeleteInternetGateway ....................................................................................................................... 104 DeleteKeyPair ..................................................................................................................................... 106 DeleteNetworkAcl ............................................................................................................................... 108 DeleteNetworkAclEntry ....................................................................................................................... 110 DeleteNetworkInterface ...................................................................................................................... 112 DeletePlacementGroup ...................................................................................................................... 114 DeleteRoute ........................................................................................................................................ 116 DeleteRouteTable ............................................................................................................................... 118 DeleteSecurityGroup .......................................................................................................................... 120 DeleteSnapshot .................................................................................................................................. 122 DeleteSpotDatafeedSubscription ........................................................................................................ 124 DeleteSubnet ...................................................................................................................................... 125 DeleteTags .......................................................................................................................................... 127 DeleteVolume ..................................................................................................................................... 130 DeleteVpc ........................................................................................................................................... 132 DeleteVpnConnection ......................................................................................................................... 134
API Version 2012-05-01 3

Amazon Elastic Compute Cloud API Reference

DeleteVpnGateway ............................................................................................................................. 136 DeregisterImage ................................................................................................................................. 138 DescribeAddresses ............................................................................................................................ 140 DescribeAvailabilityZones ................................................................................................................... 144 DescribeBundleTasks ......................................................................................................................... 147 DescribeConversionTasks .................................................................................................................. 150 DescribeCustomerGateways .............................................................................................................. 152 DescribeDhcpOptions ......................................................................................................................... 155 DescribeExportTasks .......................................................................................................................... 159 DescribeImageAttribute ...................................................................................................................... 161 DescribeImages .................................................................................................................................. 164 DescribeInstanceAttribute .................................................................................................................. 172 DescribeInstances .............................................................................................................................. 175 DescribeInstanceStatus ..................................................................................................................... 186 DescribeInternetGateways ................................................................................................................. 192 DescribeKeyPairs ............................................................................................................................... 195 DescribeNetworkAcls ......................................................................................................................... 198 DescribeNetworkInterfaceAttribute ..................................................................................................... 203 DescribeNetworkInterfaces ................................................................................................................. 205 DescribePlacementGroups ................................................................................................................. 211 DescribeRegions ................................................................................................................................ 214 DescribeReservedInstances ............................................................................................................... 217 DescribeReservedInstancesOfferings ................................................................................................ 221 DescribeRouteTables .......................................................................................................................... 225 DescribeSecurityGroups ..................................................................................................................... 229 DescribeSnapshotAttribute ................................................................................................................. 233 DescribeSnapshots ............................................................................................................................ 235 DescribeSpotDatafeedSubscription .................................................................................................... 240 DescribeSpotInstanceRequests ......................................................................................................... 242 DescribeSpotPriceHistory ................................................................................................................... 248 DescribeSubnets ................................................................................................................................ 252 DescribeTags ...................................................................................................................................... 256 DescribeVolumes ................................................................................................................................ 261 DescribeVolumeAttribute .................................................................................................................... 265 DescribeVolumeStatus ....................................................................................................................... 267 DescribeVpcs ..................................................................................................................................... 272 DescribeVpnConnections ................................................................................................................... 275 DescribeVpnGateways ....................................................................................................................... 279 DetachInternetGateway ...................................................................................................................... 283 DetachNetworkInterface ..................................................................................................................... 285 DetachVolume .................................................................................................................................... 287 DetachVpnGateway ............................................................................................................................ 289 DisassociateAddress .......................................................................................................................... 291 DisassociateRouteTable ..................................................................................................................... 293 EnableVolumeIO ................................................................................................................................. 295 GetConsoleOutput .............................................................................................................................. 297 GetPasswordData ............................................................................................................................... 299 ImportInstance .................................................................................................................................... 301 ImportKeyPair ..................................................................................................................................... 305 ImportVolume ..................................................................................................................................... 307 ModifyImageAttribute .......................................................................................................................... 310 ModifyInstanceAttribute ...................................................................................................................... 313 ModifyNetworkInterfaceAttribute ......................................................................................................... 316 ModifySnapshotAttribute ..................................................................................................................... 318 ModifyVolumeAttribute ........................................................................................................................ 320 MonitorInstances ................................................................................................................................ 322 PurchaseReservedInstancesOffering ................................................................................................. 324 RebootInstances ................................................................................................................................. 326
API Version 2012-05-01 4

Amazon Elastic Compute Cloud API Reference

RegisterImage .................................................................................................................................... 328 ReleaseAddress ................................................................................................................................. 332 ReplaceNetworkAclAssociation .......................................................................................................... 334 ReplaceNetworkAclEntry .................................................................................................................... 336 ReplaceRoute ..................................................................................................................................... 339 ReplaceRouteTableAssociation .......................................................................................................... 341 ReportInstanceStatus ......................................................................................................................... 343 RequestSpotInstances ........................................................................................................................ 346 ResetImageAttribute ........................................................................................................................... 352 ResetInstanceAttribute ....................................................................................................................... 354 ResetNetworkInterfaceAttribute .......................................................................................................... 356 ResetSnapshotAttribute ...................................................................................................................... 358 RevokeSecurityGroupEgress .............................................................................................................. 360 RevokeSecurityGroupIngress ............................................................................................................. 363 RunInstances ...................................................................................................................................... 366 StartInstances ..................................................................................................................................... 376 StopInstances ..................................................................................................................................... 378 TerminateInstances ............................................................................................................................ 380 UnmonitorInstances ............................................................................................................................ 382 Data Types .......................................................................................................................................... 384 AttachmentSetItemResponseType ..................................................................................................... 386 AttachmentType .................................................................................................................................. 387 AvailabilityZoneItemType .................................................................................................................... 388 AvailabilityZoneMessageType ............................................................................................................. 388 BlockDeviceMappingItemType ............................................................................................................ 389 BundleInstanceS3StorageType .......................................................................................................... 390 BundleInstanceTaskErrorType ............................................................................................................ 391 BundleInstanceTaskStorageType ....................................................................................................... 391 BundleInstanceTaskType .................................................................................................................... 392 CancelSpotInstanceRequestsResponseSetItemType ........................................................................ 393 ConversionTaskType ........................................................................................................................... 393 CreateVolumePermissionItemType ..................................................................................................... 394 CustomerGatewayType ....................................................................................................................... 395 DescribeAddressesResponseItemType .............................................................................................. 396 DescribeImagesResponseItemType ................................................................................................... 397 DescribeKeyPairsResponseItemType ................................................................................................. 399 DescribeReservedInstancesOfferingsResponseSetItemType ............................................................ 399 DescribeReservedInstancesResponseSetItemType .......................................................................... 400 DescribeSnapshotsSetItemResponseType ........................................................................................ 402 DescribeVolumesSetItemResponseType ............................................................................................ 403 DhcpConfigurationItemType ............................................................................................................... 404 DhcpOptionsType ............................................................................................................................... 404 DhcpValueType ................................................................................................................................... 405 DiskImageDescriptionType ................................................................................................................. 406 DiskImageVolumeDescriptionType ..................................................................................................... 406 EbsBlockDeviceType .......................................................................................................................... 407 EbsInstanceBlockDeviceMappingResponseType ............................................................................... 408 ExportTaskResponseType .................................................................................................................. 409 ExportToS3TaskResponseType .......................................................................................................... 410 GroupItemType ................................................................................................................................... 410 IcmpTypeCodeType ............................................................................................................................ 411 ImportInstanceTaskDetailsType .......................................................................................................... 412 ImportInstanceVolumeDetailItemType ................................................................................................ 412 ImportVolumeTaskDetailsType ............................................................................................................ 413 InstanceBlockDeviceMappingItemType .............................................................................................. 414 InstanceBlockDeviceMappingResponseItemType .............................................................................. 415 InstanceEbsBlockDeviceType ............................................................................................................. 415 InstanceExportTaskResponseType .................................................................................................... 416
API Version 2012-05-01 5

Amazon Elastic Compute Cloud API Reference

InstanceStatusEventsSetType ............................................................................................................ 417 InstanceStatusEventType ................................................................................................................... 417 InstanceStatusItemType ..................................................................................................................... 418 InstanceStatusSetType ....................................................................................................................... 419 InstanceStatusDetailsSetType ............................................................................................................ 419 InstanceStatusType ............................................................................................................................ 420 InstanceMonitoringStateType ............................................................................................................. 420 InstanceNetworkInterfaceSetItemRequestType .................................................................................. 421 InstanceNetworkInterfaceSetItemType ............................................................................................... 422 InstanceNetworkInterfaceSetRequestType ......................................................................................... 423 InstanceNetworkInterfaceSetType ...................................................................................................... 423 InstanceStateChangeType .................................................................................................................. 425 InstanceStateType .............................................................................................................................. 425 InternetGatewayAttachmentType ........................................................................................................ 426 InternetGatewayType .......................................................................................................................... 427 IpPermissionType ............................................................................................................................... 428 IpRangeItemType ................................................................................................................................ 429 LaunchPermissionItemType ................................................................................................................ 429 LaunchSpecificationRequestType ....................................................................................................... 430 LaunchSpecificationResponseType .................................................................................................... 431 MonitoringInstanceType ...................................................................................................................... 432 MonitorInstancesResponseSetItemType ............................................................................................ 433 NetworkAclEntryType ......................................................................................................................... 433 NetworkAclType .................................................................................................................................. 434 NetworkAclAssociationType ................................................................................................................ 435 NetworkInterfaceAssociationType ....................................................................................................... 436 NetworkInterfaceSet ........................................................................................................................... 437 NetworkInterfaceAttachmentType ....................................................................................................... 438 NetworkInterfaceType ......................................................................................................................... 438 PlacementGroupInfoType ................................................................................................................... 439 PlacementRequestType ...................................................................................................................... 440 PlacementResponseType ................................................................................................................... 440 PortRangeType ................................................................................................................................... 441 ProductCodeItemType ........................................................................................................................ 442 ProductCodesSetItemType ................................................................................................................. 442 ProductDescriptionSetItemType ......................................................................................................... 443 RecurringChargesSetItemType ........................................................................................................... 443 RegionItemType .................................................................................................................................. 444 ReservationInfoType ........................................................................................................................... 444 ResourceTagSetItemType ................................................................................................................... 445 RouteTableAssociationType ................................................................................................................ 446 RouteTableType .................................................................................................................................. 447 RouteType ........................................................................................................................................... 447 RunningInstancesItemType ................................................................................................................ 448 SecurityGroupIdSetItemType .............................................................................................................. 451 SecurityGroupItemType ...................................................................................................................... 452 SpotDatafeedSubscriptionType .......................................................................................................... 453 SpotInstanceRequestSetItemType ..................................................................................................... 454 SpotInstanceStateFaultType ............................................................................................................... 455 SpotPriceHistorySetItemType ............................................................................................................. 456 StateReasonType ............................................................................................................................... 457 SubnetType ......................................................................................................................................... 458 TagSetItemType .................................................................................................................................. 459 UserDataType ..................................................................................................................................... 459 UserIdGroupPairType ......................................................................................................................... 460 ValueType ........................................................................................................................................... 461 VolumeStatusItemType ....................................................................................................................... 461 VolumeStatusInfoType ........................................................................................................................ 462
API Version 2012-05-01 6

Amazon Elastic Compute Cloud API Reference

VolumeStatusDetailsItemType ............................................................................................................ 463 VolumeStatusEventItemType .............................................................................................................. 463 VolumeStatusActionItemType ............................................................................................................. 464 VpcType .............................................................................................................................................. 465 VpnConnectionType ............................................................................................................................ 466 VpnGatewayType ................................................................................................................................ 467 VpnTunnelTelemetryType .................................................................................................................... 468 Common Query Parameters ............................................................................................................... 469 Error Codes ........................................................................................................................................ 471 Amazon EC2 Resources .................................................................................................................... 480 Document History ............................................................................................................................... 482

API Version 2012-05-01 7

Amazon Elastic Compute Cloud API Reference

Welcome
This is the Amazon Elastic Compute Cloud API Reference. This guide provides detailed information about Amazon Elastic Compute Cloud (Amazon EC2) actions, data types, parameters, and errors. For detailed information about Amazon EC2 features and their associated API calls, go to the Amazon Elastic Compute Cloud User Guide. Amazon EC2 is a web service that provides resizeable computing capacityliterally, server instances in Amazon's data centersthat you use to build and host your software systems. With Amazon EC2, you can get access to infrastructure resources using APIs or web tools and utilities.

Note
This guide also includes the actions for Amazon Virtual Private Cloud (Amazon VPC). For more information about the service, go to the Amazon Virtual Private Cloud User Guide.

This reference has a single set of topics for both the Query and SOAP APIs (the actions are the same for both APIs). The topic for a given action shows the Query API request parameters. The XML request elements for the SOAP API have names that are very similar to the Query API parameter names. You can view the XML request elements in the WSDL, or look at the proxy classes that a SOAP toolkit generates from the WSDL. Therefore you can look at the topic for a given action and see what you need to provide for either the Query API or the SOAP API. You can also see what the XML response looks like (it's the same for both APIs). Current WSDL (2012-05-01) Making API Requests List of Actions by Function (p. 3) Location of the current WSDL Information about using the API List of the Amazon EC2 actions by function Alphabetical list of all Amazon EC2 actions Alphabetical list of all Amazon EC2 data types Parameters that all Query actions can use

Actions (p. 9)

Data Types (p. 384)

Common Query Parameters (p. 469)

API Version 2012-05-01 1

Amazon Elastic Compute Cloud API Reference

Error Codes (p. 471) Amazon EC2 product page

Client and server errors the API returns Information about this product

API Version 2012-05-01 2

Amazon Elastic Compute Cloud API Reference

List of Actions by Function

Amazon DevPay
ConfirmProductInstance (p. 49)

AMIs
CreateImage (p. 56) DeregisterImage (p. 138) DescribeImageAttribute (p. 161) DescribeImages (p. 164) ModifyImageAttribute (p. 310) RegisterImage (p. 328) ResetImageAttribute (p. 352)

Availability Zones and Regions

DescribeAvailabilityZones (p. 144) DescribeRegions (p. 214)

Customer Gateways (Amazon VPC)

CreateCustomerGateway (p. 51) DeleteCustomerGateway (p. 100) DescribeCustomerGateways (p. 152)

DHCP Options (Amazon VPC)

AssociateDhcpOptions (p. 18) CreateDhcpOptions (p. 53) DeleteDhcpOptions (p. 102)

API Version 2012-05-01 3

Amazon Elastic Compute Cloud API Reference

DescribeDhcpOptions (p. 155)

Elastic Block Store

AttachVolume (p. 26) CreateSnapshot (p. 81) CreateVolume (p. 90) DeleteSnapshot (p. 122) DeleteVolume (p. 130) DescribeSnapshotAttribute (p. 233) DescribeSnapshots (p. 235) DescribeVolumes (p. 261) DescribeVolumeAttribute (p. 265) DescribeVolumeStatus (p. 267) DetachVolume (p. 287) EnableVolumeIO (p. 295) ImportVolume (p. 307) ModifySnapshotAttribute (p. 318) ModifyVolumeAttribute (p. 320) ResetSnapshotAttribute (p. 358)

Elastic IP Addresses
AllocateAddress (p. 13) AssociateAddress (p. 15) DescribeAddresses (p. 140) DisassociateAddress (p. 291) ReleaseAddress (p. 332)

Elastic Network Interfaces

AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaces (p. 205) DescribeNetworkInterfaceAttribute (p. 203) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

General
GetConsoleOutput (p. 297)

API Version 2012-05-01 4

Amazon Elastic Compute Cloud API Reference

Instances
DescribeInstanceAttribute (p. 172) DescribeInstances (p. 175) DescribeInstanceStatus (p. 186) ImportInstance (p. 301) ModifyInstanceAttribute (p. 313) RebootInstances (p. 326) ReportInstanceStatus (p. 343) ResetInstanceAttribute (p. 354) RunInstances (p. 366) StartInstances (p. 376) StopInstances (p. 378) TerminateInstances (p. 380)

Internet Gateways (Amazon VPC)

AttachInternetGateway (p. 22) CreateInternetGateway (p. 61) DeleteInternetGateway (p. 104) DescribeInternetGateways (p. 192) DetachInternetGateway (p. 283)

Key Pairs
CreateKeyPair (p. 63) DeleteKeyPair (p. 106) DescribeKeyPairs (p. 195) ImportKeyPair (p. 305)

Monitoring
MonitorInstances (p. 322) UnmonitorInstances (p. 382)

Network ACLs (Amazon VPC)

CreateNetworkAcl (p. 65) CreateNetworkAclEntry (p. 67) DeleteNetworkAcl (p. 108) DeleteNetworkAclEntry (p. 110) DescribeNetworkAcls (p. 198) ReplaceNetworkAclAssociation (p. 334)

API Version 2012-05-01 5

Amazon Elastic Compute Cloud API Reference

ReplaceNetworkAclEntry (p. 336)

Placement Groups
CreatePlacementGroup (p. 72) DeletePlacementGroup (p. 114) DescribePlacementGroups (p. 211)

Reserved Instances
DescribeReservedInstances (p. 217) DescribeReservedInstancesOfferings (p. 221) PurchaseReservedInstancesOffering (p. 324)

Route Tables (Amazon VPC)

AssociateRouteTable (p. 20) CreateRoute (p. 74) CreateRouteTable (p. 77) DeleteRoute (p. 116) DeleteRouteTable (p. 118) DescribeRouteTables (p. 225) DisassociateRouteTable (p. 293) ReplaceRoute (p. 339) ReplaceRouteTableAssociation (p. 341)

Security Groups
AuthorizeSecurityGroupEgress (p. 31) (Amazon VPC security groups only) AuthorizeSecurityGroupIngress (p. 34) CreateSecurityGroup (p. 79) DeleteSecurityGroup (p. 120) DescribeSecurityGroups (p. 229) RevokeSecurityGroupEgress (p. 360) (Amazon VPC security groups only) RevokeSecurityGroupIngress (p. 363)

Spot Instances
CancelSpotInstanceRequests (p. 47) CreateSpotDatafeedSubscription (p. 84) DeleteSpotDatafeedSubscription (p. 124) DescribeSpotDatafeedSubscription (p. 240) DescribeSpotInstanceRequests (p. 242)

API Version 2012-05-01 6

Amazon Elastic Compute Cloud API Reference

DescribeSpotPriceHistory (p. 248) RequestSpotInstances (p. 346)

Subnets (Amazon VPC)

CreateSubnet (p. 86) DeleteSubnet (p. 125) DescribeSubnets (p. 252)

Tags
CreateTags (p. 88) DeleteTags (p. 127) DescribeTags (p. 256)

VM Import
CancelConversionTask (p. 43) DescribeConversionTasks (p. 150) ImportInstance (p. 301) ImportVolume (p. 307)

VM Export
CancelExportTask (p. 45) CreateInstanceExportTask (p. 58) DescribeExportTasks (p. 159)

VPCs (Amazon VPC)

CreateVpc (p. 92) DeleteVpc (p. 132) DescribeVpcs (p. 272)

VPN Connections (Amazon VPC)

CreateVpnConnection (p. 94) DeleteVpnConnection (p. 134) DescribeVpnConnections (p. 275)

Virtual Private Gateways (Amazon VPC)

AttachVpnGateway (p. 29) CreateVpnGateway (p. 98) DeleteVpnGateway (p. 136)
API Version 2012-05-01 7

Amazon Elastic Compute Cloud API Reference

DescribeVpnGateways (p. 279) DetachVpnGateway (p. 289)

Windows
BundleInstance (p. 38) CancelBundleTask (p. 41) DescribeBundleTasks (p. 147) GetPasswordData (p. 299)

API Version 2012-05-01 8

Amazon Elastic Compute Cloud API Reference

Actions
Topics AllocateAddress (p. 13) AssociateAddress (p. 15) AssociateDhcpOptions (p. 18) AssociateRouteTable (p. 20) AttachInternetGateway (p. 22) AttachNetworkInterface (p. 24) AttachVolume (p. 26) AttachVpnGateway (p. 29) AuthorizeSecurityGroupEgress (p. 31) AuthorizeSecurityGroupIngress (p. 34) BundleInstance (p. 38) CancelBundleTask (p. 41) CancelConversionTask (p. 43) CancelExportTask (p. 45) CancelSpotInstanceRequests (p. 47) ConfirmProductInstance (p. 49) CreateCustomerGateway (p. 51) CreateDhcpOptions (p. 53) CreateImage (p. 56) CreateInstanceExportTask (p. 58) CreateInternetGateway (p. 61) CreateKeyPair (p. 63)

CreateNetworkAcl (p. 65) CreateNetworkAclEntry (p. 67) CreateNetworkInterface (p. 70) CreatePlacementGroup (p. 72) CreateRoute (p. 74) CreateRouteTable (p. 77) CreateSecurityGroup (p. 79) CreateSnapshot (p. 81)

API Version 2012-05-01 9

Amazon Elastic Compute Cloud API Reference

CreateSpotDatafeedSubscription (p. 84) CreateSubnet (p. 86) CreateTags (p. 88) CreateVolume (p. 90) CreateVpc (p. 92) CreateVpnConnection (p. 94) CreateVpnGateway (p. 98) DeleteCustomerGateway (p. 100) DeleteDhcpOptions (p. 102) DeleteInternetGateway (p. 104) DeleteKeyPair (p. 106) DeleteNetworkAcl (p. 108) DeleteNetworkAclEntry (p. 110) DeleteNetworkInterface (p. 112) DeletePlacementGroup (p. 114) DeleteRoute (p. 116) DeleteRouteTable (p. 118) DeleteSecurityGroup (p. 120) DeleteSnapshot (p. 122) DeleteSpotDatafeedSubscription (p. 124) DeleteSubnet (p. 125) DeleteTags (p. 127) DeleteVolume (p. 130) DeleteVpc (p. 132) DeleteVpnConnection (p. 134) DeleteVpnGateway (p. 136) DeregisterImage (p. 138) DescribeAddresses (p. 140) DescribeAvailabilityZones (p. 144) DescribeBundleTasks (p. 147) DescribeConversionTasks (p. 150) DescribeCustomerGateways (p. 152)

DescribeDhcpOptions (p. 155) DescribeExportTasks (p. 159) DescribeImageAttribute (p. 161) DescribeImages (p. 164) DescribeInstanceAttribute (p. 172) DescribeInstances (p. 175) DescribeInstanceStatus (p. 186) DescribeInternetGateways (p. 192) DescribeKeyPairs (p. 195) DescribeNetworkAcls (p. 198) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205) DescribePlacementGroups (p. 211) DescribeRegions (p. 214)

API Version 2012-05-01 10

Amazon Elastic Compute Cloud API Reference

DescribeReservedInstances (p. 217) DescribeReservedInstancesOfferings (p. 221) DescribeRouteTables (p. 225) DescribeSecurityGroups (p. 229) DescribeSnapshotAttribute (p. 233) DescribeSnapshots (p. 235) DescribeSpotDatafeedSubscription (p. 240) DescribeSpotInstanceRequests (p. 242) DescribeSpotPriceHistory (p. 248) DescribeSubnets (p. 252) DescribeTags (p. 256) DescribeVolumes (p. 261) DescribeVolumeAttribute (p. 265) DescribeVolumeStatus (p. 267) DescribeVpcs (p. 272) DescribeVpnConnections (p. 275) DescribeVpnGateways (p. 279) DetachInternetGateway (p. 283) DetachNetworkInterface (p. 285) DetachVolume (p. 287) DetachVpnGateway (p. 289) DisassociateAddress (p. 291) DisassociateRouteTable (p. 293) EnableVolumeIO (p. 295) GetConsoleOutput (p. 297) GetPasswordData (p. 299) ImportInstance (p. 301) ImportKeyPair (p. 305) ImportVolume (p. 307) ModifyImageAttribute (p. 310) ModifyInstanceAttribute (p. 313) ModifyNetworkInterfaceAttribute (p. 316)

ModifySnapshotAttribute (p. 318) ModifyVolumeAttribute (p. 320) MonitorInstances (p. 322) PurchaseReservedInstancesOffering (p. 324) RebootInstances (p. 326) RegisterImage (p. 328) ReleaseAddress (p. 332) ReplaceNetworkAclAssociation (p. 334) ReplaceNetworkAclEntry (p. 336) ReplaceRoute (p. 339) ReplaceRouteTableAssociation (p. 341) ReportInstanceStatus (p. 343) RequestSpotInstances (p. 346) ResetImageAttribute (p. 352)

API Version 2012-05-01 11

Amazon Elastic Compute Cloud API Reference

ResetInstanceAttribute (p. 354) ResetNetworkInterfaceAttribute (p. 356) ResetSnapshotAttribute (p. 358) RevokeSecurityGroupEgress (p. 360) RevokeSecurityGroupIngress (p. 363) RunInstances (p. 366) StartInstances (p. 376) StopInstances (p. 378) TerminateInstances (p. 380) UnmonitorInstances (p. 382)

API Version 2012-05-01 12

Amazon Elastic Compute Cloud API Reference AllocateAddress

AllocateAddress
Description
This action applies to both EC2 Elastic IP addresses and VPC Elastic IP addresses. For EC2 addresses: This action acquires an Elastic IP address for use with your Amazon Web Services (AWS) account. For more information about EC2 Elastic IP addresses, go to Instance Addressing in the Amazon Elastic Compute Cloud User Guide. For VPC addresses: This action acquires an Elastic IP address for use with your VPC. For information about VPC addresses and how they differ from EC2 addresses, go to the Elastic IP Addresses in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
Domain

Description

Required

Set to vpc to allocate the address to your VPC. Conditional Type: String Default: Address is standard (allocated to EC2) Valid Values: vpc Condition: Required when allocating an address to a VPC

Response Elements
The elements in the following table are wrapped in an AllocateAddressResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Elastic IP address. Type: xsd:string Whether this Elastic IP address is for instances in EC2 (i.e., standard) or instances in a VPC. Type: xsd:string Valid Values: standard | vpc ID that AWS assigns to represent the allocation of the address for use with Amazon VPC. Returned only for VPC elastic IP addresses. Type: xsd:string

publicIp

domain

allocationId

API Version 2012-05-01 13

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example returns an Elastic IP address for use with the account.
https://ec2.amazonaws.com/?Action=AllocateAddress &AUTHPARAMS

Example Response
<AllocateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <publicIp>192.0.2.1</publicIp> </AllocateAddressResponse>

Example Request
This example returns a VPC Elastic IP address for use with Amazon VPC.
https://ec2.amazonaws.com/?Action=AllocateAddress Domain=vpc &AUTHPARAMS

Example Response
<AllocateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <publicIp>198.51.100.1</publicIp> <domain>vpc</domain> <allocationId>eipalloc-5723d13e</allocationId> </AllocateAddressResponse>

Related Operations
DescribeAddresses (p. 140) ReleaseAddress (p. 332) AssociateAddress (p. 15) DisassociateAddress (p. 291)

API Version 2012-05-01 14

Amazon Elastic Compute Cloud API Reference AssociateAddress

AssociateAddress
Description
This action applies to both EC2 Elastic IP addresses and VPC Elastic IP addresses. For EC2 addresses: This action associates an Elastic IP address with an instance (not running in a VPC). If the IP address is currently assigned to another instance, the IP address is assigned to the new instance. For more information about EC2 Elastic IP addresses, go to Instance Addressing in the Amazon Elastic Compute Cloud User Guide. For VPC addresses: This action associates a VPC Elastic IP address with an instance in your VPC. If the IP address is currently assigned to another instance, Amazon EC2 returns an error. For information about VPC addresses and how they differ from EC2 addresses, go to the Elastic IP Addresses in the Amazon Virtual Private Cloud User Guide. This is an idempotent operation. If you enter it more than once, Amazon EC2 does not return an error.

Request Parameters
Name
PublicIp

Description EC2 Elastic IP address to assign to the instance. Type: String Default: None Condition: Required for EC2 Elastic IP addresses The instance to associate with the IP address. Type: String Default: None The allocation ID that AWS returned when you allocated the Elastic IP address for use with Amazon VPC. Type: String Default: None Condition: Required for VPC Elastic IP addresses.

Required Conditional

InstanceId

Conditional

AllocationId

Conditional

NetworkInterfaceId

The network interface ID to associate with an instance. No Association will fail when specifying an instance id unless exactly one interface is attached. Type: String Default: None Condition: Available for VPC Elastic IP addresses only.

Response Elements
The elements in the following table are wrapped in an AssociateAddressResponse structure.

API Version 2012-05-01 15

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean ID that AWS provides to represent the association of the address with an instance. Returned only for VPC Elastic IP addresses. Type: xsd:string

return

associationId

Examples
Example Request
This example associates an EC2 Elastic IP address with an instance.
https://ec2.amazonaws.com/?Action=AssociateAddress &InstanceId=i-2ea64347 &PublicIp=192.0.2.1 &AUTHPARAMS

Example Response
<AssociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </AssociateAddressResponse>

Example Request
This example associates a VPC Elastic IP address with an instance in your VPC.
https://ec2.amazonaws.com/?Action=AssociateAddress &InstanceId=i-4fd2431a &AllocationId=eipalloc-5723d13e &AUTHPARAMS

Example Response
<AssociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> <associationId>eipassoc-fc5ca095</associationId> </AssociateAddressResponse>

API Version 2012-05-01 16

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
AllocateAddress (p. 13) DescribeAddresses (p. 140) ReleaseAddress (p. 332) DisassociateAddress (p. 291)

API Version 2012-05-01 17

Amazon Elastic Compute Cloud API Reference AssociateDhcpOptions

AssociateDhcpOptions
Description
Associates a set of DHCP options (that you've previously created) with the specified VPC. Or, associates no DHCP options with the VPC. After you associate the options with the VPC, any existing instances and all new instances that you launch in that VPC use the options. You don't need to restart or relaunch the instances. They automatically pick up the changes within a few hours, depending on how frequently the instance renews its DHCP lease. If you want, you can explicitly renew the lease using the operating system on the instance. For more information about the supported DHCP options and using them with Amazon VPC, go to Using DHCP Options in Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
DhcpOptionsId

Description

Required

The ID of the DHCP options you want to associate Yes with the VPC, or "default" if you want the VPC to use no DHCP options. Type: String Default: None The ID of the VPC you want to associate the DHCP Yes options with. Type: String Default: None

VpcId

Response Elements
The elements in the following table are wrapped in an AssociateDhcpOptionsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example associates the DHCP options with ID dopt-7a8b9c2d with the VPC with ID vpc-1a2b3c4d.

API Version 2012-05-01 18

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=AssociateDhcpOptions &DhcpOptionsId=dopt-7a8b9c2d &VpcId=vpc-1a2b3c4d &AUTHPARAMS

Example Response
<AssociateDhcpOptionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </AssociateDhcpOptionsResponse>

Example Request
This example changes the VPC with ID vpc-1a2b3c4d to use no DHCP options.
https://ec2.amazonaws.com/?Action=AssociateDhcpOptions &DhcpOptionsId=default &VpcId=vpc-1a2b3c4d &AUTHPARAMS

Example Response
<AssociateDhcpOptionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </AssociateDhcpOptionsResponse>

Related Operations
CreateDhcpOptions (p. 53) DescribeDhcpOptions (p. 155) DeleteDhcpOptions (p. 102)

API Version 2012-05-01 19

Amazon Elastic Compute Cloud API Reference AssociateRouteTable

AssociateRouteTable
Description
Associates a subnet with a route table. The subnet and route table must be in the same VPC. This association causes traffic originating from the subnet to be routed according to the routes in the route table. The action returns an association ID, which you need if you want to disassociate the route table from the subnet later. A route table can be associated with multiple subnets. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
RouteTableId

Description The ID of the route table. Type: String Default: None The ID of the subnet. Type: String Default: None

Required Yes

SubnetId

Yes

Response Elements
The elements in the following table are wrapped in an AssociateRouteTableResponse structure. Name
requestId

Description The ID of the request. Type: String ID that AWS provides to represent the association of the route table and the subnet. Type: String Example: rtbassoc-f8ad4891

associationId

Examples
Example Request
This example associates a route table with ID rtb-e4ad488d with a subnet with ID subnet-15ad487c.
https://ec2.amazonaws.com/?Action=AssociateRouteTable &RouteTableId=rtb-e4ad488d &SubnetId=subnet-15ad487c

API Version 2012-05-01 20

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<AssociateRouteTableResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <associationId>rtbassoc-f8ad4891</associationId> </AssociateRouteTableResponse>

Related Operations
CreateRouteTable (p. 77) DisassociateRouteTable (p. 293) DescribeRouteTables (p. 225) ReplaceRouteTableAssociation (p. 341)

API Version 2012-05-01 21

Amazon Elastic Compute Cloud API Reference AttachInternetGateway

AttachInternetGateway
Description
Attaches an Internet gateway to a VPC, enabling connectivity between the Internet and the VPC. For more information about your VPC and Internet gateway, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
InternetGatewayId

Description The ID of the Internet gateway to attach. Type: String Default: None The ID of the VPC. Type: String Default: None

Required Yes

VpcId

Yes

Response Elements
The elements in the following table are wrapped in an AttachInternetGatewayResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
The example attaches the Internet gateway with ID igw-eaad4883 to the VPC with ID vpc-11ad4878.
https://ec2.amazonaws.com/?Action=AttachInternetGateway &InternetGatewayId=igw-eaad4883 &VpcId=vpc-11ad4878 &AUTHPARAMS

Example Response
<AttachInternetGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/">

API Version 2012-05-01 22

Amazon Elastic Compute Cloud API Reference Related Operations

<requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </AttachInternetGatewayResponse>

Related Operations
CreateInternetGateway (p. 61) DeleteInternetGateway (p. 104) DetachInternetGateway (p. 283) DescribeInternetGateways (p. 192)

API Version 2012-05-01 23

Amazon Elastic Compute Cloud API Reference AttachNetworkInterface

AttachNetworkInterface
Description
Attaches a network interface to an instance.

Request Parameters
Name
NetworkInterfaceId

Description The ID of the network interface to attach. Type: String Default: None

Required Yes

InstanceId

The ID of the instance that will be attached to Yes the network interface. Type: String Default: None The index of the device for the network interface attachment on the instance. Type: Integer Default: None Yes

DeviceIndex

Response Elements
The elements in the following table are wrapped in an AttachNetworkInterfaceResponse structure. Name
requestId

Description The ID of the attachment request. Type: String The ID of the attachment. Type: String

attachmentId

Examples
Example Request
This example attaches an elastic network interface (ENI) eni-ffda3197 to the specified EC2 instance i-9cc316fe.
https://ec2.amazonaws.com/?Action=AttachNetworkInterface &DeviceIndex=1 &InstanceId=i-9cc316fe &NetworkInterfaceId=eni-ffda3197 &AUTHPARAMS

API Version 2012-05-01 24

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<AttachNetworkInterfaceResponse xmlns='http://ec2.amazonaws.com/doc/2011-1115/'> <requestId>ace8cd1e-e685-4e44-90fb-92014d907212</requestId> <attachmentId>eni-attach-d94b09b0</attachmentId> </AttachNetworkInterfaceResponse>

Related Operations
DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 25

Amazon Elastic Compute Cloud API Reference AttachVolume

AttachVolume
Description
Attaches an Amazon EBS volume to a running instance and exposes it as the specified device. Windows instances currently support devices xvda through xvdp. Device xvda is assigned to drive C:\, and, depending on the instance type, devices xvdb through xvde might be reserved by the ephemeral stores. Any device that is not reserved can be attached to an Amazon EBS volume.

Note
If a volume has an AWS Marketplace product code: The volume can only be attached to the root device of a stopped instance. You must be subscribed to the AWS Marketplace code that is on the volume. The configuration (instance type, operating system) of the instance must support that specific AWS Marketplace code. For example, you cannot take a volume from a Windows instance and attach it to a Linux instance. AWS Marketplace product codes will be copied from the volume to the instance.

For an overview of the AWS Marketplace, go to https://aws.amazon.com/marketplace/help/200900000. For details on how to use the AWS Marketplace, see AWS Marketplace.

Request Parameters
Name
VolumeId

Description The ID of the Amazon EBS volume. The volume and instance must be within the same Availability Zone and the instance must be running. Type: String Default: None

Required Yes

InstanceId

The ID of the instance to which the volume attaches. The Yes volume and instance must be within the same Availability Zone and the instance must be running. Type: String Default: None How the device is exposed to the instance (e.g., /dev/sdh, Yes or xvdh). Type: String Default: None

Device

Response Elements
The elements in the following table are wrapped in an AttachVolumeResponse structure.

API Version 2012-05-01 26

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string The ID of the volume. Type: xsd:string The ID of the instance. Type: xsd:string The device as it is exposed to the instance (e.g., /dev/sdh, or xvdh). Type: xsd:string Volume state. Type: xsd:string Valid Values: attaching | attached | detaching | detached Time stamp when the attachment initiated. Type: xsd:dateTime

volumeId

instanceId

device

status

attachTime

Examples
Example Request
This example attaches volume vol-4d826724 to instance i-6058a509 and exposes it as /dev/sdh. For information on standard storage locations, go to the Amazon Elastic Compute Cloud User Guide.
https://ec2.amazonaws.com/?Action=AttachVolume &VolumeId=vol-4d826724 &InstanceId=i-6058a509 &Device=/dev/sdh &AUTHPARAMS

Example Response
<AttachVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <volumeId>vol-4d826724</volumeId> <instanceId>i-6058a509</instanceId> <device>/dev/sdh</device> <status>attaching</status> <attachTime>2008-05-07T11:51:50.000Z</attachTime> </AttachVolumeResponse>

Related Operations
CreateVolume (p. 90) DeleteVolume (p. 130) DescribeVolumes (p. 261)

API Version 2012-05-01 27

Amazon Elastic Compute Cloud API Reference Related Operations

DetachVolume (p. 287)

API Version 2012-05-01 28

Amazon Elastic Compute Cloud API Reference AttachVpnGateway

AttachVpnGateway
Description
Attaches a virtual private gateway to a VPC. For more information, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpnGatewayId

Description The ID of the virtual private gateway to attach to the VPC. Type: String Default: None The ID of the VPC. Type: String Default: None

Required Yes

VpcId

Yes

Response Elements
The elements in the following table are wrapped in an AttachVpnGatewayResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Information about the attachment. Type: AttachmentType (p. 387)

attachment

Examples
Example Request
This example attaches the virtual private gateway with ID vgw-8db04f81 to the VPC with ID vpc-1a2b3c4d.
https://ec2.amazonaws.com/?Action=AttachVpnGateway &VpnGatewayId=vgw-8db04f81 &VpcId=vpc-1a2b3c4d &AUTHPARAMS

Example Response
<AttachVpnGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>

API Version 2012-05-01 29

Amazon Elastic Compute Cloud API Reference Related Operations

<attachment> <vpcId>vpc-1a2b3c4d</vpcId> <state>attaching</state> </attachment> </AttachVpnGatewayResponse>

Related Operations
CreateVpnGateway (p. 98) DescribeVpnGateways (p. 279) DetachVpnGateway (p. 289) CreateVpc (p. 92) CreateVpnConnection (p. 94)

API Version 2012-05-01 30

Amazon Elastic Compute Cloud API Reference AuthorizeSecurityGroupEgress

AuthorizeSecurityGroupEgress
Description
This action applies only to security groups in a VPC; it's not supported for EC2 security groups. For information about Amazon Virtual Private Cloud and VPC security groups, go to Security Groups in the Amazon Virtual Private Cloud User Guide. The action adds one or more egress rules to a VPC security group. Specifically, this action permits instances in a security group to send traffic to one or more destination CIDR IP address ranges, or to one or more destination security groups in the same VPC. Each rule consists of the protocol (e.g., TCP), plus either a CIDR range or a source group. For the TCP and UDP protocols, you must also specify the destination port or port range. For the ICMP protocol, you must also specify the ICMP type and code. You can use -1 for the type or code to mean all types or all codes. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.

Important
For VPC security groups: You can have up to 50 rules total per group (covering both ingress and egress).

Request Parameters
Name
GroupId

Description ID of the VPC security group to modify. Type: String Default: None

Required Yes

IpPermissions.n.IpPr otocol

IP protocol name or number (go to Protocol Numbers). Yes When you call DescribeSecurityGroups, the protocol value returned is the number. Exception: For TCP, UDP, and ICMP, the value returned is the name (e.g., tcp, udp, or icmp). Type: String Valid Values: tcp | udp | icmp or any protocol number (go to Protocol Numbers). Use -1 to specify all. Start of port range for the TCP and UDP protocols, or an ICMP type number. For the ICMP type number, you can use -1 to specify all ICMP types. Type: Integer Default: None Condition: Required for ICMP and any protocol that uses ports Conditional

IpPermissions.n.From Port

API Version 2012-05-01 31

Amazon Elastic Compute Cloud API Reference Response Elements

Name
IpPermissions.n.ToPo rt

Description

Required

End of port range for the TCP and UDP protocols, or an Conditional ICMP code number. For the ICMP code number, you can use -1 to specify all ICMP codes for the given ICMP type. Type: Integer Default: None Condition: Required for ICMP and any protocol that uses ports Name of the destination security group. Cannot be used when specifying a CIDR IP address. Type: String Default: None Condition: Required if modifying access for one or more destination security groups. Conditional

IpPermissions.n.Grou ps.m.GroupId

IpPermissions.n.IpRa nges.m.CidrIp

CIDR range. Cannot be used when specifying a destination Conditional security group. Type: String Default: None Constraints: Valid CIDR IP address range. Condition: Required if modifying access for one or more IP address ranges.

Response Elements
The elements in the following table are wrapped in an AuthorizeSecurityGroupEgressResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if request is successful. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example grants your VPC security group with ID sg-1a2b3c4d access to the 192.0.2.0/24 and 198.51.100.0/24 address ranges on TCP port 80.
https://ec2.amazonaws.com/?Action=AuthorizeSecurityGroupEgress &GroupId=sg-1a2b3c4d &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=80 &IpPermissions.1.ToPort=80

API Version 2012-05-01 32

Amazon Elastic Compute Cloud API Reference Related Operations

&IpPermissions.1.IpRanges.1.CidrIp=192.0.2.0/24 &IpPermissions.1.IpRanges.2.CidrIp=198.51.100.0/24 &AUTHPARAMS

Example Request
This example grants your VPC security group with ID sg-1a2b3c4d access to your VPC security group with ID sg-9a8d7f5c on TCP port 1433.
https://ec2.amazonaws.com/?Action=AuthorizeSecurityGroupEgress &GroupId=sg-1a2b3c4d &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=1433 &IpPermissions.1.ToPort=1433 &IpPermissions.1.Groups.1.GroupId=sg-9a8d7f5c &AUTHPARAMS

Example Response
<AuthorizeSecurityGroupEgressResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </AuthorizeSecurityGroupEgressResponse>

Related Operations
CreateSecurityGroup (p. 79) DescribeSecurityGroups (p. 229) RevokeSecurityGroupEgress (p. 360) AuthorizeSecurityGroupIngress (p. 34) RevokeSecurityGroupIngress (p. 363) DeleteSecurityGroup (p. 120)

API Version 2012-05-01 33

Amazon Elastic Compute Cloud API Reference AuthorizeSecurityGroupIngress

AuthorizeSecurityGroupIngress
Description
Adds one or more ingress rules to a security group. This action applies to both EC2 security groups and VPC security groups. For information about VPC security groups and how they differ from EC2 security groups, go to Security Groups in the Amazon Virtual Private Cloud User Guide. For EC2 security groups, this action gives one or more CIDR IP address ranges permission to access a security group in your account, or gives one or more security groups (called the source groups) permission to access a security group in your account. A source group can be in your own AWS account, or another. For VPC security groups, this action gives one or more CIDR IP address ranges permission to access a security group in your VPC, or gives one or more other security groups (called the source groups) permission to access a security group in your VPC. The groups must all be in the same VPC. Each rule consists of the protocol (e.g., TCP), plus either a CIDR range or a source group. For the TCP and UDP protocols, you must also specify the destination port or port range. For the ICMP protocol, you must also specify the ICMP type and code. You can use -1 for the type or code to mean all types or all codes. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.

Important
For EC2 security groups: You can have up to 100 rules per group. For VPC security groups: You can have up to 50 rules total per group (covering both ingress and egress).

Request Parameters
Name
UserId GroupId

Description Deprecated

Required No

ID of the EC2 or VPC security group to modify. The group Conditional must belong to your account. Type: String Default: None Condition: Required for VPC security groups; can be used instead of GroupName for EC2 security groups Name of the EC2 security group to modify. Type: String Default: None Condition: Can be used instead of GroupId for EC2 security groups Conditional

GroupName

API Version 2012-05-01 34

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
IpPermissions.n.IpPr otocol

Description

Required

IP protocol name or number (go to Protocol Numbers). Required EC2 security groups can have rules only for TCP, UDP, and ICMP, whereas VPC security groups can have rules assigned to any protocol number. When you call DescribeSecurityGroups, the protocol value returned is the number. Exception: For TCP, UDP, and ICMP, the value returned is the name (e.g., tcp, udp, or icmp). Type: String Valid Values for EC2 security groups: tcp | udp | icmp or the corresponding protocol number (6 | 17 | 1). Valid Values for VPC groups: tcp | udp | icmp or any protocol number (go to Protocol Numbers). Use -1 to specify all. Start of port range for the TCP and UDP protocols, or an ICMP type number. For the ICMP type number, you can use -1 to specify all ICMP types. Type: Integer Default: None Default: Required for ICMP and any protocol that uses ports Conditional

IpPermissions.n.From Port

IpPermissions.n.ToPo rt

End of port range for the TCP and UDP protocols, or an Conditional ICMP code number. For the ICMP code number, you can use -1 to specify all ICMP codes for the given ICMP type. Type: Integer Default: None Default: Required for ICMP and any protocol that uses ports AWS account ID that owns the source security group. Conditional Cannot be used when specifying a CIDR IP address. Type: String Default: None Condition: For EC2 security groups only. Required if modifying access for one or more source security groups. Name of the source security group. Cannot be used when Conditional specifying a CIDR IP address. Type: String Default: None Condition: Required if modifying access for one or more source security groups. ID of the source security group. Cannot be used when Conditional specifying a CIDR IP address. Type: String Default: None Condition: For VPC security groups only. Required if modifying access for one or more source security groups.

IpPermissions.n.Grou ps.m.UserId

IpPermissions.n.Grou ps.m.GroupName

IpPermissions.n.Grou ps.m.GroupId

API Version 2012-05-01 35

Amazon Elastic Compute Cloud API Reference Response Elements

Name
IpPermissions.n.IpRa nges.m.CidrIp

Description CIDR range. Cannot be used when specifying a source security group. Type: String Default: None Constraints: Valid CIDR IP address range. Condition: Required if modifying access for one or more IP address ranges.

Required Conditional

Response Elements
The elements in the following table are wrapped in an AuthorizeSecurityGroupIngressResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if request is successful. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example is for an EC2 security group. The request grants the 192.0.2.0/24 and 198.51.100.0/24 address ranges access to your websrv security group on TCP port 80.
https://ec2.amazonaws.com/?Action=AuthorizeSecurityGroupIngress &GroupName=websrv &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=80 &IpPermissions.1.ToPort=80 &IpPermissions.1.IpRanges.1.CidrIp=192.0.2.0/24 &IpPermissions.1.IpRanges.2.CidrIp=198.51.100.0/24 &AUTHPARAMS

Example Request
This example is for an EC2 security group. The request grants TCP port 80 access from the source group called OtherAccountGroup (in AWS account 111122223333) to your websrv security group.
https://ec2.amazonaws.com/?Action=AuthorizeSecurityGroupIngress &GroupName=websrv &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=80 &IpPermissions.1.ToPort=80 &IpPermissions.1.Groups.1.GroupName=OtherAccountGroup

API Version 2012-05-01 36

Amazon Elastic Compute Cloud API Reference Related Operations

&IpPermissions.1.Groups.1.UserId=111122223333 &AUTHPARAMS

Example Request
This example is for a VPC security group. The request grants TCP port 80 access from the source group called OtherGroupInMyVPC (sg-0a5d8e02) to your VpcWebServers security group (sg-140ba4c8). The request requires the group IDs and not the group names. Your AWS account ID is 111122223333.
https://ec2.amazonaws.com/?Action=AuthorizeSecurityGroupIngress &GroupId=sg-140ba4c8 &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=80 &IpPermissions.1.ToPort=80 &IpPermissions.1.Groups.1.GroupId=sg-0a5d8e02 &IpPermissions.1.Groups.1.UserId=111122223333 &AUTHPARAMS

Example Response
<AuthorizeSecurityGroupIngressResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </AuthorizeSecurityGroupIngressResponse>

Related Operations
CreateSecurityGroup (p. 79) DescribeSecurityGroups (p. 229) RevokeSecurityGroupIngress (p. 363) DeleteSecurityGroup (p. 120)

API Version 2012-05-01 37

Amazon Elastic Compute Cloud API Reference BundleInstance

BundleInstance
Description
Bundles an Amazon instance store-backed Windows instance.

Note
During bundling, only the root store (C:\) is bundled. Data on the instance store is not preserved. For step-by-step instructions to bundle an instance store-backed Windows instance, go to Bundling Amazon EC2 instance store-backed Windows AMIs. This procedure is not applicable for Linux and UNIX instances or Windows instances that use Amazon EBS volumes as their root devices.

Request Parameters
Name
InstanceId

Description The ID of the instance to bundle. Type: String Default: None

Required Yes

Storage.S3.Bucket

The bucket in which to store the AMI. You can specify a Yes bucket that you already own or a new bucket that Amazon EC2 creates on your behalf. If you specify a bucket that belongs to someone else, Amazon EC2 returns an error. Type: String Default: None The beginning of the file name of the AMI. Type: String Default: None Yes

Storage.S3.Prefix

Storage.S3.AWSAccess KeyId

The Access Key ID of the owner of the Amazon S3 bucket. Yes Type: String Default: None A Base64-encoded Amazon S3 upload policy that gives Yes Amazon EC2 permission to upload items into Amazon S3 on your behalf. Type: String Default: None The signature of the Base64 encoded JSON document. Type: String Default: None Yes

Storage.S3.UploadPol icy

Storage.S3.UploadPol icySignature

API Version 2012-05-01 38

Amazon Elastic Compute Cloud API Reference JSON Parameters

JSON Parameters
The upload policy gives Amazon EC2 limited permission to upload items into your Amazon S3 bucket. The following table describes the required parameters for the upload policy JSON document. Parameter names are case sensitive. For more information about upload policies and how to sign them, go to the sections about policy construction and signatures in the Amazon Simple Storage Service Developer Guide. Name
expiration

Description

Required

The expiration of the policy. We recommend 12 hours Yes or longer. A list of restrictions on what can be uploaded to Amazon S3. Must contain the bucket and ACL conditions in this table. The bucket to store the AMI. This must be set to ec2-bundle-read. Yes

conditions

bucket acl

Yes Yes

Response Elements
The elements in the following table are wrapped in a BundleInstanceResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Bundle task. Type: BundleInstanceTaskType (p. 392)

bundleInstanceTask

Examples
Example Request
This example bundles the i-e468cd8d instance.
https://ec2.amazonaws.com/?Action=BundleInstance &InstanceId=i-e468cd8d &Storage.S3.AWSAccessKeyId='AKIAIOSFODNN7EXAMPLE' &Storage.S3.Bucket=myawsbucket &Storage.S3.Prefix=winami &Storage.S3.UploadPolicy=eyJleHBpcmF0aW9uIjogIjIwMDgtMDgtMzBUMDg6NDk6MDlaIi wiY29uZGl0aW9ucyI6IFt7ImJ1Y2tldCI6ICJteS1idWNrZXQifSxbInN0YXJ0cy13aXRoIiwgIiR rZXkiLCAibXktbmV3LWltYWdlIl0seyJhY2wiOiAiZWMyLWJ1bmRsZS1yZWFkIn1dfEXAMPLE &Storage.S3.UploadPolicySignature=fh5tyyyQD8W4COEthj3nlGNEXAMPLE &AUTHPARAMS

API Version 2012-05-01 39

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<BundleInstanceResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <bundleInstanceTask> <instanceId>i-12345678</instanceId> <bundleId>bun-c1a540a8</bundleId> <state>bundling</state> <startTime>2008-10-07T11:41:50.000Z</startTime> <updateTime>2008-10-07T11:51:50.000Z</updateTime> <progress>70%</progress> <storage> <S3> <bucket>myawsbucket</bucket> <prefix>winami</prefix> </S3> </storage> </bundleInstanceTask> </BundleInstanceResponse>

Related Operations
CancelBundleTask (p. 41) DescribeBundleTasks (p. 147) CreateImage (p. 56)

API Version 2012-05-01 40

Amazon Elastic Compute Cloud API Reference CancelBundleTask

CancelBundleTask
Description
Cancels a bundling operation for an Amazon S3-backed Windows instance (see BundleInstance (p. 38)).

Request Parameters
Name
BundleId

Description The ID of the bundle task to cancel. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a CancelBundleTaskResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Bundle task to cancel. Type: BundleInstanceTaskType (p. 392)

bundleInstanceTask

Examples
Example Request
This example cancels the bun-cla322b9 bundle task.
https://ec2.amazonaws.com/?Action=CancelBundleTask &BundleId=bun-cla322b9 &AUTHPARAMS

Example Response
<CancelBundleTaskResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <bundleInstanceTask> <instanceId>i-12345678</instanceId> <bundleId>bun-cla322b9</bundleId> <state>canceling</state> <startTime>2008-10-07T11:41:50.000Z</startTime> <updateTime>2008-10-07T11:51:50.000Z</updateTime> <progress>20%</progress>

API Version 2012-05-01 41

Amazon Elastic Compute Cloud API Reference Related Operations

<storage> <S3> <bucket>myawsbucket</bucket> <prefix>my-new-image</prefix> </S3> </storage> </bundleInstanceTask> </CancelBundleTaskResponse>

Related Operations
BundleInstance (p. 38) DescribeBundleTasks (p. 147)

API Version 2012-05-01 42

Amazon Elastic Compute Cloud API Reference CancelConversionTask

CancelConversionTask
Description
Cancels an active conversion task. The task can be the import of an instance or volume. The command removes all artifacts of the conversion, including a partially uploaded volume or instance. If the conversion is complete or is in the process of transferring the final disk image, the command fails and returns an exception. For more information, go to Using the Command Line Tools to Import Your Virtual Machine to Amazon EC2 in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
ConversionTaskId

Description The ID of the task you want to cancel. Type: String Default: None

Required Yes

Response Elements
Name
requestId

Description ID of the request. Type: string Specifies whether the cancellation was successful or not. Type: Boolean

return

Examples
Example Request
This example cancels the conversion task with ID import-i-fh95npoc.
https://ec2.amazonaws.com/?Action=CancelConversionTask &ConversionTaskId=import-i-fh95npoc &AUTHPARAMS

Example Response
<CancelConversionTaskResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </CancelConversionTaskResponse>

API Version 2012-05-01 43

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
ImportInstance (p. 301) ImportVolume (p. 307) DescribeConversionTasks (p. 150)

API Version 2012-05-01 44

Amazon Elastic Compute Cloud API Reference CancelExportTask

CancelExportTask
Description
Cancels an active export task. The command removes all artifacts of the export, including any partially created Amazon S3 objects. If the export task is complete or is in the process of transferring the final disk image, the command fails and returns an error.

Request Parameters
Name
ExportTaskId

Description The ID of the export task you want to cancel. Type: String Default: None

Required Yes

Response Elements
Name
requestId

Description ID of the request. Type: string Specifies whether the cancellation was successful or not. Type: Boolean

return

Examples
Example Request
This example cancels the export task with ID export-i-1234wxyz.
https://ec2.amazonaws.com/?Action=CancelExportTask &exportTaskId=export-i-1234wxyz &AUTHPARAMS

Example Response
<CancelExportTask xmlns="http://ec2.amazonaws.com/doc/EC2UserGuide"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </CancelExportTask>

Related Operations
CreateInstanceExportTask (p. 58)

API Version 2012-05-01 45

Amazon Elastic Compute Cloud API Reference Related Operations

DescribeExportTasks (p. 159)

API Version 2012-05-01 46

Amazon Elastic Compute Cloud API Reference CancelSpotInstanceRequests

CancelSpotInstanceRequests
Description
Cancels one or more Spot Instance requests. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current Spot Instance requests. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide.

Important
Canceling a Spot Instance request does not terminate running Spot Instances associated with the request.

Request Parameters
Name
SpotInstanceRequestI d.n

Description One or more Spot Instance request IDs. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a CancelSpotInstanceRequestsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of Spot Instance requests. Each request is wrapped in an item element. Type: CancelSpotInstanceRequestsResponseSetItemType (p. 393)

spotInstanceRequestSet

Examples
Example Request
This example cancels a Spot Instance request.
https://ec2.amazonaws.com/?Action=CancelSpotInstanceRequests &SpotInstanceRequestId.1=sir-e95fae02 &AUTHPARAMS

API Version 2012-05-01 47

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<CancelSpotInstanceRequestsResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <spotInstanceRequestSet> <item> <spotInstanceRequestId>sir-e95fae02</spotInstanceRequestId> <state>cancelled</state> </item> </spotInstanceRequestSet></CancelSpotInstanceRequestsResponse>

Related Operations
DescribeSpotInstanceRequests (p. 242) RequestSpotInstances (p. 346) DescribeSpotPriceHistory (p. 248)

API Version 2012-05-01 48

Amazon Elastic Compute Cloud API Reference ConfirmProductInstance

ConfirmProductInstance
Description
Verifies whether a product code is associated with an instance. This can only be executed by the owner of the product code and is useful when a product code owner wants to verify whether another EC2 users instance is eligible for support.

Request Parameters
Name
ProductCode

Description The product code to confirm. Type: String Default: None The instance to confirm. Type: String Default: None

Required Yes

InstanceId

Yes

Response Elements
The elements in the following table are wrapped in a ConfirmProductInstanceResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the product code is attached to the instance. Otherwise, returns an error. Type: xsd:boolean The instance owner's account ID. Only present if the product code is attached to the instance. Type: xsd:string

return

ownerId

Examples
Example Request
This example displays the product code that is associated with the instance.
https://ec2.amazonaws.com/?Action=ConfirmProductInstance &ProductCode=774F4FF8 &InstanceId=i-10a64379 &AUTHPARAMS

API Version 2012-05-01 49

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<ConfirmProductInstanceResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> <ownerId>111122223333</ownerId> </ConfirmProductInstanceResponse>

Related Operations
DescribeInstances (p. 175) RunInstances (p. 366)

API Version 2012-05-01 50

Amazon Elastic Compute Cloud API Reference CreateCustomerGateway

CreateCustomerGateway
Description
Provides information to AWS about your VPN customer gateway device. The customer gateway is the appliance at your end of the VPN connection (compared to the virtual private gateway, which is the device at the AWS side of the VPN connection). You must provide the Internet-routable IP address of the customer gateway's external interface. The IP address must be static and can't be behind a device performing network address translation (NAT). You must also provide the device's Border Gateway Protocol (BGP) Autonomous System Number (ASN). You can use an existing ASN assigned to your network. If you don't have an ASN already, you can use a private ASN (in the 64512 - 65534 range).

Note
Amazon EC2 supports all 2-byte ASN numbers in the range of 1 - 65534, with the exception of 7224, which is reserved in US East, and 9059, which is reserved in EU West.

For more information about ASNs, go to the Wikipedia article. For more information about Amazon Virtual Private Cloud and VPN customer gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
Type

Description

Required

The type of VPN connection this customer gateway Yes supports. Type: String Default: None Valid Values: ipsec.1 The Internet-routable IP address for the customer Yes gateway's outside interface. The address must be static. Type: String Default: None The customer gateway's Border Gateway Protocol Yes (BGP) Autonomous System Number (ASN). Type: Integer Default: None

IpAddress

BgpAsn

Response Elements
The elements in the following table are wrapped in an CreateCustomerGatewayResponse structure.

API Version 2012-05-01 51

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string Information about the customer gateway. Type: CustomerGatewayType (p. 395)

customerGateway

Examples
Example Request
This example passes information to AWS about the VPN customer gateway with IP address 12.1.2.3 and ASN 65534.
https://ec2.amazonaws.com/?Action=CreateCustomerGateway &Type=ipsec.1 &IpAddress=12.1.2.3 &BgpAsn=65534 &AUTHPARAMS

Example Response
<CreateCustomerGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <customerGateway> <customerGatewayId>cgw-b4dc3961</customerGatewayId> <state>pending</state> <type>ipsec.1</type> <ipAddress>12.1.2.3</ipAddress> <bgpAsn>65534</bgpAsn> <tagSet/> </customerGateway> </CreateCustomerGatewayResponse>

Related Operations
DescribeCustomerGateways (p. 152) DeleteCustomerGateway (p. 100)

API Version 2012-05-01 52

Amazon Elastic Compute Cloud API Reference CreateDhcpOptions

CreateDhcpOptions
Description
Creates a set of DHCP options for your VPC. After creating the new set, you must then associate it with the VPC, causing all existing and new instances that you launch in the VPC to use the new set of DHCP options. The following table lists the individual DHCP options you can specify. For more information about the options, go to RFC 2132. DHCP Option Name domain-name domain-name-servers Description A domain name of your choice (e.g., example.com). The IP address of a domain name server. You can specify up to four addresses. The IP address of a Network Time Protocol (NTP) server. You can specify up to four addresses. The IP address of a NetBIOS name server. You can specify up to four addresses. Value indicating the NetBIOS node type (1, 2, 4, or 8). For more information about the values, go to RFC 2132. We recommend you only use 2 at this time (broadcast and multicast are currently not supported).

ntp-servers

netbios-name-servers

netbios-node-type

Important
Your VPC automatically starts out with a set of DHCP options that includes only a DNS server that we provide (AmazonProvidedDNS). If you create a new set of options, and if your VPC has an Internet gateway, make sure to set the domain-name-servers option either to AmazonProvidedDNS or to a domain name server of your choice.

For more information about Amazon Virtual Private Cloud and DHCP options, go to Using DHCP Options in Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
DhcpConfiguration.n.Key

Description The name of a DHCP option. Type: String Default: None

Required Yes

DhcpConfiguration.n.Value.m A value for the DHCP option. Type: String Default: None

Yes

API Version 2012-05-01 53

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in an CreateDhcpOptionsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Set of DHCP options. Type: DhcpOptionsType (p. 404)

dhcpOptions

Examples
Example Request
This example creates a new set of DHCP options with a domain name example.com and two DNS servers (10.2.5.1 and 10.2.5.2).
https://ec2.amazonaws.com/?Action=CreateDhcpOptions &DhcpConfiguration.1.Key=domain-name &DhcpConfiguration.1.Value.1=example.com &DhcpConfiguration.2.Key=domain-name-servers &DhcpConfiguration.2.Value.1=10.2.5.1 &DhcpConfiguration.2.Value.2=10.2.5.2 &AUTHPARAMS

Example Response
<CreateDhcpOptionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <dhcpOptions> <dhcpOptionsId>dopt-7a8b9c2d</dhcpOptionsId> <dhcpConfigurationSet> <item> <key>domain-name</key> <valueSet> <item> <value>example.com</value> </item> </valueSet> </item> <item> <key>domain-name-servers</key> <valueSet> <item> <value>10.2.5.1</value> </item> <item> <value>10.2.5.2</value> </item> </valueSet>

API Version 2012-05-01 54

Amazon Elastic Compute Cloud API Reference Related Operations

</item> </dhcpConfigurationSet> <tagSet/> </dhcpOptions> </CreateDhcpOptionsResponse>

Related Operations
AssociateDhcpOptions (p. 18) DescribeDhcpOptions (p. 155) DeleteDhcpOptions (p. 102)

API Version 2012-05-01 55

Amazon Elastic Compute Cloud API Reference CreateImage

CreateImage
Description
Creates an Amazon EBS-backed AMI from an Amazon EBS-backed instance that is in either the running or stopped state. For more information about Amazon EBS-backed AMIs, go to Using Amazon EBS-Backed AMIs and Instances.

Note
If you customized your instance with ephemeral storage devices or additional EBS volumes besides the root device, the new AMI contains block device mapping information for those storage devices and volumes. When you then launch an instance from your new AMI, the instance automatically launches with the additional devices and volumes.

Request Parameters
Name
InstanceId

Description The ID of the instance. Type: String Default: None

Required Yes

Name

A name for the new image you're creating. Yes Type: String Default: None Constraints: 3-128 alphanumeric characters, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_) A description of the new image. Type: String Default: None Constraints: Up to 255 characters No

Description

NoReboot

By default this parameter is set to false, which means No Amazon EC2 attempts to cleanly shut down the instance before image creation and reboots the instance afterwards. When the parameter is set to true, Amazon EC2 does not shut down the instance before creating the image. When this option is used, file system integrity on the created image cannot be guaranteed. Type: Boolean Default: false

Response Elements
The elements in the following table are wrapped in a CreateImageResponse structure.

API Version 2012-05-01 56

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string The ID of the AMI. Type: xsd:string

imageId

Examples
Example Request
This example creates an AMI from the i-10a64379 instance.
https://ec2.amazonaws.com/?Action=CreateImage &Description=Standard+Web+Server+v1.0 &InstanceId=i-10a64379 &Name=standard-web-server-v1.0 &AUTHPARAMS

Example Response
<CreateImageResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <imageId>ami-4fa54026</imageId> </CreateImageResponse>

Related Operations
RunInstances (p. 366) DescribeInstances (p. 175) TerminateInstances (p. 380)

API Version 2012-05-01 57

Amazon Elastic Compute Cloud API Reference CreateInstanceExportTask

CreateInstanceExportTask
Description
Creates a new export task, produces an image of an EC2 instance for use in another virtualization environment, and then writes the image to the specified Amazon S3 bucket. If the instance is running at the time of export, Amazon EC2 will attempt to shut down the instance, initiate the export process, and then reboot the instance. Only instances derived from your own ImportInstance tasks may be exported. When the task is complete, the image can be downloaded from your Amazon S3 bucket.

Request Parameters
Name
Description

Description Description of the conversion task or the resource being exported. Type: String Default: None The ID of the instance being exported. Type: String Default: None The target virtualization environment. Type: String Default: None Valid Values: vmware | citrix | microsoft The format for the exported image. Type: String Default: vmdk if TargetEnvironment = vmware, otherwise vhd Valid Values: vmdk | vhd

Required No

InstanceId

Yes

TargetEnvironment

Yes

ExportToS3.DiskImage Format

No

ExportToS3.Container Format

The container format used to combine disk images with No metadata (such as OVF). If absent, only the disk image will be exported. Type: String Default: ova if TargetEnvironment = vmare, otherwise blank Valid Values: ova The Amazon S3 bucket for the destination image. The bucket must exist and grant write permissions to AWS account [email protected]. Type: String Default: None Yes

ExportToS3.S3Bucket

API Version 2012-05-01 58

Amazon Elastic Compute Cloud API Reference Response Elements

Name
ExportToS3.S3Prefix

Description The image is written to a single object in the Amazon S3 bucket at the S3 key s3prefix + exportTaskId + . +diskImageFormat. Type: String Default: None

Required No

Response Elements
The elements in the following table are wrapped in a CreateInstanceExportTaskResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The details of the created ExportVM task. Type: ExportTaskResponseType (p. 409)

exportTask

Examples
Example Request
This example creates an Export VM task that makes a Windows instance available as an OVA.
https://ec2.amazonaws.com/?Action=CreateInstanceExportTask &Description=Example%20for%20docs &InstanceId=i-12345678 &TargetEnvironment=VMWare &ExportToS3.DiskImageFormat=VMDK &ExportToS3.ContainerFormat=OVA &ExportToS3.S3bucket=my-bucket-for-exported-vm &ExportToS3.S3prefix=my-exports/ &AUTHPARAMS

Example Response
<CreateInstanceExportTaskResponse xmlns="http://ec2.amazonaws.com/doc/2020-0202/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <exportTask> <exportTaskId>export-i-1234wxyz</exportTaskId> <description>Example for docs</description> <state>active</state> <statusMessage>Running</statusMessage> <instanceExport> <instanceId>i-12345678</ instanceId > <targetEnvironment>VMWare</ targetEnvironment > </instanceExport>

API Version 2012-05-01 59

Amazon Elastic Compute Cloud API Reference Related Operations

<exportToS3> <diskImageFormat >VMDK</ diskImageFormat > <containerFormat>OVA</ containerFormat> <s3bucket>my-bucket-for-exported-vm</s3bucket> <s3Key>my-exports/ export-i-1234wxyz .ova</s3Key> </exportToS3> </exportTask> </CreateInstanceExportTaskResponse >

Related Operations
CancelExportTask (p. 45) DescribeExportTasks (p. 159)

API Version 2012-05-01 60

Amazon Elastic Compute Cloud API Reference CreateInternetGateway

CreateInternetGateway
Description
Creates a new Internet gateway in your AWS account. After creating the Internet gateway, you then attach it to a VPC using AttachInternetGateway. For more information about your VPC and Internet gateway, go to Amazon Virtual Private Cloud User Guide.

Request Parameters
This action has no request parameters.

Response Elements
The elements in the following table are wrapped in a CreateInternetGatewayResponse structure. Name
requestId

Description The ID of the request. Type: String Information about the Internet gateway Type: InternetGatewayType (p. 427)

internetGateway

Examples
Example Request
This example creates an Internet gateway.
https://ec2.amazonaws.com/?Action=CreateInternetGateway &AUTHPARAMS

Example Response
CreateInternetGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <internetGateway> <internetGatewayId>igw-eaad4883</internetGatewayId> <attachmentSet/> <tagSet/> </internetGateway> </CreateInternetGatewayResponse>

Related Operations
DeleteInternetGateway (p. 104)

API Version 2012-05-01 61

Amazon Elastic Compute Cloud API Reference Related Operations

AttachInternetGateway (p. 22) DetachInternetGateway (p. 283) DescribeInternetGateways (p. 192)

API Version 2012-05-01 62

Amazon Elastic Compute Cloud API Reference CreateKeyPair

CreateKeyPair
Description
Creates a new 2048-bit RSA key pair with the specified name. The public key is stored by Amazon EC2 and the private key is returned to you. The private key is returned as an unencrypted PEM encoded PKCS#8 private key. If a key with the specified name already exists, Amazon EC2 returns an error.

Tip
The key pair returned to you works only in the Region you're using when you create the key pair. If you'd like to create a key pair that works in all Regions, see ImportKeyPair (p. 305).

Request Parameters
Name
KeyName

Description A unique name for the key pair. Type: String Default: None Constraints: Accepts alphanumeric characters, spaces, dashes, and underscores.

Required Yes

Response Elements
The elements in the following table are wrapped in a CreateKeyPairResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The key pair name you provided. Type: xsd:string A SHA-1 digest of the DER encoded private key. Type: xsd:string An unencrypted PEM encoded RSA private key. Type: xsd:string

keyName

keyFingerprint

keyMaterial

Examples
Example Request
This example creates a key pair named gsg-keypair.

API Version 2012-05-01 63

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=CreateKeyPair &KeyName=gsg-keypair &AUTHPARAMS

Example Response
<CreateKeyPairResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <keyName>gsg-keypair</keyName> <keyFingerprint> 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 </keyFingerprint> <keyMaterial>-----BEGIN RSA PRIVATE KEY----MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6 b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ 21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4 nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE= -----END RSA PRIVATE KEY----</keyMaterial> </CreateKeyPairResponse>

Related Operations
RunInstances (p. 366) DescribeKeyPairs (p. 195) DeleteKeyPair (p. 106)

API Version 2012-05-01 64

Amazon Elastic Compute Cloud API Reference CreateNetworkAcl

CreateNetworkAcl
Description
Creates a new network ACL in a VPC. Network ACLs provide an optional layer of security (on top of security groups) for the instances in your VPC. For more information about network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpcId

Description

Required

The ID of the VPC where the network ACL will Yes be created. Type: String Default: None

Response Elements
The elements in the following table are wrapped in a CreateNetworkAclResponse structure. Name
requestId

Description The ID of the request. Type: String Information about the new network ACL. Type: NetworkAclType (p. 434)

networkAcl

Examples
Example Request
The example creates a new network ACL in the VPC with ID vpc-11ad4878. Notice that the response includes a default entry for egress, and another for ingress, each with a very high rule number. These are the last entries Amazon VPC processes to decide whether traffic is allowed in our out of an associated subnet. If the traffic doesn't match any rules with a lower rule number, then these default entries ultimately deny the traffic.
https://ec2.amazonaws.com/?Action=CreateNetworkAcl &VpcId=vpc-11ad4878 &AUTHPARAMS

Example Response
<CreateNetworkAclResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>

API Version 2012-05-01 65

Amazon Elastic Compute Cloud API Reference Related Operations

<networkAcl> <networkAclId>acl-5fb85d36</networkAclId> <vpcId>vpc-11ad4878</vpcId> <default>false</default> <entrySet> <item> <ruleNumber>32767</ruleNumber> <protocol>all</protocol> <ruleAction>deny</ruleAction> <egress>true</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> <item> <ruleNumber>32767</ruleNumber> <protocol>all</protocol> <ruleAction>deny</ruleAction> <egress>false</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> </entrySet> <associationSet/> <tagSet/> </networkAcl> </CreateNetworkAclResponse>

Related Operations
DeleteNetworkAcl (p. 108) DescribeNetworkAcls (p. 198) ReplaceNetworkAclAssociation (p. 334)

API Version 2012-05-01 66

Amazon Elastic Compute Cloud API Reference CreateNetworkAclEntry

CreateNetworkAclEntry
Description
Creates an entry (i.e., rule) in a network ACL with a rule number you specify. Each network ACL has a set of numbered ingress rules and a separate set of numbered egress rules. When determining whether a packet should be allowed in or out of a subnet associated with the ACL, Amazon VPC processes the entries in the ACL according to the rule numbers, in ascending order.

Important
We recommend that you leave room between the rule numbers (e.g., 100, 110, 120, etc.), and not number them one right after the other (e.g., 101, 102, 103, etc.). This allows you to easily add a new rule between existing ones without having to renumber the rules.

After you add an entry, you can't modify it; you must either replace it, or create a new entry and delete the old one. For more information about network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
NetworkAclId

Description ID of the ACL where the entry will be created. Type: String Default: None Rule number to assign to the entry (e.g., 100). ACL entries are processed in ascending order by rule number. Type: Integer Default: None Constraints: Positive integer from 1 to 32766

Required Yes

RuleNumber

Yes

Protocol

IP protocol the rule applies to.You can use -1 to mean Yes all protocols. Type: Integer Valid Values: -1 or a protocol number (go to Protocol Numbers). Whether to allow or deny traffic that matches the rule. Yes Type: String Default: None Valid Values: allow | deny

RuleAction

API Version 2012-05-01 67

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Egress

Description

Required

Whether this rule applies to egress traffic from the No subnet (true) or ingress traffic to the subnet (false). Type: Boolean Default: false Valid Values: true | false The CIDR range to allow or deny, in CIDR notation (e.g., 172.16.0.0/24). Type: String Default: None Yes

CidrBlock

Icmp.Code

For the ICMP protocol, the ICMP code. You can use Conditional -1 to specify all ICMP codes for the given ICMP type. Type: Integer Default: None Condition: Required if specifying 1 (ICMP) for the protocol. For the ICMP protocol, the ICMP type. You can use -1 to specify all ICMP types. Type: Integer Default: None Condition: Required if specifying 1 (ICMP) for the protocol. Conditional

Icmp.Type

PortRange.From

The first port in the range. Conditional Type: Integer Default: None Condition: Required if specifying 6 (TCP) or 17 (UDP) for the protocol. The last port in the range. Conditional Type: Integer Default: None Condition: Required if specifying 6 (TCP) or 17 (UDP) for the protocol.

PortRange.To

Response Elements
The elements in the following table are wrapped in a CreateNetworkAclEntryResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

API Version 2012-05-01 68

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example creates an entry with rule number 110 in the network ACL with ID acl-2cb85d45. The rule allows ingress traffic from anywhere (0.0.0.0/0) on UDP port 53 into any associated subnet.
https://ec2.amazonaws.com/?Action=CreateNetworkAclEntry &NetworkAclId=acl-2cb85d45 &RuleNumber=110 &Protocol=udp &RuleAction=allow &Egress=false &CidrBlock=0.0.0.0/0 &PortRange.From=53 &PortRange.To=53 &AUTHPARAMS

Example Response
<CreateNetworkAclEntryResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </CreateNetworkAclEntryResponse>

Related Operations
DeleteNetworkAclEntry (p. 110) ReplaceNetworkAclEntry (p. 336) DescribeNetworkAcls (p. 198)

API Version 2012-05-01 69

Amazon Elastic Compute Cloud API Reference CreateNetworkInterface

CreateNetworkInterface
Description
Creates a network interface in the specified subnet.

Request Parameters
Name
SubnetId

Description The ID of the subnet to associate with the network interface. Type: String Default: None

Required Yes

PrivateIpAddress

The private IP address of the network interface. No Type: String Default: None The description of the network interface. Type: String Default: None Lists the group IDs for use by the network interface. Type: SecurityGroupIdSetItemType (p. 451) Default: None No

Description

SecurityGroupId.n

No

Response Elements
The elements in the following table are wrapped in an CreateNetworkInterface structure. Name
requestId

Description The ID of the request to create a network interface. Type: String The network interface that was created. Type: NetworkInterfaceType (p. 438)

networkInterface

Examples
Example Request
This example creates an elastic network interface (ENI) in the specified subnet.

API Version 2012-05-01 70

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=CreateNetworkInterface &SubnetId=subnet-b2a249da &AUTHPARAMS

Example Response
<CreateNetworkInterfaceResponse xmlns='http://ec2.amazonaws.com/doc/2011-1115/'> <requestId>86c6c651-be3a-4bec-83d7-711ee24c515f</requestId> <networkInterface> <networkInterfaceId>eni-ffda3197</networkInterfaceId> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <availabilityZone>us-east-1b</availabilityZone> <description/> <ownerId>111122223333</ownerId> <requesterManaged>false</requesterManaged> <status>pending</status> <macAddress>06:01:92:a4:43:77</macAddress> <privateIpAddress>10.0.0.182</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <tagSet/> </networkInterface> </CreateNetworkInterfaceResponse>

Related Operations
AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205)

ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 71

Amazon Elastic Compute Cloud API Reference CreatePlacementGroup

CreatePlacementGroup
Description
Creates a placement group that you launch cluster instances into.You must give the group a name unique within the scope of your account. For more information about placement groups and cluster instances, go to Using Cluster Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
GroupName

Description A name for the placement group. Type: string Default: None The placement group strategy. Type: string Valid Values: cluster

Required Yes

Strategy

Yes

Response Elements
The elements in the following table are wrapped in a CreatePlacementGroupResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example creates a placement group named XYZ-cluster.
https://ec2.amazonaws.com/?Action=CreatePlacementGroup &GroupName=XYZ-cluster &Strategy=cluster &AUTHPARAMS

Example Response
<CreatePlacementGroupResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/">

API Version 2012-05-01 72

Amazon Elastic Compute Cloud API Reference Related Operations

<requestId>d4904fd9-82c2-4ea5-adfe-a9cc3EXAMPLE</requestId> <return>true</return> </CreatePlacementGroupResponse>

Related Operations
DeletePlacementGroup (p. 114) DescribePlacementGroups (p. 211)

API Version 2012-05-01 73

Amazon Elastic Compute Cloud API Reference CreateRoute

CreateRoute
Description
Creates a new route in a route table within a VPC. The route's target can be either a gateway attached to the VPC or a NAT instance in the VPC. When determining how to route traffic, we use the route with the most specific match. For example, let's say the traffic is destined for 192.0.2.3, and the route table includes the following two routes: 192.0.2.0/24 (goes to some target A) 192.0.2.0/28 (goes to some target B) Both routes apply to the traffic destined for 192.0.2.3. However, the second route in the list covers a smaller number of IP addresses and is therefore more specific, so we use that route to determine where to target the traffic. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
RouteTableId

Description The ID of the route table where the route will be added. Type: String Default: None The CIDR address block used for the destination match. For example: 0.0.0.0/0. Routing decisions are based on the most specific match. Type: String Default: None The ID of a gateway attached to your VPC. Type: String Default: None Condition: You must provide only one of the following: a GatewayID, InstanceID, or NetworkInterfaceId. The ID of a NAT instance in your VPC. Type: String Default: None Condition: You must provide only one of the following: a GatewayID, InstanceID, or NetworkInterfaceId.

Required Yes

DestinationCidrBlock

Yes

GatewayId

Conditional

InstanceId

Conditional

API Version 2012-05-01 74

Amazon Elastic Compute Cloud API Reference Response Elements

Name
NetworkInterfaceId

Description Allows the routing of network interface IDs. Exactly one interface must be attached when specifying an instance ID or it will fail. Type: String Default: None Condition: You must provide only one of the following: a GatewayID, InstanceID, or NetworkInterfaceId.

Required Conditional

Response Elements
The elements in the following table are wrapped in a CreateRouteResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example creates a route in the route table with ID rtb-e4ad488d.The route matches all traffic (0.0.0.0/0) and routes it to the Internet gateway with ID igw-eaad4883.
https://ec2.amazonaws.com/?Action=CreateRoute &RouteTableId=rtb-e4ad488d &DestinationCidrBlock=0.0.0.0/0 &GatewayId=igw-eaad4883 &AUTHPARAMS

Example Request
This example creates a route in the route table with ID rtb-g8ff4ea2. The route sends all traffic (0.0.0.0/0) to the NAT instance with ID i-1a2b3c4d.
https://ec2.amazonaws.com/?Action=CreateRoute &RouteTableId=rtb-g8ff4ea2 &DestinationCidrBlock=0.0.0.0/0 &InstanceId=i-1a2b3c4d &AUTHPARAMS

API Version 2012-05-01 75

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<CreateRouteResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </CreateRouteResponse>

Related Operations
DeleteRoute (p. 116) ReplaceRoute (p. 339) DescribeRouteTables (p. 225)

API Version 2012-05-01 76

Amazon Elastic Compute Cloud API Reference CreateRouteTable

CreateRouteTable
Description
Creates a new route table within a VPC. After you create a new route table, you can add routes and associate the table with a subnet. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpcId

Description The ID of the VPC where the route table will be created. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a CreateRouteTableResponse structure. Name
requestId

Description Unique identifier for the request received. Type: String Information about the newly created route table. Type: RouteTableType (p. 447)

routeTable

Examples
Example Request
This example creates a route table within the VPC with ID of vpc-11ad4878.
https://ec2.amazonaws.com/?Action=CreateRouteTable &VpcId=vpc-11ad4878 &AUTHPARAMS

Example Response
By default, every route table includes a local route that enables traffic to flow within the VPC. The following response shows that route.
CreateRouteTableResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01 /"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <routeTable>

API Version 2012-05-01 77

Amazon Elastic Compute Cloud API Reference Related Operations

<routeTableId>rtb-f9ad4890</routeTableId> <vpcId>vpc-11ad4878</vpcId> <routeSet> <item> <destinationCidrBlock>10.0.0.0/22</destinationCidrBlock> <gatewayId>local</gatewayId> <state>active</state> </item> </routeSet> <associationSet/> <tagSet/> </routeTable> </CreateRouteTableResponse>

Related Operations
AssociateRouteTable (p. 20) DisassociateRouteTable (p. 293) DescribeRouteTables (p. 225) DeleteRouteTable (p. 118) ReplaceRouteTableAssociation (p. 341) CreateRoute (p. 74)

API Version 2012-05-01 78

Amazon Elastic Compute Cloud API Reference CreateSecurityGroup

CreateSecurityGroup
Description
Creates a new security group. You can create either an EC2 security group (which works only with EC2), or a VPC security group (which works only with Amazon Virtual Private Cloud). The two types of groups have different capabilities. For information about VPC security groups and how the two types of groups differ, go to Security Groups in the Amazon Virtual Private Cloud User Guide. For information about EC2 security groups, go to Using Security Groups in the Amazon Elastic Compute Cloud User Guide. When you create a security group, you give it a friendly name of your choice. You can have an EC2 security group with the same name as a VPC security group (each group has a unique security group ID separate from the name). Two standard groups can't have the same name, and two VPC groups can't have the same name. If you don't specify a security group when you launch an instance, the instance is launched into the default security group. This group (and only this group) includes a default rule that gives the instances in the group unrestricted network access to each other. You have a default EC2 security group for instances you launch with EC2 (i.e., outside a VPC), and a default VPC security group for instances you launch in your VPC. You can add or remove rules from your security groups (i.e., authorize or revoke permissions) using the AuthorizeSecurityGroupIngress, AuthorizeSecurityGroupEgress, RevokeSecurityGroupIngress, and RevokeSecurityGroupEgress actions.

Important
For EC2 security groups: You can have up to 500 groups. For VPC security groups: You can have up to 50 groups per VPC.

Request Parameters
Name
GroupName

Description Name of the security group. Type: String Default: None Constraints: Accepts alphanumeric characters, spaces, dashes, and underscores. Description of the group. This is informational only. Type: String Default: None Constraints: Accepts alphanumeric characters, spaces, dashes, and underscores. ID of the VPC. Type: String Default: None Condition: Required for VPC security groups

Required Yes

GroupDescription

Yes

VpcId

Conditional

API Version 2012-05-01 79

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a CreateSecurityGroupResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean ID that AWS assigns to the security group. Type: xsd:string

return

groupId

Examples
Example Request
This example creates the websrv security group.
https://ec2.amazonaws.com/?Action=CreateSecurityGroup &GroupName=websrv &GroupDescription=Web Servers &AUTHPARAMS

Example Response
<CreateSecurityGroupResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> <groupId>sg-1a2b3c4d</groupId> </CreateSecurityGroupResponse>

Related Operations
RunInstances (p. 366) DescribeSecurityGroups (p. 229) AuthorizeSecurityGroupIngress (p. 34) RevokeSecurityGroupIngress (p. 363) DeleteSecurityGroup (p. 120)

API Version 2012-05-01 80

Amazon Elastic Compute Cloud API Reference CreateSnapshot

CreateSnapshot
Description
Creates a snapshot of an Amazon EBS volume and stores it in Amazon S3. You can use snapshots for backups, to make identical copies of instance devices, and to save data before shutting down an instance. For more information about Amazon EBS, go to the Using Amazon Elastic Block Store. When a snapshot is created, any AWS Marketplace product codes from the volume will be propagated to the snapshot. When taking a snapshot of a file system, we recommend unmounting it first. This ensures the file system metadata is in a consistent state, that the 'mounted indicator' is cleared, and that all applications using that file system are stopped and in a consistent state. Some file systems, such as xfs, can freeze and unfreeze activity so a snapshot can be made without unmounting. For Linux/UNIX, enter the following command from the command line to unmount the volume.
umount -d device_name

For example:
umount -d /dev/sdh

For Windows, open Disk Management, right-click the volume to unmount, and select Change Drive Letter and Path. Then, select the mount point to remove and click Remove.

Request Parameters
Name
VolumeId

Description The ID of the Amazon EBS volume of which to take a snapshot. Type: String Default: None Description of the Amazon EBS snapshot. Type: String Default: None Constraints: Up to 255 characters

Required Yes

Description

No

Response Elements
The elements in the following table are wrapped in a CreateSnapshotResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string

API Version 2012-05-01 81

Amazon Elastic Compute Cloud API Reference Examples

Name
snapshotId

Description The ID of the snapshot. Type: xsd:string The ID of the volume. Type: xsd:string Snapshot state Type: xsd:string Valid Values: pending | completed | error Time stamp when the snapshot was initiated. Type: xsd:dateTime The progress of the snapshot, in percentage. Type: xsd:string The AWS account ID of the Amazon EBS snapshot owner. Type: xsd:string The size of the volume, in GiB. Type: xsd:string Description of the snapshot. Type: xsd:string

volumeId

status

startTime

progress

ownerId

volumeSize

description

Examples
Example Request
This example creates a snapshot of volume vol-4d826724.
https://ec2.amazonaws.com/?Action=CreateSnapshot &VolumeId=vol-4d826724 &Description=Daily+Backup &AUTHPARAMS

Example Response
<CreateSnapshotResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <snapshotId>snap-78a54011</snapshotId> <volumeId>vol-4d826724</volumeId> <status>pending</status> <startTime>2008-05-07T12:51:50.000Z</startTime> <progress>60%</progress> <ownerId>111122223333</ownerId> <volumeSize>10</volumeSize> <description>Daily Backup</description> </CreateSnapshotResponse>

API Version 2012-05-01 82

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
DeleteSnapshot (p. 122) DescribeSnapshots (p. 235)

API Version 2012-05-01 83

Amazon Elastic Compute Cloud API Reference CreateSpotDatafeedSubscription

CreateSpotDatafeedSubscription
Description
Creates the datafeed for Spot Instances, enabling you to view Spot Instance usage logs. You can create one data feed per account. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
Bucket

Description

Required

The Amazon S3 bucket in which to store the Spot Instance Yes datafeed. Type: String Default: None Constraints: Must be a valid bucket associated with your account. Prefix that is prepended to datafeed files. Type: String Default: None No

Prefix

Response Elements
The elements in the following table are wrapped in a CreateSpotDatafeedSubscriptionResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string

spotDatafeedSubscription Datafeed subscription. Type: SpotDatafeedSubscriptionType (p. 453)

Examples
Example Request
This example creates the data feed for the account.
https://ec2.amazonaws.com/?Action=CreateSpotDatafeedSubscription &Bucket=myawsbucket &AUTHPARAMS

API Version 2012-05-01 84

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<CreateSpotDatafeedSubscriptionResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <spotDatafeedSubscription> <ownerId>111122223333</ownerId> <bucket>myawsbucket</bucket> <prefix/> <state>Active</state> </spotDatafeedSubscription> </CreateSpotDatafeedSubscriptionResponse>

Related Operations
DeleteSpotDatafeedSubscription (p. 124) DescribeSpotDatafeedSubscription (p. 240)

API Version 2012-05-01 85

Amazon Elastic Compute Cloud API Reference CreateSubnet

CreateSubnet
Description
Creates a subnet in an existing VPC. You can create up to 20 subnets in a VPC. If you add more than one subnet to a VPC, they're set up in a star topology with a logical router in the middle. If you feel you need more than 20 subnets, you can request more by going to http://aws.amazon.com/contact-us/vpc-request/. When you create each subnet, you provide the VPC ID and the CIDR block you want for the subnet. After you create a subnet, you can't change its CIDR block. The subnet's CIDR block can be the same as the VPC's CIDR block (assuming you want only a single subnet in the VPC), or a subset of the VPC's CIDR block. If you create more than one subnet in a VPC, the subnets' CIDR blocks must not overlap. The smallest subnet (and VPC) you can create uses a /28 netmask (16 IP addresses), and the largest uses a /16 netmask (65,536 IP addresses).

Important
AWS reserves both the first four and the last IP address in each subnet's CIDR block. They're not available for use.

Important
If you launch an instance in a VPC using an Amazon EBS-backed AMI, the IP address doesn't change if you stop and restart the instance (unlike a similar instance launched outside a VPC, which gets a new IP address when restarted). It's therefore possible to have a subnet with no running instances (they're all stopped), but no remaining IP addresses available. For more information about Amazon EBS-backed AMIs, go to AMI Basics in the Amazon Elastic Compute Cloud User Guide.

For more information about Amazon Virtual Private Cloud and subnets, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpcId

Description The ID of the VPC where you want to create the subnet. Type: String Default: None

Required Yes

CidrBlock

The CIDR block you want the subnet to cover (e.g., Yes 10.0.0.0/24). Type: String Default: None The Availability Zone you want the subnet in. Type: String Default: AWS selects a zone for you (recommended) No

AvailabilityZone

API Version 2012-05-01 86

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in an CreateSubnetResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Information about the subnet. Type: SubnetType (p. 458)

subnet

Examples
Example Request
This example creates a subnet with CIDR block 10.0.1.0/24 in the VPC with ID vpc-1a2b3c4d.
https://ec2.amazonaws.com/?Action=CreateSubnet &VpcId=vpc-1a2b3c4d &CidrBlock=10.0.1.0/24 &AUTHPARAMS

Example Response
<CreateSubnetResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <subnet> <subnetId>subnet-9d4a7b6c</subnetId> <state>pending</state> <vpcId>vpc-1a2b3c4d</vpcId> <cidrBlock>10.0.1.0/24</cidrBlock> <availableIpAddressCount>250</availableIpAddressCount> <availabilityZone>us-east-1a</availabilityZone> <tagSet/> </subnet> </CreateSubnetResponse>

Related Operations
DescribeSubnets (p. 252) DeleteSubnet (p. 125)

API Version 2012-05-01 87

Amazon Elastic Compute Cloud API Reference CreateTags

CreateTags
Description
Adds or overwrites one or more tags for the specified resource or resources. Each resource can have a maximum of 10 tags. Each tag consists of a key and optional value.Tag keys must be unique per resource. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
ResourceId.n

Description

Required

ID of a resource to tag. For example, ami-1a2b3c4d.You Yes can specify multiple resources to assign the tags to. Type: String Default: None Key for a tag. Type: String Default: None Constraints: Tag keys are case sensitive and accept a maximum of 128 Unicode characters. Value for a tag. If you don't want the tag to have a value, specify the parameter with no value, and we will set the value to an empty string. Type: String Default: None Constraints: Tag values are case sensitive and accept a maximum of 256 Unicode characters. Yes

Tag.n.Key

Tag.n.Value

Yes

Response Elements
The elements in the following table are wrapped in a CreateTagsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

API Version 2012-05-01 88

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example adds (or overwrites) two tags for an AMI and an instance. One of the tags is just a key (webserver), with no value (we set the value to an empty string). The other consists of a key (stack) and value (Production).
https://ec2.amazonaws.com/?Action=CreateTags &ResourceId.1=ami-1a2b3c4d &ResourceId.2=i-7f4d3a2b &Tag.1.Key=webserver &Tag.1.Value= &Tag.2.Key=stack &Tag.2.Value=Production &AUTHPARAMS

Example Response
<CreateTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </CreateTagsResponse>

Related Operations
DescribeTags (p. 256) DeleteTags (p. 127)

API Version 2012-05-01 89

Amazon Elastic Compute Cloud API Reference CreateVolume

CreateVolume
Description
Creates a new Amazon EBS volume that any Amazon EC2 instance in the same Availability Zone can attach to. Any AWS Marketplace product codes from the snapshot are propagated to the volume. For more information about Amazon EBS, go to the Amazon Elastic Block Store.

Note
You must specify an Availability Zone when creating a volume. The volume and the instance to which it attaches must be in the same Availability Zone.

Request Parameters
Name
Size

Description The size of the volume, in GiBs. Type: String Valid Values: 1-1024 Default: If you're creating a volume from a snapshot and don't specify a size, the default is the snapshot size. Condition: Required if you're not creating a volume from a snapshot. The snapshot from which to create the new volume. Type: String Default: None Condition: Required if you are creating a volume from a snapshot.

Required Conditional

SnapshotId

Conditional

AvailabilityZone

The Availability Zone in which to create the new volume. Yes Use DescribeAvailabilityZones (p. 144) to display Availability Zones that are currently available to your account. Type: String Default: None

Response Elements
The elements in the following table are wrapped in a CreateVolumeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The ID of the volume. Type: xsd:string

volumeId

API Version 2012-05-01 90

Amazon Elastic Compute Cloud API Reference Examples

Name
size

Description The size of the volume, in GiBs. Type: xsd:string Snapshot from which the volume was created, if applicable. Type: xsd:string Availability Zone in which the volume was created. Type: xsd:string Volume state. Type: xsd:string Valid Values: creating | available | in-use | deleting | deleted | error Time stamp when volume creation was initiated. Type: xsd:dateTime

snapshotId

availabilityZone

status

createTime

Examples
Example Request
This example creates a new 80 GiB volume in Availability Zone us-east-1a.
https://ec2.amazonaws.com/?Action=CreateVolume &Size=80 &AvailabilityZone=us-east-1a &AUTHPARAMS

Example Response
<CreateVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <volumeId>vol-4d826724</volumeId> <size>80</size> <snapshotId/> <availabilityZone>us-east-1a</availabilityZone> <status>creating</status> <createTime>2008-05-07T11:51:50.000Z</createTime> </CreateVolumeResponse>

Related Operations
DeleteVolume (p. 130) DescribeVolumes (p. 261) AttachVolume (p. 26) DetachVolume (p. 287) DescribeAvailabilityZones (p. 144)

API Version 2012-05-01 91

Amazon Elastic Compute Cloud API Reference CreateVpc

CreateVpc
Description
Creates a VPC with the CIDR block you specify. The smallest VPC you can create uses a /28 netmask (16 IP addresses), and the largest uses a /16 netmask (65,536 IP addresses). To help you decide how big to make your VPC, go to Your VPC and Subnets in the Amazon Virtual Private Cloud User Guide. By default, each instance you launch in the VPC has the default DHCP options, which includes only a default DNS server that we provide (AmazonProvidedDNS). For more information about Amazon Virtual Private Cloud and DHCP options, go to Using DHCP Options in Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
CidrBlock

Description The CIDR block you want the VPC to cover (e.g., 10.0.0.0/16). Type: String Default: None

Required Yes

instanceTenancy

The supported tenancy of instances launched into No the VPC. A value of default means instances can be launched with any tenancy; a value of dedicated means all instances launched into the VPC will be launched as dedicated tenancy instances regardless of the tenancy assigned to the instance at launch. Setting the instance's tenancy attribute to dedicated specifies that your instance will run on single-tenant hardware. Type: String Default: default

Response Elements
The elements in the following table are wrapped in an CreateVpcResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Information about the VPC. Type: VpcType (p. 465)

vpc

API Version 2012-05-01 92

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example creates a VPC with CIDR block 10.0.0.0/16.
https://ec2.amazonaws.com/?Action=CreateVpc &CidrBlock=10.0.0.0/16 &AUTHPARAMS

Example Response
<CreateVpcResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <vpc> <vpcId>vpc-1a2b3c4d</vpcId> <state>pending</state> <cidrBlock>10.0.0.0/16</cidrBlock> <dhcpOptionsId>default</dhcpOptionsId> <tagSet/> </vpc> </CreateVpcResponse>

Related Operations
DescribeVpcs (p. 272) DeleteVpc (p. 132) CreateDhcpOptions (p. 53) AssociateDhcpOptions (p. 18)

API Version 2012-05-01 93

Amazon Elastic Compute Cloud API Reference CreateVpnConnection

CreateVpnConnection
Description
Creates a new VPN connection between an existing virtual private gateway and a VPN customer gateway. The only supported connection type is ipsec.1. The response includes information that you need to configure your customer gateway, in XML format. We recommend you use the command line version of this operation (ec2-create-vpn-connection), which lets you get the configuration information formatted in a friendlier way. For information about the command, go to ec2-create-vpn-connection in the Amazon Elastic Compute Cloud Command Line Reference.

Important
We strongly recommend you use HTTPS when calling this operation because the response contains sensitive cryptographic information for configuring your customer gateway.

If you decide to shut down your VPN connection for any reason and then create a new one, you must reconfigure your customer gateway with the new information returned from this call. For more information about Amazon Virtual Private Cloud and VPN connections, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
Type

Description The type of VPN connection. Type: String Default: None Valid Values: ipsec.1 The ID of the customer gateway. Type: String Default: None The ID of the virtual private gateway. Type: String Default: None

Required Yes

CustomerGatewayId

Yes

VpnGatewayId

Yes

AvailabilityZone

The Availability Zone option has been deprecated. No The command will accept this option and ignore it. Type: String Default: None

Response Elements
The elements in the following table are wrapped in an CreateVpnConnectionResponse structure.

API Version 2012-05-01 94

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string Information about the VPN connection. Type: VpnConnectionType (p. 466)

vpnConnection

Examples
Example Request
This example creates a VPN connection between the virtual private gateway with ID vgw-8db04f81 and the customer gateway with ID cgw-b4dc3961. The response includes configuration information for the VPN connection's customer gateway (in the native XML format, but escaped).
https://ec2.amazonaws.com/?Action=CreateVpnConnection &Type=ipsec.1 &CustomerGatewayId=cgw-b4dc3961 &VpnGatewayId=vgw-8db04f81 &AUTHPARAMS

Example Response
<CreateVpnConnectionResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <vpnConnection> <vpnConnectionId>vpn-44a8938f</vpnConnectionId> <state>pending</state> <customerGatewayConfiguration> <?xml version="1.0" encoding="UTF-8"?> <vpn_connection id="vpn-44a8938f"> <customer_gateway_id>cgw-b4dc3961</customer_gateway_id> <vpn_gateway_id>vgw-8db04f81</vpn_gateway_id> <vpn_connection_type>ipsec.1</vpn_connection_type> <ipsec_tunnel> <customer_gateway> <tunnel_outside_address> <ip_address>YOUR_UPLINK_ADDRESS</ip_address> </tunnel_outside_address> <tunnel_inside_address> <ip_address>169.254.255.1</ip_address> <network_mask>255.255.255.252</network_mask> <network_cidr>30</network_cidr> </tunnel_inside_address> <bgp> <asn>YOUR_BGP_ASN</asn> <hold_time>30</hold_time> </bgp> </customer_gateway> <vpn_gateway> <tunnel_outside_address>

API Version 2012-05-01 95

Amazon Elastic Compute Cloud API Reference Examples

<ip_address>72.21.209.193</ip_address> </tunnel_outside_address> <tunnel_inside_address> <ip_address>169.254.255.2</ip_address> <network_mask>255.255.255.252</network_mask> <network_cidr>30</network_cidr> </tunnel_inside_address> <bgp> <asn>7224</asn> <hold_time>30</hold_time> </bgp> </vpn_gateway> <ike> <authentication_protocol>sha1</authentication_protocol> <encryption_protocol>aes-128-cbc</encryption_protocol> <lifetime>28800</lifetime> <perfect_forward_secrecy>group2</perfect_forward_secrecy> <mode>main</mode> <pre_shared_key>plain-text-password1</pre_shared_key> </ike> <ipsec> <protocol>esp</protocol> <authentication_protocol>hmac-sha1-96</authentication_protocol> <encryption_protocol>aes-128-cbc</encryption_protocol> <lifetime>3600</lifetime> <perfect_forward_secrecy>group2</perfect_forward_secrecy> <mode>tunnel</mode> <clear_df_bit>true</clear_df_bit> <fragmentation_before_encryption>true</fragmentation_before_en cryption> <tcp_mss_adjustment>1396</tcp_mss_adjustment> <dead_peer_detection> <interval>10</interval> <retries>3</retries> </dead_peer_detection> </ipsec> </ipsec_tunnel> <ipsec_tunnel> <customer_gateway> <tunnel_outside_address> <ip_address>YOUR_UPLINK_ADDRESS</ip_address> </tunnel_outside_address> <tunnel_inside_address> <ip_address>169.254.255.5</ip_address> <network_mask>255.255.255.252</network_mask> <network_cidr>30</network_cidr> </tunnel_inside_address> <bgp> <asn>YOUR_BGP_ASN</asn> <hold_time>30</hold_time> </bgp> </customer_gateway> <vpn_gateway> <tunnel_outside_address> <ip_address>72.21.209.225</ip_address> </tunnel_outside_address> <tunnel_inside_address> <ip_address>169.254.255.6</ip_address>

API Version 2012-05-01 96

Amazon Elastic Compute Cloud API Reference Related Operations

<network_mask>255.255.255.252</network_mask> <network_cidr>30</network_cidr> </tunnel_inside_address> <bgp> <asn>7224</asn> <hold_time>30</hold_time> </bgp> </vpn_gateway> <ike> <authentication_protocol>sha1</authentication_protocol> <encryption_protocol>aes-128-cbc</encryption_protocol> <lifetime>28800</lifetime> <perfect_forward_secrecy>group2</perfect_forward_secrecy> <pre_shared_key>plain-text-password2</pre_shared_key> <mode>main</mode> </ike> <ipsec> <protocol>esp</protocol> <authentication_protocol>hmac-sha1-96</authentication_protocol> <encryption_protocol>aes-128-cbc</encryption_protocol> <lifetime>3600</lifetime> <perfect_forward_secrecy>group2</perfect_forward_secrecy> <mode>tunnel</mode> <clear_df_bit>true</clear_df_bit> <fragmentation_before_encryption>true</fragmentation_before_en cryption> <tcp_mss_adjustment>1396</tcp_mss_adjustment> <dead_peer_detection> <interval>10</interval> <retries>3</retries> </dead_peer_detection> </ipsec> </ipsec_tunnel> </vpn_connection> </customerGatewayConfiguration> <type>ipsec.1</type> <customerGatewayId>cgw-b4dc3961</customerGatewayId> <vpnGatewayId>vgw-8db04f81</vpnGatewayId> <tagSet/> </vpnConnection> </CreateVpnConnectionResponse>

Related Operations
DescribeVpnConnections (p. 275) DeleteVpnConnection (p. 134) CreateVpc (p. 92) CreateSubnet (p. 86) AttachVpnGateway (p. 29)

API Version 2012-05-01 97

Amazon Elastic Compute Cloud API Reference CreateVpnGateway

CreateVpnGateway
Description
Creates a new virtual private gateway. A virtual private gateway is the VPC-side endpoint for your VPN connection. You can create a virtual private gateway before creating the VPC itself. For more information about Amazon Virtual Private Cloud and virtual private gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
Type

Description The type of VPN connection this virtual private gateway supports. Type: String Default: None Valid Values: ipsec.1

Required Yes

AvailabilityZone

The Availability Zone option has been deprecated. No The API will accept this option and ignore it. Type: String Default: None

Response Elements
The elements in the following table are wrapped in an CreateVpnGatewayResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Information about the virtual private gateway. Type: VpnGatewayType (p. 467)

vpnGateway

Examples
Example Request
This example creates a virtual private gateway.
https://ec2.amazonaws.com/?Action=CreateVpnGateway &Type=ipsec.1 &AUTHPARAMS

API Version 2012-05-01 98

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<CreateVpnGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <vpnGateway> <vpnGatewayId>vgw-8db04f81</vpnGatewayId> <state>pending</state> <type>ipsec.1</type> <availabilityZone>us-east-1a</availabilityZone> <attachments/> <tagSet/> </vpnGateway> </CreateVpnGatewayResponse>

Related Operations
DescribeVpnGateways (p. 279) DeleteVpnGateway (p. 136) AttachVpnGateway (p. 29) DetachVpnGateway (p. 289)

API Version 2012-05-01 99

Amazon Elastic Compute Cloud API Reference DeleteCustomerGateway

DeleteCustomerGateway
Description
Deletes a VPN customer gateway. You must delete the VPN connection before deleting the customer gateway. For more information about Amazon Virtual Private Cloud and VPN customer gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
CustomerGatewayId

Description

Required

The ID of the customer gateway you want to delete. Yes Type: String Default: None

Response Elements
The elements in the following table are wrapped in an DeleteCustomerGatewayResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the customer gateway with ID cgw-b4dc3961.
https://ec2.amazonaws.com/?Action=DeleteCustomerGateway &CustomerGatewayId=cgw-b4dc3961 &AUTHPARAMS

Example Response
<DeleteCustomerGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>

API Version 2012-05-01 100

Amazon Elastic Compute Cloud API Reference Related Operations

<return>true</return> </DeleteCustomerGatewayResponse>

Related Operations
CreateCustomerGateway (p. 51) DescribeCustomerGateways (p. 152)

API Version 2012-05-01 101

Amazon Elastic Compute Cloud API Reference DeleteDhcpOptions

DeleteDhcpOptions
Description
Deletes a set of DHCP options that you specify. Amazon VPC returns an error if the set of options you specify is currently associated with a VPC. You can disassociate the set of options by associating either a new set of options or the default options with the VPC. For more information about Amazon Virtual Private Cloud and DHCP options sets, go to Using DHCP Options in Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
DhcpOptionsId

Description

Required

The ID of the DHCP options set you want to delete. Yes Type: String Default: None

Response Elements
The elements in the following table are wrapped in an DeleteDhcpOptionsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the set of DHCP options with ID dopt-7a8b9c2d.
https://ec2.amazonaws.com/?Action=DeleteDhcpOptions &DhcpOptionsId=dopt-7a8b9c2d &AUTHPARAMS

Example Response
<DeleteDhcpOptionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>

API Version 2012-05-01 102

Amazon Elastic Compute Cloud API Reference Related Operations

<return>true</return> </DeleteDhcpOptionsResponse>

Related Operations
AssociateDhcpOptions (p. 18) CreateDhcpOptions (p. 53) DescribeDhcpOptions (p. 155)

API Version 2012-05-01 103

Amazon Elastic Compute Cloud API Reference DeleteInternetGateway

DeleteInternetGateway
Description
Deletes an Internet gateway from your AWS account. The gateway must not be attached to a VPC. For more information about your VPC and Internet gateway, go to Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
InternetGatewayId

Description The ID of the Internet gateway to be deleted. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeleteInternetGatewayResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the Internet gateway with ID igw-eaad4883.
https://ec2.amazonaws.com/?Action=DeleteInternetGateway &InternetGatewayId=igw-eaad4883 &AUTHPARAMS

Example Response
<DeleteInternetGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteInternetGatewayResponse>

API Version 2012-05-01 104

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
CreateInternetGateway (p. 61) AttachInternetGateway (p. 22) DetachInternetGateway (p. 283) DescribeInternetGateways (p. 192)

API Version 2012-05-01 105

Amazon Elastic Compute Cloud API Reference DeleteKeyPair

DeleteKeyPair
Description
Deletes the specified key pair, by removing the public key from Amazon EC2. You must own the key pair.

Request Parameters
Name
KeyName

Description Name of the key pair to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeleteKeyPairResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the gsg-keypair key pair.
https://ec2.amazonaws.com/?Action=DeleteKeyPair &KeyName=gsg-keypair &AUTHPARAMS

Example Response
<DeleteKeyPairResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteKeyPairResponse>

Related Operations
CreateKeyPair (p. 63)

API Version 2012-05-01 106

Amazon Elastic Compute Cloud API Reference Related Operations

DescribeKeyPairs (p. 195) ImportKeyPair (p. 305)

API Version 2012-05-01 107

Amazon Elastic Compute Cloud API Reference DeleteNetworkAcl

DeleteNetworkAcl
Description
Deletes a network ACL from a VPC. The ACL must not have any subnets associated with it. You can't delete the default network ACL. For more information about network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
NetworkAclId

Description The ID of the network ACL to be deleted. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeleteNetworkAclResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the network ACL with ID acl-2cb85d45.
https://ec2.amazonaws.com/?Action=DeleteNetworkAcl &NetworkAclId=acl-2cb85d45 &AUTHPARAMS

Example Response
<DeleteNetworkAclResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteNetworkAclResponse>

API Version 2012-05-01 108

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
DeleteNetworkAcl (p. 108) DescribeNetworkAcls (p. 198) ReplaceNetworkAclAssociation (p. 334)

API Version 2012-05-01 109

Amazon Elastic Compute Cloud API Reference DeleteNetworkAclEntry

DeleteNetworkAclEntry
Description
Deletes an ingress or egress entry (i.e., rule) from a network ACL. For more information about network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
NetworkAclId

Description ID of the network ACL. Type: string Default: none Rule number for the entry to delete. Type: Number Default: none

Required Yes

RuleNumber

Yes

Egress

Whether the rule to delete is an egress rule (true) or No ingress rule (false). Type: Boolean Default: false Valid Values: true | false

Response Elements
The elements in the following table are wrapped in a ReplaceNetworkAclEntryResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the ingress entry with rule number 100 from the network ACL with ID acl-2cb85d45.
https://ec2.amazonaws.com/?Action=DeleteNetworkAclEntry &NetworkAclId=acl-2cb85d45 &RuleNumber=100 &AUTHPARAMS

API Version 2012-05-01 110

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DeleteNetworkAclEntryResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteNetworkAclEntryResponse>

Related Operations
CreateNetworkAclEntry (p. 67) ReplaceNetworkAclEntry (p. 336) DescribeNetworkAcls (p. 198)

API Version 2012-05-01 111

Amazon Elastic Compute Cloud API Reference DeleteNetworkInterface

DeleteNetworkInterface
Description
Deletes the specified network interface.

Request Parameters
Name
NetworkInterfaceId

Description The ID of the network interface to delete. Type: string Default: None

Required Yes

Response Elements
Name
requestId

Description The ID of the request to delete the network interface. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes an elastic network interface (ENI) eni-ffda3197.
https://ec2.amazonaws.com/?Action=DeleteNetworkInterface &NetworkInterfaceId=eni-ffda3197 &AUTHPARAMS

Example Response
<DeleteNetworkInterfaceResponse xmlns='http://ec2.amazonaws.com/doc/2011-1115/'> <requestId>e1c6d73b-edaa-4e62-9909-6611404e1739</requestId> <return>true</return> </DeleteNetworkInterfaceResponse>

Related Operations
AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285)

API Version 2012-05-01 112

Amazon Elastic Compute Cloud API Reference Related Operations

CreateNetworkInterface (p. 70) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 113

Amazon Elastic Compute Cloud API Reference DeletePlacementGroup

DeletePlacementGroup
Description
Deletes a placement group from your account. You must terminate all instances in the placement group before deleting it. For more information about placement groups and cluster instances, go to Using Cluster Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
GroupName

Description The name of the placement group to delete. Type: string Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeletePlacementGroupResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the placement group named XYZ-cluster.
https://ec2.amazonaws.com/?Action=DeletePlacementGroup &GroupName=XYZ-cluster &AUTHPARAMS

Example Response
<DeletePlacementGroupResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>d4904fd9-82c2-4ea5-adfe-a9cc3EXAMPLE</requestId> <return>true</return> </DeletePlacementGroupResponse>

API Version 2012-05-01 114

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
CreatePlacementGroup (p. 72) DescribePlacementGroups (p. 211)

API Version 2012-05-01 115

Amazon Elastic Compute Cloud API Reference DeleteRoute

DeleteRoute
Description
Deletes a route from a route table in a VPC. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
RouteTableId

Description The ID of the route table where the route will be deleted. Type: String Default: None The CIDR range for the route you want to delete. The value you specify must exactly match the CIDR for the route you want to delete. Type: String Default: None

Required Yes

DestinationCidrBlock

Yes

Response Elements
The elements in the following table are wrapped in a ReplaceRouteResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example removes the route with destination CIDR 172.16.1.0/24 from the route table with ID rtb-e4ad488d.
https://ec2.amazonaws.com/?Action=DeleteRoute &RouteTableId=rtb-e4ad488d &DestinationCidrBlock=172.16.1.0/24 &AUTHPARMS

API Version 2012-05-01 116

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DeleteRouteResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteRouteResponse>

Related Operations
CreateRoute (p. 74) ReplaceRoute (p. 339) DescribeRouteTables (p. 225)

API Version 2012-05-01 117

Amazon Elastic Compute Cloud API Reference DeleteRouteTable

DeleteRouteTable
Description
Deletes a route table from a VPC. The route table must not be associated with a subnet. You can't delete the main route table. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
RouteTableId

Description The ID of the route table to be deleted. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeleteRouteTableResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean Type: Boolean

return

Examples
Example Request
This example deletes the route table with ID rtb-e4ad488d.
https://ec2.amazonaws.com/?Action=DeleteRouteTable &RouteTableId=rtb-e4ad488d &AUTHPARAMS

Example Response
<DeleteRouteTableResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteRouteTableResponse>

API Version 2012-05-01 118

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
AssociateRouteTable (p. 20) DisassociateRouteTable (p. 293) DescribeRouteTables (p. 225) CreateRouteTable (p. 77) ReplaceRouteTableAssociation (p. 341)

API Version 2012-05-01 119

Amazon Elastic Compute Cloud API Reference DeleteSecurityGroup

DeleteSecurityGroup
Description
Deletes a security group. This action applies to both EC2 security groups and VPC security groups. For information about VPC security groups and how they differ from EC2 security groups, go to Security Groups in the Amazon Virtual Private Cloud User Guide.

Note
If you attempt to delete a security group that contains instances, or attempt to delete a security group that is referenced by another security group, an error is returned. For example, if security group B has a rule that allows access from security group A, security group A cannot be deleted until the rule is removed. The fault returned is InvalidGroup.InUse for EC2 security groups, or DependencyViolation for VPC security groups.

Request Parameters
Name
GroupName

Description Name of the security group to delete. Type: String Default: None Condition: Either GroupName or GroupId is required

Required Conditional

GroupId

ID of the security group to delete. Conditional Type: String Default: None Condition: Required for a VPC security group; for an EC2 security group, either GroupName or GroupId is required

Response Elements
The elements in the following table are wrapped in a DeleteSecurityGroupResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

API Version 2012-05-01 120

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example deletes the EC2 security group named websrv.
https://ec2.amazonaws.com/?Action=DeleteSecurityGroup &GroupName=websrv &AUTHPARAMS

Example Request
This example deletes the VPC security group with ID sg-77d0f5a2.
https://ec2.amazonaws.com/?Action=DeleteSecurityGroup &GroupId=sg-77d0f5a2 &AUTHPARAMS

Example Response
<DeleteSecurityGroupResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteSecurityGroupResponse>

Related Operations
CreateSecurityGroup (p. 79) DescribeSecurityGroups (p. 229) AuthorizeSecurityGroupIngress (p. 34) RevokeSecurityGroupIngress (p. 363)

API Version 2012-05-01 121

Amazon Elastic Compute Cloud API Reference DeleteSnapshot

DeleteSnapshot
Description
Deletes a snapshot of an Amazon EBS volume.

Note
If you make periodic snapshots of a volume, the snapshots are incremental so that only the blocks on the device that have changed since your last snapshot are incrementally saved in the new snapshot. Even though snapshots are saved incrementally, the snapshot deletion process is designed so that you need to retain only the most recent snapshot in order to restore the volume.

Request Parameters
Name
SnapshotId

Description The ID of the Amazon EBS snapshot to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeleteSnapshotResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes snapshot snap-78a54011.
https://ec2.amazonaws.com/?Action=DeleteSnapshot &SnapshotId.1=snap-78a54011 &AUTHPARAMS

API Version 2012-05-01 122

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DeleteSnapshotResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteSnapshotResponse>

Related Operations
CreateSnapshot (p. 81) DescribeSnapshots (p. 235)

API Version 2012-05-01 123

Amazon Elastic Compute Cloud API Reference DeleteSpotDatafeedSubscription

DeleteSpotDatafeedSubscription
Description
Deletes the datafeed for Spot Instances. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
The DeleteSpotDatafeedSubscription operation does not have any request parameters.

Response Elements
The elements in the following table are wrapped in a DeleteSpotDatafeedSubscriptionResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the data feed for the account.
https://ec2.amazonaws.com/?Action=DeleteSpotDatafeedSubscription &AUTHPARAMS

Example Response
<DeleteSpotDatafeedSubscriptionResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteSpotDatafeedSubscriptionResponse>

Related Operations
CreateSpotDatafeedSubscription (p. 84) DescribeSpotDatafeedSubscription (p. 240)

API Version 2012-05-01 124

Amazon Elastic Compute Cloud API Reference DeleteSubnet

DeleteSubnet
Description
Deletes a subnet from a VPC. You must terminate all running instances in the subnet before deleting it, otherwise Amazon VPC returns an error.

Request Parameters
Name
SubnetId

Description The ID of the subnet you want to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in an DeleteSubnetResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the subnet with ID subnet-9d4a7b6c.
https://ec2.amazonaws.com/?Action=DeleteSubnet &SubnetId=subnet-9d4a7b6c &AUTHPARAMS

Example Response
<DeleteSubnetResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </DeleteSubnetResponse>

API Version 2012-05-01 125

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
CreateSubnet (p. 86) DescribeSubnets (p. 252)

API Version 2012-05-01 126

Amazon Elastic Compute Cloud API Reference DeleteTags

DeleteTags
Description
Deletes a specific set of tags from a specific set of resources. This call is designed to follow a DescribeTags call. You first determine what tags a resource has, and then you call DeleteTags with the resource ID and the specific tags you want to delete. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
ResourceId.n

Description

Required

ID of the resource. For example, ami-1a2b3c4d.You can Yes specify more than one resource ID. Type: String Default: None The tag's key.You can specify more than one tag to delete. Yes Type: String Default: None The tag's value. Type: String Default: If you omit this parameter, we delete the tag regardless of its value. If you specify this parameter with an empty string as the value, we delete the key only if its value is an empty string. No

Tag.n.Key

Tag.n.Value

Response Elements
The elements in the following table are wrapped in a DeleteTagsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the tags for the AMI with ID ami-1a2b3c4d. You first get a list of the tags.

API Version 2012-05-01 127

Amazon Elastic Compute Cloud API Reference Examples

https://ec2.amazonaws.com/?Action=DescribeTags &ResourceId.1=ami-1a2b3c4d &AUTHPARAMS

Sample response:
<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>ami-1a2b3c4d</resourceId> <resourceType>image</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>ami-1a2b3c4d</resourceId> <resourceType>image</resourceType> <key>stack</key> <value>Production</value> </item> </tagSet> </DescribeTagsResponse>

Then you delete the tags. Specifying the value for the stack tag is optional.
https://ec2.amazonaws.com/?Action=DeleteTags &ResourceId.1=ami-1a2b3c4d &Tag.1.Key=webserver &Tag.2.Key=stack &AUTHPARAMS

Sample response:
<DeleteTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </DeleteTagsResponse>

Example Request
This example deletes the stack tag from two particular instances.
https://ec2.amazonaws.com/?Action=DeleteTags &ResourceId.1=i-5f4e3d2a &Tag.1.Key=stack &ResourceId.2=i-12345678 &Tag.2.Key=stack &AUTHPARAMS

Example Request
This example deletes the stack and webserver tags for one particular instance.

API Version 2012-05-01 128

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DeleteTags &ResourceId.1=i-5f4e3d2a &Tag.1.Key=stack &ResourceId.2=i-5f4e3d2a &Tag.2.Key=webserver &AUTHPARAMS

Example Request
You can specify a tag key without a corresponding tag value if you want to delete the tag regardless of its value. This example deletes all tags whose key=Purpose, regardless of the tag value.
https://ec2.amazonaws.com/?Action=DeleteTags &ResourceId.1=i-5f4e3d2a &Tag.1.Key=Purpose &AUTHPARAMS

Example Request
When you create a tag, you can set the tag value to the empty string. Correspondingly, you can delete only tags that have a specific key and whose value is the empty string. This example deletes all tags for the specified instance where key=Purpose and the tag value is the empty string.
https://ec2.amazonaws.com/?Action=DeleteTags &ResourceId.1=i-5f4e3d2a &Tag.1.Key=Purpose &Tag.2.Value= &AUTHPARAMS

Related Operations
CreateTags (p. 88) DescribeTags (p. 256)

API Version 2012-05-01 129

Amazon Elastic Compute Cloud API Reference DeleteVolume

DeleteVolume
Description
Deletes an Amazon EBS volume. The volume must be in the available state (not attached to an instance). For more information about Amazon EBS, go to Using Amazon Elastic Block Store in the Amazon Elastic Compute Cloud User Guide.

Note
The volume remains in the deleting state for several minutes after you call this action.

Request Parameters
Name
VolumeId

Description The ID of the volume to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeleteVolumeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes volume vol-4282672b.
https://ec2.amazonaws.com/?Action=DeleteVolume &VolumeId=vol-4282672b &AUTHPARAMS

Example Response
<DeleteVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>

API Version 2012-05-01 130

Amazon Elastic Compute Cloud API Reference Related Operations

<return>true</return> </DeleteVolumeResponse>

Related Operations
CreateVolume (p. 90) DescribeVolumes (p. 261) AttachVolume (p. 26) DetachVolume (p. 287)

API Version 2012-05-01 131

Amazon Elastic Compute Cloud API Reference DeleteVpc

DeleteVpc
Description
Deletes a VPC. You must detach or delete all gateways or other objects that are dependent on the VPC first. For example, you must terminate all running instances, delete all VPC security groups (except the default), delete all the route tables (except the default), etc. For more information about Amazon Virtual Private Cloud and VPCs, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpcId

Description The ID of the VPC you want to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in an DeleteVpcResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the VPC with ID vpc-1a2b3c4d.
https://ec2.amazonaws.com/?Action=DeleteVpc &VpcId=vpc-1a2b3c4d &AUTHPARAMS

Example Response
<DeleteVpcResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>

API Version 2012-05-01 132

Amazon Elastic Compute Cloud API Reference Related Operations

<return>true</return> </DeleteVpcResponse>

Related Operations
CreateVpc (p. 92) DescribeVpcs (p. 272)

API Version 2012-05-01 133

Amazon Elastic Compute Cloud API Reference DeleteVpnConnection

DeleteVpnConnection
Description
Deletes a VPN connection. Use this if you want to delete a VPC and all its associated components. Another reason to use this operation is if you believe the tunnel credentials for your VPN connection have been compromised. In that situation, you can delete the VPN connection and create a new one that has new keys, without needing to delete the VPC or virtual private gateway. If you create a new VPN connection, you must reconfigure the customer gateway using the new configuration information returned with the new VPN connection ID. If you're deleting the VPC and all its associated parts, we recommend you detach the virtual private gateway from the VPC and delete the VPC before deleting the VPN connection. For more information about Amazon Virtual Private Cloud and VPN connections, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpnConnectionId

Description The ID of the VPN connection you want to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in an DeleteVpnConnectionResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the VPN connection with ID vpn-44a8938f.
https://ec2.amazonaws.com/?Action=DeleteVpnConnection &vpnConnectionId=vpn-44a8938f &AUTHPARAMS

API Version 2012-05-01 134

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DeleteVpnConnectionResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </DeleteVpnConnectionResponse>

Related Operations
CreateVpnConnection (p. 94) DescribeVpnConnections (p. 275) DetachVpnGateway (p. 289) DeleteVpc (p. 132)

API Version 2012-05-01 135

Amazon Elastic Compute Cloud API Reference DeleteVpnGateway

DeleteVpnGateway
Description
Deletes a virtual private gateway. Use this when you want to delete a VPC and all its associated components because you no longer need them. We recommend that before you delete a virtual private gateway, you detach it from the VPC and delete the VPN connection. Note that you don't need to delete the virtual private gateway if you just want to delete and recreate the VPN connection between your VPC and data center. For more information about Amazon Virtual Private Cloud and virtual private gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpnGatewayId

Description The ID of the virtual private gateway you want to delete. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in an DeleteVpnGatewayResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deletes the virtual private gateway with ID vgw-8db04f81.
https://ec2.amazonaws.com/?Action=DeleteVpnGateway &vpnGatewayId=vgw-8db04f81 &AUTHPARAMS

API Version 2012-05-01 136

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DeleteVpnGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </DeleteVpnGatewayResponse>

Related Operations
CreateVpnGateway (p. 98) DescribeVpnGateways (p. 279) DeleteVpnConnection (p. 134)

API Version 2012-05-01 137

Amazon Elastic Compute Cloud API Reference DeregisterImage

DeregisterImage
Description
Deregisters the specified AMI. Once deregistered, the AMI cannot be used to launch new instances.

Note
This command does not delete the AMI.

Request Parameters
Name
ImageId

Description ID of the AMI to deregister. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DeregisterImageResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example deregisters the ami-4fa54026 AMI.
https://ec2.amazonaws.com/?Action=DeregisterImage &ImageId=ami-4fa54026 &AUTHPARAMS

Example Response
<DeregisterImageResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeregisterImageResponse>

API Version 2012-05-01 138

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
RegisterImage (p. 328) DescribeImages (p. 164)

API Version 2012-05-01 139

Amazon Elastic Compute Cloud API Reference DescribeAddresses

DescribeAddresses
Description
Gives information about Elastic IP addresses allocated to your account. This includes both EC2 and VPC Elastic IP addresses. For information about VPC addresses and how they differ from EC2 addresses, go to Elastic IP Addresses in the Amazon Virtual Private Cloud User Guide. You can filter the results to return information only about Elastic IP addresses that match criteria you specify. For example, you could get information only about addresses tagged with a certain value. You can specify multiple values for a filter. An address must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the address is a particular value, and is tagged with a certain value). The result includes information for an address only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
domain

Description Whether the address is a EC2 address, or a VPC address. Type: String Valid Values: standard | vpc Instance the address is associated with (if any). Type: String The Elastic IP address. Type: String Allocation ID for the address (for VPC addresses only). Type: String Association ID for the address (for VPC addresses only). Type: String

instance-id

public-ip

allocation-id

association-id

Request Parameters
Name
PublicIp.n

Description

Required

One or more Elastic IP addresses. Applies only to standard No (EC2) addresses. Type: String Default: None

API Version 2012-05-01 140

Amazon Elastic Compute Cloud API Reference Response Elements

Name
AllocationId.n

Description

Required

One or more allocation IDs corresponding to the address No or addresses to describe. Applies only to VPC addresses. Type: String Default: None Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

Filter.n.Name

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeAddressesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of IP addresses. Each IP address's information is wrapped in an item element. Type: DescribeAddressesResponseItemType (p. 396)

addressesSet

Examples
Example Request
EC2 addresses: This example describes two specific EC2 Elastic IP addresses assigned to the account. Amazon EC2 returns information about 192.0.2.1, which is assigned to instance i-f15ebb98, and for 198.51.100.2, which is not assigned to an instance.
https://ec2.amazonaws.com/?Action=DescribeAddresses &PublicIp.1=192.0.2.1 &PublicIp.2=198.51.100.2 &AUTHPARAMS

Example Response
<DescribeAddressesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <addressesSet> <item>

API Version 2012-05-01 141

Amazon Elastic Compute Cloud API Reference Examples

<publicIp>192.0.2.1</publicIp> <domain>standard</domain> <instanceId>i-f15ebb98</instanceId> </item> <item> <publicIp>198.51.100.2</publicIp> <domain>standard</domain> <instanceId/> </item> </addressesSet> </DescribeAddressesResponse>

Example Request
VPC Addresses: This example describes a specific VPC address allocated to your account. You must use the allocation ID to specify the address.
https://ec2.amazonaws.com/?Action=DescribeAddresses &AllocationId.1= eipalloc-5723d13e &AUTHPARAMS

Example Response
<DescribeAddressesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <addressesSet> <item> <publicIp>203.0.113.1</publicIp> <allocationId>eipalloc-5723d13e</allocationId> <domain>vpc</domain> <instanceId>i-9e9da4e9</instanceId> <associationId>eipassoc-ba03f1d3</associationId> </item> </addressesSet> </DescribeAddressesResponse>

Example Request
VPC Addresses: This example lists only your VPC addresses (assuming you have both standard and VPC addresses).
https://ec2.amazonaws.com/?Action=DescribeAddresses &Filter.1.Name=allocation-id &Filter.1.Value.1=* &AUTHPARAMS

Example Response
<DescribeAddressesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <addressesSet> <item>

API Version 2012-05-01 142

Amazon Elastic Compute Cloud API Reference Related Operations

<publicIp>198.51.100.9</publicIp> <allocationId>eipalloc-5723d13e</allocationId> <domain>vpc</domain> <instanceId>i-9e9da4e9</instanceId> <associationId>eipassoc-ba03f1d3</associationId> </item> <item> <publicIp>203.0.113.4</publicIp> <allocationId>eipalloc-993dd4a2</allocationId> <domain>vpc</domain> <instanceId>i-225fg8a</instanceId> <associationId>eipassoc-85d2a3d</associationId> </item> </addressesSet> </DescribeAddressesResponse>

Related Operations
AllocateAddress (p. 13) ReleaseAddress (p. 332) AssociateAddress (p. 15) DisassociateAddress (p. 291)

API Version 2012-05-01 143

Amazon Elastic Compute Cloud API Reference DescribeAvailabilityZones

DescribeAvailabilityZones
Description
Displays Availability Zones that are currently available to the account. The results include zones only for the Region you're currently using.

Note
Availability Zones are not the same across accounts.The Availability Zone us-east-1a for account A is not necessarily the same as us-east-1a for account B. Zone assignments are mapped independently for each account.

You can filter the results to return information only about zones that match criteria you specify. For example, you could filter the results to return only the zones whose state is available. You can specify multiple filters (e.g., the zone is in a particular Region, and the state is available). The result includes information for a particular zone only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
message

Description Message giving information about the Availability Zone. Type: String Region the Availablity Zone is in (e.g., us-east-1). Type: String State of the Availability Zone Type: String Valid Values: available Name of the zone. Type: String

region-name

state

zone-name

Request Parameters
Name
ZoneName.n

Description One or more Availability Zones. Type: String Default: None

Required No

API Version 2012-05-01 144

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Name

Description Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeAvailabilityZonesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of Availability Zones. Each zone's information is wrapped in an item element. Type: AvailabilityZoneItemType (p. 388)

availabilityZoneInfo

Examples
Example Request
This example displays information about Availability Zones that are available to the account. The results includes zones only in the Region (endpoint) you're currently using.
https://ec2.amazonaws.com/?Action=DescribeAvailabilityZones &AUTHPARAMS

Example Response
<DescribeAvailabilityZonesResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <availabilityZoneInfo> <item> <zoneName>us-east-1a</zoneName> <zoneState>available</zoneState> <regionName>us-east-1</regionName> <messageSet/> </item> <item> <zoneName>us-east-1b</zoneName> <zoneState>available</zoneState>

API Version 2012-05-01 145

Amazon Elastic Compute Cloud API Reference Related Operations

<regionName>us-east-1</regionName> <messageSet/> </item> <item> <zoneName>us-east-1c</zoneName> <zoneState>available</zoneState> <regionName>us-east-1</regionName> <messageSet/> </item> <item> <zoneName>us-east-1d</zoneName> <zoneState>available</zoneState> <regionName>us-east-1</regionName> <messageSet/> </item> </availabilityZoneInfo> </DescribeAvailabilityZonesResponse>

Related Operations
RunInstances (p. 366) DescribeRegions (p. 214)

API Version 2012-05-01 146

Amazon Elastic Compute Cloud API Reference DescribeBundleTasks

DescribeBundleTasks
Description
Describes current bundling tasks for Amazon S3-backed Windows instances.

Note
Completed bundle tasks are listed for only a limited time. If your bundle task is no longer in the list, you can still register an AMI from it. Just use the RegisterImage action with the Amazon S3 bucket name and image manifest name you provided to the bundle task.

You can filter the results to return information only about tasks that match criteria you specify. For example, you could filter the results to return only the tasks whose state is complete. You can specify multiple values for a filter. A bundle task must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the bundle is stored in a particular Amazon S3 bucket and the state is complete). The result includes information for a particular bundle task only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
bundle-id

Description ID of the bundle task. Type: String If the task failed, the error code returned. Type: String If the task failed, the error message returned. Type: String ID of the instance that was bundled. Type: String Level of task completion, in percent (e.g., 20%). Type: String Amazon S3 bucket where the AMI will be stored. Type: String Beginning of the AMI name. Type: String Time the task started, e.g., 2008-09-15T17:15:20.000Z. Type: xsd:dateTime

error-code

error-message

instance-id

progress

s3-bucket

s3-prefix

start-time

API Version 2012-05-01 147

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
state

Description State of the task. Type: String Valid Values: pending | waiting-for-shutdown | bundling | storing | cancelling | complete | failed Time of the most recent update for the task, e.g., 2008-09-15T17:15:20.000Z. Type: xsd:dateTime

update-time

Request Parameters
Name
BundleId.n

Description

Required

One or more bundle task IDs. No Type: String Default: If no ID is specified, all bundle tasks are described. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

Filter.n.Name

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeBundleTasksResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of bundle tasks. Each task's information is wrapped in an item element. Type: BundleInstanceTaskType (p. 392)

bundleInstanceTasksSet

Examples
Example Request
This example describes the status of the bun-57a5403e bundle task.

API Version 2012-05-01 148

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribeBundleTasks &bundleId.1=bun-c1a540a8 &AUTHPARAMS

Example Response
<DescribeBundleTasksResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <bundleInstanceTasksSet> <item> <instanceId>i-12345678</instanceId> <bundleId>bun-c1a540a8</bundleId> <state>cancelling</state> <startTime>2008-10-07T11:41:50.000Z</startTime> <updateTime>2008-10-07T11:51:50.000Z</updateTime> <storage> <S3> <bucket>myawsbucket</bucket> <prefix>winami</prefix> </S3> </storage> <progress>20%</progress> </item> <bundleInstanceTasksSet> </DescribeBundleTasksResponse>

Example Request
This example filters the results to display only bundle tasks whose state is either complete or failed, and in addition are targeted for the Amazon S3 bucket called myawsbucket.
https://ec2.amazonaws.com/?Action=DescribeBundleTasks &Filter.1.Name=s3-bucket &Filter.1.Value.1=myawsbucket &Filter.2.Name=state &Filter.2.Name.1=complete &Filter.2.Name.2=failed &AUTHPARAMS

Related Operations
BundleInstance (p. 38) CancelBundleTask (p. 41)

API Version 2012-05-01 149

Amazon Elastic Compute Cloud API Reference DescribeConversionTasks

DescribeConversionTasks
Description
Describes your conversion tasks. For more information, go to Using the Command Line Tools to Import Your Virtual Machine to Amazon EC2 in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
ConversionTaskId.n

Description One or more conversion task IDs. Type: String

Required No

Response Elements
The elements in the following table are wrapped in a DescribeConversionTasksResponse structure. Name
conversionTasks

Description A list of conversion tasks. Each task's information is wrapped in an item element. Type: ConversionTaskType (p. 393)

Examples
Example Request
This example describes all your conversion tasks.
https://ec2.amazonaws.com/?Action=DescribeConversionTasks &AUTHPARAMS

Example Response
<DescribeConversionTasksResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <conversionTasks> <item> <conversionTask> <conversionTaskId>import-i-fh95npoc</conversionTaskId> <expirationTime>2010-12-22T12:01Z</expirationTime> <importVolume> <bytesConverted>1000</bytesConverted> <availabilityZone>us-east-1a</availabilityZone> <description/> <image> <format>VDMK</format>

API Version 2012-05-01 150

Amazon Elastic Compute Cloud API Reference Related Operations

<size>128696320</size> <importManifestUrl> https://s3.amazonaws.com/myawsbucket/a3a5e1b6-590d-43cc-97c115c7325d3f41/Win_2008_Server_Data_Center_SP2_32-bit.vmdkmanifest.xml?AWSAccess KeyId=AKIAIOSFODNN7EXAMPLE&Expires=1294855591&Signature=5snej01TlTtL0uR7KEx tEXAMPLE%3D </importManifestUrl> </image> <volume> <size>8</size> <id>vol-34d8a2ff</id> </volume> </importVolume> <state>active</state> <statusMessage/> </conversionTask> </item> </conversionTasks> </DescribeConversionTasksResponse>

Related Operations
ImportInstance (p. 301) ImportVolume (p. 307) CancelConversionTask (p. 43)

API Version 2012-05-01 151

Amazon Elastic Compute Cloud API Reference DescribeCustomerGateways

DescribeCustomerGateways
Description
Gives you information about your VPN customer gateways. You can filter the results to return information only about customer gateways that match criteria you specify. For example, you could get information only about gateways whose state is pending or available. The customer gateway must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the customer gateway has a particular IP address for the Internet-routable external interface, and the gateway's state is pending or available). The result includes information for a particular customer gateway only if the gateway matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
bgp-asn

Description The customer gateway's Border Gateway Protocol (BGP) Autonomous System Number (ASN). Type: String

customer-gateway-id ID of the customer gateway. Type: String ip-address

The IP address of the customer gateway's Internet-routable external interface (e.g., 12.1.2.3). Type: String The state of the customer gateway. Type: String Valid Values: pending | available | deleting | deleted The type of customer gateway. Currently the only supported type is ipsec.1. Type: String Valid Values: ipsec.1 Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

state

type

tag-key

tag-value

API Version 2012-05-01 152

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y

For more information about Amazon Virtual Private Cloud and VPN customer gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
CustomerGatewayId.n

Description

Required

A customer gateway ID.You can specify more than No one in the request. Type: String Default: Returns information about all your customer gateways Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: Returns information about all your customer gateways or those you specify by ID. A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

Filter.n.Name

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in an DescribeCustomerGatewaysResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of customer gateways. Each customer gateway's information is wrapped in an element. Type: CustomerGatewayType (p. 395)

customerGatewaySet

API Version 2012-05-01 153

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example gives a description of the customer gateway with ID cgw-b4dc3961.
https://ec2.amazonaws.com/?Action=DescribeCustomerGateways &CustomerGatewayId.1=cgw-b4dc3961 &AUTHPARAMS

Example Response
<DescribeCustomerGatewaysResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <customerGatewaySet> <item> <customerGatewayId>cgw-b4dc3961</customerGatewayId> <state>available</state> <type>ipsec.1</type> <ipAddress>12.1.2.3</ipAddress> <bgpAsn>65534</bgpasn> <tagSet/> </item> </customerGatewaySet> </DescribeCustomerGatewaysResponse>

Example Request
This example uses filters to give a description of any customer gateway you own whose IP address is 12.1.2.3, and whose state is either pending or available.
https://ec2.amazonaws.com/?Action=DescribeCustomerGateways &Filter.1.Name=ip-address &Filter.1.Value.1=12.1.2.3 &Filter.2.Name=state &Filter.2.Value.1=pending &Filter.2.Value.2=available &AUTHPARAMS

Related Operations
CreateCustomerGateway (p. 51) DeleteCustomerGateway (p. 100)

API Version 2012-05-01 154

Amazon Elastic Compute Cloud API Reference DescribeDhcpOptions

DescribeDhcpOptions
Description
Gives you information about one or more sets of DHCP options. You can specify one or more DHCP options set IDs, or no IDs (to describe all your sets of DHCP options). You can filter the results to return information only about sets of options that match criteria you specify. For example, you could get information for sets that have a certain value for the domain-name option. You can specify multiple values for the filter. The option must match at least one of the specified values for the options set to be included in the results. You can specify multiple filters (e.g., a certain value for domain-name, and a tag with a certain value). The result includes information for a set of options only if the specified option matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
dhcp-options-id

Description The ID of a set of DHCP options. Type: String The key for one of the options (e.g., domain-name). Type: String The value for one of the options. Type: String Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

key

value

tag-key

tag-value

API Version 2012-05-01 155

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y

For more information about Amazon Virtual Private Cloud and DHCP options sets, go to Using DHCP Options in Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
DhcpOptionsId.n

Description

Required

A DHCP options set ID.You can specify more than No one in the request. Type: String Default: Returns information about all your sets of DHCP options, or only those otherwise specified. Name of a filter. See the preceding table for a list No of allowed filter names. Type: String Default: Returns information about all your sets of DHCP options, or only those you otherwise specify. A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

Filter.n.Name

Filter.n.Value.m

Response Elements
The elements in the following table are wrapped in a DescribeDhcpOptionsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string

API Version 2012-05-01 156

Amazon Elastic Compute Cloud API Reference Examples

Name
dhcpOptionsSet

Description A list of DHCP options sets. Each set's information is wrapped in an item element. Type: DhcpOptionsType (p. 404) Ancestor: DescribeDhcpOptionsResponse Children: item

Examples
Example Request
This example gives a description of the DHCP options set with ID dopt-7a8b9c2d.
https://ec2.amazonaws.com/?Action=DescribeDhcpOptions &DhcpOptionsId.1=dopt-7a8b9c2d &AUTHPARAMS

Example Response
<DescribeDhcpOptionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <dhcpOptionsSet> <item> <dhcpOptionsId>dopt-7a8b9c2d</dhcpOptionsId> <dhcpConfigurationSet> <item> <key>domain-name</key> <valueSet> <item> <value>example.com</value> </item> </valueSet> </item> <item> <key>domain-name-servers</key> <valueSet> <item> <value>10.2.5.1</value> </item> </valueSet> </item> <item> <key>domain-name-servers</key> <valueSet> <item> <value>10.2.5.2</value> </item> </valueSet> </item> </dhcpConfigurationSet> <tagSet/>

API Version 2012-05-01 157

Amazon Elastic Compute Cloud API Reference Related Operations

</item> </dhcpOptionsSet> </DescribeDhcpOptionsResponse>

Example Request
This example uses filters to give a description of any DHCP options set that includes a domain-name option whose value includes the string example.
https://ec2.amazonaws.com/?Action=DescribeDhcpOptions &Filter.1.Name=key &Filter.1.Value.1=domain-name &Filter.2.Name=value &Filter.2.Value.1=*example* &AUTHPARAMS

Related Operations
CreateDhcpOptions (p. 53) AssociateDhcpOptions (p. 18) DeleteDhcpOptions (p. 102)

API Version 2012-05-01 158

Amazon Elastic Compute Cloud API Reference DescribeExportTasks

DescribeExportTasks
Description
Describes your export tasks. If no export task IDs are specified, all export tasks initiated by you are returned.

Request Parameters
Name
ExportTaskId.n

Description

Required

One or more export task IDs. If no task IDs are No provided, all active export tasks will be described. Type: String Default: None

Response Elements
The elements in the following table are wrapped in a DescribeExportTasks structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of export tasks. Each tasks information is wrapped in an item element. Type: ExportTaskResponseType (p. 409)

exportTaskSet

Examples
Example Request
This example describes a single export task.
https://ec2.amazonaws.com/?Action=DescribeExportTasks &exportTaskId.1=export-i-1234wxyz &AUTHPARAMS

Example Response
<DescribeExportTasksResponse xmlns="http://ec2.amazonaws.com/doc/2020-02-02/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <exportTaskSet> <item> <exportTaskId>export-i-1234wxyz</exportTaskId> <description>Example for docs</description>

API Version 2012-05-01 159

Amazon Elastic Compute Cloud API Reference Related Operations

<state>active</state> <statusMessage>Running</statusMessage> <instanceExport> <instanceId>i-12345678</ instanceId > <targetEnvironment>VMWare</ targetEnvironment > </instanceExport> <exportToS3> <diskImageFormat >VMDK</ diskImageFormat > <containerFormat>OVA</ containerFormat> <s3bucket>my-bucket-for-exported-vm</s3bucket> <s3Key>my-exports/ export-i-1234wxyz .ova</s3Key> </exportToS3> </item> </exportTaskSet> </ DescribeExportTasksResponse>

Related Operations
CancelExportTask (p. 45) CreateInstanceExportTask (p. 58)

API Version 2012-05-01 160

Amazon Elastic Compute Cloud API Reference DescribeImageAttribute

DescribeImageAttribute
Description
Returns information about an attribute of an AMI. You can get information about only one attribute per call. These are the available attributes: descriptionDescription of the AMI provided at image creation kernelID of the kernel associated with the AMI ramdiskID of the RAM disk associated with the AMI launchPermissionLaunch permissions for the AMI productCodesProduct codes associated with the AMI (if any). Each product code contains a product code and a type. blockDeviceMappingBlock device mapping of the AMI

Request Parameters
Name
ImageId

Description The AMI ID. Type: String Default: None The AMI attribute to get. Type: String Default: None Valid Values: description | kernel | ramdisk | launchPermission | productCodes | blockDeviceMapping

Required Yes

Attribute

Yes

Response Elements
The elements in the following table are wrapped in a DescribeImageAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The ID of the AMI. Type: xsd:string A list of launch permissions. Each launch permission's information is wrapped in an item element. Type: LaunchPermissionItemType (p. 429)

imageId

launchPermission

API Version 2012-05-01 161

Amazon Elastic Compute Cloud API Reference Examples

Name
productCodes

Description A list of product codes. Each product code's information is wrapped in an item element that contains a product code and a product code type. Type: ProductCodeItemType (p. 442) Kernel ID, wrapped in a value element. Type: xsd:string RAM disk ID, wrapped in a value element. Type: xsd:string User-created description of the AMI, wrapped in a value element. Type: xsd:string List of block device mappings. Each mapping's information is wrapped in an item element. Type: BlockDeviceMappingItemType (p. 389)

kernel

ramdisk

description

blockDeviceMapping

Examples
Example Request
This example lists the launch permissions for the ami-61a54008 AMI
https://ec2.amazonaws.com/?Action=DescribeImageAttribute &ImageId=ami-61a54008 &Attribute=launchPermission &AUTHPARAMS

Example Response
<DescribeImageAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId<59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <imageId>ami-61a54008</imageId> <launchPermission> <item> <group>all</group> </item> <item> <userId>495219933132</userId> </item> </launchPermission> </DescribeImageAttributeResponse>

Example Request
This example lists the product code for the ami-2bb65342 AMI.

API Version 2012-05-01 162

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribeImageAttribute &ImageId=ami-2bb65342 &Attribute=productCodes &AUTHPARAMS

Example Response
<DescribeImageAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <imageId>ami-2bb65342</imageId> <productCodes> <item> <productCode>a1b2c3d4e5f6g7h8i9j10k11</productCode> <type>marketplace</type> </item> </productCodes> </DescribeImageAttributeResponse>

Related Operations
DescribeImages (p. 164) ModifyImageAttribute (p. 310) ResetImageAttribute (p. 352)

API Version 2012-05-01 163

Amazon Elastic Compute Cloud API Reference DescribeImages

DescribeImages
Description
Returns information about AMIs, AKIs, and ARIs. Images available to you include public images, private images that you own, and private images owned by other AWS accounts but for which you have explicit launch permissions. Launch permissions fall into three categories: Launch Permission public explicit implicit Description The owner of the AMI granted launch permissions for the AMI to the all group. All AWS accounts have launch permissions for these AMIs. The owner of the AMI granted launch permissions to a specific AWS account. An AWS account has implicit launch permissions for all the AMIs it owns.

The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, or AWS accounts with launch permissions. If no options are specified, Amazon EC2 returns all AMIs for which you have launch permissions. If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. If you specify an invalid AMI ID, an error is returned. If you specify an AMI ID for which you do not have access, it will not be included in the returned results. If you specify one or more AMI owners, only AMIs from the specified owners and for which you have access are returned. The results can include the account IDs of the specified ownersamazon for AMIs owned by Amazon or self, for AMIs that you own, or marketplace for AMIs from the AWS Marketplace.

Note
For an overview of the AWS Marketplace, go to https://aws.amazon.com/marketplace/help/200900000. For details on how to use the AWS Marketplace, see AWS Marketplace. If you specify a list users with launch permissions, only AMIs with launch permissions for those users are returned. You can specify account IDs (if you own the AMI(s)), self for AMIs for which you own or have explicit permissions, or all for public AMIs.

Note
Deregistered images are included in the returned results for an unspecified interval after deregistration.

You can filter the results to return information only about images that match criteria you specify. For example, you could get information only about images that use a certain kernel. You can specify multiple values for a filter (e.g., the image uses either kernel aki-1a2b3c4d or kernel aki-9b8c7d6f). An image must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the image uses a certain kernel, and uses an Amazon EBS volume as the root device). The result includes information for a particular image only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty.
API Version 2012-05-01 164

Amazon Elastic Compute Cloud API Reference Description

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
architecture

Description Image architecture. Type: String Valid Values: i386 | x86_64

block-device-mapping.delete-on-termination Whether the Amazon EBS volume is deleted on instance termination. Type: Boolean block-device-mapping.device-name

Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the image. Type: String Snapshot ID for an Amazon EBS volume mapped to the image. Type: String Volume size for an Amazon EBS volume mapped to the image. Type: Integer Description of the AMI (provided during image creation). Type: String ID of the image. Type: String Type of image. Type: String Valid Values: machine | kernel | ramdisk Whether the image is public. Type: Boolean Kernel ID. Type: String Location of the image manifest. Type: String Name of the AMI (provided during image creation). Type: String AWS account alias (e.g., amazon) Type: String

block-device-mapping.snapshot-id

block-device-mapping.volume-size

description

image-id

image-type

is-public

kernel-id

manifest-location

name

owner-alias

API Version 2012-05-01 165

Amazon Elastic Compute Cloud API Reference Description

Filter Name
owner-id

Description AWS account ID of the image owner. Type: String To only list Windows-based AMIs, use windows. Otherwise leave blank. Type: String Valid Value: windows Product code associated with the AMI. Type: String Type of AMI product code. Type: String Valid Values: devpay | marketplace RAM disk ID. Type: String Root device name of the AMI (e.g., /dev/sda1). Type: String Root device type the AMI uses. Type: String Valid Values: ebs | instance-store State of the image. Type: String Valid Values: available | pending | failed Reason code for the state change. Type: String Message for the state change. Type: String Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

platform

product-code

product-code.type

ramdisk-id

root-device-name

root-device-type

state

state-reason-code

state-reason-message

tag-key

tag-value

API Version 2012-05-01 166

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y Virtualization type of the image. Type: String Valid Values: paravirtual | hvm Hypervisor type of the image. Type: String Valid Values: ovm | xen

virtualization-type

hypervisor

Request Parameters
Name
ExecutableBy.n

Description

Required

Returns AMIs for which the specified user ID has explicit No launch permissions. The user ID can be an AWS account ID, self to return AMIs for which the sender of the request has explicit launch permissions, or all to return AMIs with public launch permissions. Type: String Default: None One or more AMI IDs. Type: String Default: Returns all AMIs, or only those otherwise specified. No

ImageId.n

Owner.n

Returns AMIs owned by the specified owner. Multiple No owner values can be specified. The IDs amazon, aws-marketplace, and self can be used to include AMIs owned by Amazon, AWS Marketplace, or AMIs owned by you, respectively. Type: String Default: None Valid Values: amazon | aws-marketplace | self | AWS account ID | all

API Version 2012-05-01 167

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Name

Description Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeImagesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of images. Each image's information is wrapped in an item element. Type: DescribeImagesResponseItemType (p. 397)

imagesSet

Examples
Example Request
This example describes the ami-be3adfd7 AMI.
https://ec2.amazonaws.com/?Action=DescribeImages &ImageId.1=ami-be3adfd7 &AUTHPARAMS

Example Response
<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <imagesSet> <item> <imageId>ami-be3adfd7</imageId> <imageLocation>amazon/getting-started</imageLocation> <imageState>available</imageState> <imageOwnerId>206029621532</imageOwnerId> <isPublic>true</isPublic> <architecture>i386</architecture> <imageType>machine</imageType> <kernelId>aki-d3376696</kernelId> <ramdiskId>ari-e73766a2</ramdiskId>

API Version 2012-05-01 168

Amazon Elastic Compute Cloud API Reference Examples

<imageOwnerAlias>amazon</imageOwnerAlias> <name>getting-started</name> <description>Fedora 8 v1.11 i386 lvm-rootVG-rootFS ext3 ec2pnp enabled</de scription> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda</rootDeviceName> <blockDeviceMapping> <item> <deviceName>/dev/sda</deviceName> <ebs> <snapshotId>snap-32885f5a</snapshotId> <volumeSize>15</volumeSize> <deleteOnTermination>false</deleteOnTermination> </ebs> </item> </blockDeviceMapping> <virtualizationType>paravirtual</virtualizationType> <tagSet/> <hypervisor>xen</hypervisor> </item> </imagesSet> </DescribeImagesResponse>

Example Request
This example filters the results to display only the public Windows images with an x86_64 architecture.
https://ec2.amazonaws.com/?Action=DescribeImages &Filter.1.Name=is-public &Filter.1.Value.1=true &Filter.2.Name=architecture &Filter.2.Value.1=x86_64 &Filter.3.Name=platform &Filter.3.Value.1=windows &AUTHPARAMS

Example Response
<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <imagesSet> <item> <imageId>ami-dd20c3b4</imageId> <imageLocation>ec2-public-windows-images/Server2003r2-x86_64-Winv1.07.manifest.xml</imageLocation> <imageState>available</imageState> <imageOwnerId>206029621532</imageOwnerId> <isPublic>true</isPublic> <architecture>x86_64</architecture> <imageType>machine</imageType> <platform>windows</platform> <imageOwnerAlias>amazon</imageOwnerAlias> <rootDeviceType>instance-store</rootDeviceType> <blockDeviceMapping/> <virtualizationType>hvm</virtualizationType>

API Version 2012-05-01 169

Amazon Elastic Compute Cloud API Reference Examples

<tagSet/> <hypervisor>xen</hypervisor> </item> ... </imagesSet> </DescribeImagesResponse>

Example Request
This example retruns the results to display images where the owner is aws-marketplace.
https://ec2.amazonaws.com/?Action=DescribeImages &Owner.0=aws-marketplace &AUTHPARAMS

Example Response
<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>4a4a27a2-2e7c-475d-b35b-ca822EXAMPLE</requestId> <imagesSet> <item> <imageId>ami-a2469acf</imageId> <imageLocation>aws-marketplace/example-marketplace-amzn-ami.1</im ageLocation> <imageState>available</imageState> <imageOwnerId>123456789999</imageOwnerId> <isPublic>true</isPublic> <productCodes> <item> <productCode>a1b2c3d4e5f6g7h8i9j10k11</productCode> <type>marketplace</type> </item> </productCodes> <architecture>i386</architecture> <imageType>machine</imageType> <kernelId>aki-805ea7e9</kernelId> <imageOwnerAlias>aws-marketplace</imageOwnerAlias> <name>example-marketplace-amzn-ami.1</name> <description>Amazon Linux AMI i386 EBS</description> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping> <item> <deviceName>/dev/sda1</deviceName> <ebs> <snapshotId>snap-787e9403</snapshotId> <volumeSize>8</volumeSize> <deleteOnTermination>true</deleteOnTermination> </ebs> </item> </blockDeviceMapping> <virtualizationType>paravirtual</virtualizationType> <hypervisor>xen</hypervisor> </item> ...

API Version 2012-05-01 170

Amazon Elastic Compute Cloud API Reference Related Operations

</imagesSet> </DescribeImagesResponse>

Related Operations
DescribeInstances (p. 175) DescribeImageAttribute (p. 161)

API Version 2012-05-01 171

Amazon Elastic Compute Cloud API Reference DescribeInstanceAttribute

DescribeInstanceAttribute
Description
Returns information about an attribute of an instance. You can get information about only one attribute per call. These are the available attributes: instanceTypeInstance type (e.g., m1.small) kernelID of the kernel associated with the instance ramdiskID of the RAM disk associated with the instance userDataMIME, Base64-encoded user data provided to the instance disableApiTerminationWhether the instance can be terminated using the Amazon EC2 API (false means the instance can be terminated with the API) instanceInitiatedShutdownBehaviorWhether the instance stops or terminates when an instance shutdown is initiated (default is stop) productCodesProduct codes associated with the instance. Each product code contains a product code and a type. blockDeviceMappingBlock device mapping of the instance sourceDestCheckThis attribute exists to enable a Network Address Translation (NAT) instance in a VPC to perform NAT. The attribute controls whether source/destination checking is enabled on the instance. A value of true means checking is enabled. The value must be false for the instance to perform NAT. groupSetSecurity groups the instance belongs to

Request Parameters
Name
InstanceId

Description The instance ID. Type: String Default: None The instance attribute to get. Type: String Default: None Valid Values: instanceType | kernel | ramdisk | userData | disableApiTermination | instanceInitiatedShutdownBehavior | rootDeviceName | blockDeviceMapping | productCodes | sourceDestCheck | groupSet

Required Yes

Attribute

Yes

Response Elements
The elements in the following table are wrapped in a DescribeInstanceAttributeResponse structure.

API Version 2012-05-01 172

Amazon Elastic Compute Cloud API Reference Response Elements

Name
requestId

Description The ID of the request. Type: xsd:string The ID of the instance. Type: xsd:string The instance type (e.g., m1.small), wrapped in a value element. Type: xsd:string The kernel ID, wrapped in a value element. Type: xsd:string The RAM disk ID, wrapped in a value element. Type: xsd:string MIME, Base64-encoded user data, wrapped in a value element. Type: xsd:string Indicates whether the instance can be terminated through the Amazon EC2 API. The value is wrapped in a value element. A value of true means you can't terminate the instance using the API (i.e., the instance is "locked"); a value of false means you can. You must modify this attribute before you can terminate any "locked" instances using the API. Type: xsd:boolean If an instance shutdown is initiated, this determines whether the instance stops or terminates. The value is wrapped in a value element. Type: xsd:string Valid Values: stop | terminate The root device name (e.g., /dev/sda1), wrapped in a value element. Type: xsd:string List of block device mappings for the instance. Each mapping's information is wrapped in an item element. Type: InstanceBlockDeviceMappingResponseItemType (p. 415) This attribute exists to enable a Network Address Translation (NAT) instance in a VPC to perform NAT. The attribute controls whether source/destination checking is enabled on the instance. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform NAT. For more information, go to NAT Instances in the Amazon Virtual Private Cloud User Guide. Type: xsd:boolean Security groups the instance belongs to. Each group's information is wrapped in an item element. Type: GroupItemType (p. 410)

instanceId

instanceType

kernel

ramdisk

userData

disableApiTermination

instanceInitiatedShu tdownBehavior

rootDeviceName

blockDeviceMapping

sourceDestCheck

groupSet

API Version 2012-05-01 173

Amazon Elastic Compute Cloud API Reference Examples

Name
productCodes

Description A list of product codes. Each product code's information is wrapped in an item element that contains a product code and a product code type that contains a product code and a type. Type: ProductCodesSetItemType (p. 442)

Examples
Example Request
This example lists the kernel ID of the i-10a64379 instance.
https://ec2.amazonaws.com/?Action=DescribeInstanceAttribute &InstanceId=i-10a64379 &Attribute=kernel &AUTHPARAMS

Example Response
<DescribeInstanceAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instanceId>i-10a64379</instanceId> <kernel> <value>aki-f70657b2</value> </kernel> </DescribeInstanceAttributeResponse>

Related Operations
DescribeInstances (p. 175) ModifyInstanceAttribute (p. 313) ResetInstanceAttribute (p. 354)

API Version 2012-05-01 174

Amazon Elastic Compute Cloud API Reference DescribeInstances

DescribeInstances
Description
Returns information about instances that you own. If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an invalid instance ID, an error is returned. If you specify an instance that you do not own, it will not be included in the returned results. Recently terminated instances might appear in the returned results. This interval is usually less than one hour. You can filter the results to return information only about instances that match criteria you specify. For example, you could get information about only instances launched with a certain key pair.You can specify multiple values for a filter (e.g., the instance was launched with either key pair A or key pair B). An instance must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the instance was launched with a certain key pair and uses an Amazon EBS volume as the root device). An instance must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
architecture

Description Instance architecture. Type: String Valid Values: i386 | x86_64 Instance's Availability Zone. Type: String Attach time for an Amazon EBS volume mapped to the instance, e.g., 2010-09-15T17:15:20.000Z Type: xsd:dateTime

availability-zone

block-device-mapping.attach-time

block-device-mapping.delete-on-termination Whether the Amazon EBS volume is deleted on instance termination. Type: Boolean block-device-mapping.device-name

Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the instance. Type: String Status for an Amazon EBS volume mapped to the instance. Type: String Valid Values: attaching | attached | detaching | detached

block-device-mapping.status

API Version 2012-05-01 175

Amazon Elastic Compute Cloud API Reference Description

Filter Name
block-device-mapping.volume-id

Description ID for an Amazon EBS volume mapped to the instance. Type: String Idempotency token you provided when you launched the instance. Type: String Public DNS name of the instance. Type: String ID of a EC2 security group the instance is in. This filter does not work for VPC security groups (instead, use instance.group-id). Type: String Name of a EC2 security group the instance is in. This filter does not work for VPC security groups (instead, use instance.group-name). Type: String ID of the image used to launch the instance. Type: String ID of the instance. Type: String Whether this is a Spot Instance. Type: String Valid Values: spot Code identifying the instance's state. A 16-bit unsigned integer. The high byte is an opaque internal value and should be ignored. The low byte is set based on the state represented Type: Integer Valid Values: 0 (pending) | 16 (running) | 32 (shutting-down) | 48 (terminated) | 64 (stopping) | 80 (stopped) Instance's state. Type: String Valid Values: pending | running | shutting-down | terminated | stopping | stopped Type of instance (e.g., m1.small). Type: String

client-token

dns-name

group-id

group-name

image-id

instance-id

instance-lifecycle

instance-state-code

instance-state-name

instance-type

API Version 2012-05-01 176

Amazon Elastic Compute Cloud API Reference Description

Filter Name
instance.group-id

Description ID of a VPC security group the instance is in. This filter does not work for EC2 security groups (instead, use group-id). Type: String Name of a VPC security group the instance is in. This filter does not work for EC2 security groups (instead, use group-name). Type: String Public IP address of the instance. Type: String Kernel ID. Type: String Name of the key pair used when the instance was launched. Type: String When launching multiple instances at once, this is the index for the instance in the launch group (e.g., 0, 1, 2, etc.). Type: String Time instance was launched, e.g., 2010-08-07T11:54:42.000Z. Type: xsd:dateTime Whether monitoring is enabled for the instance. Type: String Valid Values: disabled | enabled AWS account ID of the instance owner. Type: String Name of the placement group the instance is in. Type: String Use windows if you have Windows based instances; otherwise, leave blank. Type: String Valid Value: windows Private DNS name of the instance. Type: String Private IP address of the instance. Type: String

instance.group-name

ip-address

kernel-id

key-name

launch-index

launch-time

monitoring-state

owner-id

placement-group-name

platform

private-dns-name

private-ip-address

API Version 2012-05-01 177

Amazon Elastic Compute Cloud API Reference Description

Filter Name
product-code

Description Product code associated with the AMI used to launch the instance. Type: String Type of product code. Type: String Valid Values: devpay | marketplace RAM disk ID. Type: String Reason for the instance's current state (e.g., shows "User Initiated [date]" when you stop or terminate the instance). Similar to the state-reason-code filter. Type: String ID of the entity that launched the instance on your behalf (e.g., AWS Management Console, Auto Scaling, etc.) Type: String ID of the instance's reservation. A reservation ID is created any time you launch an instance. A reservation ID has a one-to-one relationship with an instance launch request, but can be associated with more than one instance if you launch multiple instances using the same launch request. For example, if you launch one instance, youll get one reservation ID. If you launch ten instances using the same launch request, youll also get one reservation ID. Type: String Root device name of the instance (e.g., /dev/sda1). Type: String Root device type the instance uses. Type: String Valid Values: ebs | instance-store Whether the instance performs source/destination checking. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform Network Address Translation (NAT) in your VPC. Type: Boolean ID of the Spot Instance request. Type: String Reason code for the state change. Type: String

product-code.type

ramdisk-id

reason

requester-id

reservation-id

root-device-name

root-device-type

source-dest-check

spot-instance-request-id

state-reason-code

API Version 2012-05-01 178

Amazon Elastic Compute Cloud API Reference Description

Filter Name
state-reason-message

Description Message for the state change. Type: String ID of the subnet the instance is in (if using Amazon Virtual Private Cloud). Type: String Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y Virtualization type of the instance. Type: String Valid Values: paravirtual | hvm ID of the VPC the instance is in (if using Amazon Virtual Private Cloud). Type: String Hypervisor type of the instance. Type: String Valid Values: ovm | xen

subnet-id

tag-key

tag-value

tag:key

virtualization-type

vpc-id

hypervisor

API Version 2012-05-01 179

Amazon Elastic Compute Cloud API Reference Request Parameters

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: Returns all instances, or only those otherwise specified. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Name

No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of reservations. Each reservation's information is wrapped in an item element. Type: ReservationInfoType (p. 444)

reservationSet

Examples
Example Request
This example describes the current state of the instances owned by your AWS account.
https://ec2.amazonaws.com/?Action=DescribeInstances &AUTHPARAMS

Example Response
<DescribeInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2011-11-15/'> <requestId>d70b71d8-33ee-420f-a9a6-aa8eb76976bf</requestId> <reservationSet> <item> <reservationId>r-93933bf2</reservationId>

API Version 2012-05-01 180

Amazon Elastic Compute Cloud API Reference Examples

<ownerId>111122223333</ownerId> <groupSet/> <instancesSet> <item> <instanceId>i-9cc316fe</instanceId> <imageId>ami-31814f58</imageId> <instanceState> <code>272</code> <name>running</name> </instanceState> <privateDnsName/> <dnsName/> <reason/> <amiLaunchIndex>0</amiLaunchIndex> <productCodes/> <instanceType>m1.small</instanceType> <launchTime>2011-12-20T07:48:20.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> <groupName/> <tenancy>default</tenancy> </placement> <kernelId>aki-805ea7e9</kernelId> <monitoring> <state>disabled</state> </monitoring> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <privateIpAddress>10.0.0.4</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <architecture>i386</architecture> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping> <item> <deviceName>/dev/sda1</deviceName> <ebs> <volumeId>vol-37d5b75a</volumeId> <status>attached</status> <attachTime>2011-12-20T07:49:00.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </ebs> </item> </blockDeviceMapping> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <hypervisor>xen</hypervisor> <networkInterfaceSet> <item> <networkInterfaceId>eni-21a04b49</networkInterfaceId>

API Version 2012-05-01 181

Amazon Elastic Compute Cloud API Reference Examples

<subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <description/> <ownerId>111122223333</ownerId> <status>in-use</status> <privateIpAddress>10.0.0.4</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <attachment> <attachmentId>eni-attach-0720626e</attachmentId> <deviceIndex>0</deviceIndex> <status>attached</status> <attachTime>2011-12-20T07:48:20.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </attachment> </item> </networkInterfaceSet> </item> </instancesSet> </item> <item> <reservationId>r-157ad274</reservationId> <ownerId>111122223333</ownerId> <groupSet/> <instancesSet> <item> <instanceId>i-0ee0356c</instanceId> <imageId>ami-31814f58</imageId> <instanceState> <code>16</code> <name>running</name> </instanceState> <privateDnsName/> <dnsName/> <reason/> <amiLaunchIndex>0</amiLaunchIndex> <productCodes> <item> <productCode>a1b2c3d4e5f6g7h8i9j10k11</productCode> <type>marketplace</type> </item> <productCodes/> <instanceType>m1.small</instanceType> <launchTime>2011-12-20T08:29:31.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> <groupName/> <tenancy>default</tenancy>

API Version 2012-05-01 182

Amazon Elastic Compute Cloud API Reference Examples

</placement> <kernelId>aki-805ea7e9</kernelId> <monitoring> <state>disabled</state> </monitoring> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <privateIpAddress>10.0.0.142</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <architecture>i386</architecture> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping> <item> <deviceName>/dev/sda1</deviceName> <ebs> <volumeId>vol-b52a47d8</volumeId> <status>attached</status> <attachTime>2011-12-20T08:30:21.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </ebs> </item> </blockDeviceMapping> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <hypervisor>xen</hypervisor> <networkInterfaceSet> <item> <networkInterfaceId>eni-c6bb50ae</networkInterfaceId> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <description/> <ownerId>111122223333</ownerId> <status>in-use</status> <privateIpAddress>10.0.0.142</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <attachment> <attachmentId>eni-attach-0326646a</attachmentId> <deviceIndex>0</deviceIndex> <status>attached</status> <attachTime>2011-12-20T08:29:31.000Z</attachTime>

API Version 2012-05-01 183

Amazon Elastic Compute Cloud API Reference Examples

<deleteOnTermination>true</deleteOnTermination> </attachment> </item> </networkInterfaceSet> </item> </instancesSet> </item> </reservationSet> </DescribeInstancesResponse>

Example Request
This example filters the results to display only the m1.small or m1.large instances that have an Amazon EBS volume that is both attached and set to delete on termination.
https://ec2.amazonaws.com/?Action=DescribeInstances &Filter.1.Name=instance-type &Filter.1.Value.1=m1.small &Filter.1.Value.2=m1.large &Filter.2.Name=block-device-mapping.status &Filter.2.Value.1=attached &Filter.3.Name=block-device-mapping.delete-on-termination &Filter.3.Value.1=true &AUTHPARAMS

Example Response
<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <reservationSet> <item> <reservationId>r-bc7e30d7</reservationId> <ownerId>111122223333</ownerId> <groupSet> <item> <groupId>sg-2eac845a</groupId> <groupName>default</groupName> </item> </groupSet> <instancesSet> <item> <instanceId>i-c7cd56ad</instanceId> <imageId>ami-b232d0db</imageId> <instanceState> <code>16</code> <name>running</name> </instanceState> <privateDnsName>domU-12-31-39-01-76-06.compute-1.intern al</privateDnsName> <dnsName>ec2-72-44-52-124.compute-1.amazonaws.com</dnsName> <keyName>GSG_Keypair</keyName> <amiLaunchIndex>0</amiLaunchIndex> <productCodes/> <instanceType>m1.small</instanceType>

API Version 2012-05-01 184

Amazon Elastic Compute Cloud API Reference Examples

<launchTime>2010-08-17T01:15:16.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> </placement> <kernelId>aki-94c527fd</kernelId> <ramdiskId>ari-96c527ff</ramdiskId> <monitoring> <state>disabled</state> </monitoring> <privateIpAddress>10.255.121.240</privateIpAddress> <ipAddress>72.44.52.124</ipAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-2eac845a</groupId> <groupName>default</groupName> </item> </groupSet> <architecture>i386</architecture> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping> <item> <deviceName>/dev/sda1</deviceName> <ebs> <volumeId>vol-a482c1cd</volumeId> <status>attached</status> <attachTime>2010-08-17T01:15:26.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </ebs> </item> </blockDeviceMapping/> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <tagSet/> <hypervisor>xen</hypervisor> </item> </instancesSet> </item> </reservationSet> </DescribeInstancesResponse>

Related Operations
RunInstances (p. 366) StopInstances (p. 378) StartInstances (p. 376) TerminateInstances (p. 380)

API Version 2012-05-01 185

Amazon Elastic Compute Cloud API Reference DescribeInstanceStatus

DescribeInstanceStatus
Description
Describes the status of an Amazon EC2 instance including any scheduled events for an instance. Instance status has two main components: System Status reports impaired functionality that stems from issues related to the systems that support an instance, such as such as hardware failures and network connectivity problems. The DescribeInstanceStatus response elements report such problems as impaired reachability.. Instance Status reports impaired functionality that arises from problems internal to the instance. The DescribeInstanceStatus response elements report such problems as impaired reachability.

Instance status provides information about three types of scheduled events for an instance that may require your attention: Scheduled Reboot: When Amazon EC2 determines that an instance must be rebooted, the instances status will return one of two event codes: system-reboot or instance-reboot. System reboot commonly occurs if certain maintenance or upgrade operations require a reboot of the underlying host that supports an instance. Instance reboot commonly occurs if the instance must be rebooted, rather than the underlying host. Rebooting events include a scheduled start and end time. System Maintenance: When Amazon EC2 determines that an instance requires maintenance that requires power or network impact, the instance's status will return an event code called system-maintenance. System maintenance is either power maintenance or network maintenance. For power maintenance, your instance will be unavailable for a brief period of time and then rebooted. For network maintenance, your instance will experience a brief loss of network connectivity. System maintenance events include a scheduled start and end time. You will also be notified by email if one of your instances is set for system maintenance. The email message indicates when your instance is scheduled for maintenance. Scheduled Retirement: When Amazon EC2 determines that an instance must be shut down, the instances status will return an event code called instance-retirement. Retirement commonly occurs when the underlying host is degraded and must be replaced. Retirement events include a scheduled start and end time.You will also be notified by email if one of your instances is set to retiring. The email message indicates when your instance will be permanently retired.

When your instance is retired, it will either be terminated (if its root device type is the instance-store) or stopped (if its root device type is an EBS volume). Instances stopped due to retirement will not be restarted, but you can do so manually.You can also avoid retirement of EBS-backed instances by manually restarting your instance when its event code is instance-retirement. This ensures that your instance is started on a different underlying host.
DescribeInstanceStatus returns information only for instances in the running state.

You can filter the results to return information only about instances that match criteria you specify. For example, you could get information about instances in a specific Availability Zone.You can specify multiple values for a filter (e.g., more than one Availability Zone). An instance must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the instance is in a specific Availability Zone and its status is set to retiring). An instance must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty.

API Version 2012-05-01 186

Amazon Elastic Compute Cloud API Reference Description

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
availability-zone

Description Instance's Availability Zone. Type: String Code identifying the type of event. Type: String Valid Values: instance-reboot | system-reboot | system-maintenance | instance-retirement A description of the event. Type: String The latest end time for the scheduled event. Type: dateType The earliest start time for the scheduled event. Type: dateType Intended state of the instance, e.g., running Type: String Code for intended state of the instance, e.g., 16. Type: Integer The instance's system status. Type: String Valid Values: ok | impaired | initializing | insufficient-data | not-applicable Filters on system status where the name is reachability. Type: String Valid Values: passed | failed | initializing | insufficient-data The instance's status. Type: String Valid Values: ok | impaired | initializing | insufficient-data | not-applicable Filters on instance status where the name is reachability. Type: String Valid Values: passed | failed |initializing | insufficient-data

event.code

event.description

event.not-after

event.not-before

instance-state-name

instance-state-code

system-status.status

system-status.reachability

instance-status.status

instance-status.reachability

API Version 2012-05-01 187

Amazon Elastic Compute Cloud API Reference Request Parameters

Request Parameters
Name
InstanceId

Description The list of instance IDs. If not specified, all instances are described. Type: String Default: None

Required No

IncludeAllInstances

When true, returns the health status for all instances (e.g., No running, stopped, pending, shutting down, etc.). When false, returns only the health status for running instances. Type: Boolean Default: false The maximum number of paginated instance items per response. Type: Integer Default: None A string specifying the next paginated set of results to return. Type: String Default: None No

MaxResults

NextToken

No

Response Elements
The elements in the following table are wrapped in a DescribeInstanceStatusResponse structure. Name
requestId

Description The ID of the request. Type: String A set of InstanceStatusItemType (p. 418) elements that describe the status of each instance. A string specifying the next paginated set of results to return. Type: String

InstanceStatusSet

NextToken

Examples
Example Request
This example returns instance status descriptions for all instances.
https://ec2.amazonaws.com/? Action=DescribeInstanceStatus

API Version 2012-05-01 188

Amazon Elastic Compute Cloud API Reference Examples

&Version=2011-10-01 &AuthParams

Example Request
This example returns instance status descriptions for the specified instances.
https://ec2.amazonaws.com/? Action=DescribeInstanceStatus &InstanceId.0=i-0cf27c63 &InstanceId.1=i-283f9f47 &Version=2011-10-01 &AuthParams

Example Request
This example returns instance status descriptions for all instances specified by supported DescribeInstanceStatus filters.
https://ec2.amazonaws.com/? Action=DescribeInstanceStatus &Filter.0.Name=system-status.reachability &Filter.0.Value.failed &Version=2011-10-01 &AuthParams

Example Response
<DescribeInstanceStatusResponse xmlns='http://ec2.amazonaws.com/doc/2012-0401/'> <requestId>3be1508e-c444-4fef-89cc-0b1223c4f02f</requestId> <instanceStatusSet> <item> <instanceId>i-283f9f47</instanceId> <availabilityZone>us-east-1d</availabilityZone> <instanceState> <code>16</code> <name>running</name> </instanceState> <systemStatus> <status>impaired</status> <details> <item> <name>reachability</name> <status>failed</status> <impairedSince>2012-03-27T16:10:46.000Z</impairedSince> </item> </details> </systemStatus> <instanceStatus> <status>impaired</status>

API Version 2012-05-01 189

Amazon Elastic Compute Cloud API Reference Examples

<details> <item> <name>reachability</name> <status>failed</status> <impairedSince>2012-03-27T16:10:46.000Z</impairedSince> </item> </details> </instanceStatus> <eventsSet> <code>instance-retirement</eventcode> <notBefore>2011-12-05T13:00:00+0000</notBefore> <notAfter>2011-12-06T13:00:00+000</notAfter> <description> The instance is running on degraded hardware </description> </eventsSet> </item> <item> <instanceId>i-d2e36dbd</instanceId> <availabilityZone>us-east-1d</availabilityZone> <instanceState> <code>16</code> <name>running</name> </instanceState> <systemStatus> <status>ok</status> <details> <item> <name>reachability</name> <status>passed</status> </item> </details> </systemStatus> <instanceStatus> <status>ok</status> <details> <item> <name>reachability</name> <status>passed</status> </item> </details> </instanceStatus> <eventsSet> <code>instance-reboot</eventcode> <notBefore>2011-12-05T13:00:00+0000</notBefore> <notAfter>2011-12-06T13:00:00+000</notAfter> <description> The instance is scheduled for a reboot </description> </eventsSet> </item> <item> <instanceId>i-9fa454f1</instanceId> <availabilityZone>us-east-1c</availabilityZone> <instanceState> <code>16</code> <name>running</name>

API Version 2012-05-01 190

Amazon Elastic Compute Cloud API Reference Examples

</instanceState> <systemStatus> <status>ok</status> <details> <item> <name>reachability</name> <status>passed</status> </item> </details> </systemStatus> <instanceStatus> <status>ok</status> <details> <item> <name>reachability</name> <status>passed</status> </item> </details> </instanceStatus> </item> <item> <instanceId>i-0ed2936e</instanceId> <availabilityZone>us-east-1c</availabilityZone> <instanceState> <code>16</code> <name>running</name> </instanceState> <systemStatus> <status>ok</status> <details> <item> <name>reachability</name> <status>passed</status> </item> </details> </systemStatus> <instanceStatus> <status>insufficient-data</status> <details> <item> <name>reachability</name> <status>insufficient-data</status> </item> </details> </instanceStatus> </item> </instanceStatusSet> </DescribeInstanceStatusResponse>

API Version 2012-05-01 191

Amazon Elastic Compute Cloud API Reference DescribeInternetGateways

DescribeInternetGateways
Description
Gives you information about your Internet gateways. You can filter the results to return information only about Internet gateways that match criteria you specify. For example, you could get information only about gateways with particular tags. The Internet gateway must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the Internet gateway is attached to a particular VPC and is tagged with a particular value). The result includes information for a particular Internet gateway only if the gateway matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
attachment.state

Description Current state of the attachment between the gateway and the VPC. Returned only if a VPC is attached. Type: String Valid Value: available ID of an attached VPC. Type: String

attachment.vpc-id

internet-gateway-id ID of the Internet gateway. Type: String tag-key

Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

tag-value

API Version 2012-05-01 192

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y

For more information about Amazon Virtual Private Cloud and Internet gateways, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
InternetGatewayId.n

Description One or more Internet gateway IDs. Type: String Default: None

Required No

Filter.n.Name

Name of a filter. See the preceding table for a No list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed filter values for each filter. Type: String Default: None No

Filter.n.Value.m

Response Elements
The elements in the following table are wrapped in a DescribeInternetGatewaysResponse structure. Name
requestId

Description The ID of the request. Type: String A list of Internet gateways. Each gateway's information is wrapped in an item element. Type: InternetGatewayType (p. 427)

internetGatewaysSet

API Version 2012-05-01 193

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example describes your Internet gateways.
https://ec2.amazonaws.com/?Action=DescribeInternetGateways

Example Response
<DescribeInternetGatewaysResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <internetGatewaySet> <item> <internetGatewayId>igw-eaad4883EXAMPLE</internetGatewayId> <attachmentSet> <item> <vpcId>vpc-11ad4878</vpcId> <state>available</state> </item> </attachmentSet> <tagSet/> </item> </internetGatewaySet> </DescribeInternetGatewaysResponse>

Related Operations
CreateInternetGateway (p. 61) DeleteInternetGateway (p. 104) DetachInternetGateway (p. 22) DetachInternetGateway (p. 283)

API Version 2012-05-01 194

Amazon Elastic Compute Cloud API Reference DescribeKeyPairs

DescribeKeyPairs
Description
Returns information about key pairs available to you. If you specify key pairs, information about those key pairs is returned. Otherwise, information for all your key pairs is returned. You can filter the results to return information only about key pairs that match criteria you specify. For example, you could filter the results to return only the key pairs whose names include the string Dave. You can specify multiple values for a filter. A key pair must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the key pair name includes the string Dave, and the fingerprint equals a certain value). The result includes information for a particular key pair only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
fingerprint

Description Fingerprint of the key pair. Type: String Name of the key pair. Type: String

key-name

Request Parameters
Name
KeyName.n

Description One or more key pair names. Type: String Default: Describes all key pairs you own, or only those otherwise specified. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Name

No

Filter.n.Value.m

No

API Version 2012-05-01 195

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a DescribeKeyPairsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of key pairs. Each key pair's information is wrapped in an item element. Type: DescribeKeyPairsResponseItemType (p. 399)

keySet

Examples
Example Request
This example describes the keypair with name gsg-keypair.
https://ec2.amazonaws.com/?Action=DescribeKeyPairs &KeyName.1=gsg-keypair &AUTHPARAMS

Example Response
<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <keySet> <item> <keyName>gsg-keypair</keyName> <keyFingerprint> 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 </keyFingerprint> </item> </keySet> </DescribeKeyPairsResponse>

Example Request
This example filters the results to display only key pairs whose names include the string Dave.
https://ec2.amazonaws.com/?Action=DescribeKeyPairs &Filter.1.Name=key-name &Filter.1.Value.1=*Dave* &AUTHPARAMS

Related Operations
CreateKeyPair (p. 63) ImportKeyPair (p. 305)
API Version 2012-05-01 196

Amazon Elastic Compute Cloud API Reference Related Operations

DeleteKeyPair (p. 106)

API Version 2012-05-01 197

Amazon Elastic Compute Cloud API Reference DescribeNetworkAcls

DescribeNetworkAcls
Description
Gives you information about the network ACLs in your VPC. You can filter the results to return information only about ACLs that match criteria you specify. For example, you could get information only about the ACL associated with a particular subnet. The ACL must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the ACL is associated with a particular subnet and has an egress entry that denies traffic to a particular port). The result includes information for a particular ACL only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
association.association-id

Description ID of an association ID for the ACL. Type: String ID of the network ACL involved in the association. Type: String ID of the subnet involved in the association. Type: String Whether the ACL is the default network ACL in the VPC. Type: Boolean CIDR range specified in the entry. Type: String Whether the entry applies to egress traffic. Type: Boolean The ICMP code specified in the entry, if any. Type: Integer The ICMP type specified in the entry, if any. Type: Integer Start of port range specified in the entry. Type: Integer End of port range specified in the entry. Type: Integer

association.network-acl-id

association.subnet-id

default

entry.cidr

entry.egress

entry.icmp.code

entry.icmp.type

entry.port-range.from

entry.port-range.to

API Version 2012-05-01 198

Amazon Elastic Compute Cloud API Reference Description

Filter Name
entry.protocol

Description Protocol specified in the entry. Type: String Valid Values: tcp | udp | icmp or a protocol number Whether the entry allows or denies the matching traffic. Type: String Valid Values: allow | deny Number of an entry (i.e., rule) in the ACL's set of entries. Type: Integer ID of the network ACL. Type: String Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y The ID of the VPC the network ACL is in. Type: String

entry.rule-action

entry.rule-number

network-acl-id

tag-key

tag-value

tag:key

vpc-id

For more information about Amazon Virtual Private Cloud and network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.
API Version 2012-05-01 199

Amazon Elastic Compute Cloud API Reference Request Parameters

Request Parameters
Name
NetworkAclId.n

Description One or more network ACL IDs. Type: string Default: None

Required No

Filter.n.Name

Name of a filter. See the preceding table for a No list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed filter values for each filter. Type: String Default: None No

Filter.n.Value.m

Response Elements
The elements in the following table are wrapped in a DescribeNetworkAclsResponse structure. Name
requestId

Description The ID of the request. Type: String A list of network ACLs. Each network ACL's information is wrapped in an item element. Type: NetworkAclType (p. 434)

networkAclSet

Examples
Example Request
This example describes all the network ACLs in your VPC.
https://ec2.amazonaws.com/?Action=DescribeNetworkAcls

Example Response
The first ACL in the returned list is the VPC's default ACL.
<DescribeNetworkAclsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <networkAclSet> <item>

API Version 2012-05-01 200

Amazon Elastic Compute Cloud API Reference Examples

<networkAclId>acl-5566953c</networkAclId> <vpcId>vpc-5266953b</vpcId> <default>true</default> <entrySet> <item> <ruleNumber>100</ruleNumber> <protocol>all</protocol> <ruleAction>allow</ruleAction> <egress>true</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> <item> <ruleNumber>32767</ruleNumber> <protocol>all</protocol> <ruleAction>deny</ruleAction> <egress>true</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> <item> <ruleNumber>100</ruleNumber> <protocol>all</protocol> <ruleAction>allow</ruleAction> <egress>false</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> <item> <ruleNumber>32767</ruleNumber> <protocol>all</protocol> <ruleAction>deny</ruleAction> <egress>false</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> </entrySet> <associationSet/> <tagSet/> </item> <item> <networkAclId>acl-5d659634</networkAclId> <vpcId>vpc-5266953b</vpcId> <default>false</default> <entrySet> <item> <ruleNumber>110</ruleNumber> <protocol>6</protocol> <ruleAction>allow</ruleAction> <egress>true</egress> <cidrBlock>0.0.0.0/0</cidrBlock> <portRange> <from>49152</from> <to>65535</to> </portRange> </item> <item> <ruleNumber>32767</ruleNumber> <protocol>all</protocol> <ruleAction>deny</ruleAction> <egress>true</egress> <cidrBlock>0.0.0.0/0</cidrBlock>

API Version 2012-05-01 201

Amazon Elastic Compute Cloud API Reference Related Operations

</item> <item> <ruleNumber>110</ruleNumber> <protocol>6</protocol> <ruleAction>allow</ruleAction> <egress>false</egress> <cidrBlock>0.0.0.0/0</cidrBlock> <portRange> <from>80</from> <to>80</to> </portRange> </item> <item> <ruleNumber>120</ruleNumber> <protocol>6</protocol> <ruleAction>allow</ruleAction> <egress>false</egress> <cidrBlock>0.0.0.0/0</cidrBlock> <portRange> <from>443</from> <to>443</to> </portRange> </item> <item> <ruleNumber>32767</ruleNumber> <protocol>all</protocol> <ruleAction>deny</ruleAction> <egress>false</egress> <cidrBlock>0.0.0.0/0</cidrBlock> </item> </entrySet> <associationSet> <item> <networkAclAssociationId>aclassoc-5c659635</networkAclAssociationId> <networkAclId>acl-5d659634</networkAclId> <subnetId>subnet-ff669596</subnetId> </item> <item> <networkAclAssociationId>aclassoc-c26596ab</networkAclAssociationId> <networkAclId>acl-5d659634</networkAclId> <subnetId>subnet-f0669599</subnetId> </item> </associationSet> <tagSet/> </item> </networkAclSet> </DescribeNetworkAclsResponse>

Related Operations
CreateNetworkAcl (p. 65) DeleteNetworkAcl (p. 108) ReplaceNetworkAclAssociation (p. 334) CreateNetworkAclEntry (p. 67) DeleteNetworkAclEntry (p. 110) ReplaceNetworkAclEntry (p. 336)
API Version 2012-05-01 202

Amazon Elastic Compute Cloud API Reference DescribeNetworkInterfaceAttribute

DescribeNetworkInterfaceAttribute
Description
Describes a network interface attribute. Only one attribute can be specified per call.

Request Parameters
Name
NetworkInterfaceId

Description The ID of the network interface. Type: String Default: None The attribute of the network interface to get. Type: String Default: None Valid values: description | groupSet | sourceDestCheck | attachment

Required Yes

Attribute

Yes

Response Elements
The elements in the following table are wrapped in a DescribeNetworkInterfaceAttribute structure. Name
requestId

Description The ID of the request. Type: xsd:string The ID of the network interface. Type: xsd:string

networkInterfaceId

Examples
Example Request
This example describes the attributes of a network interface.
http://ec2.us-east-1.amazonaws.com/?Action=DescribeNetworkInterfaceAttribute&Net workInterfaceId=eni-686ea200&Attribute=sourceDestCheck&AUTH_PARAMS

Example Response
<DescribeNetworkInterfaceAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/"> <requestId>7a20c6b2-d71c-45fb-bba7-37306850544b</requestId> <networkInterfaceId>eni-686ea200</networkInterfaceId>

API Version 2012-05-01 203

Amazon Elastic Compute Cloud API Reference Related Operations

<sourceDestCheck> <value>true</value> </sourceDestCheck> </DescribeNetworkInterfaceAttributeResponse>

Related Operations
AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaces (p. 205) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 204

Amazon Elastic Compute Cloud API Reference DescribeNetworkInterfaces

DescribeNetworkInterfaces
Description
Provides information about one or more network interfaces. You can filter the results to return information only about network interfaces that match criteria you specify. For example, you could get information about only network interfaces launched in a specific Availability Zone.You can specify multiple values for a filter (e.g., more than one Availability Zone). A network interface must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the network interface is in a specific Availability Zone, and its owner ID matches a specific owner ID). A network interface must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
association.association-id

Description The association ID returned when the network interface was associated with an IP address. Type: String The allocation ID that AWS returned when you allocated the Elastic IP address for your network interface. Type: String The owner of the Elastic IP address associated with the network interface. Type: String The address of the Elastic IP address bound to the network interface. Type: String The ID of the interface attachment. Type: String The ID of the instance to which the network interface is attached. Type: String The owner ID of the instance to which the network interface is attached. Type: String The device index to which the network interface is attached. Type: Integer

association.allocation-id

association.ip-owner-id

association.public-ip

attachment.attachment-id

attachment.instance-id

attachment.instance-owner-id

attachment.device-index

API Version 2012-05-01 205

Amazon Elastic Compute Cloud API Reference Description

Filter Name
attachment.status

Description The status of the attachment. Type: String Valid values: attaching | attached | detaching | detached The time that the network interface was attached to an instance. Type: Date Indicates whether or not the attachment is deleted when an instance is terminated. Type: Boolean Availability Zone of the network interface. Type: String The description of the network interface. Type: String ID of a VPC security group associated with the network interface. Type: String Name of a VPC security group associated with the network interface. Type: String The MAC address of the network interface. Type: String The ID of the network interface. Type: String The AWS account ID of the network interface owner. Type: String The private IP address of the network interface. Type: String The private DNS name of the network interface. Type: String ID of the entity that launched the instance on your behalf (e.g., AWS Management Console, Auto Scaling, etc.). Type: String Indicates whether the network interface is being managed by an AWS service (e.g., AWS Management Console, Auto Scaling, etc). Type: Boolean

attachment.attach.time

attachment.delete-on-termination

availability-zone

description

group-id

group-name

mac-address

network-interface-id

owner-id

private-ip-address

private-dns-name

requester-id

requester-managed

API Version 2012-05-01 206

Amazon Elastic Compute Cloud API Reference Description

Filter Name
source-dest-check

Description Whether the network interface performs source/destination checking. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the network interface to perform Network Address Translation (NAT) in your VPC. Type: Boolean The status of the network interface. If the network interface is not attached to an instance, the status shows available; if a network interface is attached to an instance the status shows in-use. Type: String Valid values: available | in-use The ID of the subnet that the network interface is in. Type: String Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y The ID of the VPC that the network interface is in. Type: String

status

subnet-id

tag-key

tag-value

tag:key

vpc-id

API Version 2012-05-01 207

Amazon Elastic Compute Cloud API Reference Request Parameters

Request Parameters
Name
NetworkInterfaceId.n

Description One or more network interface IDs. Type: String Default: None The filter name to use. Type: string Default: None The filter value to use. Type: string Default: None

Required No

Filter.n.Name

No

Filter.n.Value.n

No

Response Elements
Name
requestId

Description The ID of the request. Type: xsd:string Returns information about the network interfaces. Type: InstanceNetworkInterfaceSetRequestType (p. 423)

networkInterfaceSet

Examples
Example Request
This example describes network interfaces.
https://ec2.amazonaws.com/?Action=DescribeNetworkInterfaces &AUTHPARAMS

Example Response
<DescribeNetworkInterfacesResponse xmlns='http://ec2.amazonaws.com/doc/2011-1115/'> <requestId>8ac55c54-792d-415b-a14c-3dffbc0aed2e</requestId> <networkInterfaceSet> <item> <networkInterfaceId>eni-ffda3197</networkInterfaceId> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <availabilityZone>us-east-1b</availabilityZone> <description/> <ownerId>111122223333</ownerId>

API Version 2012-05-01 208

Amazon Elastic Compute Cloud API Reference Examples

<requesterManaged>false</requesterManaged> <status>available</status> <macAddress>06:01:92:a4:43:77</macAddress> <privateIpAddress>10.0.0.182</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <tagSet/> </item> <item> <networkInterfaceId>eni-21a04b49</networkInterfaceId> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <availabilityZone>us-east-1b</availabilityZone> <description/> <ownerId>111122223333</ownerId> <requesterManaged>false</requesterManaged> <status>in-use</status> <macAddress>06:01:92:94:7d:52</macAddress> <privateIpAddress>10.0.0.4</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <attachment> <attachmentId>eni-attach-0720626e</attachmentId> <instanceId>i-9cc316fe</instanceId> <instanceOwnerId>111122223333</instanceOwnerId> <deviceIndex>0</deviceIndex> <status>attached</status> <attachTime>2011-12-20T07:48:20.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </attachment> <tagSet/> </item> <item> <networkInterfaceId>eni-c6bb50ae</networkInterfaceId> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <availabilityZone>us-east-1b</availabilityZone> <description/> <ownerId>111122223333</ownerId> <requesterManaged>false</requesterManaged> <status>in-use</status> <macAddress>06:01:92:a7:f4:5c</macAddress> <privateIpAddress>10.0.0.142</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName>

API Version 2012-05-01 209

Amazon Elastic Compute Cloud API Reference Related Operations

</item> </groupSet> <attachment> <attachmentId>eni-attach-0326646a</attachmentId> <instanceId>i-0ee0356c</instanceId> <instanceOwnerId>111122223333</instanceOwnerId> <deviceIndex>0</deviceIndex> <status>attached</status> <attachTime>2011-12-20T08:29:31.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </attachment> <tagSet/> </item> </networkInterfaceSet> </DescribeNetworkInterfacesResponse>

Related Operations
AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaceAttribute (p. 203) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 210

Amazon Elastic Compute Cloud API Reference DescribePlacementGroups

DescribePlacementGroups
Description
Returns information about one or more placement groups in your account. For more information about placement groups and cluster instances, go to Using Cluster Instances in the Amazon Elastic Compute Cloud User Guide. You can filter the results to return information only about placement groups that match criteria you specify. For example, you could filter the results to return only the groups whose state is deleted.You can specify multiple values for a filter. A placement group must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the group's state is deleted and the name includes the string Project). The result includes information for a particular group only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
group-name

Description Name of the placement group. Type: String Placement group's state. Type: String Valid Values: pending | available | deleting | deleted Placement group's strategy. Type: String Valid Value: cluster

state

strategy

Request Parameters
Name
GroupName.n

Description

Required

One or more placement group names. No Type: string Default: Describes all your placement groups, or only those otherwise specified. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None No

Filter.n.Name

API Version 2012-05-01 211

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Value.m

Description A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Response Elements
The elements in the following table are wrapped in a DescribePlacementGroupsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of placement groups. Each group's information is wrapped in an item element. Type: PlacementGroupInfoType (p. 439)

placementGroupSet

Examples
Example Request
This example describes the placement group named XYZ-cluster.
https://ec2.amazonaws.com/?Action=DescribePlacementGroups &GroupName.1=XYZ-cluster &AUTHPARAMS

Example Response
<DescribePlacementGroupsResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestID>d4904fd9-82c2-4ea5-adfe-a9cc3EXAMPLE</requestID> <placementGroupSet> <item> <groupName>XYZ-cluster</groupName> <strategy>cluster</strategy> <state>available</state> </item> </placementGroupSet> </DescribePlacementGroupsResponse>

Example Request
This example filters the results to display only placement groups that include the string Project in the name.

API Version 2012-05-01 212

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribePlacementGroups &Filter.1.Name=group-name &Filter.1.Value=*Project* &AUTHPARAMS

Related Operations
CreatePlacementGroup (p. 72) DeletePlacementGroup (p. 114)

API Version 2012-05-01 213

Amazon Elastic Compute Cloud API Reference DescribeRegions

DescribeRegions
Description
Describes Regions that are currently available to the account. You can use filters with this call just as you can with other "describe" calls. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
endpoint

Description Region's endpoint (e.g., ec2.us-east-1.amazonaws.com). Type: String Name of the Region. Type: String

region-name

Request Parameters
Name
RegionName.n

Description One or more Region names. Type: String Default: Describes all Regions available to the account. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Name

No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeRegionsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string

API Version 2012-05-01 214

Amazon Elastic Compute Cloud API Reference Examples

Name
regionInfo

Description List of Regions. Each Region's information is wrapped in an item element. Type: RegionItemType (p. 444)

Examples
Example Request
This example displays information about all Regions.
https://ec2.amazonaws.com/?Action=DescribeRegions &AUTHPARAMS

Example Request
This example displays information about just the specified Regions.
https://ec2.amazonaws.com/?Action=DescribeRegions &RegionName.1=us-east-1 &RegionName.2=eu-west-1 &AUTHPARAMS

Example Response
<DescribeRegionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <regionInfo> <item> <regionName>us-east-1</regionName> <regionEndpoint>ec2.us-east-1.amazonaws.com</regionEndpoint> </item> <item> <regionName>eu-west-1</regionName> <regionEndpoint>ec2.eu-west-1.amazonaws.com</regionEndpoint> </item> </regionInfo> </DescribeRegionsResponse>

Example Request
This example displays information about all Regions that have the string ap in the endpoint.
https://ec2.amazonaws.com/?Action=DescribeRegions &Filter.1.Name=endpoint &Filter.1.Value.1=*ap* &AUTHPARAMS

API Version 2012-05-01 215

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DescribeRegionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <regionInfo> <item> <regionName>ap-southeast-1</regionName> <regionEndpoint>ec2.ap-southeast-1.amazonaws.com</regionEndpoint> </item> </regionInfo> </DescribeRegionsResponse>

Related Operations
DescribeAvailabilityZones (p. 144) RunInstances (p. 366)

API Version 2012-05-01 216

Amazon Elastic Compute Cloud API Reference DescribeReservedInstances

DescribeReservedInstances
Description
Describes Reserved Instances that you purchased. Starting with the 2011-11-01 API version, AWS expanded its offering of Amazon EC2 Reserved Instances to address a range of projected instance use. There are three types of Reserved Instances based on customer utilization levels: Heavy Utilization, Medium Utilization, and Light Utilization. You determine the type of the Reserved Instances offerings by including the optional offeringType parameter.The Medium Utilization offering type is equivalent to the Reserved Instance offering available before API version 2011-11-01. If you are using tools that predate the 2011-11-01 API version, you only have access to the Medium Utilization Reserved Instance offering type. For more information about Reserved Instances, go to Reserved Instances in the Amazon Elastic Compute Cloud User Guide. You can filter the results to return information about Reserved Instances that matches criteria you specify. For example, you could get information about Reserved Instances in a particular Availability Zone. Or you can specify multiple values for a filter. A Reserved Instance must match at least one of the specified values for it to be included in the results. You can specify multiple filters as well. For example, you could specify that your Reserved Instance must be in a particular Availability Zone and must be tagged with a particular value. The result includes information for a particular instance only if it matches all of your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
availability-zone

Description Availability Zone where the Reserved Instance can be used. Type: String Duration of the Reserved Instance (one year or three years), in seconds. Type: xs:long Valid Values: 31536000 | 94608000 Purchase price of the Reserved Instance (e.g., 9800.0) Type: xs:double Instance type on which the Reserved Instance can be used. Type: String Reserved Instance description. Type: String Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC)

duration

fixed-price

instance-type

product-description

API Version 2012-05-01 217

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
reserved-instances-id

Description Reserved Instance's ID. Type: String Time the Reserved Instance purchase request was placed, e.g., 2010-08-07T11:54:42.000Z. Type: xsd:dateTime State of the Reserved Instance. Type: String Valid Values: pending-payment | active | payment-failed | retired Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y Usage price of the Reserved Instance, per hour (e.g., 0.84) Type: xs:double

start

state

tag-key

tag-value

tag:key

usage-price

Request Parameters
Name
ReservedInstancesId. n

Description One or more Reserved Instance IDs. Type: String Default: Describes all your Reserved Instances, or only those otherwise specified.

Required No

API Version 2012-05-01 218

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Name

Description Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None The Reserved Instance offering type. Type: String Valid Values: Heavy Utilization | Medium Utilization | Light Utilization

Required No

Filter.n.Value.m

No

offeringType

No

Response Elements
The elements in the following table are wrapped in a DescribeReservedInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of Reserved Instances. Each Reserved Instance's information is wrapped in an item element. Type: DescribeReservedInstancesResponseSetItemType (p. 400)

reservedInstancesSet

Examples
Example Request
This example describes Reserved Instances owned by your account.
https://ec2.amazonaws.com/?Action=DescribeReservedInstances &AUTHPARAMS

Example Response
<DescribeReservedInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <reservedInstancesSet> <item> <reservedInstancesId>4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8EXAMPLE</re servedInstancesId> <instanceType>m1.xlarge</instanceType>

API Version 2012-05-01 219

Amazon Elastic Compute Cloud API Reference Related Operations

<availabilityZone>us-east-1a</availabilityZone> <duration>31536000</duration> <fixedPrice>1820.0</fixedPrice> <usagePrice>0.24</usagePrice> <instanceCount>3</instanceCount> <productDescription>Linux/UNIX</productDescription> <state>active</state> <tagSet/> </item> </reservedInstancesSet> </DescribeReservedInstancesResponse>

Example Request
This example filters the results to display only one-year, m1.small Linux/UNIX Reserved Instances. If you want Linux/UNIX Reserved Instances specifically for use with Amazon VPC, set the product descripton to Linux/UNIX (Amazon VPC).
https://ec2.amazonaws.com/?Action=DescribeReservedInstances &Filter.1.Name=duration &Filter.1.Value.1=31536000 &Filter.2.Name=instance-type &Filter.2.Value.1=m1.small &Filter.3.Name=product-description &Filter.3.Value.1=Linux/UNIX &AUTHPARAMS

Related Operations
PurchaseReservedInstancesOffering (p. 324) DescribeReservedInstancesOfferings (p. 221)

API Version 2012-05-01 220

Amazon Elastic Compute Cloud API Reference DescribeReservedInstancesOfferings

DescribeReservedInstancesOfferings
Description
Describes Reserved Instance offerings that are available for purchase. With Amazon EC2 Reserved Instances, you purchase the right to launch Amazon EC2 instances for a period of time (without getting insufficient capacity errors) and pay a lower usage rate for the actual time used. Starting with the 2011-11-01 API version, AWS expanded its offering of Amazon EC2 Reserved Instances to address a range of projected instance use. There are three types of Reserved Instances based on customer utilization levels: Heavy Utilization, Medium Utilization, and Light Utilization. You determine the type of the Reserved Instances offerings by including the optional offeringType parameter when calling DescribeReservedInstancesOfferings. The Medium Utilization offering type is equivalent to the Reserved Instance offering available before API version 2011-11-01. If you are using tools that predate the 2011-11-01 API version, DescribeReservedInstancesOfferings will only list information about the Medium Utilization Reserved Instance offering type. For more information about Reserved Instances, go to Reserved Instances in the Amazon Elastic Compute Cloud User Guide. Our policy is to provide filters for all describe calls so you can limit the results to your specified criteria. Therefore, you can use filters to limit the results when describing Reserved Instances offerings, even though you can use the regular request parameters to do something similar. For example, you could use the regular request parameters or a filter to get the offerings for a particular instance type. You can specify multiple request parameters or multiple filters (e.g., limit the results to the m2.xlarge instance type, and only for Windows instances). The result includes information for a particular offering only if it matches all your request parameters or filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
availability-zone

Description Availability Zone where the Reserved Instance can be used. Type: String Duration of the Reserved Instance (e.g., one year or three years), in seconds. Type: xs:long Valid Values: 31536000 | 94608000 Purchase price of the Reserved Instance (e.g., 9800.0) Type: xs:double Instance type on which the Reserved Instance can be used. Type: String

duration

fixed-price

instance-type

API Version 2012-05-01 221

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
product-description

Description Reserved Instance description. Type: String Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC) Reserved Instances offering ID. Type: String Usage price of the Reserved Instance, per hour (e.g., 0.84) Type: xs:double

reserved-instances-offering-id

usage-price

Request Parameters
Name
ReservedInstancesOff eringId.n

Description One or more Reserved Instances offering IDs. Type: String Default: None

Required No

InstanceType

The instance type on which the Reserved Instance can be No used. Type: String Default: None The Availability Zone in which the Reserved Instance can No be used. Type: String Default: None The Reserved Instance description. Instances that include No (Amazon VPC) in the description are for use with Amazon VPC. Type: String Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC) Default: None Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

AvailabilityZone

ProductDescription

Filter.n.Name

Filter.n.Value.m

No

API Version 2012-05-01 222

Amazon Elastic Compute Cloud API Reference Response Elements

Name
instanceTenancy

Description

Required

The tenancy of the Reserved Instance offering. A Reserved No Instance with tenancy of dedicated will run on single-tenant hardware and can only be launched within a VPC. Type: String Valid Values: default | dedicated Default: default The Reserved Instance offering type. Type: String Valid Values: Heavy Utilization | Medium Utilization | Light Utilization Default: none No

offeringType

Response Elements
The elements in the following table are wrapped in a DescribeReservedInstancesOfferingsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of Reserved Instances offerings. Each offering's information is wrapped in an item element. Type: DescribeReservedInstancesOfferingsResponseSetItemType (p. 399)

reservedInstancesOff eringsSet

Examples
Example Request
This example describes available Reserved Instance offerings.
https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings &AUTHPARAMS

Example Response
<DescribeReservedInstancesOfferingsResponse xmlns="http://ec2.amazon aws.com/doc/2012-05-01/"> <requestId>48692a1d-3036-48fd-8c0e-d34681b97efdEXAMPLE</requestId> <reservedInstancesOfferingsSet> <item> <reservedInstancesOfferingId>248e7b75-c83a-48c1-bcf7b7f03e9c43feEXAMPLE</reservedInstancesOfferingId> <instanceType>c1.medium</instanceType>

API Version 2012-05-01 223

Amazon Elastic Compute Cloud API Reference Related Operations

<availabilityZone>us-east-1b</availabilityZone> <duration>94608000</duration> <fixedPrice>700.0</fixedPrice> <usagePrice>0.06</usagePrice> <productDescription>Linux/UNIX (Amazon VPC)</productDescription> <instanceTenancy>default</instanceTenancy> <currencyCode>USD</currencyCode> <offeringType>Medium Utilization</offeringType> <recurringCharges/> </item> ... </reservedInstancesOfferingsSet> </DescribeReservedInstancesOfferingsResponse>

Example Request
This example filters the results to display only one-year, m1.small or m1.large Linux/UNIX Reserved Instances. If you want Linux/UNIX Reserved Instances specifically for use with Amazon VPC, set the product descripton to Linux/UNIX (Amazon VPC).
https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings &Filter.1.Name=duration &Filter.1.Value.1=31536000 &Filter.2.Name=instance-type &Filter.2.Value.1=m1.small &Filter.2.Value.2=m1.large &Filter.3.Name=product-description &Filter.3.Value.1=Linux/UNIX &AUTHPARAMS

Related Operations
PurchaseReservedInstancesOffering (p. 324) DescribeReservedInstances (p. 217)

API Version 2012-05-01 224

Amazon Elastic Compute Cloud API Reference DescribeRouteTables

DescribeRouteTables
Description
Gives you information about your route tables. You can filter the results to return information only about tables that match criteria you specify. For example, you could get information only about a table associated with a particular subnet. You can specify multiple values for the filter. The table must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the table has a particular route, and is associated with a particular subnet). The result includes information for a particular table only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name Description

association.route-table-association-id ID of an association ID for the route table. Type: String association.route-table-id

ID of the route table involved in the association. Type: String ID of the subnet involved in the association. Type: String Whether the route table is the main route table in the VPC. Type: Boolean ID of the route table. Type: String CIDR range specified in a route in the table. Type: String ID of a gateway specified in a route in the table. Type: String ID of an instance specified in a route in the table. Type: String State of a route in the route table. The blackhole state indicates that the route's target isn't available (e.g., the specified gateway isn't attached to the VPC, the specified NAT instance has been terminated, etc.). Type: String Valid Values: active | blackhole

association.subnet-id

association.main

route-table-id

route.destination-cidr-block

route.gateway-id

route.instance-id

route.state

API Version 2012-05-01 225

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag-key

Description Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y The ID of the VPC the route table is in. Type: String

tag-value

tag:key

vpc-id

For more information about Amazon Virtual Private Cloud and route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
RouteTableId.n

Description

Required

One or more route table IDs. No Type: string Default: Returns all route tables, or only those otherwise specified. Name of a filter. See the preceding table for a No list of allowed filter names. Type: String Default: None

Filter.n.Name

API Version 2012-05-01 226

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Value.m

Description A value for the filter. See the preceding table for a list of allowed filter values for each filter. Type: String Default: None

Required No

Response Elements
The elements in the following table are wrapped in a DescribeRouteTablesResponse structure. Name
requestId

Description The ID of the request. Type: String A list of route tables. Each table's information is wrapped in an item element. Type: RouteTableType (p. 447)

routeTableSet

Examples
Example Request
This example describes all route tables in the VPC.
https://ec2.amazonaws.com/?Action=DescribeRouteTables

Example Response
The first route table in the returned list is the VPC's main route table. Its association ID represents the association between the table and the VPC
DescribeRouteTablesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>6f570b0b-9c18-4b07-bdec-73740dcf861a</requestId> <routeTableSet> <item> <routeTableId>rtb-13ad487a</routeTableId> <vpcId>vpc-11ad4878</vpcId> <routeSet> <item> <destinationCidrBlock>10.0.0.0/22</destinationCidrBlock> <gatewayId>local</gatewayId> <state>active</state> </item> </routeSet> <associationSet> <item> <routeTableAssociationId>rtbassoc-12ad487b</routeTableAssoci ationId>

API Version 2012-05-01 227

Amazon Elastic Compute Cloud API Reference Related Operations

<routeTableId>rtb-13ad487a</routeTableId> <main>true</main> </item> </associationSet> <tagSet/> </item> <item> <routeTableId>rtb-f9ad4890</routeTableId> <vpcId>vpc-11ad4878</vpcId> <routeSet> <item> <destinationCidrBlock>10.0.0.0/22</destinationCidrBlock> <gatewayId>local</gatewayId> <state>active</state> </item> <item> <destinationCidrBlock>0.0.0.0/0</destinationCidrBlock> <gatewayId>igw-eaad4883</gatewayId> <state>active</state> </item> </routeSet> <associationSet> <item> <routeTableAssociationId>rtbassoc-faad4893</routeTableAssoci ationId> <routeTableId>rtb-f9ad4890</routeTableId> <subnetId>subnet-15ad487c</subnetId> </item> </associationSet> <tagSet/> </item> </routeTableSet> </DescribeRouteTablesResponse>

Related Operations
AssociateRouteTable (p. 20) DisassociateRouteTable (p. 293) DeleteRouteTable (p. 118) CreateRouteTable (p. 77)

ReplaceRouteTableAssociation (p. 341)

API Version 2012-05-01 228

Amazon Elastic Compute Cloud API Reference DescribeSecurityGroups

DescribeSecurityGroups
Description
Returns information about security groups in your account. This includes both EC2 security groups and VPC security groups. For information about how the two types of groups differ, go to Security Groups in the Amazon Virtual Private Cloud User Guide. You can filter the results to return information only about security groups that match criteria you specify. For example, you could get information about groups whose name contains a particular string. You can specify multiple values for a filter. A security group must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the group's name contains a particular string, and the group gives permission to another security group with a different string in its name). The result includes information for a particular group only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty.

Important
Filters are based on literal strings only. This is important to remember when you want to use filters to return only security groups with access allowed on a specific port number or numbers. For example, let's say you want to get all groups that have access on port 22. And let's say GroupA gives access on a range of ports using fromPort=20 and toPort=30. If you filter with ip-permission.from-port=22 or ip-permission.to-port=22 (or both), GroupA will not be returned in the results. It will only be returned in the results if you specify ip-permission.from-port=20 or ip-permission.to-port=30 (or both).

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
description

Description Description of the security group. Type: String ID of the security group. Type: String Name of the security group. Type: String CIDR range that has been granted the permission. Type: String Start of port range for the TCP and UDP protocols, or an ICMP type number. Type: String

group-id

group-name

ip-permission.cidr

ip-permission.from-port

API Version 2012-05-01 229

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
ip-permission.group-name

Description Name of security group that has been granted the permission. Type: String IP protocol for the permission. Type: String Valid Values: tcp | udp | icmp or a protocol number End of port range for the TCP and UDP protocols, or an ICMP code. Type: String ID of AWS account that has been granted the permission. Type: String AWS account ID of the owner of the security group. Type: String Key of a tag assigned to the security group. Type: String Value of a tag assigned to the security group. Type: String

ip-permission.protocol

ip-permission.to-port

ip-permission.user-id

owner-id

tag-key

tag-value

Request Parameters
Name
GroupName.n

Description One or more security group names. Type: String Default: Describes all groups you own, or only those otherwise specified. One or more security group IDs. Type: String Default: Describes all groups you own, or only those otherwise specified. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

GroupId.n

No

Filter.n.Name

No

Filter.n.Value.m

No

API Version 2012-05-01 230

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a DescribeSecurityGroupsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of security groups. Each group's information is wrapped in an item element. Type: SecurityGroupItemType (p. 452)

securityGroupInfo

Examples
Example Request
This example returns information about two security groups that are configured for the account.
https://ec2.amazonaws.com/?Action=DescribeSecurityGroups &GroupName.1=WebServers &GroupName.2=RangedPortsBySource &AUTHPARAMS

Example Response
<DescribeSecurityGroupsResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <securityGroupInfo> <item> <ownerId>111122223333</ownerId> <groupId>sg-443d0a12</groupId> <groupName>WebServers</groupName> <groupDescription>Web Servers</groupDescription> <vpcId/> <ipPermissions> <item> <ipProtocol>tcp</ipProtocol> <fromPort>80</fromPort> <toPort>80</toPort> <groups/> <ipRanges> <item> <cidrIp>0.0.0.0/0</cidrIp> </item> </ipRanges> </item> </ipPermissions> <ipPermissionsEgress/> <tagSet/> </item>

API Version 2012-05-01 231

Amazon Elastic Compute Cloud API Reference Related Operations

<item> <ownerId>111122223333</ownerId> <groupId>sg-5ff8a023</groupId> <groupName>RangedPortsBySource</groupName> <groupDescription>Group A</groupDescription> <ipPermissions> <item> <ipProtocol>tcp</ipProtocol> <fromPort>6000</fromPort> <toPort>7000</toPort> <groups> <item> <userId>111122223333</userId> <groupId>sg-99gh4012</groupId> <groupName>Group B</groupName> </item> </groups> <ipRanges/> </item> </ipPermissions> <ipPermissionsEgress/> <tagSet/> </item> </securityGroupInfo> </DescribeSecurityGroupsResponse>

Example Request
This example returns information about all security groups that grant access over TCP specifically on port 22 from instances in either the app_server_group or database_group.
https://ec2.amazonaws.com/?Action=DescribeSecurityGroups &Filter.1.Name=ip-permission.protocol &Filter.1.Value.1=tcp &Filter.2.Name=ip-permission.from-port &Filter.2.Value.1=22 &Filter.3.Name=ip-permission.to-port &Filter.3.Value.1=22 &Filter.4.Name=ip-permission.group-name &Filter.4.Value.1=app_server_group &Filter.4.Value.2=database_group &AUTHPARAMS

Related Operations
CreateSecurityGroup (p. 79) AuthorizeSecurityGroupIngress (p. 34) RevokeSecurityGroupIngress (p. 363) DeleteSecurityGroup (p. 120)

API Version 2012-05-01 232

Amazon Elastic Compute Cloud API Reference DescribeSnapshotAttribute

DescribeSnapshotAttribute
Description
Returns information about an attribute of a snapshot. You can get information about only one attribute per call.

Request Parameters
Name
SnapshotId

Description The ID of the Amazon EBS snapshot. Type: String Default: None The attribute to get. Type: String Default: None Valid Value: createVolumePermission | productCodes

Required Yes

Attribute

Yes

Response Elements
The elements in the following table are wrapped in a DescribeSnapshotAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The ID of the Amazon EBS snapshot. Type: xsd:string List of permissions for creating volumes from the snapshot. Each permission is wrapped in an item element. Type: CreateVolumePermissionItemType (p. 394) A list of product codes. Each product code's information is wrapped in an item element type that contains a product code and a type. Type: ProductCodesSetItemType (p. 442)

snapshotId

createVolumePermission

productCodes

Examples
Example Request
This example describes permissions for the snap-78a54011 snapshot.

API Version 2012-05-01 233

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribeSnapshotAttribute &SnapshotId=snap-78a54011 &Attribute=createVolumePermission &AUTHPARAMS

Example Response
<DescribeSnapshotAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <snapshotId>snap-78a54011</snapshotId> <createVolumePermission> <item> <group>all</group> </item> </createVolumePermission> </DescribeSnapshotAttributeResponse>

Example Request
This example describes product codes associated with the snap-78a12345 snapshot.
https://ec2.amazonaws.com/?Action=DescribeSnapshotAttribute &SnapshotId=snap-78a12345 &Attribute=productCodes &AUTHPARAMS

Example Response
<DescribeSnapshotAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0401/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <snapshotId>snap-78a12345</snapshotId> <productCodes> <item> <productCode>a1b2c3d4e5f6g7h8i9j10k11</productCode> <type>marketplace</type> </item> </productCodes> </DescribeSnapshotAttributeResponse>

Related Operations
ModifySnapshotAttribute (p. 318) DescribeSnapshots (p. 235) ResetSnapshotAttribute (p. 358) CreateSnapshot (p. 81)

API Version 2012-05-01 234

Amazon Elastic Compute Cloud API Reference DescribeSnapshots

DescribeSnapshots
Description
Returns information about Amazon EBS snapshots available to you. Snapshots available to you include public snapshots available for any AWS account to launch, private snapshots you own, and private snapshots owned by another AWS account but for which you've been given explicit create volume permissions. The create volume permissions fall into 3 categories: Permission public Description The owner of the snapshot granted create volume permissions for the snapshot to the all group. All AWS accounts have create volume permissions for these snapshots. The owner of the snapshot granted create volume permissions to a specific AWS account. An AWS account has implicit create volume permissions for all snapshots it owns.

explicit implicit

The list of snapshots returned can be modified by specifying snapshot IDs, snapshot owners, or AWS accounts with create volume permissions. If no options are specified, Amazon EC2 returns all snapshots for which you have create volume permissions. If you specify one or more snapshot IDs, only snapshots that have the specified IDs are returned. If you specify an invalid snapshot ID, an error is returned. If you specify a snapshot ID for which you do not have access, it will not be included in the returned results. If you specify one or more snapshot owners, only snapshots from the specified owners and for which you have access are returned. The results can include the AWS account IDs of the specified owners, amazon for snapshots owned by Amazon, or self for snapshots that you own. If you specify a list of restorable users, only snapshots with create snapshot permissions for those users are returned. You can specify AWS account IDs (if you own the snapshot(s)), self for snapshots for which you own or have explicit permissions, or all for public snapshots. You can filter the results to return information only about snapshots that match criteria you specify. For example, you could get information about snapshots whose status is pending. You can specify multiple values for a filter (e.g., the snapshot's status is either pending or completed). A snapshot must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the snapshot's status is pending, and it is tagged with a particular value). The result includes information for a particular snapshot only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters.

API Version 2012-05-01 235

Amazon Elastic Compute Cloud API Reference Description

Filter Name
description

Description Description of the snapshot. Type: String The AWS account alias (e.g., amazon) that owns the snapshot. Type: String ID of the AWS account that owns the snapshot. Type: String The progress of the snapshot, in percentage (e.g., 80%). Type: String Snapshot ID. Type: String Time stamp when the snapshot was initiated. Type: xsd:dateTime Status of the snapshot. Type: String Valid Values: pending | completed | error Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y ID of the volume the snapshot is for. Type: String The size of the volume, in GiB (e.g., 20). Type: String

owner-alias

owner-id

progress

snapshot-id

start-time

status

tag-key

tag-value

tag:key

volume-id

volume-size

API Version 2012-05-01 236

Amazon Elastic Compute Cloud API Reference Request Parameters

Request Parameters
Name
SnapshotId.n

Description One or more snapshot IDs. Type: String Default: Describes snapshots for which you have launch permissions.

Required No

Owner.n

Returns snapshots owned by the specified owner. Multiple No owners can be specified. Type: String Valid Values: self | amazon | AWS Account ID Default: None One or more AWS accounts IDs that can create volumes No from the snapshot. Type: String Default: None Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

RestorableBy.n

Filter.n.Name

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeSnapshotsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of snapshots. Each snapshot's information is wrapped in an item element. Type: DescribeSnapshotsSetItemResponseType (p. 402)

snapshotSet

Examples
Example Request
This example describes snapshot snap-78a54011.

API Version 2012-05-01 237

Amazon Elastic Compute Cloud API Reference Examples

https://ec2.amazonaws.com/?Action=DescribeSnapshots &SnapshotId=snap-78a54011 &AUTHPARAMS

Example Response
<DescribeSnapshotsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <snapshotSet> <item> <snapshotId>snap-78a54011</snapshotId> <volumeId>vol-4d826724</volumeId> <status>pending</status> <startTime>2008-05-07T12:51:50.000Z</startTime> <progress>80&#x0025;</progress> <ownerId>111122223333</ownerId> <volumeSize>10</volumeSize> <description>Daily Backup</description> <tagSet/> </item> </snapshotSet> </DescribeSnapshotsResponse>

Example Request
This example filters the results to display only snapshots with the pending status, and that are also tagged with a value that includes the string db_.
https://ec2.amazonaws.com/?Action=DescribeSnapshots &Filter.1.Name=status &Filter.1.Value.1=pending &Filter.2.Name=tag-value &Filter.2.Value.1=*db_* &AUTHPARAMS

Example Response
<DescribeSnapshotsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <snapshotSet> <item> <snapshotId>snap-1a2b3c4d</snapshotId> <volumeId>vol-8875daef</volumeId> <status>pending</status> <startTime>2010-07-29T04:12:01.000Z</startTime> <progress>30%</progress> <ownerId>111122223333</ownerId> <volumeSize>15</volumeSize> <description>Daily Backup</description> <tagSet> <item> <key>Purpose</key> <value>demo_db_14_backup</value>

API Version 2012-05-01 238

Amazon Elastic Compute Cloud API Reference Related Operations

</item> </tagSet> </item> </snapshotSet> </DescribeSnapshotsResponse>

Related Operations
CreateSnapshot (p. 81) DeleteSnapshot (p. 122)

API Version 2012-05-01 239

Amazon Elastic Compute Cloud API Reference DescribeSpotDatafeedSubscription

DescribeSpotDatafeedSubscription
Description
Describes the datafeed for Spot Instances. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
The DescribeSpotDatafeedSubscription operation does not have any request parameters.

Response Elements
The elements in the following table are wrapped in a DescribeSpotDatafeedSubscriptionResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string

spotDatafeedSubscription The Spot Instance datafeed subscription. Type: SpotDatafeedSubscriptionType (p. 453)

Examples
Example Request
This example describes the datafeed for the account.
https://ec2.amazonaws.com/?Action=DescribeSpotDatafeedSubscription &AUTHPARAMS

Example Response
<DescribeSpotDatafeedSubscriptionResponse xmlns="http://ec2.amazon aws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <spotDatafeedSubscription> <ownerId>111122223333</ownerId> <bucket>myawsbucket</bucket> <prefix>spotdata</prefix> <state>Active</state> </spotDatafeedSubscription> </DescribeSpotDatafeedSubscriptionResponse>

Related Operations
CreateSpotDatafeedSubscription (p. 84)
API Version 2012-05-01 240

Amazon Elastic Compute Cloud API Reference Related Operations

DeleteSpotDatafeedSubscription (p. 124)

API Version 2012-05-01 241

Amazon Elastic Compute Cloud API Reference DescribeSpotInstanceRequests

DescribeSpotInstanceRequests
Description
Describes the Spot Instance requests that belong to your account. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current Spot Instance requests. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide. You can filter the results to return information only about Spot Instance requests that match criteria you specify. For example, you could get information about requests where the Spot Price you specified is a certain value (however, you can't use greater than or less than comparison, but you can use * and ? wildcards). You can specify multiple values for a filter. A Spot Instance request must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the Spot Price is equal to a particular value, and the instance type is m1.small). The result includes information for a particular request only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
availability-zone-group

Description Availability Zone group. If you specify the same Availability Zone group for all Spot Instance requests, all Spot Instances are launched in the same Availability Zone. Type: String Time stamp when the Spot Instance request was created. Type: String Fault code related to the request. Type: String Fault message related to the request. Type: String ID of the instance that fulfilled the request. Type: String Spot Instance launch group. Launch groups are Spot Instances that launch together and terminate together. Type: String Whether an Amazon EBS volume mapped to the instance is deleted on instance termination. Type: Boolean

create-time

fault-code

fault-message

instance-id

launch-group

launch.block-device-mapping.deleteon-termination

API Version 2012-05-01 242

Amazon Elastic Compute Cloud API Reference Description

Filter Name

Description

launch.block-device-mapping.device-name Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the instance. Type: String launch.block-device-mapping.snapshot-id ID for a snapshot mapped to the instance. Type: String launch.block-device-mapping.volume-size Size of an Amazon EBS volume mapped to the instance (in GiB). Type: String launch.group-id

A security group the instance is in. Type: String The AMI ID. Type: String Type of instance (e.g., m1.small). Type: String Kernel ID. Type: String Name of the key pair the instance launched with. Type: String Whether monitoring is enabled for the Spot Instance. Type: Boolean RAM disk ID. Type: String

launch.image-id

launch.instance-type

launch.kernel-id

launch.key-name

launch.monitoring-enabled

launch.ramdisk-id

network-interface.network-interface-id The ID of the network interface. Type: String network-interface.device-index

The index of the device for the network interface attachment on the instance. Type: Integer The ID of the subnet that the instance is in. Type: String Description of the network interface. Type: String IP address of the network interface. Type: String

network-interface.subnet-id

network-interface.description

network-interface.private-ip-address

network-interface.delete-on-termination Whether the network interface is deleted when the instance is terminated. Type: Boolean

API Version 2012-05-01 243

Amazon Elastic Compute Cloud API Reference Description

Filter Name
network-interface.group-id

Description The ID of the security group associated with the network interface. Type: String Product description associated with the instance. Type: String Valid Values: Linux/UNIX | Windows Spot Instance request ID. Type: String Maximum hourly price for any Spot Instance launched to fulfill the request. Type: String State of the Spot Instance request. Type: String Valid Values: active | cancelled | open | closed | failed Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y

product-description

spot-instance-request-id

spot-price

state

tag-key

tag-value

tag:key

API Version 2012-05-01 244

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
type

Description Type of Spot Instance request. Type: String Valid Values: one-time | persistent The Availability Zone in which the bid is launched. Type: String Valid Values: us-east-1a, etc. Start date of the request. Type: xsd:dateTime End date of the request. Type: xsd:dateTime

launched-availability-zone

valid-from

valid-until

Request Parameters
Name
SpotInstanceRequestI d.n

Description One or more Spot Instance request IDs. Type: String Default: None Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Name

No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeSpotInstanceRequestsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of Spot Instance requests. Each request's information is wrapped in an item element. Type: SpotInstanceRequestSetItemType (p. 454) The ID of the network interface. Type: InstanceNetworkInterfaceSetType (p. 423)

spotInstanceRequestSet

networkInterfaceId

API Version 2012-05-01 245

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example returns information about current Spot Instance requests.
https://ec2.amazonaws.com/?Action=DescribeSpotInstanceRequests &AUTHPARAMS

Example Response
<DescribeSpotInstanceRequestsResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/" <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <spotInstanceRequestSet> <item> <spotInstanceRequestId>sir-e1471206</spotInstanceRequestId> <spotPrice>0.09</spotPrice> <type>one-time</type> <state>active</state> <launchSpecification> <imageId>ami-813968c4</imageId> <keyName>MyKey</keyName> <groupSet> <item> <groupId>default</groupId> </item> </groupSet> <instanceType>m1.small</instanceType> <blockDeviceMapping/> <monitoring> <enabled>false</enabled> </monitoring> </launchSpecification> <instanceId>i-992cf7dd&lt;/instanceId> <createTime>2010-09-13T23:50:44.000Z</createTime> <productDescription>Linux/UNIX</productDescription> <launchedAvailabilityZone>us-east-1c</launchedAvailabilityZone> </item> <spotInstanceRequestSet/> <DescribeSpotInstanceRequestsResponse>

Example Request
This example describes all persistent Spot Instance requests that have resulted in the launch of at least one m1.small instance, that has been fulfilled in the us-east-1a Availability Zone, and that also has monitoring enabled.
https://ec2.amazonaws.com/?Action=DescribeSpotInstanceRequests &Filter.1.Name=type &Filter.1.Value.1=persistent &Filter.2.Name=instance-type &Filter.2.Value.1=m1.small

API Version 2012-05-01 246

Amazon Elastic Compute Cloud API Reference Related Operations

&Filter.3.Name=monitoring-enabled &Filter.3.Value.1=true &Filter.4.Name=launched-availability-zone &Filter.4.Value.1=us-east-1a &AUTHPARAMS

Related Operations
RequestSpotInstances (p. 346) CancelSpotInstanceRequests (p. 47) DescribeSpotPriceHistory (p. 248)

API Version 2012-05-01 247

Amazon Elastic Compute Cloud API Reference DescribeSpotPriceHistory

DescribeSpotPriceHistory
Description
Describes the Spot Price history. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current Spot Instance requests. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide. When you use the availability-zone option, this command describes the price history for the specified Availability Zone with the most recent set of prices listed first. If you don't specify an Availability Zone, the command returns the prices across all Availability Zones, starting with the most recent set. However, if you use this command with versions of the API earlier than the 2011-05-15 version, this command returns the lowest price across the Region for the given time period. The prices returned will be listed in chronological order from the oldest to the most recent.

Note
Our policy is to provide filters for all "describe" calls so you can limit the results to your specified criteria. Therefore, you can use filters to limit the results when describing Spot Price histories, even though you can use the regular request parameters to do something similar.

For example, you could use the regular request parameters or a filter to get the history for a particular instance type. You can specify multiple request parameters or multiple filters (e.g., limit the results to the m2.xlarge instance type, and only for Windows instances). The result includes information for a particular price history only if it matches all your request parameters or filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
instance-type

Description Type of instance (e.g., m1.small). Type: String

product-description Product description for the Spot Price. Type: String Valid Values: Linux/UNIX | SUSE Linux | Windows | Linux/UNIX (Amazon VPC) | SUSE Linux (Amazon VPC) | Windows (Amazon VPC) spot-price

Spot Price. The value must match exactly (or use wildcards; greater than or less than comparison is not supported). Type: String Timestamp of the Spot Price history, e.g., 2010-08-16T05:06:11.000Z. You can use wildcards (* and ?). Greater than or less than comparison is not supported. Type: xsd:dateTime

timestamp

API Version 2012-05-01 248

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
availability-zone

Description The Availability Zone for which prices should be returned. Type: String

Request Parameters
Name
StartTime

Description

Required

Start date and time of the Spot Instance price history data. No Type: DateTime Default: None End date and time of the Spot Instance price history data. No Type: DateTime Default: None The instance type to return. Type: String Valid Values: m1.small | m1.large | m1.xlarge | c1.medium | c1.xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge | t1.micro Default: None Filters the results by basic product description. Type: String Valid Values: Linux/UNIX | SUSE Linux | Windows | Linux/UNIX (Amazon VPC) | SUSE Linux (Amazon VPC) | Windows (Amazon VPC) Default: Returns all information Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None Filters the results by availability zone. Type: String Valid Values: us-east-1a, etc. Default: None Specifies the number of rows to return. Type: int Valid Values: >0 Default: None No

EndTime

InstanceType.n

ProductDescription.n

No

Filter.n.Name

No

Filter.n.Value.m

No

AvailabilityZone

No

MaxResults

No

API Version 2012-05-01 249

Amazon Elastic Compute Cloud API Reference Response Elements

Name
NextToken

Description Specifies the next set of rows to return. Type: String Valid Values: A NextToken value returned by a previous call of the API. Default: None

Required No

Response Elements
The elements in the following table are wrapped in a DescribeSpotPriceHistoryResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of historical Spot Prices. Each price's information is wrapped in an item element. Type: SpotPriceHistorySetItemType (p. 456) The string marking the next set of results returned. Displays empty if there are no more results to be returned. Type: xsd:string

spotPriceHistorySet

nextToken

Examples
Example Request
This example returns Spot Price history for a particular day in December 2009 for Availability Zone us-east-1a.
https://ec2.amazonaws.com/?Action=DescribeSpotPriceHistory &StartTime=2009-12-04T00:00:00.000Z &EndTime=2009-12-04T23:59:59.000Z &AvailabilityZone=us-east-1a &AUTHPARAMS

This request uses filters instead of regular request parameters to achieve the same results.
https://ec2.amazonaws.com/?Action=DescribeSpotPriceHistory &Filter.1.Name=timestamp &Filter.1.Value.1=2009-12-04* &Filter.2.Name=availability-zone &Filter.2.Value.1=us-east-1a &AUTHPARAMS

API Version 2012-05-01 250

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DescribeSpotPriceHistoryResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <spotPriceHistorySet> <item> <instanceType>m1.small</instanceType> <productDescription>Linux/UNIX</productDescription> <spotPrice>0.287</spotPrice> <timestamp>2009-12-04T20:56:05.000Z</timestamp> <availabilityZone>us-east-1a</availabilityZone> </item> <item> <instanceType>m1.small</instanceType> <productDescription>Windows</productDescription> <spotPrice>0.033</spotPrice> <timestamp>2009-12-04T22:33:47.000Z</timestamp> <availabilityZone>us-east-1a</availabilityZone> </item> </spotPriceHistorySet> <nextToken/> </DescribeSpotPriceHistoryResponse>

Related Operations
DescribeSpotInstanceRequests (p. 242) RequestSpotInstances (p. 346) CancelSpotInstanceRequests (p. 47)

API Version 2012-05-01 251

Amazon Elastic Compute Cloud API Reference DescribeSubnets

DescribeSubnets
Description
Gives you information about your subnets. You can filter the results to return information only about subnets that match criteria you specify. For example, you could get information only about subnets whose state is available. You can specify multiple values for the filter. The subnet must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the subnet is in a particular VPC, and the subnet's state is available). The result includes information for a particular subnet only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
availability-zone

Description The Availability Zone the subnet is in. Type: String

available-ip-address Number of IP addresses in the subnet that are available. -count Type: String cidr

The CIDR block of the subnet. The CIDR block you specify must exactly match the subnet's CIDR block for information to be returned for the subnet. Type: String Constraints: Must contain the slash followed by one or two digits (e.g., /28) The state of the subnet. Type: String Valid Values: pending | available The ID of the subnet. Type: String Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

state

subnet-id

tag-key

tag-value

API Version 2012-05-01 252

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y The ID of the VPC the subnet is in. Type: String

vpc-id

For more information about Amazon Virtual Private Cloud and subnets, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
SubnetId.n

Description

Required

A subnet ID. You can specify more than one in the No request. Type: String Default: Returns information about all your subnets Name of a filter. See the preceding table for a list No of allowed filter names. Type: String Default: Returns information about all your subnets or those you specify by ID. A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

Filter.n.Name

Filter.n.Value.m

Response Elements
The elements in the following table are wrapped in an DescribeSubnetsResponsestructure. Name
requestId

Description The ID of the request. Type: xsd:string A list of subnets. Each subnet's information is wrapped in an item element. Type: SubnetType (p. 458)

subnetSet

API Version 2012-05-01 253

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example gives a description of two subnets with IDs subnet-9d4a7b6c and subnet-6e7f829e.
https://ec2.amazonaws.com/?Action=DescribeSubnets &SubnetId.1=subnet-9d4a7b6c &SubnetId.2=subnet-6e7f829e &AUTHPARAMS

Example Response
<DescribeSubnetsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <subnetSet> <item> <subnetId>subnet-9d4a7b6c</subnetId> <state>available</state> <vpcId>vpc-1a2b3c4d</vpcId> <cidrBlock>10.0.1.0/24</cidrBlock> <availableIpAddressCount>250</availableIpAddressCount> <availabilityZone>us-east-1a</availabilityZone> <tagSet/> </item> <item> <subnetId>subnet-6e7f829e</subnetId> <state>available</state> <vpcId>vpc-1a2b3c4d>/vpcId> <cidrBlock>10.0.0.0/24</cidrBlock> <availableIpAddressCount>250</availableIpAddressCount> <availabilityZone>us-east-1a</availabilityZone> <tagSet/> </item> <subnetSet/> </DescribeSubnetsResponse>

Example Request
This example uses filters to give a description of any subnet you own that is in the VPC with ID vpc-1a2b3c4d or vpc-6e7f8a92, and whose state is available.
https://ec2.amazonaws.com/?Action=DescribeSubnets &Filter.1.Name=vpc-id &Filter.1.Value.1=vpc-1a2b3c4d &Filter.1.Value.2=vpc-6e7f8a92 &Filter.2.Name=state &Filter.2.Value.1=available &AUTHPARAMS

Related Operations
CreateSubnet (p. 86)
API Version 2012-05-01 254

Amazon Elastic Compute Cloud API Reference Related Operations

DeleteSubnet (p. 125)

API Version 2012-05-01 255

Amazon Elastic Compute Cloud API Reference DescribeTags

DescribeTags
Description
Lists your tags. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. You can use filters to limit the results when describing tags. For example, you could get only the tags for a particular resource type. You can specify multiple values for a filter. A tag must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., limit the results to a specific resource type, and get only tags with values that contain the string database). The result includes information for a particular tag only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
key

Description Tag key. Type: String Resource ID. Type: String Resource type. Type: String Valid Values: customer-gateway | dhcp-options | image | instance | internet-gateway | network-acl | reserved-instances | route-table | security-group | snapshot | spot-instances-request | subnet | volume | vpc | vpn-connection | vpn-gateway Tag value. Type: String

resource-id

resource-type

value

Request Parameters
Name
Filter.n.Name

Description Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Value.m

No

API Version 2012-05-01 256

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a DescribeTagsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of tags. Each tag's information is wrapped in an item element. Type: TagSetItemType (p. 459)

tagSet

Examples
Example Request
This example describes all the tags in your account.
https://ec2.amazonaws.com/?Action=DescribeTags &AUTHPARAMS

Sample response:
<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>ami-1a2b3c4d</resourceId> <resourceType>image</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>ami-1a2b3c4d</resourceId> <resourceType>image</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-5f4e3d2a</resourceId> <resourceType>instance</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>i-5f4e3d2a</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-12345678</resourceId> <resourceType>instance</resourceType>

API Version 2012-05-01 257

Amazon Elastic Compute Cloud API Reference Examples

<key>database_server</key> <value/> </item> <item> <resourceId>i-12345678</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Test</value> </item> </tagSet> </DescribeTagsResponse>

Example Request
This example describes only the tags for the AMI with ID ami-1a2b3c4d.
https://ec2.amazonaws.com/?Action=DescribeTags &Filter.1.Name=resource-id &Filter.1.Value.1=ami-1a2b3c4d &AUTHPARAMS

Sample response:
<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>ami-1a2b3c4d</resourceId> <resourceType>image</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>ami-1a2b3c4d</resourceId> <resourceType>image</resourceType> <key>stack</key> <value>Production</value> </item> </tagSet> </DescribeTagsResponse>

Example Request
This example describes the tags for all your instances.
https://ec2.amazonaws.com/?Action=DescribeTags &Filter.1.Name=resource-type &Filter.1.Value.1=instance &AUTHPARAMS

Sample response:

API Version 2012-05-01 258

Amazon Elastic Compute Cloud API Reference Examples

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>i-5f4e3d2a</resourceId> <resourceType>instance</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>i-5f4e3d2a</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-12345678</resourceId> <resourceType>instance</resourceType> <key>database_server</key> <value/> </item> <item> <resourceId>i-12345678</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Test</value> </item> </tagSet> </DescribeTagsResponse>

Example Request
This example describes the tags for all your instances tagged with the key webserver. Note that you can use wildcards with filters. So you could specify the value as ?ebserver to find tags with the key webserver or Webserver.
https://ec2.amazonaws.com/?Action=DescribeTags &Filter.1.Name=key &Filter.1.Value.1=webserver &AUTHPARAMS

Sample response:
<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>i-5f4e3d2a</resourceId> <resourceType>instance</resourceType> <key>webserver</key> <value/> </item> </tagSet> </DescribeTagsResponse>

API Version 2012-05-01 259

Amazon Elastic Compute Cloud API Reference Related Operations

Example Request
This example describes the tags for all your instances tagged with either stack=Test or stack=Production.
https://ec2.amazonaws.com/?Action=DescribeTags &Filter.1.Name=resource-type &Filter.1.Value.1=instance &Filter.2.Name=key &Filter.2.Value.1=stack &Filter.3.Name=value &Filter.3.Value.1=Test &Filter.3.Value.2=Production &AUTHPARAMS

Sample response:
<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>i-5f4e3d2a</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-12345678</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Test</value> </item> </tagSet> </DescribeTagsResponse>

Example Request
This example describes the tags for all your instances tagged with Purpose=[empty string].
https://ec2.amazonaws.com/?Action=DescribeTags &Filter.1.Name=resource-type &Filter.1.Value.1=instance &Filter.2.Name=key &Filter.2.Value.1=Purpose &Filter.3.Name=value &Filter.3.Value.1= &AUTHPARAMS

Related Operations
CreateTags (p. 88) DeleteTags (p. 127)

API Version 2012-05-01 260

Amazon Elastic Compute Cloud API Reference DescribeVolumes

DescribeVolumes
Description
Describes your Amazon EBS volumes. For more information about Amazon EBS, go to Using Amazon Elastic Block Store in the Amazon Elastic Compute Cloud User Guide. You can filter the results to return information only about volumes that match criteria you specify. For example, you could get information about volumes whose status is available. You can specify multiple values for a filter (e.g., the volume's status is either available or in-use). A volume must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the volume's status is available, and it is tagged with a particular value). The result includes information for a particular volume only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
attachment.attach-time

Description Time stamp when the attachment initiated. Type: xsd:dateTime Whether the volume will be deleted on instance termination. Type: Boolean How the volume is exposed to the instance (e.g., /dev/sda1). Type: String ID of the instance the volume is attached to. Type: String Attachment state. Type: String Valid Values: attaching | attached | detaching | detached Availability Zone in which the volume was created. Type: String Time stamp when the volume was created. Type: xsd:dateTime Size of the volume, in GiB (e.g., 20). Type: String Snapshot from which the volume was created. Type: String

attachment.delete-on-termination

attachment.device

attachment.instance-id

attachment.status

availability-zone

create-time

size

snapshot-id

API Version 2012-05-01 261

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
status

Description Status of the volume. Type: String Valid Values: creating | available | in-use | deleting | deleted | error Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y Volume ID. Type: String

tag-key

tag-value

tag:key

volume-id

Request Parameters
Name
VolumeId.n

Description

Required

One or more volume IDs. No Type: String Default: Describes all volumes that you own, or only those otherwise specified.

API Version 2012-05-01 262

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Name

Description Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in a DescribeVolumesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of volumes. Each volume's information is wrapped in an item element. Type: DescribeVolumesSetItemResponseType (p. 403)

volumeSet

Examples
Example Request
This example describes all volumes associated with your account.
https://ec2.amazonaws.com/?Action=DescribeVolumes &AUTHPARAMS

Example Response
<DescribeVolumesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <volumeSet> <item> <volumeId>vol-4282672b</volumeId> <size>80</size> <snapshotId/> <availabilityZone>us-east-1a</availabilityZone> <status>in-use</status> <createTime>2008-05-07T11:51:50.000Z</createTime> <attachmentSet> <item> <volumeId>vol-4282672b</volumeId> <instanceId>i-6058a509</instanceId>

API Version 2012-05-01 263

Amazon Elastic Compute Cloud API Reference Related Operations

<device>/dev/sdh</device> <status>attached</status> <attachTime>2008-05-07T12:51:50.000Z</attachTime> <deleteOnTermination>false</deleteOnTermination> </item> </attachmentSet> <tagSet/> </item> </volumeSet> </DescribeVolumesResponse>

Example Request
This example describes all volumes that are both attached to instance i-1a2b3c4d and also set to delete when the instance terminates.
https://ec2.amazonaws.com/?Action=DescribeVolumes &Filter.1.Name=attachment.instance-id &Filter.1.Value.1=i-1a2b3c4d &Filter.2.Name=attachment.delete-on-termination &Filter.2.Value.1=true &AUTHPARAMS

Related Operations
CreateVolume (p. 90) DeleteVolume (p. 130) AttachVolume (p. 26) DetachVolume (p. 287)

API Version 2012-05-01 264

Amazon Elastic Compute Cloud API Reference DescribeVolumeAttribute

DescribeVolumeAttribute
Description
Describes an attribute of the volume. Currently, volumes have two attributes, autoEnableIO and productCodes. You can only specify the description of a single attribute.

Request Parameters
Name
VolumeId

Description The ID of the volume. Type: String Default: None The instance attribute to get. Type: String Default: None Valid Values: autoEnableIO |productCodes

Required Yes

Attribute

Yes

Response Elements
The elements in the following table are wrapped in a DescribeVolumeAttributeResponse structure. Only one attribute (either autoEnableIo or productCodes is returned, depending on what attribute you specified. Name
requestId

Description The ID of the request. Type: xsd:string The ID of the volume. Type: xsd:string The state of autoEnableIO attribute. Type: NullableAttributeBooleanValueType A list of product codes. Each product code's information is wrapped in an item element that contains a product code and a type. Type:ProductCodesSetItemType (p. 442)

volumeId

autoEnableIO

productCodes

Example
Example Request
This example describes the autoEnableIO attribute of the volume vol-12345678.

API Version 2012-05-01 265

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribeVolumeAttribute &Attribute=autoEnableIO &VolumeId=vol-12345678 &AUTHPARAMS

Example Response
<DescribeVolumeAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>5jkdf074-37ed-4004-8671-a78ee82bf1cbEXAMPLE</requestId> <volumeId>vol-12345678</volumeId> <autoEnableIO> <value>false</value> </autoEnableIO> </DescribeVolumeAttributeResponse>

Example Request
This example describes the productCodes attribute of the volume vol-12345678.
https://ec2.amazonaws.com/?Action=DescribeVolumeAttribute &Attribute=productCodes &VolumeId=vol-12345678 &AUTHPARAMS

Example Response
<DescribeVolumeAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>5jkdf074-37ed-4004-8671-a78ee82bf1cbEXAMPLE</requestId> <volumeId>vol-12345678</volumeId> <productCodes> <item> <productCode>a1b2c3d4e5f6g7h8i9j10k11</productCode> <type>marketplace</type> </item> </productCodes> </DescribeVolumeAttributeResponse>

Related Operations
DescribeVolumeStatus (p. 267) ModifyVolumeAttribute (p. 320)

API Version 2012-05-01 266

Amazon Elastic Compute Cloud API Reference DescribeVolumeStatus

DescribeVolumeStatus
Description
Returns the status of one or more volumes. Volume status provides the result of the checks performed on your volumes to determine events that can impair the performance of your volumes. The performance of a volume can be affected if an issue occurs on the volume's underlying host. If the volume's underlying host experiences a power outage or system issue, once the system is restored there could be data inconsistencies on the volume. Volume events notify you if this occurs. Volume actions notify you if any action needs to be taken in response to the event. The DescribeVolumeStatus operation provides the following information about the specified volumes: Status: Reflects the current status of the volume. The possible values are ok, impaired , or insufficient-data. If all checks pass, the overall status of the volume is ok. If the check fails, the overall status is impaired. If the status is insufficient-data, then the checks may still be taking place on your volume at the time. We recommend you retry the request. For more information on volume status, go to Monitoring the Status of Your Volumes. Events: Reflect the cause of a volume status and may require you to take an action. For example, if your volume returns an impaired status, then the volume event might be potential-data-inconsistency. This means that your volume has been affected by an issue with the underlying host, has all I/O operations disabled, and may have inconsistent data. Actions: Reflect the actions you may have to take in response to an event. For example, if the status of the volume is impaired and the volume event shows potential-data-inconsistency, then the action will show enable-volume-io. This means that you may want to to enable the I/O operations for the volume by calling the EnableVolumeIO (p. 295) action and then check the volume for data consistency.

Note
Volume status only has one status check. It does not check volume state as reported by DescribeVolumes. Therefore, it does not detect volumes in the ERROR state (i.e., when a volume is incapable of accepting I/Os because it is in an error state.) You can filter the results to return information only about volumes that match criteria you specify. For example, you could get information about volumes that have impaired status. You can specify multiple values for a filter (e.g., more than one Availability Zone). A volume must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the volume is in a specific Availability Zone and its status is set to impaired). A volume must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
availability-zone

Description Instance's Availability Zone. Type: String

API Version 2012-05-01 267

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
volume-status.status

Description The status of the volume. Type: String Valid Values: ok | impaired | insufficient-data The cause for the volume-status.status. Type: String Valid value: io-enabled The status of the volume-status.details-name. Type: String Valid Values: passed | failed A description of the event. Type: String The latest end time for the event. Type: dateType The earliest start time for the event. Type: dateType The event ID. Type: String The event type, e.g., potential-data-inconsistency Type: String The action code for the event, e.g., enable-volume-io Type: String The event ID associated with the action. Type: String A description of the action. Type: String

volume-status.details-name

volume-status.details-status

event.description

event.not-after

event.not-before

event.event-id

event.event-type

action.code

action.event-id

action.description

Request Parameters
Name
VolumeId.n

Description

Required

One or more volume IDs. No Type: String Default: Describes all volumes that you own, or only those otherwise specified.

API Version 2012-05-01 268

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Filter.n.Name

Description Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None Value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None The maximum number of paginated volume items per response. Type: Integer Default: None A string specifying the next paginated set of results to return using the pagination token returned by a previous call to this API. Type: String Default: None

Required No

Filter.n.Value.m

No

MaxResults

No

NextToken

No

Response Elements
The elements in the following table are wrapped in a DescribeVolumeStatusResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of volumes. Each volume's information is wrapped in an item element. Type: VolumeStatusItemType A string specifying the next paginated set of results to return. Type: String

volumeStatusSet

nextToken

Examples
Example Request
This example describes the status of all the volumes associated with your account.
https://ec2.amazonaws.com/?Action=DescribeVolumeStatus &AUTHPARAMS

API Version 2012-05-01 269

Amazon Elastic Compute Cloud API Reference Examples

Example Response
<DescribeVolumeStatus xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>5jkdf074-37ed-4004-8671-a78ee82bf1cbEXAMPLE</requestId> <volumeStatusSet> <item> <VolumeId>vol-11111111</volumeId> <availabilityZone>us-east-1d</availabilityZone> <volumeStatus> <status>ok</status> <details> <item> <name>io-enabled</name> <status>passed</status> </item> </details> </volumeStatus> </item> <item> <volumeId>vol-22222222</volumeId> <availabilityZone>us-east-1d</availabilityZone> <volumeStatus> <status>impaired</status> <details> <item> <name>io-enabled</name> <status>failed</status> </item> </details> </volumeStatus> <eventsSet> <item> <eventId>evol-61a54008</eventId> <eventType>potential-data-inconsistency</eventType> <description>THIS IS AN EXAMPLE</description> <notBefore>2011-12-01T14:00:00.000Z</notBefore> <notAfter>2011-12-01T15:00:00.000Z</notAfter> </item> </eventsSet> <actionsSet> <item> <code>enable-volume-io</code> <eventId> evol-61a54008</eventId> <eventType>potential-data-inconsistency</eventType> <description>THIS IS AN EXAMPLE</description> </item> </actionsSet> </item> </volumeStatusSet> </DescribeVolumesStatusResponse>

Example Request
This example describes all the volumes in the us-east-1d Availability Zone with failed io-enabled status.

API Version 2012-05-01 270

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribeVolumeStatus &Filter.1.Name=availability-zone &Filter.1.Value.1=us-east-1d &Filter.2.Name=volume-status.details-name &Filter.2.Value.1=io-enabled &Filter.3.Name=volume-status.details-status &Filter.3.Value.1=failed &AUTHPARAMS

Related Operations
ModifyVolumeAttribute (p. 320) DescribeVolumeAttribute (p. 265) EnableVolumeIO (p. 295)

API Version 2012-05-01 271

Amazon Elastic Compute Cloud API Reference DescribeVpcs

DescribeVpcs
Description
Gives you information about your VPCs. You can filter the results to return information only about VPCs that match criteria you specify. For example, you could get information only about VPCs whose state is available. You can specify multiple values for the filter. A VPC must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the VPC uses one of several sets of DHCP options, and the VPC's state is available). The result includes information for a particular VPC only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
cidr

Description The CIDR block of the VPC. The CIDR block you specify must exactly match the VPC's CIDR block for information to be returned for the VPC. Type: String Constraints: Must contain the slash followed by one or two digits (e.g., /28) The ID of a set of DHCP options. Type: String The state of the VPC. Type: String Valid Values: pending | available Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

dchp-options-id

state

tag-key

tag-value

API Version 2012-05-01 272

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y ID of the VPC. Type: String

vpc-id

For more information about Amazon Virtual Private Cloud and VPCs, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpcId.n

Description The ID of a VPC you want information about. Type: String Default: Returns information about all your VPCs, or only those otherwise specified Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: Returns information about all your VPCs, or only those otherwise specified. A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Name

No

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in an DescribeVpcsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of VPCs. Each VPC's information is wrapped in an item element. Type: VpcType (p. 465)

vpcSet

API Version 2012-05-01 273

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example gives a description of the VPC with ID vpc-1a2b3c4d.
https://ec2.amazonaws.com/?Action=DescribeVpcs &VpcId.1=vpc-1a2b3c4d &AUTHPARAMS

Example Response
<DescribeVpcsResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <vpcSet> <item> <vpcId>vpc-1a2b3c4d</vpcId> <state>available</state> <cidrBlock>10.0.0.0/23</cidrBlock> <dhcpOptionsId>dopt-7a8b9c2d</dhcpOptionsId> <tagSet/> </item> </vpcSet> </DescribeVpcsResponse>

Example Request
This example uses filters to give a description of any VPC you own that uses the set of DHCP options with ID dopt-7a8b9c2d or dopt-2b2a3d3c and whose state is available.
https://ec2.amazonaws.com/?Action=DescribeVpcs &Filter.1.Name=dhcp-options-id &Filter.1.Value.1=dopt-7a8b9c2d &Filter.1.Value.2=dopt-2b2a3d3c &Filter.2.Name=state &Filter.2.Value.1=available &AUTHPARAMS

Related Operations
CreateVpc (p. 92) DeleteVpc (p. 132) CreateDhcpOptions (p. 53) AssociateDhcpOptions (p. 18)

API Version 2012-05-01 274

Amazon Elastic Compute Cloud API Reference DescribeVpnConnections

DescribeVpnConnections
Description
Gives you information about your VPN connections.

Important
We strongly recommend you use HTTPS when calling this operation because the response contains sensitive cryptographic information for configuring your customer gateway.

You can filter the results to return information only about VPN connections that match criteria you specify. For example, you could get information only about VPN connections whose state is pending or available. You can specify multiple values for the filter. A VPN connection must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the VPN connection is associated with a particular virtual private gateway, and the gateway's state is pending or available). The result includes information for a particular VPN connection only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name Description

customer-gateway-con Configuration information for the customer gateway. figuration Type: String customer-gateway-id The ID of a customer gateway associated with the VPN connection. Type: String state

The state of the VPN connection. Type: String Valid Values: pending | available | deleting | deleted Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

tag-key

tag-value

API Version 2012-05-01 275

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y The type of VPN connection. Currently the only supported type is ipsec.1. Type: String Valid Values: ipsec.1 ID of the VPN connection. Type: String The ID of a virtual private gateway associated with the VPN connection. Type: String

type

vpn-connection-id

vpn-gateway-id

For more information about Amazon Virtual Private Cloud and VPN connections, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Note
You can get the customer gateway configuration information in a friendly format by using the ec2-describe-vpn-connections command instead. For more information, go to ec2-describe-vpn-connections in the Amazon Virtual Private Cloud Command Line Reference.

Request Parameters
Name
VpnConnectionId.n

Description A VPN connection ID. You can specify more than one in the request. Type: String Default: Returns information about all your VPN connections Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: Returns information about all your VPN connections or those you specify by ID. A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None

Required No

Filter.n.Name

No

Filter.n.Value.m

No

API Version 2012-05-01 276

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in an DescribeVpnConnectionsResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string A list of VPN connections. Each VPN connection's information is wrapped in an item element. Type: VpnConnectionType (p. 466)

vpnConnectionSet

Examples
Example Request
This example gives a description of the VPN connection with ID vpn-44a8938f. The response includes the customer gateway configuration information. Because it's a long set of information, we haven't displayed it here. You can see an example in the topic for CreateVpnConnection.
https://ec2.amazonaws.com/?Action=DescribeVpnConnections &VpnConnectionId.1=vpn-44a8938f &AUTHPARAMS

Example Response
<DescribeVpnConnectionsResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <vpnConnectionSet> <item> <vpnConnectionId>vpn-44a8938f</vpnConnectionId> <state>available</state> <CustomerGatewayConfiguration> Customer gateway configuration data in escaped XML format... ... </CustomerGatewayConfiguration> <type>ipsec.1</type> <customerGatewayId>cgw-b4dc3961</customerGatewayId> <vpnGatewayId>vgw-8db04f81</vpnGatewayId> <tagSet/> </item> </vpnConnectionSet> </DescribeVpnConnectionsResponse>

Example Request
This example gives a description of any VPN connection you own associated with the customer gateway with ID cgw-b4dc3961, and whose state is either pending or available.

API Version 2012-05-01 277

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DescribeVpnConnections &Filter.1.Name=customer-gateway-id &Filter.1.Value.1=cgw-b4dc3961 &Filter.2.Name=state &Filter.2.Value.1=pending &Filter.2.Value.2=available &AUTHPARAMS

Related Operations
CreateVpnConnection (p. 94) DeleteVpnConnection (p. 134)

API Version 2012-05-01 278

Amazon Elastic Compute Cloud API Reference DescribeVpnGateways

DescribeVpnGateways
Description
Gives you information about your virtual private gateways. You can filter the results to return information only about virtual private gateways that match criteria you specify. For example, you could get information only about virtual private gateways whose state is pending or available. You can specify multiple values for the filter. A virtual private gateway must match at least one of the specified values for it to be included in the results. You can specify multiple filters (e.g., the virtual private gateway is in a particular Availability Zone and the gateway's state is pending or available). The result includes information for a particular virtual private gateway only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty. You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\. The following table shows the available filters. Filter Name
attachment.state

Description Current state of the attachment between the gateway and the VPC. Type: String Valid Values: attaching | attached | detaching | detached ID of an attached VPC. Type: String The Availability Zone the virtual private gateway is in. Type: String The state of the virtual private gateway. Type: String Valid Values: pending | available | deleting | deleted Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String Value of a tag assigned to the resource. This filter is independent of the tag-key filter. Type: String

attachment.vpc-id

availability-zone

state

tag-key

tag-value

API Version 2012-05-01 279

Amazon Elastic Compute Cloud API Reference Request Parameters

Filter Name
tag:key

Description Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: Filter.1.Name=tag:Purpose Filter.1.Value.1=X Filter.1.Value.2=Y The type of virtual private gateway. Currently the only supported type is ipsec.1. Type: String Valid Values: ipsec.1 ID of the virtual private gateway. Type: String

type

vpn-gateway-id

For more information about Amazon Virtual Private Cloud and virtual private gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpnGatewayId.n

Description

Required

A virtual private gateway ID. You can specify more No than one in the request. Type: String Default: Returns information about all your virtual private gateways. Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: Returns information about all your virtual private gateways or those you specify by ID. A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None No

Filter.n.Name

Filter.n.Value.m

No

Response Elements
The elements in the following table are wrapped in an DescribeVpnGatewaysResponsestructure.

API Version 2012-05-01 280

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string A list of virtual private gateways. Each virtual private gateway's information is wrapped in an item element. Type: VpnGatewayType (p. 467)

vpnGatewaySet

Examples
Example Request
This example gives a description of the virtual private gateway with ID vgw-8db04f81.
https://ec2.amazonaws.com/?Action=DescribeVpnGateways &VpnGatewayId.1=vgw-8db04f81 &AUTHPARAMS

Example Response
<DescribeVpnGatewaysResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <vpnGatewaySet> <item> <vpnGatewayId>vgw-8db04f81</vpnGatewayId> <state>available</state> <type>ipsec.1</type> <availabilityZone>us-east-1a</availabilityZone> <attachments> <item> <vpcId>vpc-1a2b3c4d<vpcId> <state>attached</state> </item> </attachments> <tagSet/> </item> </vpnGatewaySet> </DescribeVpnGatewaysResponse>

Example Request
This example uses filters to give a description of any virtual private gateway you own that is in the us-east-1a Availability Zone, and whose state is either pending or available.
https://ec2.amazonaws.com/?Action=DescribeVpnGateways &Filter.1.Name=availability-zone &Filter.1.Value.1=us-east-1a &Filter.2.Name=state &Filter.2.Value.1=pending

API Version 2012-05-01 281

Amazon Elastic Compute Cloud API Reference Related Operations

&Filter.2.Value.2=available &AUTHPARAMS

Related Operations
CreateVpnGateway (p. 98) DeleteVpnGateway (p. 136)

API Version 2012-05-01 282

Amazon Elastic Compute Cloud API Reference DetachInternetGateway

DetachInternetGateway
Description
Detaches an Internet gateway from a VPC, disabling connectivity between the Internet and the VPC. The VPC must not contain any running instances with Elastic IP addresses. For more information about your VPC and Internet gateway, go to the Amazon Virtual Private Cloud User Guide. For more information about Amazon Virtual Private Cloud and Internet gateways, go to the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
InternetGatewayId

Description The ID of the Internet gateway to detach. Type: String Default: None The ID of the VPC. Type: String Default: None

Required Yes

VpcId

Yes

Response Elements
The elements in the following table are wrapped in a DetachInternetGatewayResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
The example detaches the Internet gateway with ID igw-eaad4883 from the VPC with ID vpc-11ad4878.
https://ec2.amazonaws.com/?Action=DetachInternetGateway &InternetGatewayId=igw-eaad4883 &VpcId=vpc-11ad4878 &AUTHPARAMS

API Version 2012-05-01 283

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<DetachInternetGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DetachInternetGatewayResponse>

Related Operations
CreateInternetGateway (p. 61) DeleteInternetGateway (p. 104) DetachInternetGateway (p. 22) DescribeInternetGateways (p. 192)

API Version 2012-05-01 284

Amazon Elastic Compute Cloud API Reference DetachNetworkInterface

DetachNetworkInterface
Description
Detaches a network interface from an instance.

Request Parameters
Name
AttachmentId

Description The ID of the attachment to detach. Type: String Default: None Set to true to force a detachment. Type: Boolean Default: None

Required Yes

Force

No

Response Elements
The elements in the following table are wrapped in a DetachNetworkInterface structure. Name
requestId

Description The ID of the request to detach the network interface. Type: String Type: Boolean

return

Examples
Example Request
This example detaches an elastic network interface (ENI) eni-attach-d94b09b0.
https://ec2.amazonaws.com/?Action=DetachNetworkInterface &AttachmentId=eni-attach-d94b09b0 &AUTHPARAMS

Example Response
<DetachNetworkInterfaceResponse xmlns='http://ec2.amazonaws.com/doc/2011-1115/'> <requestId>ce540707-0635-46bc-97da-33a8a362a0e8</requestId> <return>true</return> </DetachNetworkInterfaceResponse>

API Version 2012-05-01 285

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
AttachNetworkInterface (p. 24) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 286

Amazon Elastic Compute Cloud API Reference DetachVolume

DetachVolume
Description
Detaches an Amazon EBS volume from an instance. Make sure to unmount any file systems on the device within your operating system before detaching the volume. Failure to do so will result in volume being stuck in "busy" state while detaching. For more information about Amazon EBS, go to Using Amazon Elastic Block Store in the Amazon Elastic Compute Cloud User Guide.

Note
If an Amazon EBS volume is the root device of an instance, it cannot be detached while the instance is in the "running" state. To detach the root volume, stop the instance first. If the root volume is detached from an instance with an AWS Marketplace product code, then the AWS Marketplace product codes from that volume will no longer be associated with the instance.

Request Parameters
Name
VolumeId

Description The ID of the volume. Type: String Default: None The ID of the instance. Type: String Default: None The device name. Type: String Default: None

Required Yes

InstanceId

No

Device

No

Force

Forces detachment if the previous detachment attempt did No not occur cleanly (logging into an instance, unmounting the volume, and detaching normally). This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance will not have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures. Type: Boolean Default: None

Response Elements
The elements in the following table are wrapped in a DetachVolumeResponse structure.

API Version 2012-05-01 287

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string The ID of the volume. Type: xsd:string The ID of the instance. Type: xsd:string The device as it is exposed to the instance. Type: xsd:string Attachment state. Type: xsd:string Valid Values: attaching | attached | detaching | detached Time stamp when the attachment initiated. Type: xsd:dateTime

volumeId

instanceId

device

status

attachTime

Examples
Example Request
This example detaches volume vol-4d826724.
https://ec2.amazonaws.com/?Action=DetachVolume &VolumeId=vol-4d826724 &InstanceId=i-6058a509 &AUTHPARAMS

Example Response
<DetachVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <volumeId>vol-4d826724</volumeId> <instanceId>i-6058a509</instanceId> <device>/dev/sdh</device> <status>detaching</status> <attachTime>2008-05-08T11:51:50.000Z</attachTime> </DetachVolumeResponse>

Related Operations
CreateVolume (p. 90) DeleteVolume (p. 130) DescribeVolumes (p. 261) AttachVolume (p. 26)

API Version 2012-05-01 288

Amazon Elastic Compute Cloud API Reference DetachVpnGateway

DetachVpnGateway
Description
Detaches a virtual private gateway from a VPC. You do this if you're planning to turn off the VPC and not use it anymore. You can confirm a virtual private gateway has been completely detached from a VPC by describing the virtual private gateway (any attachments to the virtual private gateway are also described). You must wait for the attachment's state to switch to detached before you can delete the VPC or attach a different VPC to the virtual private gateway. For more information about Amazon Virtual Private Cloud and virtual private gateways, go to Adding an IPsec Hardware Virtual Private Gateway to Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
VpnGatewayId

Description The ID of the virtual private gateway you want to detach from the VPC. Type: String Default: None The ID of the VPC you want to detach the virtual private gateway from. Type: String Default: None

Required Yes

VpcId

Yes

Response Elements
The elements in the following table are wrapped in an DetachVpnGatewayResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example detaches the virtual private gateway with ID vgw-8db04f81 from the VPC with VPC ID vpc-1a2b3c4d.

API Version 2012-05-01 289

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DetachVpnGateway &VpnGatewayId=vgw-8db04f81 &VpcId=vpc-1a2b3c4d &AUTHPARAMS

Example Response
<DetachVpnGatewayResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <return>true</return> </DetachVpnGatewayResponse>

Related Operations
AttachVpnGateway (p. 29) DescribeVpnGateways (p. 279)

API Version 2012-05-01 290

Amazon Elastic Compute Cloud API Reference DisassociateAddress

DisassociateAddress
Description
Disassociates an Elastic IP address from the instance it's assigned to. This action applies to both EC2 Elastic IP addresses and VPC Elastic IP addresses. For information about VPC addresses and how they differ from EC2 addresses, go to Elastic IP Addresses in the Amazon Virtual Private Cloud User Guide. This is an idempotent action. If you enter it more than once, Amazon EC2 does not return an error.

Request Parameters
Name
PublicIp

Description EC2 Elastic IP address you want to disassociate. Type: String Default: None Condition: Required for EC2 Elastic IP addresses Association ID corresponding to the VPC Elastic IP address you want to disassociate. Type: String Default: None Condition: Required for VPC Elastic IP addresses

Required Conditional

AssociationId

Conditional

Response Elements
The elements in the following table are wrapped in a DisassociateAddressResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example disassociates the EC2 Elastic IP address 67.202.55.255 from the instance to which it is assigned.

API Version 2012-05-01 291

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=DisassociateAddress &PublicIp=192.0.2.1 &AUTHPARAMS

Example Request
This example disassociates the VPC Elastic IP address with association ID eipassoc-aa7486c3 from the VPC instance to which it is assigned.
https://ec2.amazonaws.com/?Action=DisassociateAddress &AssociationID=eipassoc-aa7486c3 &AUTHPARAMS

Example Response
<DisassociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DisassociateAddressResponse>

Related Operations
AllocateAddress (p. 13) DescribeAddresses (p. 140) ReleaseAddress (p. 332) AssociateAddress (p. 15)

API Version 2012-05-01 292

Amazon Elastic Compute Cloud API Reference DisassociateRouteTable

DisassociateRouteTable
Description
Disassociates a subnet from a route table. After you perform this action, the subnet no longer uses the routes in the route table. Instead, it uses the routes in the VPC's main route table. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
AssociationId

Description The association ID representing the current association between the route table and subnet. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a DisassociateRouteTableResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example disassociates the route table with association ID rtbassoc-fdad4894 from the subnet it's associated to.
https://ec2.amazonaws.com/?Action=DisassociateRouteTable &AssociationId=rtbassoc-fdad4894 &AUTHPARAMS

Example Response
<DisassociateRouteTableResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/">

API Version 2012-05-01 293

Amazon Elastic Compute Cloud API Reference Related Operations

<requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DisassociateRouteTableResponse>

Related Operations
CreateRouteTable (p. 77) AssociateRouteTable (p. 20) DeleteRouteTable (p. 118) DescribeRouteTables (p. 225) ReplaceRouteTableAssociation (p. 341)

API Version 2012-05-01 294

Amazon Elastic Compute Cloud API Reference EnableVolumeIO

EnableVolumeIO
Description
Enables I/O operations for a volume that had I/O operations disabled because the data on the volume was potentially inconsistent.

Request Parameters
Name
VolumeId

Description The volume ID. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a EnableVolumeIOResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the I/O operations of the volume are enabled. Type: xsd:boolean

return

Examples
Example Request
This example enables the I/O operations of the volume vol-8888888.
https://ec2.amazonaws.com/?Action=EnableVolumeIO &VolumeId= vol-8888888 &AUTHPARAMS

Example Response
<EnableVolumeIOResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </EnableVolumeIOResponse>

Related Operations
DescribeVolumeStatus (p. 267)
API Version 2012-05-01 295

Amazon Elastic Compute Cloud API Reference Related Operations

ModifyVolumeAttribute (p. 320) DescribeVolumeAttribute (p. 265)

API Version 2012-05-01 296

Amazon Elastic Compute Cloud API Reference GetConsoleOutput

GetConsoleOutput
Description
Retrieves console output for the specified instance. Instance console output is buffered and posted shortly after instance boot, reboot, and termination. Amazon EC2 preserves the most recent 64 KB output which will be available for at least one hour after the most recent post.

Request Parameters
Name
InstanceId

Description ID of the instance. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a GetConsoleOutputResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The instance ID. Type: xsd:string The time the output was last updated. Type: xsd:dateTime The console output, Base64 encoded. Type: xsd:string

instanceId

timestamp

output

Examples
Example Request
This example retrieves the console output for the i-10a64379 Linux and UNIX instance.
https://ec2.amazonaws.com/?Action=GetConsoleOutput &InstanceId=i-10a64379 &AUTHPARAMS

API Version 2012-05-01 297

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<GetConsoleOutputResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instanceId>i-28a64341</instanceId> <timestamp>2010-10-14T01:12:41.000Z</timestamp> <output>TGludXggdmVyc2lvbiAyLjYuMTYteGVuVSAoYnVpbGRlckBwYXRjaGJhdC5hb WF6b25zYSkgKGdj YyB2ZXJzaW9uIDQuMC4xIDIwMDUwNzI3IChSZWQgSGF0IDQuMC4xLTUpKSAjMSBTTVAgVGh1IE9j dCAyNiAwODo0MToyNiBTQVNUIDIwMDYKQklPUy1wcm92aWRlZCBwaHlzaWNhbCBSQU0gbWFwOgpY ZW46IDAwMDAwMDAwMDAwMDAwMDAgLSAwMDAwMDAwMDZhNDAwMDAwICh1c2FibGUpCjk4ME1CIEhJ R0hNRU0gYXZhaWxhYmxlLgo3MjdNQiBMT1dNRU0gYXZhaWxhYmxlLgpOWCAoRXhlY3V0ZSBEaXNh YmxlKSBwcm90ZWN0aW9uOiBhY3RpdmUKSVJRIGxvY2t1cCBkZXRlY3Rpb24gZGlzYWJsZWQKQnVp bHQgMSB6b25lbGlzdHMKS2VybmVsIGNvbW1hbmQgbGluZTogcm9vdD0vZGV2L3NkYTEgcm8gNApF bmFibGluZyBmYXN0IEZQVSBzYXZlIGFuZCByZXN0b3JlLi4uIGRvbmUuCg==</output> </GetConsoleOutputResponse>

Related Operations
RunInstances (p. 366)

API Version 2012-05-01 298

Amazon Elastic Compute Cloud API Reference GetPasswordData

GetPasswordData
Description
Retrieves the encrypted administrator password for an instance running Windows.

Note
The Windows password is only generated the first time an AMI is launched. It is not generated for rebundled AMIs or after the password is changed on an instance. The password is encrypted using the key pair that you provided.

Request Parameters
Name
InstanceId

Description A Windows instance ID. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a GetPasswordDataResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The ID of the instance. Type: xsd:string The time the data was last updated. Type: xsd:dateTime The password of the instance. Type: xsd:string

instanceId

timestamp

passwordData

Examples
Example Request
This example returns the encrypted version of the administrator password for the i-2574e22a instance.
https://ec2.amazonaws.com/?Action=GetPasswordData &InstanceId=i-10a64379 &AUTHPARAMS

API Version 2012-05-01 299

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<GetPasswordDataResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instanceId>i-2574e22a</instanceId> <timestamp>2009-10-24 15:00:00</timestamp> <passwordData>TGludXggdmVyc2lvbiAyLjYuMTYteGVuVSAoYnVpbGRlckBwYXRjaGJhdC5hb WF6b25zYSkgKGdj</passwordData> </GetPasswordDataResponse>

Related Operations
RunInstances (p. 366)

API Version 2012-05-01 300

Amazon Elastic Compute Cloud API Reference ImportInstance

ImportInstance
Description
Creates a new import instance task using metadata from the specified disk image. After importing the image, you then upload it using the ec2-upload-disk-image command in the EC2 command line tools. For more information, go to Using the Command Line Tools to Import Your Virtual Machine to Amazon EC2 in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
Description

Description Description of the instance being imported Type: String Default: None Architecture of the instance. Type: String Default: None Valid Values: i386 | x86_64 One or more security group names. Type: String Default: None User data to be made available to the instance. Type: String Default: None

Required No

Architecture

Yes

SecurityGroup.n

No

UserData

No

InstanceType

The instance type. Yes Type: String Valid Values: m1.small | m1.large | m1.xlarge | c1.medium | c1.xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge | t1.micro Default: m1.small The Availability Zone you want to launch the instance into. Type: xsd:string Default: EC2 chooses a zone for you Enables detailed monitoring for the instance. Type: Boolean Default: false If you're using Amazon Virtual Private Cloud, this specifies the ID of the subnet you want to launch the instance into. Type: String Default: None No

Placement.Availabili tyZone

Monitoring.Enabled

No

SubnetId

No

API Version 2012-05-01 301

Amazon Elastic Compute Cloud API Reference Response Elements

Name
InstanceInitiatedShu tdownBehavior

Description Determines whether the instance stops or terminates on instance-initiated shutdown. Type: String Valid Values: stop | terminate Default: stop If you're using Amazon Virtual Private Cloud, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (e.g., 10.0.0.25). Type: String Default: Amazon VPC selects an IP address from the subnet for the instance File format of the disk image. Type: String Default: None Valid Values: VMDK | RAW | VHD

Required No

PrivateIpAddress

No

DiskImage.n.Image.Fo rmat

Yes

DiskImage.n.Image.Bytes Number of bytes in the disk image. Type: xsd:long Default: None DiskImage.n.Image.Im portManifestUrl

Yes

The manifest for the disk image, stored in Amazon S3 Yes and presented here as an Amazon S3 presigned URL. For information about creating a presigned URL for an Amazon S3 object, read the "Signing and Authenticating REST Requests" section of the Signing and Authenticating REST Requests topic in the Amazon Simple Storage Service Developer Guide. Type: String Default: None Optional description of the disk image. Type: String Default: None No

DiskImage.n.Image.De scription

DiskImage.n.Volume.Size The size, in GB (2^30 bytes), of the Amazon EBS volume that will hold the converted image. Type: Integer Default: None Platform

Yes

The EC2 instance operating system. Type: String Default: None Valid Value: Windows

Yes

Response Elements
The elements in the following table are wrapped in an ImportInstanceResponse structure.
API Version 2012-05-01 302

Amazon Elastic Compute Cloud API Reference Examples

Name
conversionTask

Description Information about the import instance task. Type: ConversionTaskType (p. 393)

Examples
Example Request
This example creates an import instance task that migrates a Windows Server 2008 SP2 (32-bit) VM into the AWS us-east-1 Region.
https://ec2.amazonaws.com/?Action=ImportInstance &Architecture=x86_64 &InstanceType=m1.xlarge &DiskImage.1.Image.Format=VMDK &DiskImage.1.Image.Bytes=1179593728 &DiskImage.1.Image.ImportManifestUrl=https://s3.amazonaws.com/myawsbucket/ a3a5e1b6-590d-43cc-97c1-15c7325d3f41/Win_2008_Server_Data_Center_SP2_32-bit. vmdkmanifest.xml?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Expires=1294855591&Signa ture=5snej01TlTtL0uR7KExtEXAMPLE%3D &DiskImage.1.Volume.Size=12 &Platform=Windows &AUTHPARAMS

Example Response
<ImportInstanceResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <conversionTask> <conversionTaskId>import-i-ffvko9js</conversionTaskId> <expirationTime>2010-12-22T12:01Z</expirationTime> <importInstance> <volumes> <item> <bytesConverted>0</bytesConverted> <availabilityZone>us-east-1a</availabilityZone> <image> <format>VMDK</format> <size>1179593728</size> <importManifestUrl> https://s3.amazonaws.com/myawsbucket/a3a5e1b6-590d-43cc-97c115c7325d3f41/Win_2008_Server_Data_Center_SP2_32-bit.vmdkmanifest.xml?AWSAccess KeyId=AKIAIOSFODNN7EXAMPLE&Expires=1294855591&Signature=5snej01TlTtL0uR7KEx tEXAMPLE%3D </importManifestUrl> </image> <description/> <volume> <size>12</size> <id>vol-1a2b3c4d</id> </volume> <status>active</status> <statusMessage/>

API Version 2012-05-01 303

Amazon Elastic Compute Cloud API Reference Related Operations

</item> </volumes> <instanceId>i-12655a7f</instanceId> <description/> </importInstance> </conversionTask> </ImportInstanceResponse>

Related Operations
ImportVolume (p. 307) DescribeConversionTasks (p. 150) CancelConversionTask (p. 43)

API Version 2012-05-01 304

Amazon Elastic Compute Cloud API Reference ImportKeyPair

ImportKeyPair
Description
Imports the public key from an RSA key pair that you created with a third-party tool. Compare this with CreateKeyPair, in which AWS creates the key pair and gives the keys to you (AWS keeps a copy of the public key). With ImportKeyPair, you create the key pair and give AWS just the public key. The private key is never transferred between you and AWS. You can easily create an RSA key pair on Windows and Linux using the ssh-keygen command line tool (provided with the standard OpenSSH installation). Standard library support for RSA key pair creation is also available in Java, Ruby, Python, and many other programming languages. Supported formats: OpenSSH public key format (e.g., the format in ~/.ssh/authorized_keys) Base64 encoded DER format SSH public key file format as specified in RFC4716 DSA keys are not supported. Make sure your key generator is set up to create RSA keys. Supported lengths: 1024, 2048, and 4096.

Request Parameters
Name
KeyName

Description A unique name for the key pair. Type: String Default: None Constraints: Accepts alphanumeric characters, spaces, dashes, and underscores. The public key. You must base64 encode the public key material before sending it to AWS. Type: String Default: None

Required Yes

PublicKeyMaterial

Yes

Response Elements
The elements in the following table are wrapped in an ImportKeyPairResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The key pair name you provided. Type: xsd:string

keyName

API Version 2012-05-01 305

Amazon Elastic Compute Cloud API Reference Examples

Name
keyFingerprint

Description MD5 public key fingerprint as specified in section 4 of RFC4716. Type: xsd:string

Examples
Example Request
This example uploads the public key for a key pair you name gsg-keypair.
https://ec2.amazonaws.com/?Action=ImportKeyPair &KeyName=gsg-keypair &PublicKeyMaterial=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlDZHp DQ0FlQ2dBd0lCQWdJR0FQalRyR3pQ TUEwR0NTcUdTSWIzRFFFQkJRVUFNRk14Q3pBSkJnTlZCQVlUDQpBbFZUTVJNd0VRWURWUVFLRXdw QmJXRjZiMjR1WTI5dE1Rd3dDZ1lEVlFRTEV3TkJWMU14SVRBZkJnTlZCQU1UDQpHRUZYVXlCTWFX MXBkR1ZrTFVGemMzVnlZVzVqWlNCRFFUQWVGdzB3T1RBM016RXlNVFEzTXpWYUZ3MHhNREEzDQpN ekV5TVRRM016VmFNRkl4Q3pBSkJnTlZCQVlUQWxWVE1STXdFUVlEVlFRS0V3cEJiV0Y2YjI0dVky OXRNUmN3DQpGUVlEVlFRTEV3NUJWMU10UkdWMlpXeHZjR1Z5Y3pFVk1CTUdBMVVFQXhNTWJUSnVi RGhxZW00MWVHUjFNSUdmDQpNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0R05BRENCaVFLQmdRQ1dOazBo QytrcExBRnp2YkFQc3U1TDU5bFMwUnI0DQprZEpaM0RFak1pL0IwV2ZDSzhpS2hWYWt1WitHSnJt NDdMUHZCaFVKWk9IeHVUU0VXakFDNmlybDJzKzlSWXVjDQpFZXg0TjI4ZlpCZGpORlAzdEgwZ2Nu WjdIbXZ4aFBrTEtoRTdpZmViNmNGWUhRdHpHRnRPQ0ZQTmdUSE92VDE5DQoyR3lZb1VyU3BDVGFC UUlEQVFBQm8xY3dWVEFPQmdOVkhROEJBZjhFQkFNQ0JhQXdGZ1lEVlIwbEFRSC9CQXd3DQpDZ1lJ S3dZQkJRVUhBd0l3REFZRFZSMFRBUUgvQkFJd0FEQWRCZ05WSFE0RUZnUVU1RVNuTUZZUzdyTDNX TUdLDQpqejMxVXZ5TThnMHdEUVlKS29aSWh2Y05BUUVGQlFBRGdZRUFnWjdDZ1lJWHR1WFM1NHVq bU5jOTR0NWRNc3krDQpCM0Z3WVVNdUd4WUI2eGQvSUVWMTFLRVEyZ0hpZUdMU21jUWg4c2JXTTdt KzcrYm9UNmc2U2hLbU1jblkzWkRTDQpWRVFZZ25qcEt1aEZRd2pmaVpTUEc1UG5SVENhdkVqS3lT TUpDVGxpdTdTTjMrR2J3cFU5Uzg3K21GM2tsMGRmDQpZNlIrbEl5SWcrU3ROOTg9DQotLS0tLUVO RCBDRVJUSUZJQ0FURS0tLS0tEXAMPLE &AUTHPARAMS

Example Response
<ImportKeyPairResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <keyName>gsg-keypair</keyName> <keyFingerprint> 00:00:00: 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 </keyFingerprint> </ImportKeyPairResponse>

Related Operations
CreateKeyPair (p. 63) DescribeKeyPairs (p. 195) DeleteKeyPair (p. 106)

API Version 2012-05-01 306

Amazon Elastic Compute Cloud API Reference ImportVolume

ImportVolume
Description
Creates a new import volume task using metadata from the specified disk image. After importing the image, you then upload it using the ec2-upload-disk-image command in the EC2 command line tools. For more information, go to Using the Command Line Tools to Import Your Virtual Machine to Amazon EC2 in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
AvailabilityZone

Description

Required

Availability Zone where the resulting Amazon EBS volume Yes will reside. Type: String Default: None The file format of the disk image. Type: String Default: None Valid Values: VMDK | RAW | VHD Number of bytes in the disk image. Type: xs:long Default: None Yes

Image.Format

Image.Bytes

Yes

Image.ImportManifest Url

The manifest for the disk image, stored in Amazon S3 and Yes presented here as an Amazon S3 presigned URL. For information about creating a presigned URL for an Amazon S3 object, read the "Signing and Authenticating REST Requests" section of the Signing and Authenticating REST Requests topic in the Amazon Simple Storage Service Developer Guide. Type: String Default: None Optional description of the volume being imported. Type: String Default: None The size, in GB (2^30 bytes), of an Amazon EBS volume that will hold the converted image. Type: Integer Default: None No

Description

Volume.Size

Yes

Response Elements
The elements in the following table are wrapped in an ImportVolumeResponse structure.

API Version 2012-05-01 307

Amazon Elastic Compute Cloud API Reference Examples

Name
conversionTask

Description Information about the import volume task. Type: ConversionTaskType (p. 393)

Examples
Example Request
This example creates an import volume task that migrates a Windows Server 2008 SP2 (32-bit) volume into the AWS us-east-1 Region.
https://ec2.amazonaws.com/?Action=ImportVolume &AvailabilityZone=us-east-1c &Image.Format=VMDK &Image.Bytes=128696320 &Image.ImportManifestUrl=https://s3.amazonaws.com/myawsbucket/a3a5e1b6-590d43cc-97c1-15c7325d3f41/Win_2008_Server_Data_Center_SP2_32-bit.vmdkmani fest.xml?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Expires=1294855591&Signa ture=5snej01TlTtL0uR7KExtEXAMPLE%3D &VolumeSize=8 &AUTHPARAMS

Example Response
<ImportVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <conversionTask> <conversionTaskId>import-i-fh95npoc</conversionTaskId> <expirationTime>2010-12-22T12:01Z</expirationTime> <importVolume> <bytesConverted>0</bytesConverted> <availabilityZone>us-east-1c</availabilityZone> <description/> <image> <format>VDMK</format> <size>128696320</size> <importManifestUrl> https://s3.amazonaws.com/myawsbucket/a3a5e1b6-590d-43cc-97c115c7325d3f41/Win_2008_Server_Data_Center_SP2_32-bit.vmdkmanifest.xml?AWSAccess KeyId=AKIAIOSFODNN7EXAMPLE&Expires=1294855591&Signature=5snej01TlTtL0uR7KEx tEXAMPLE%3D </importManifestUrl> <checksum>ccb1b0536a4a70e86016b85229b5c6b10b14a4eb</checksum> </image> <volume> <size>8</size> <id>vol-34d8a2ff</id> </volume> </importVolume> <state>active</state> <statusMessage/> </conversionTask> </ImportVolumeResponse>

API Version 2012-05-01 308

Amazon Elastic Compute Cloud API Reference Related Operations

Related Operations
ImportInstance (p. 301) DescribeConversionTasks (p. 150) CancelConversionTask (p. 43)

API Version 2012-05-01 309

Amazon Elastic Compute Cloud API Reference ModifyImageAttribute

ModifyImageAttribute
Description
Modifies an attribute of an AMI.

Note
AWS Marketplace product codes cannot be modified. Images with an AWS Marketplace product code cannot be made public.

Request Parameters
Name
ImageId

Description The AMI ID. Type: String Default: None Adds the specified AWS account ID to the AMI's list of launch permissions. Type: String Default: None Removes the specified AWS account ID from the AMI's list of launch permissions. Type: String Default: None Adds the specified group to the image's list of launch permissions. The only valid value is all. Type: String Valid Value: all (for all EC2 users) Default: None Removes the specified group from the image's list of launch permissions. The only valid value is all. Type: String Valid Value: all (for all EC2 users) Default: None

Required Yes

LaunchPermission.Add .n.UserId

No

LaunchPermission.Rem ove.n.UserId

No

LaunchPermission.Add .n.Group

No

LaunchPermission.Rem ove.n.Group

No

ProductCode.n

Adds the specified product code to the specified Amazon No S3-backed AMI. Once you add a product code to an AMI, it can't be removed. Type: String Default: None Changes the AMI's description to the specified value. Type: String Default: None No

Description.Value

API Version 2012-05-01 310

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a ModifyImageAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if successful. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example makes the AMI public (i.e., so any AWS account can launch it).
https://ec2.amazonaws.com/?Action=ModifyImageAttribute &ImageId=ami-61a54008 &LaunchPermission.Add.1.Group=all &AUTHPARAMS

Example Request
This example makes the AMI private (i.e., so only you as the owner can launch it).
https://ec2.amazonaws.com/?Action=ModifyImageAttribute &ImageId=ami-61a54008 &LaunchPermission.Remove.1.Group=all &AUTHPARAMS

Example Request
This example grants launch permission to the AWS account with ID 111122223333.
https://ec2.amazonaws.com/?Action=ModifyImageAttribute &ImageId=ami-61a54008 &LaunchPermission.Add.1.UserId=111122223333 &AUTHPARAMS

Example Request
This example removes launch permission from the AWS account with ID 111122223333.
https://ec2.amazonaws.com/?Action=ModifyImageAttribute &ImageId=ami-61a54008 &LaunchPermission.Remove.1.UserId=111122223333 &AUTHPARAMS

API Version 2012-05-01 311

Amazon Elastic Compute Cloud API Reference Related Operations

Example Request
This example adds the 774F4FF8 product code to the ami-61a54008 AMI.
https://ec2.amazonaws.com/?Action=ModifyImageAttribute &ImageId=ami-61a54008 &ProductCode.1=774F4FF8 &AUTHPARAMS

Example Request
This example changes the description of the AMI to New_Description
https://ec2.amazonaws.com/?Action=ModifyImageAttribute &ImageId=ami-61a54008 &Description.Value=New_Description &AUTHPARAMS

Example Response
<ModifyImageAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <return>true</return> </ModifyImageAttributeResponse>

Related Operations
ResetImageAttribute (p. 352) DescribeImageAttribute (p. 161)

API Version 2012-05-01 312

Amazon Elastic Compute Cloud API Reference ModifyInstanceAttribute

ModifyInstanceAttribute
Description
Modifies an attribute of an instance.

Note
To modify some attributes, the instance must be stopped. For more information, see Using Instance Metadata in the Amazon Elastic Compute Cloud User's Guide.

Note
If you want to add ephemeral storage to an Amazon EBS-backed instance, you must add the ephemeral storage at the time you launch the instance. For more information, go to Overriding the AMI's Block Device Mapping in the Amazon Elastic Compute Cloud User Guide, or to Using Amazon EC2 Instance Storage in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
InstanceId

Description The ID of the instance. Type: String Default: None Changes the instance type to the specified value. Type: String Default: None Changes the instance's kernel to the specified value. Type: String Default: None Changes the instance's RAM disk to the specified value. Type: String Default: None Changes the instance's user data to the specified value. Type: String Default: None

Required Yes

InstanceType.Value

No

Kernel.Value

No

Ramdisk.Value

No

UserData.Value

No

DisableApiTerminatio n.Value

Changes the instance's DisableApiTermination flag No to the specified value. A value of true means you can't terminate the instance using the API (i.e., the instance is "locked"); a value of false means you can. You must modify this attribute before you can terminate any "locked" instances using the API. Type: Boolean Default: None

API Version 2012-05-01 313

Amazon Elastic Compute Cloud API Reference Response Elements

Name
InstanceInitiatedShu tdownBehavior.Value

Description Changes the instance's InstanceInitiatedShutdownBehavior flag to the specified value. Type: String Default: None Valid Values: stop | terminate

Required No

BlockMappingDevice.V alue

Modifies the DeleteOnTermination atttribute for No volumes that are currently attached. The volume must be owned by the caller. If no value is specified for DeleteOnTerminaton, the value defaults to true and the volume will be deleted when the instance is terminated. Type: BlockDeviceMapping Default: None Example:
&BlockDeviceMapping1.DeviceName=/dev/sdh &BlockDeviceMapping.1.Ebs.DeleteOnTermina tion=true

SourceDestCheck.Valu e

This attribute exists to enable a Network Address No Translation (NAT) instance in a VPC to perform NAT. The attribute controls whether source/destination checking is enabled on the instance. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform NAT. For more information, go to NAT Instances in the Amazon Virtual Private Cloud User Guide. Type: Boolean Default: None This attribute is applicable only to instances running in a No VPC. Use this parameter when you want to change the security groups that an instance is in. The new set of groups you specify replaces the current set. You must specify at least one group, even if it's just the default security group in the VPC. You must specify the group ID and not the group name. For example, if you want the instance to be in sg-1a1a1a1a and sg-9b9b9b9b, specify GroupId.1=sg-1a1a1a1a and GroupId.2=sg-9b9b9b9b. Type: String Default: None

GroupId.n

Response Elements
The elements in the following table are wrapped in a ModifyInstanceAttributeResponse structure.

API Version 2012-05-01 314

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string Returns true if successful. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example changes the kernel for the instance.
https://ec2.amazonaws.com/?Action=ModifyInstanceAttribute &InstanceId=i-10a64379 &Kernel.Value=aki-f70657b2 &AUTHPARAMS

Example Response
<ModifyInstanceAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ModifyInstanceAttributeResponse>

Related Operations
ResetInstanceAttribute (p. 354) DescribeInstanceAttribute (p. 172)

API Version 2012-05-01 315

Amazon Elastic Compute Cloud API Reference ModifyNetworkInterfaceAttribute

ModifyNetworkInterfaceAttribute
Description
Modifies a network interface attribute. Only one attribute can be specified per call.

Request Parameters
Name
NetworkInterfaceId

Description The ID of the network interface. Type: String Default: None The description of the network interface. Type: String Default: None

Required Yes

Description.Value

No

SecurityGroupId.n

Use this parameter when you want to change the security No groups that a network interface is in. The new set of groups you specify replaces the current set. You must specify at least one group, even if it's just the default security group in the VPC. You must specify the group ID and not the group name. For example, if you want the instance to be in sg-1a1a1a1a and sg-9b9b9b9b, specify GroupId.1=sg-1a1a1a1a and GroupId.2=sg-9b9b9b9b. Type: String Default: None This attribute exists to enable a Network Address No Translation (NAT) instance in a VPC to perform NAT. The attribute controls whether source/destination checking is enabled on the instance. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform NAT. For more information, go to NAT Instances in the Amazon Virtual Private Cloud User Guide. Type: Boolean Default: None The ID of the interface attachment. This parameter is Conditional required if you are modifying the DeleteOnTermination attribute of an interface attachment. Type: String Default: None Whether to delete the attachment when terminating the instance. You must specify a specific attachment ID to change this attribute. Type: Boolean Default: None Conditional

SourceDestCheck.Valu e

Attachment.Attachmen tId

Attachment.DeleteOnT ermination

API Version 2012-05-01 316

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a ModifyNetworkInterfaceAttribute structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example sets source/destination checking to false for the elastic network interface (ENI) eni-ffda3197.
https://ec2.amazonaws.com/?Action=ModifyNetworkInterfaceAttribute &NetworkInterfaceId=eni-ffda3197 &SourceDestCheck.Value=false &AUTHPARAMS

Example Response
<ModifyNetworkInterfaceAttributeResponse xmlns='http://ec2.amazon aws.com/doc/2011-11-15/'> <requestId>657a4623-5620-4232-b03b-427e852d71cf</requestId> <return>true</return> </ModifyNetworkInterfaceAttributeResponse>

Related Operations
AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205) ResetNetworkInterfaceAttribute (p. 356)

API Version 2012-05-01 317

Amazon Elastic Compute Cloud API Reference ModifySnapshotAttribute

ModifySnapshotAttribute
Description
Adds or remove permission settings for the specified snapshot.

Note
Snapshots with AWS Marketplace product codes cannot be made public.

Request Parameters
Name
SnapshotId

Description The ID of the snapshot. Type: String Default: None

Required Yes

CreateVolumePermissi on.Add.n.UserId

Adds the specified AWS account ID to the volume's list of Yes create volume permissions. Type: String Default: None Adds the specified group to the volume's list of create volume permissions. The only valid value is all. Type: String Default: None Yes

CreateVolumePermissi on.Add.n.Group

CreateVolumePermissi on.Remove.n.UserId

Removes the specified AWS account ID from the volume's No list of create volume pernissions. Type: String Default: None Removes the specified group from the volume's list of create volume permissions. Type: String Default: None No

CreateVolumePermissi on.Remove.n.Group

Response Elements
The elements in the following table are wrapped in a ModifySnapshotAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if successful. Otherwise, returns an error. Type: xsd:boolean

return

API Version 2012-05-01 318

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example makes the snap-78a54011 snapshot public, and gives the account with ID 111122223333 permission to create volumes from the snapshot.
https://ec2.amazonaws.com/?Action=ModifySnapshotAttribute &snapshotId=snap-78a54011 &CreateVolumePermission.Add.1.UserId=111122223333 &CreateVolumePermission.Add.1.Group=all &AUTHPARAMS

This example makes the snap-78a54011 snapshot public, and removes the account with ID 111122223333 from the list of users with permission to create volumes from the snapshot.
https://ec2.amazonaws.com/?Action=ModifySnapshotAttribute &snapshotId=snap-78a54011 &CreateVolumePermission.Remove.1.UserId=111122223333 &CreateVolumePermission.Add.1.Group=all &AUTHPARAMS

Example Response
<ModifySnapshotAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ModifySnapshotAttributeResponse>

Related Operations
DescribeSnapshotAttribute (p. 233) DescribeSnapshots (p. 235) ResetSnapshotAttribute (p. 358) CreateSnapshot (p. 81)

API Version 2012-05-01 319

Amazon Elastic Compute Cloud API Reference ModifyVolumeAttribute

ModifyVolumeAttribute
Description
Modifies a volume attribute. By default, all I/O operations for the volume are suspended when the data on the volume is determined to be potentially inconsistent, to prevent undetectable, latent data corruption. The I/O access to the volume can be resumed by first calling EnableVolumeIO (p. 295) action to enable I/O access and then checking the data consistency on your volume. You can change the default behavior to resume I/O operations without calling EnableVolumeIO (p. 295) action by setting the AutoEnableIO attribute of the volume to true. We recommend that you change this attribute only for volumes that are stateless, or disposable, or for boot volumes.

Request Parameters
Name
VolumeId

Description The ID of the volume. Type: String Default: None This attribute exists to auto-enable the I/O operations to the volume. Type: AttributeBooleanValueType Default: false

Required Yes

AutoEnableIO.Value

Yes

Response Elements
The elements in the following table are wrapped in a ModifyVolumeAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the auto-enable of the specified volume is enabled. Type: xsd:boolean

return

Examples
Example Request
This example modifies the attribute of the volume vol-12345678
https://ec2.amazonaws.com/?Action=ModifyVolumeAttribute &VolumeId=vol-12345678

API Version 2012-05-01 320

Amazon Elastic Compute Cloud API Reference Related Operations

&AutoEnableIO.Value=true &AUTHPARAMS

Example Response
<ModifyVolumeAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>5jkdf074-37ed-4004-8671-a78ee82bf1cbEXAMPLE</requestId> <return>true</return> </ModifyVolumeAttributeResponse>

Related Operations
DescribeVolumeAttribute (p. 265) DescribeVolumeStatus (p. 267)

API Version 2012-05-01 321

Amazon Elastic Compute Cloud API Reference MonitorInstances

MonitorInstances
Description
Enables monitoring for a running instance. For more information about monitoring instances, go to Monitoring Your Instances and Volumes in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a MonitorInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of instances. Each instance's information is wrapped in an item element. Type: MonitorInstancesResponseSetItemType (p. 433)

instancesSet

Examples
Example Request
This example enables monitoring for i-43a4412a and i-23a3397d.
https://ec2.amazonaws.com/?Action=MonitorInstances &InstanceId.1=i-43a4412a &InstanceId.2=i-23a3397d &AUTHPARAMS

Example Response
<MonitorInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instancesSet> <item> <instanceId>i-43a4412a</instanceId> <monitoring>

API Version 2012-05-01 322

Amazon Elastic Compute Cloud API Reference Related Operations

<state>pending</state> </monitoring> </item> <item> <instanceId>i-23a3397d</instanceId> <monitoring> <state>pending</state> </monitoring> </item> </instancesSet> </MonitorInstancesResponse>

Related Operations
UnmonitorInstances (p. 382) RunInstances (p. 366)

API Version 2012-05-01 323

Amazon Elastic Compute Cloud API Reference PurchaseReservedInstancesOffering

PurchaseReservedInstancesOffering
Description
Purchases a Reserved Instance for use with your account. With Amazon EC2 Reserved Instances, you purchase the right to launch Amazon EC2 instances for a period of time (without getting insufficient capacity errors) and pay a lower usage rate for the actual time used. Starting with the 2011-11-01 API version, AWS expanded its offering of Amazon EC2 Reserved Instances to address a range of projected instance use. There are three types of Reserved Instances based on customer utilization levels: Heavy Utilization, Medium Utilization, and Light Utilization. You determine the type of the Reserved Instances offerings by including the optional offeringType parameter when calling DescribeReservedInstancesOfferings. After you've identified the Reserved Instance with the offering type you want, specify its ReservedInstancesOfferingId when you call PurchaseReservedInstancesOffering. The Medium Utilization offering type is equivalent to the Reserved Instance offering available before API version 2011-11-01. If you are using tools that predate the 2011-11-01 API version, DescribeReservedInstancesOfferings will only list information about the Medium Utilization Reserved Instance offering type. For more information about Reserved Instances, go to Reserved Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
ReservedInstancesOff eringId

Description

Required

ID of the Reserved Instance offering you want to purchase. Yes Type: String Default: None The number of Reserved Instances to purchase. Type: Integer Default: 1 No

InstanceCount

Response Elements
The elements in the following table are wrapped in a PurchaseReservedInstancesOfferingResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string The IDs of the purchased Reserved Instances. Type: xsd:string

reservedInstancesId

API Version 2012-05-01 324

Amazon Elastic Compute Cloud API Reference Examples

Examples
Example Request
This example illustrates a purchase of a Reserved Instances offering.
https://ec2.amazonaws.com/?Action=PurchaseReservedInstancesOffering &ReservedInstancesOfferingId=4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8 &InstanceCount=2 &AUTHPARAMS

Example Response
<PurchaseReservedInstancesOfferingResponse xmlns="http://ec2.amazon aws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <reservedInstancesId>af9f760e-c1c1-449b-8128-1342d3a6927a</reservedIn stancesId> </PurchaseReservedInstancesOfferingResponse>

Related Operations
DescribeReservedInstancesOfferings (p. 221) DescribeReservedInstances (p. 217)

API Version 2012-05-01 325

Amazon Elastic Compute Cloud API Reference RebootInstances

RebootInstances
Description
Requests a reboot of one or more instances. This operation is asynchronous; it only queues a request to reboot the specified instance(s). The operation will succeed if the instances are valid and belong to you. Requests to reboot terminated instances are ignored.

Note
If a Linux/UNIX instance does not cleanly shut down within four minutes, Amazon EC2 will perform a hard reboot.

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a RebootInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if successful. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example reboots two instances.
https://ec2.amazonaws.com/?Action=RebootInstances &InstanceId.1=i-1a2b3c4d &InstanceId.2=i-4d3acf62 &AUTHPARAMS

API Version 2012-05-01 326

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<RebootInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </RebootInstancesResponse>

Related Operations
RunInstances (p. 366)

API Version 2012-05-01 327

Amazon Elastic Compute Cloud API Reference RegisterImage

RegisterImage
Description
Registers a new AMI with Amazon EC2. When you're creating an AMI, this is the final step you must complete before you can launch an instance from the AMI. For more information about creating AMIs, go to Creating Your Own AMIs in the Amazon Elastic Compute Cloud User Guide.

Note
For Amazon EBS-backed instances, the CreateImage operation creates and registers the AMI in a single request, so you don't have to register the AMI yourself.

You can also use the RegisterImage action to create an EBS-backed AMI from a snapshot of a root device volume. For more information, go to Launching an Instance from a Snapshot in the Amazon Elastic Compute Cloud User Guide. If needed, you can deregister an AMI at any time. Any modifications you make to an AMI backed by Amazon S3 invalidates its registration. If you make changes to an image, deregister the previous image and register the new image.

Note
You cannot register an image where a secondary (non-root) snapshot has AWS Marketplace product codes.

Request Parameters
Name
ImageLocation

Description Full path to your AMI manifest in Amazon S3 storage. Type: String Default: None Condition: Required if registering an Amazon-S3 backed AMI

Required Conditional

Name

A name for your AMI. Yes Type: String Default: None Constraints: 3-128 alphanumeric characters, parenthesis (()), commas (,), slashes (/), dashes (-), or underscores(_) The description of the AMI. Type: String Default: None Constraints: Up to 255 characters. No

Description

API Version 2012-05-01 328

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
Architecture

Description

Required

The architecture of the image. No Type: String Valid Values: i386 | x86_64 Default: i386 for EBS backed AMIs. Instance store-backed AMIs will try to use the architecture specified in the manifest file. The ID of the kernel to select. Type: String Default: None No

KernelId

RamdiskId

The ID of the RAM disk to select. Some kernels require No additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, refer to the Resource Center and search for the kernel ID. Type: String Default: None The root device name (e.g., /dev/sda1, or xvda). Conditional Type: String Default: None Condition: Required if registering an Amazon EBS-backed AMI The device name (e.g., /dev/sdh, or xvdh). Conditional Type: String Default: None Condition: If registering an Amazon EBS-backed AMI from a snapshot, you must at least specify this field with the root device name (e.g., /dev/sda1, or xvda), and BlockDeviceMapping.n.Ebs.SnapshotId with the snapshot ID The virtual device name. Type: String Default: None No

RootDeviceName

BlockDeviceMapping.n .DeviceName

BlockDeviceMapping.n .VirtualName

BlockDeviceMapping.n .Ebs.SnapshotId

The ID of the snapshot. Conditional Type: String Default: None Condition: If registering an Amazon EBS-backed AMI from a snapshot, you must at least specify this field with the snapshot ID, and BlockDeviceMapping.n.DeviceName with the root device name The size of the volume, in GiBs. Conditional Type: Integer Default: None Condition: Required if you are not creating a volume from a snapshot.

BlockDeviceMapping.n .Ebs.VolumeSize

API Version 2012-05-01 329

Amazon Elastic Compute Cloud API Reference Response Elements

Name
BlockDeviceMapping.n .Ebs.NoDevice

Description Specifies that no device should be mapped. Type: Boolean Default: true

Required No

BlockDeviceMapping.n .Ebs.DeleteOnTermina tion

Whether the Amazon EBS volume is deleted on instance No termination. Type: Boolean Default: true

Response Elements
The elements in the following table are wrapped in a RegisterImageResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Unique ID of the newly registered machine image. Type: xsd:string

imageId

Examples
Example Request
This example registers the AMI specified in the my-new-image.manifest.xml manifest file, located in the bucket called myawsbucket.
https://ec2.amazonaws.com/?Action=RegisterImage &ImageLocation=myawsbucket/my-new-image.manifest.xml &AUTHPARAMS

Example Request
This example registers an Amazon EBS snapshot to create an AMI backed by Amazon EBS.
https://ec2.amazonaws.com/?Action=RegisterImage &RootDeviceName=/dev/sda1 &BlockDeviceMapping.1.DeviceName=/dev/sda1 &BlockDeviceMapping.1.Ebs.SnapshotId=snap-6eba6e06 &Name=MyImage &AUTHPARAMS

Example Request
This example registers the AMI with an Amazon EBS snapshot as the root device, a separate snapshot as a secondary device, and an empty 100 GiB Amazon EBS volume as a storage device.

API Version 2012-05-01 330

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=RegisterImage &RootDeviceName=/dev/sda1 &BlockDeviceMapping.1.DeviceName=/dev/sda1 &BlockDeviceMapping.1.Ebs.SnapshotId=snap-6eba6e06 &BlockDeviceMapping.2.DeviceName=/dev/sdb &BlockDeviceMapping.2.Ebs.SnapshotId=snap-823ea6df &BlockDeviceMapping.3.DeviceName=/dev/sdc &BlockDeviceMapping.3.Ebs.VolumeSize=100 &Name=MyImage &AUTHPARAMS

Example Response
<RegisterImageResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <imageId>ami-78a54043</imageId> </RegisterImageResponse>

Related Operations
DescribeImages (p. 164) DeregisterImage (p. 138)

API Version 2012-05-01 331

Amazon Elastic Compute Cloud API Reference ReleaseAddress

ReleaseAddress
Description
Releases an Elastic IP address allocated to your account. This action applies to both EC2 Elastic IP addresses and VPC Elastic IP addresses. For information about VPC addresses and how they differ from EC2 addresses, go to Elastic IP Addresses in the Amazon Virtual Private Cloud User Guide. If you run this action on an Elastic IP address that is already released, the address might be assigned to another account, which will cause Amazon EC2 to return an error (AuthFailure).

Note
For EC2 addresses only: Releasing an IP address automatically disassociates it from any instance it's associated with. To disassociate an IP address without releasing it, use the DisassociateAddress action. If you try to release a VPC address that's associated with an instance, Amazon EC2 returns an error (InvalidIPAddress.InUse).

Important
After releasing an Elastic IP address, it is released to the IP address pool and might be unavailable to your account. Make sure to update your DNS records and any servers or devices that communicate with the address.

Request Parameters
Name
PublicIp

Description The EC2 Elastic IP address to release. Type: String Default: None Condition: Required for EC2 Elastic IP addresses The allocation ID that AWS provided when you allocated the address for use with Amazon VPC. Type: String Default: None Condition: Required for VPC Elastic IP addresses

Required Conditional

AllocationId

Conditional

Response Elements
The elements in the following table are wrapped in a ReleaseAddressResponse structure.

API Version 2012-05-01 332

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string Returns true if successful. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example releases an EC2 Elastic IP address (67.202.55.255).
https://ec2.amazonaws.com/?Action=ReleaseAddress &PublicIp=192.0.2.1 &AUTHPARAMS

Example Request
This example releases a VPC Elastic IP address with allocation ID eipalloc-5723d13e.
https://ec2.amazonaws.com/?Action=ReleaseAddress &AllocationId=eipalloc-5723d13e &AUTHPARAMS

Example Response
<ReleaseAddressResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ReleaseAddressResponse>

Related Operations
AllocateAddress (p. 13) DescribeAddresses (p. 140) AssociateAddress (p. 15) DisassociateAddress (p. 291)

API Version 2012-05-01 333

Amazon Elastic Compute Cloud API Reference ReplaceNetworkAclAssociation

ReplaceNetworkAclAssociation
Description
Changes which network ACL a subnet is associated with. By default when you create a subnet, it's automatically associated with the default network ACL. For more information about network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
AssociationId

Description The ID representing the current association between the original network ACL and the subnet. Type: String Default: None The ID of the new ACL to associate with the subnet. Type: String Default: None

Required Yes

NetworkAclId

Yes

Response Elements
The elements in the following table are wrapped in a ReplaceNetworkAclAssociationResponse structure. Name
requestId

Description The ID of the request. Type: String The ID representing the new association. Type: String

newAssociationId

Examples
Example Request
This example starts with a network ACL associated with a subnet, and a corresponding association ID aclassoc-e5b95c8c. You want to associate a different network ACL (acl-5fb85d36) with the subnet. The result is a new association ID representing the new association.
https://ec2.amazonaws.com/?Action=ReplaceNetworkAclAssociation &AssociationId=aclassoc-e5b95c8c &NetworkAclId=acl-5fb85d36 &AUTHPARAMS

API Version 2012-05-01 334

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<ReplaceNetworkAclAssociationResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <newAssociationId>aclassoc-17b85d7e</newAssociationId> </ReplaceNetworkAclAssociationResponse>

Related Operations
CreateNetworkAcl (p. 65) DeleteNetworkAcl (p. 108) DescribeNetworkAcls (p. 198)

API Version 2012-05-01 335

Amazon Elastic Compute Cloud API Reference ReplaceNetworkAclEntry

ReplaceNetworkAclEntry
Description
Replaces an entry (i.e., rule) in a network ACL. For more information about network ACLs, go to Network ACLs in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
NetworkAclId

Description ID of the ACL where the entry will be replaced. Type: String Default: None Rule number of the entry to replace. Type: Integer Default: None

Required Yes

RuleNumber

Yes

Protocol

IP protocol the rule applies to.You can use -1 to mean Yes all protocols. Type: Integer Valid Values: -1 or a protocol number (go to Protocol Numbers). Whether to allow or deny traffic that matches the rule. Yes Type: String Default: None Valid Values: allow | deny Whether this rule applies to egress traffic from the No subnet (true) or ingress traffic to the subnet (false). Type: Boolean Default: false Valid Values: true | false The CIDR range to allow or deny, in CIDR notation (e.g., 172.16.0.0/24). Type: String Default: None Yes

RuleAction

Egress

CidrBlock

Icmp.Code

For the ICMP protocol, the ICMP code. You can use Conditional -1 to specify all ICMP codes for the given ICMP type. Type: Integer Default: None Condition: Required if specifying 1 (ICMP) for the protocol.

API Version 2012-05-01 336

Amazon Elastic Compute Cloud API Reference Response Elements

Name
Icmp.Type

Description For the ICMP protocol, the ICMP type. You can use -1 to specify all ICMP types. Type: Integer Default: None Condition: Required if specifying 1 (ICMP) for the protocol.

Required Conditional

PortRange.From

The first port in the range. Conditional Type: Integer Default: None Condition: Required if specifying 6 (TCP) or 17 (UDP) for the protocol. The last port in the range. Conditional Type: Integer Default: None Condition: Required if specifying 6 (TCP) or 17 (UDP) for the protocol.

PortRange.To

Response Elements
The elements in the following table are wrapped in a ReplaceNetworkAclEntryResponse structure. Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example replaces the egress entry numbered 110 in the network ACL with ID acl-2cb85d45. The new rule denies egress traffic destined for anywhere (0.0.0.0/0) on TCP port 139.
https://ec2.amazonaws.com/?Action=ReplaceNetworkAclEntry &NetworkAclId=acl-2cb85d45 &RuleNumber=110 &Protocol=tcp &RuleAction=deny &Egress=true &CidrBlock=0.0.0.0/0 &PortRange.From=139 &PortRange.To=139 &AUTHPARAMS

API Version 2012-05-01 337

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<ReplaceNetworkAclEntryResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ReplaceNetworkAclEntryResponse>

Related Operations
CreateNetworkAclEntry (p. 67) DeleteNetworkAclEntry (p. 110) DescribeNetworkAcls (p. 198)

API Version 2012-05-01 338

Amazon Elastic Compute Cloud API Reference ReplaceRoute

ReplaceRoute
Description
Replaces an existing route within a route table in a VPC. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
RouteTableId

Description The ID of the route table where the route will be replaced. Type: String Default: None

Required Yes

DestinationCidrBlock

The CIDR address block used for the Yes destination match. For example: 0.0.0.0/0. The value you provide must match the CIDR of an existing route in the table. Type: String Default: None The ID of a gateway attached to your VPC. Type: String Default: None Condition: You must provide only one of the following: a GatewayID, InstanceID, or NetworkInterfaceId. The ID of a NAT instance in your VPC. Type: String Default: None Condition: You must provide only one of the following: a GatewayID, InstanceID, or NetworkInterfaceId. Conditional

GatewayId

InstanceId

Conditional

NetworkInterfaceId

Allow routing to network interface attachments. Conditional Type: String Default: None Condition: You must provide only one of the following: GatewayId, InstanceId, or NetworkInterfaceId.

Response Elements
The elements in the following table are wrapped in a ReplaceRouteResponse structure.

API Version 2012-05-01 339

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: String Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example replaces a route in the route table with ID rtb-e4ad488d. The new route matches the CIDR 10.0.0.0/8 and sends the traffic to the virtual private gateway with ID vgw-1d00376e.
https://ec2.amazonaws.com/?Action=ReplaceRoute &RouteTableId=rtb-e4ad488d &DestinationCidrBlock=10.0.0.0/8 &GatewayId=vgw-1d00376e &AUTHPARAMS

Example Response
<ReplaceRouteResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ReplaceRouteResponse>

Related Operations
DeleteRoute (p. 116) CreateRoute (p. 74) DescribeRouteTables (p. 225)

API Version 2012-05-01 340

Amazon Elastic Compute Cloud API Reference ReplaceRouteTableAssociation

ReplaceRouteTableAssociation
Description
Changes the route table associated with a given subnet in a VPC. After you execute this action, the subnet uses the routes in the new route table it's associated with. For more information about route tables, go to Route Tables in the Amazon Virtual Private Cloud User Guide. You can also use this action to change which table is the main route table in the VPC. You just specify the main route table's association ID and the route table that you want to be the new main route table.

Request Parameters
Name
AssociationId

Description The ID representing the current association between the original route table and the subnet. Type: String Default: None

Required Yes

RouteTableId

The ID of the new route table to associate with Yes the subnet. Type: String Default: None

Response Elements
The elements in the following table are wrapped in a ReplaceRouteTableAssociationResponse structure. Name
requestId

Description The ID of the request. Type: String The ID representing the new association. Type: String

newAssociationId

Examples
Example Request
This example starts with a route table associated with a subnet, and a corresponding association ID rtbassoc-f8ad4891. You want to associate a different route table (table rtb-f9ad4890) to the subnet. The result is a new association ID representing the new association.

API Version 2012-05-01 341

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=ReplaceRouteTableAssociation &AssociationId=rtbassoc-f8ad4891 &RouteTableId=rtb-f9ad4890 &AUTHPARAMS

Example Response
<ReplaceRouteTableAssociationResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <newAssociationId>rtbassoc-faad4893</newAssociationId> </ReplaceRouteTableAssociationResponse>

Related Operations
CreateRouteTable (p. 77) DisassociateRouteTable (p. 293) DeleteRouteTable (p. 118) DescribeRouteTables (p. 225) AssociateRouteTable (p. 20)

API Version 2012-05-01 342

Amazon Elastic Compute Cloud API Reference ReportInstanceStatus

ReportInstanceStatus
Description
Use this action to submit feedback about an instance's status. This action works only for instances that are in the running state. If your experience with the instance differs from the instance status returned by the DescribeInstanceStatus action, use ReportInstanceStatus to report your experience with the instance. Amazon EC2 collects this information to improve the accuracy of status checks.

Note
Use of this action does not change the value returned by DescribeInstanceStatus.

To report an instance's status, specify an instance ID with the InstanceID.n parameter and a reason code with the ReasonCodes.n parameter that applies to that instance. The following table contains descriptions of all available reason codes. Reason Code instance-stuck-in-state unresponsive not-accepting-credentials password-not-available performance-network performance-instance-store performance-ebs-volume performance-other other Description My instance is stuck in a state. My instance is unresponsive. My instance is not accepting my credentials. A password is not available for my instance. My instance is experiencing performance problems which I believe are network related. My instance is experiencing performance problems which I believe are related to the instance stores. My instance is experiencing performance problems which I believe are related to an EBS volume. My instance is experiencing performance problems. Other, explained in the submitted description parameter.

Request Parameters
Name
InstanceID.n

Description One or more instance IDs. Type: String The status of all instances listed in the InstanceID.n parameter. Type: String Valid Values: ok | impaired

Required Yes

Status

Yes

StartTime

The time at which the reported instance health state began. No Type: DateTime

API Version 2012-05-01 343

Amazon Elastic Compute Cloud API Reference Response Elements

Name
EndTime

Description

Required

The time at which the reported instance health state ended. No Type: DateTime A reason code that describes a specific instance's health Yes state. Each code you supply corresponds to an instance ID that you supply with the InstanceID.n parameter. See the Description (p. 343) section for descriptions of each reason code. Type: String Valid Values: instance-stuck-in-state | unresponsive | not-accepting-credentials | password-not-available | performance-network | performance-instance-store | performance-ebs-volume | performance-other | other Descriptive text about the instance health state. Type: String Default: None No

ReasonCodes.n

Description

Response Elements
The elements in the following table are wrapped in a ReportInstanceStatusResponse structure. Name
requestId

Description The ID of the request. Type: String Whether the values submitted were accepted by Amazon EC2. Type: Boolean

Return

Examples
Example Request
This example reports instance health state for two instances.
https://ec2.amazonaws.com/?Action=ReportInstanceStatus &Status=impaired &InstanceId.0=i-9440effb &InstanceId.1=i-0cf27c63 &Version=2012-05-01 &AuthParams

Example Request
This example reports instance health state for two instances with reason codes.

API Version 2012-05-01 344

Amazon Elastic Compute Cloud API Reference Examples

https://ec2.amazonaws.com/?Action=ReportInstanceStatus &Description=Description+of+my+issue. &Status=impaired &InstanceId.0=i-9440effb &InstanceId.1=i-0cf27c63 &ReasonCode.0=instance-performance-network &ReasonCode.1=instance-performance-disk &Version=2012-05-01 &AuthParams

Example Response
<ReportInstanceStatusResponse xmlns='http://ec2.amazonaws.com/doc/2011-10-01/'> <requestId>b8131cff-dfbd-4277-bafe-be006fd0c4da</requestId> <return>true</return> </ReportInstanceStatusResponse>

API Version 2012-05-01 345

Amazon Elastic Compute Cloud API Reference RequestSpotInstances

RequestSpotInstances
Description
Creates a Spot Instance request. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current Spot Instance requests. For more information about Spot Instances, go to Using Spot Instances in the Amazon Elastic Compute Cloud User Guide.

Note
Users must be subscribed to the required product to run an instance with AWS Marketplace product codes.

Request Parameters
Name
SpotPrice

Description

Required

The maximum hourly price for any Spot Instance launched Yes to fulfill the request. Type: String Default: None The maximum number of Spot Instances to launch. Type: xs:integer Default: 1 The Spot Instance request type. Type: String Valid Values: one-time | persistent Default: one-time No

InstanceCount

Type

No

ValidFrom

Start date of the request. If this is a one-time request, the No request becomes active at this date and time and remains active until all instances launch, the request expires, or the request is canceled. If the request is persistent, the request becomes active at this date and time and remains active until it expires or is canceled. Type: DateTime Default: Request is effective independently End date of the request. If this is a one-time request, the No request remains active until all instances launch, the request is canceled, or this date is reached. If the request is persistent, it remains active until it is canceled or this date and time is reached. Type: DateTime Default: Request is effective indefinitely

ValidUntil

API Version 2012-05-01 346

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
Subnet

Description

Required

The ID of the Amazon VPC subnet in which to launch the No Spot Instance. Type: String Default: None The instance launch group. Launch groups are Spot No Instances that launch together and terminate together. Type: String Default: Instances are launched and terminated individually The user-specified name for a logical grouping of bids. No When you specify AvailabilityZoneGroup in a Spot Instance request, all Spot Instances in the request are launched in the same Availability Zone. Instance proximity is maintained with this parameter, but choice of Availability Zone is not. AvailabilityZoneGroup applies only to bids for Spot Instances of the same instance type. Any additional Spot Instance requests that are specified with the same AvailabilityZoneGroup name will be launched in that same Availability Zone, as long as at least one instance from the group is still active. If there is no active instance running in the Availability Zone group that you specify for a new Spot Instance request (i.e., all instances are terminated, the bid is expired, or the bid falls below current market), then Amazon EC2 will launch the instance in any Availability Zone where the constraint can be met. Consequently, the subsequent set of Spot Instances could be placed in a different zone from the original request, even if the same AvailabilityZoneGroup name was specified. To ensure that all Spot Instances across all bids are launched into a particular Availability Zone, specify LaunchSpecification.Placement.AvailabilityZone in the API or availability-zone in the CLI. Type: String Default: Instances are launched in any available Availability Zone. The name of an existing placement group you want to launch the instance into (for cluster instances). Type: String Default: None. The AMI ID. Type: String Default: None The name of the key pair. Type: String Default: None No

LaunchGroup

AvailabilityZoneGrou p

Placement.GroupName

LaunchSpecification. ImageId

Yes

LaunchSpecification. KeyName

No

API Version 2012-05-01 347

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
LaunchSpecification. SecurityGroupId.n

Description

Required

ID of the security group.You can use either this parameter Conditional or the next to specify a security group. You can use this parameter when launching instances with or without Amazon VPC. Type: String Default: The instance uses the default security group Condition: If you want to specify one or more security groups, you can use either LaunchSpecification.SecurityGroupId.n or LaunchSpecification.SecurityGroup.n . Name of the security group.You cannot use this parameter Conditional when launching an instance with Amazon VPC. Type: String Default: The instance uses the default security group Condition: If you want to specify one or more security groups, you can use either LaunchSpecification.SecurityGroupId.n or LaunchSpecification.SecurityGroup.n . MIME, Base64-encoded user data to make available to the instances. Type: String Default: None Deprecated. Type: String Default: None The instance type. Type: String Valid Values: m1.small | m1.large | m1.xlarge | c1.medium | c1.xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge | t1.micro Default: m1.small No

LaunchSpecification. SecurityGroup.n

LaunchSpecification. UserData

LaunchSpecification. AddressingType

No

LaunchSpecification. InstanceType

Yes

LaunchSpecification. Placement.Availabili tyZone

The placement constraint (i.e., specific Availability Zone) No for launching the instances. Specify if you want all of the Spot Instances in all of your bids to be launched in a particular Availability Zone. Specifying this option requires Amazon EC2 to find capacity in the specified Availability Zone instead of letting Amazon EC2 pick the best Availability Zone available; this can potentially delay the fulfillment of your bid, and/or require a higher bid price. Type: String Default: Amazon EC2 selects an Availability Zone.

API Version 2012-05-01 348

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
LaunchSpecification. KernelId

Description The ID of the kernel to select. Type: String Default: None

Required No

LaunchSpecification. RamdiskId

The ID of the RAM disk to select. Some kernels require No additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk and search for the kernel ID. Type: String Default: None Describes the mapping that defines native device names No to use when exposing virtual devices. Type: String Default: None The virtual device name. Type: String Default: None The ID of the snapshot. Type: String Default: None The size of the volume, in GiBs. Required if you are not creating a volume from a snapshot. Type: Integer Default: None Specifies that no device should be mapped. Type: Boolean Default: true No

LaunchSpecification. BlockDeviceMapping.n .DeviceName

LaunchSpecification. BlockDeviceMapping.n .VirtualName LaunchSpecification. BlockDeviceMapping.n .Ebs.SnapshotId LaunchSpecification. BlockDeviceMapping.n .Ebs.VolumeSize

No

No

LaunchSpecification. BlockDeviceMapping.n .Ebs.NoDevice LaunchSpecification. BlockDeviceMapping.n .Ebs.DeleteOnTermina tion LaunchSpecification. Monitoring.Enabled

No

Whether the Amazon EBS volume is deleted on instance No termination. Type: Boolean Default: true Enables monitoring for the instance. Type: String Default: Disabled Attaches an existing interface to a single instance. Requires n=1 instances. Type: String Default: Applies to both attaching existing network interfaces and when creating new network interfaces. Type: Integer Default: No

LaunchSpecification. NetworkInterface.n.N etworkInterfaceId

No

LaunchSpecification. NetworkInterface.n.D eviceIndex

No

API Version 2012-05-01 349

Amazon Elastic Compute Cloud API Reference Response Elements

Name
LaunchSpecification. NetworkInterface.n.S ubnetId LaunchSpecification. NetworkInterface.n.D escription LaunchSpecification. NetworkInterface.n.P rivateIpAddress

Description Applies only when creating new network interfaces. Type: String Default: Applies only when creating new network interfaces. Type: String Default: Applies only when creating new network interfaces. Requires n=1 network interfaces in launch. Type: String Default:

Required No

No

No

LaunchSpecification. NetworkInterface.n.S ecurityGroupId.n

Security group IDs to associate with the created instance. No Applies only when creating new network interfaces. Type: String Default: Applies to all network interfaces. Type: Boolean Default: No

LaunchSpecification. NetworkInterface.n.D eleteOnTermination

Response Elements
The elements in the following table are wrapped in a RequestSpotInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Information about the Spot Instance request, wrapped in an item element. Type: SpotInstanceRequestSetItemType (p. 454) The ID of the network interface. Type: InstanceNetworkInterfaceSetRequestType (p. 423)

spotInstanceRequestSet

networkInterfaceId

Examples
Example Request
This example creates a Spot Instances request for two m1.small instances.
https://ec2.amazonaws.com/?Action=RequestSpotInstances &SpotPrice=0.50 &InstanceCount=2 &Type=one-time

API Version 2012-05-01 350

Amazon Elastic Compute Cloud API Reference Related Operations

&AvailabilityZoneGroup=MyAzGroup &LaunchSpecification.ImageId=ami-43a4412a &LaunchSpecification.KeyName=MyKeypair &LaunchSpecification.Group.1=websrv &LaunchSpecification.InstanceType=m1.small &AUTHPARAMS

Example Response
<RequestSpotInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <spotInstanceRequestSet> <item> <spotInstanceRequestId>sir-83d64e02</spotInstanceRequestId> <spotPrice>0.5</spotPrice> <type>one-time</type> <state>open</state> <availabilityZoneGroup>MyAzGroup</availabilityZoneGroup> <launchSpecification> <imageId>ami-43a4412a</imageId> <keyName>MyKeypair</keyName> <groupSet> <item> <groupId>websrv</groupId> </item> </groupSet> <instanceType>m1.small</instanceType> <blockDeviceMapping/> <monitoring> <enabled>false</enabled> </monitoring> </launchSpecification> <createTime>2010-10-20T18:23:41.000Z</createTime> <productDescription>Linux/UNIX</productDescription> </item> <item> ... </item> </spotInstanceRequestSet> </RequestSpotInstancesResponse>

Related Operations
DescribeSpotInstanceRequests (p. 242) CancelSpotInstanceRequests (p. 47) DescribeSpotPriceHistory (p. 248)

API Version 2012-05-01 351

Amazon Elastic Compute Cloud API Reference ResetImageAttribute

ResetImageAttribute
Description
Resets an attribute of an AMI to its default value.

Note
The productCodes attribute cannot be reset.

Request Parameters
Name
ImageId

Description ID of the AMI. Type: String Default: None

Required Yes

Attribute

Attribute to reset (currently you can only reset the launch Yes permission attribute). Type: String Default: None Valid Value: launchPermission

Response Elements
The elements in the following table are wrapped in a ResetImageAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example resets the launchPermission attribute for the specified AMI.
https://ec2.amazonaws.com/?Action=ResetImageAttribute &ImageId=ami-61a54008 &Attribute=launchPermission &AUTHPARAMS

API Version 2012-05-01 352

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<ResetImageAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ResetImageAttributeResponse>

Related Operations
ModifyImageAttribute (p. 310) DescribeImageAttribute (p. 161)

API Version 2012-05-01 353

Amazon Elastic Compute Cloud API Reference ResetInstanceAttribute

ResetInstanceAttribute
Description
Resets an attribute of an instance to its default value. To reset the kernel or RAM disk, the instance must be in a stopped state. To reset the SourceDestCheck, the instance can be either running or stopped. The SourceDestCheck attribute exists to enable a Network Address Translation (NAT) instance in a VPC to perform NAT. The attribute controls whether source/destination checking is enabled on the instance. The default value is true, which means checking is enabled. The value must be false for the instance to perform NAT. For more information, go to NAT Instances in the Amazon Virtual Private Cloud User Guide.

Request Parameters
Name
InstanceId

Description ID of the instance. Type: String Default: None Attribute to reset. Type: String Default: None Valid Values: kernel | ramdisk | sourceDestCheck

Required Yes

Attribute

Yes

Response Elements
The elements in the following table are wrapped in a ResetInstanceAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example resets the kernel attribute.
https://ec2.amazonaws.com/?Action=ResetInstanceAttribute &InstanceId=i-10a64379 &Attribute=kernel &AUTHPARAMS

API Version 2012-05-01 354

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<ResetInstanceAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ResetInstanceAttributeResponse>

Related Operations
ModifyInstanceAttribute (p. 313) DescribeInstanceAttribute (p. 172)

API Version 2012-05-01 355

Amazon Elastic Compute Cloud API Reference ResetNetworkInterfaceAttribute

ResetNetworkInterfaceAttribute
Description
Resets a network interface attribute. Only one attribute can be specified per call.

Request Parameters
Name
NetworkInterfaceId

Description

Required

The ID of the network interface with the attributes that you Yes want to reset. Type: String Default: None The name of the attribute to reset, sourceDestCheck defaults to true. Type: String Default: None Yes

Attribute=[sourceDes tCheck]

Response Elements
The elements in the following table are wrapped in a ResetNetworkInterfaceAttribute structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example resets the sourceDestCheck attribute for the elastic network interface (ENI) eni-ffda3197.
https://ec2.amazonaws.com/?Action=ResetNetworkInterfaceAttribute&NetworkInter faceId=eni-ffda3197&Attribute=sourceDestCheck&AUTHPARAMS

Example Response
<ResetNetworkInterfaceAttributeResponse xmlns='http://ec2.amazonaws.com/doc/201111-15/'> <requestId>5187642e-3f16-44a3-b05f-24c3848b5162</requestId>

API Version 2012-05-01 356

Amazon Elastic Compute Cloud API Reference Related Operations

<return>true</return> </ResetNetworkInterfaceAttributeResponse>

Related Operations
AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaceAttribute (p. 203) DescribeNetworkInterfaces (p. 205) ModifyNetworkInterfaceAttribute (p. 316)

API Version 2012-05-01 357

Amazon Elastic Compute Cloud API Reference ResetSnapshotAttribute

ResetSnapshotAttribute
Description
Resets permission settings for the specified snapshot.

Request Parameters
Name
SnapshotId

Description The ID of the snapshot. Type: String Default: None

Required Yes

Attribute

Attribute to reset (currently only the attribute for permission Yes to create volumes can be reset) Type: String Default: None Valid Value: createVolumePermission

Response Elements
The elements in the following table are wrapped in a ResetSnapshotAttributeResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example resets the permissions for snap-78a54011, making it a private snapshot that can only be used by the account that created it.
https://ec2.amazonaws.com/?Action=ResetSnapshotAttribute &SnapshotId=snap-78a54011 &Attribute=createVolumePermission &AUTHPARAMS

API Version 2012-05-01 358

Amazon Elastic Compute Cloud API Reference Related Operations

Example Response
<ResetSnapshotAttributeResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </ResetSnapshotAttributeResponse>

Related Operations
ModifySnapshotAttribute (p. 318) DescribeSnapshotAttribute (p. 233) DescribeSnapshots (p. 235) CreateSnapshot (p. 81)

API Version 2012-05-01 359

Amazon Elastic Compute Cloud API Reference RevokeSecurityGroupEgress

RevokeSecurityGroupEgress
Description
This action applies only to security groups in a VPC. It doesn't work with EC2 security groups. For information about Amazon Virtual Private Cloud and VPC security groups, go to Security Groups in the Amazon Virtual Private Cloud User Guide. The action removes one or more egress rules from a VPC security group. The values that you specify in the revoke request (e.g., ports, etc.) must match the existing rule's values for the rule to be revoked. Each rule consists of the protocol and the CIDR range or destination security group. For the TCP and UDP protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must also specify the ICMP type and code. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.

Request Parameters
Name
GroupId

Description ID of the VPC security group to modify. Type: String Default: None

Required Yes

IpPermissions.n.IpPr otocol

IP protocol name or number (go to Protocol Numbers). Yes When you call DescribeSecurityGroups, the protocol value returned is the number. Exception: For TCP, UDP, and ICMP, the value returned is the name (e.g., tcp, udp, or icmp). Type: String Valid Values: tcp | udp | icmp or any protocol number (go to Protocol Numbers). Use -1 to specify all. Start of port range for the TCP and UDP protocols, or an ICMP type number. For the ICMP type number, you can use -1 to specify all ICMP types. Type: Integer Default: None Condition: Required for ICMP and any protocol that uses ports Conditional

IpPermissions.n.From Port

IpPermissions.n.ToPo rt

End of port range for the TCP and UDP protocols, or an Conditional ICMP code number. For the ICMP code number, you can use -1 to specify all ICMP codes for the given ICMP type. Type: Integer Default: None Condition: Required for ICMP and any protocol that uses ports

API Version 2012-05-01 360

Amazon Elastic Compute Cloud API Reference Response Elements

Name
IpPermissions.n.Grou ps.m.GroupId

Description Name of the destination security group. Cannot be used when specifying a CIDR IP address. Type: String Default: None Condition: Required if modifying access for one or more destination security groups.

Required Conditional

IpPermissions.n.IpRa nges.m.CidrIp

CIDR range. Cannot be used when specifying a destination Conditional security group. Type: String Default: None Constraints: Valid CIDR IP address range. Condition: Required if modifying access for one or more IP address ranges.

Response Elements
The elements in the following table are wrapped in a RevokeSecurityGroupEgressResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example revokes the access that the websrv VPC security group (with ID sg-1a2b3c4d) has to the 205.192.0.0/16 and 205.159.0.0/16 address ranges on TCP port 80.
https://ec2.amazonaws.com/?Action=RevokeSecurityGroupEgress &GroupName=websrv &GroupName=sg-1a2b3c4d &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=80 &IpPermissions.1.ToPort=80 &IpPermissions.1.IpRanges.1.CidrIp=205.192.0.0/16 &IpPermissions.1.IpRanges.2.CidrIp=205.159.0.0/16 &AUTHPARAMS

Example Request
This example revokes the access that the VPC security group with ID sg-1a2b3c4d has to the VPC security group with ID sg-9a8d7f5c on TCP port 1433.
API Version 2012-05-01 361

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=RevokeSecurityGroupEgress &GroupId=sg-1a2b3c4d &IpPermissions.1.IpProtocol=tcp &IpPermissions.1.FromPort=1433 &IpPermissions.1.ToPort=1433 &IpPermissions.1.Groups.1.GroupId=sg-9a8d7f5c &AUTHPARAMS

Example Response
<RevokeSecurityGroupEgressResponse xmlns="http://ec2.amazonaws.com/doc/2012-0501/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </RevokeSecurityGroupEgressResponse>

Related Operations
CreateSecurityGroup (p. 79) DescribeSecurityGroups (p. 229) AuthorizeSecurityGroupEgress (p. 31) AuthorizeSecurityGroupIngress (p. 34) AuthorizeSecurityGroupIngress (p. 363) DeleteSecurityGroup (p. 120)

API Version 2012-05-01 362

Amazon Elastic Compute Cloud API Reference RevokeSecurityGroupIngress

RevokeSecurityGroupIngress
Description
This action applies to both EC2 security groups and VPC security groups. For information about VPC security groups and how they differ from EC2 security groups, go to Security Groups in the Amazon Virtual Private Cloud User Guide. This action removes one or more ingress rules from a security group. The values that you specify in the revoke request (e.g., ports, etc.) must match the existing rule's values for the rule to be removed. Each rule consists of the protocol and the CIDR range or source security group. For the TCP and UDP protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must also specify the ICMP type and code. Rule changes are propagated to instances within the security group as quickly as possible. However, depending on the number of instances, a small delay might occur.

Request Parameters
Name
UserId GroupId

Description Deprecated

Required No

ID of the EC2 or VPC security group to modify. The group Conditional must belong to your account. Type: String Default: None Condition: Required for VPC security groups; can be used instead of GroupName for EC2 security groups Name of the EC2 security group to modify. Type: String Default: None Condition: Can be used instead of GroupId for EC2 security groups Conditional

GroupName

IpPermissions.n.IpPr otocol

IP protocol name or number (go to Protocol Numbers). Required EC2 security groups can have rules only for TCP, UDP, and ICMP, whereas VPC security groups can have rules assigned to any protocol number. When you call DescribeSecurityGroups, the protocol value returned is the number. Exception: For TCP, UDP, and ICMP, the value returned is the name (e.g., tcp, udp, or icmp). Type: String Valid Values for EC2 security groups: tcp | udp | icmp or the corresponding protocol number (6 | 17 | 1). Valid Values for VPC groups: tcp | udp | icmp or any protocol number (go to Protocol Numbers). Use -1 to specify all.

API Version 2012-05-01 363

Amazon Elastic Compute Cloud API Reference Response Elements

Name
IpPermissions.n.From Port

Description Start of port range for the TCP and UDP protocols, or an ICMP type number. For the ICMP type number, you can use -1 to specify all ICMP types. Type: Integer Default: None Default: Required for ICMP and any protocol that uses ports

Required Conditional

IpPermissions.n.ToPo rt

End of port range for the TCP and UDP protocols, or an Conditional ICMP code number. For the ICMP code number, you can use -1 to specify all ICMP codes for the given ICMP type. Type: Integer Default: None Default: Required for ICMP and any protocol that uses ports AWS account ID that owns the source security group. Conditional Cannot be used when specifying a CIDR IP address. Type: String Default: None Condition: For EC2 security groups only. Required if modifying access for one or more source security groups. Name of the source security group. Cannot be used when Conditional specifying a CIDR IP address. Type: String Default: None Condition: Required if modifying access for one or more source security groups. ID of the source security group. Cannot be used when Conditional specifying a CIDR IP address. Type: String Default: None Condition: For VPC security groups only. Required if modifying access for one or more source security groups. CIDR range. Cannot be used when specifying a source security group. Type: String Default: None Constraints: Valid CIDR IP address range. Condition: Required if modifying access for one or more IP address ranges. Conditional

IpPermissions.n.Grou ps.m.UserId

IpPermissions.n.Grou ps.m.GroupName

IpPermissions.n.Grou ps.m.GroupId

IpPermissions.n.IpRa nges.m.CidrIp

Response Elements
The elements in the following table are wrapped in a RevokeSecurityGroupIngressResponse structure.

API Version 2012-05-01 364

Amazon Elastic Compute Cloud API Reference Examples

Name
requestId

Description The ID of the request. Type: xsd:string Returns true if the request succeeds. Otherwise, returns an error. Type: xsd:boolean

return

Examples
Example Request
This example revokes TCP port 80 access from the 205.192.0.0/16 address range for the websrv security group. Note that if the security group were a VPC security group, the ID of the security group would instead be required in the request.
https://ec2.amazonaws.com/?Action=RevokeSecurityGroupIngress &GroupName=websrv &IpProtocol=tcp &FromPort=80 &ToPort=80 &CidrIp=205.192.0.0/16 &AUTHPARAMS

Example Response
<RevokeSecurityGroupIngressResponse xmlns="http://ec2.amazonaws.com/doc/201205-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </RevokeSecurityGroupIngressResponse>

Related Operations
CreateSecurityGroup (p. 79) DescribeSecurityGroups (p. 229) AuthorizeSecurityGroupIngress (p. 34) DeleteSecurityGroup (p. 120)

API Version 2012-05-01 365

Amazon Elastic Compute Cloud API Reference RunInstances

RunInstances
Description
Launches a specified number of instances of an AMI for which you have permissions. If Amazon EC2 cannot launch the minimum number of instances you request, no instances will be launched. If there is insufficient capacity to launch the maximum number of instances you request, Amazon EC2 launches the minimum number specified and allocates the remaining available instances using round robin.

Note
Every instance is launched in a security group (created using the CreateSecurityGroup operation). If you don't specify a security group in the RunInstances request, the "default" security group is used.

For Linux instances, you can provide an optional key pair ID in the launch request (created using the CreateKeyPair or ImportKeyPair operation). The instances will have access to the public key at boot. You can use this key to provide secure access to an instance of an image on a per-instance basis. Amazon EC2 public images use this feature to provide secure access without passwords.

Important
Launching public images without a key pair ID will leave them inaccessible.

The public key material is made available to the instance at boot time by placing it in the openssh_id.pub file on a logical device that is exposed to the instance as /dev/sda2 (the instance store). The format of this file is suitable for use as an entry within ~/.ssh/authorized_keys (the OpenSSH format). This can be done at boot (e.g., as part of rc.local) allowing for secure access without passwords. You can provide optional user data in the launch request. All instances that collectively comprise the launch request have access to this data. For more information, go to Instance Metadata in the Amazon Elastic Compute Cloud User Guide.

Note
If any of the AMIs have a product code attached for which the user has not subscribed, the RunInstances call will fail.

Request Parameters
Name
ImageId

Description ID of the AMI you want to launch. Type: String Default: None

Required Yes

API Version 2012-05-01 366

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
MinCount

Description

Required

Minimum number of instances to launch. If the value is Yes more than Amazon EC2 can launch, no instances are launched at all. Type: Integer Default: None Constraints: Between 1 and the maximum number allowed for your account (default: 20). Maximum number of instances to launch. If the value is Yes more than Amazon EC2 can launch, the largest possible number above MinCount will be launched instead. Type: Integer Default: None Constraints: Between 1 and the maximum number allowed for your account (default: 20). The name of the key pair to use. Type: String Default: None One or more security group IDs. Type: String Default: None Condition: Required for VPC security groups; optional for EC2 security groups One or more security group names. Type: String Default: None Condition: Valid only for EC2 security groups; for EC2 groups either a group ID or a group name is accepted No

MaxCount

KeyName

SecurityGroupId.n

Conditional

SecurityGroup.n

Conditional

UserData

Base64-encoded MIME user data to be made available to No the instance(s) in this reservation. Type: String Default: None This parameter is deprecated. Type: String Default: None The instance type. Type: String Valid Values: m1.small | m1.medium | m1.large | m1.xlarge | c1.medium | c1.xlarge | m2.xlarge | m2.2xlarge | m2.4xlarge | cc1.4xlarge | cg1.4xlarge | cc2.8xlarge | t1.micro Default: m1.small No

AddressingType

InstanceType

No

API Version 2012-05-01 367

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
Placement.Availabili tyZone

Description

Required

The Availability Zone you want to launch the instance into. No Type: xsd:string Default: EC2 chooses a zone for you The name of an existing placement group you want to launch the instance into (for cluster instances). Type: xsd:string Default: None The tenancy of the instance you want to launch. An instance with a tenancy of dedicated runs on single-tenant hardware and can only be launched into a VPC. Type: xsd:string Default: default The ID of the kernel with which to launch the instance. Type: String Default: None No

Placement.GroupName

Placement.Tenancy

No

KernelId

No

RamdiskId

The ID of the RAM disk to select. Some kernels require No additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk. To find kernel requirements, refer to the Resource Center and search for the kernel ID. Type: String Default: None The device name (e.g., /dev/sdh, or xvdh). The device can No be mapped to an EBS volume, a virtual device, or to nothing. If you are using this device to map an EBS volume, follow this with the EBS volume specific parameters. For information about block device mapping, go to Block Device Mapping in the Amazon Elastic Compute Cloud User Guide. Type: String Default: None Specifies that no device should be mapped.This parameter No takes an empty string as input. Type: Empty String Default: None The virtual device name (e.g., /ephemeral0, /ephemeral1 No etc). The count following ephemeral goes up based on your instance type. For a small image, it has an ephemeral0 (ext3, 15GB) and an ephemeral1 (swap, 1GB). For information about block device mapping, go to Block Device Mapping in the Amazon Elastic Compute Cloud User Guide. Type: String Default: None

BlockDeviceMapping.n .DeviceName

BlockDeviceMapping.n .NoDevice

BlockDeviceMapping.n .VirtualName

API Version 2012-05-01 368

Amazon Elastic Compute Cloud API Reference Request Parameters

Name
BlockDeviceMapping.n .Ebs.SnapshotId

Description The ID of the snapshot. Type: String Default: None The size of the volume, in GiBs. Required if you are not creating a volume from a snapshot. Type: Integer Default: None

Required No

BlockDeviceMapping.n .Ebs.VolumeSize

No

BlockDeviceMapping.n .Ebs.DeleteOnTermina tion

Whether the Amazon EBS volume is deleted on instance No termination. Type: Boolean Default: true Enables monitoring for the instance. Type: Boolean Default: false No

Monitoring.Enabled

SubnetId

If you're using Amazon Virtual Private Cloud, this specifies No the ID of the subnet you want to launch the instance into. Type: String Default: None Specifies whether you can terminate the instance using No the EC2 API. A value of true means you can't terminate the instance using the API (i.e., the instance is "locked"); a value of false means you can. If you set this to true, and you later want to terminate the instance, you must first change the disableApiTermination attribute's value to false using ModifyInstanceAttribute. Type: Boolean Default: false Determines whether the instance stops or terminates on instance-initiated shutdown. Type: String Valid Values: stop | terminate Default: stop If you're using Amazon Virtual Private Cloud, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (e.g., 10.0.0.25). Type: String Default: Amazon VPC selects an IP address from the subnet for the instance No

DisableApiTerminatio n

InstanceInitiatedShu tdownBehavior

PrivateIpAddress

No

API Version 2012-05-01 369

Amazon Elastic Compute Cloud API Reference Response Elements

Name
ClientToken

Description Unique, case-sensitive identifier you provide to ensure idempotency of the request. For more information, go to How to Ensure Idempotency in the Amazon Elastic Compute Cloud User Guide. Type: String Default: None Constraints: Maximum 64 ASCII characters Attaches an existing interface to a single instance. Requires n=1 instances. Type: String Default: Applies to both attaching existing network interfaces and when creating new network interfaces. Type: Integer Default: Applies only when creating new network interfaces. Type: String Default: Applies only when creating new network interfaces. Type: String Default: Applies only when creating new network interfaces. Requires n=1 network interfaces in launch. Type: String Default: Applies only when creating new network interfaces. Type: String Default: Applies to all network interfaces. Type: Boolean Default:

Required No

NetworkInterface.n.N etworkInterfaceId

No

NetworkInterface.n.D eviceIndex

No

NetworkInterface.n.S ubnetId

No

NetworkInterface.n.D escription

No

NetworkInterface.n.P rivateIpAddress

No

NetworkInterface.n.S ecurityGroupId.n

No

NetworkInterface.n.D eleteOnTermination

No

Response Elements
The elements in the following table are wrapped in a RunInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string

API Version 2012-05-01 370

Amazon Elastic Compute Cloud API Reference Examples

Name
reservationId

Description Unique ID of the reservation. Type: xsd:string ID of the AWS account that owns the reservation. Type: xsd:string List of security groups the instance belongs to. Each group's information is wrapped in an item element. Type: GroupItemType (p. 410) A list of instances. Each instance's information is wrapped in an item element. Type: RunningInstancesItemType (p. 448) ID of the requester that launched the instances on your behalf (e.g., AWS Management Console, Auto Scaling). Type: xsd:string

ownerId

groupSet

instancesSet

requesterId

Examples
Example Request
This example launches three instances of the ami-60a54009 AMI.
https://ec2.amazonaws.com/?Action=RunInstances &ImageId=ami-60a54009 &MaxCount=3 &MinCount=1 &Placement.AvailabilityZone=us-east-1b &Monitoring.Enabled=true &AUTHPARAMS

Example Response
<RunInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <reservationId>r-47a5402e</reservationId> <ownerId>111122223333</ownerId> <groupSet> <item> <groupId>sg-245f6a01</groupId> <groupName>default</groupName> </item> </groupSet> <instancesSet> <item> <instanceId>i-2ba64342</instanceId> <imageId>ami-60a54009</imageId> <instanceState> <code>0</code>

API Version 2012-05-01 371

Amazon Elastic Compute Cloud API Reference Examples

<name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <keyName>example-key-name</keyName> <amiLaunchIndex>0</amiLaunchIndex> <instanceType>m1.small</instanceType> <launchTime>2007-08-07T11:51:50.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> </placement> <monitoring> <enabled>true</enabled> </monitoring> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-245f6a01</groupId> <groupName>default</groupName> </item> </groupSet> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <tagSet/> <hypervisor>xen</hypervisor> </item> <item> <instanceId>i-2bc64242</instanceId> <imageId>ami-60a54009</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <keyName>example-key-name</keyName> <amiLaunchIndex>1</amiLaunchIndex> <instanceType>m1.small</instanceType> <launchTime>2007-08-07T11:51:50.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> </placement> <monitoring> <enabled>true</enabled> </monitoring> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-245f6a01</groupId> <groupName>default</groupName> </item> </groupSet> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <tagSet/> <hypervisor>xen</hypervisor> <item> <instanceId>i-2be64332</instanceId>

API Version 2012-05-01 372

Amazon Elastic Compute Cloud API Reference Examples

<imageId>ami-60a54009</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName></privateDnsName> <dnsName></dnsName> <keyName>example-key-name</keyName> <amiLaunchIndex>2</amiLaunchIndex> <instanceType>m1.small</instanceType> <launchTime>2007-08-07T11:51:50.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> </placement> <monitoring> <enabled>true</enabled> </monitoring> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-245f6a01</groupId> <groupName>default</groupName> </item> </groupSet> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <tagSet/> <hypervisor>xen</hypervisor> </item> </instancesSet> </RunInstancesResponse>

Example Request
This example launches an instance of the ami-31814f58 AMI and attaches an elastic network interface to it.
https://ec2.amazonaws.com/?Action=RunInstances ImageId=ami-31814f58 &InstanceType=m1.small &MaxCount=1 &MinCount=1 &Monitoring.Enabled=false &SubnetId=subnet-b2a249da &AUTHPARAMS

Example Response
<RunInstancesResponse xmlns='http://ec2.amazonaws.com/doc/2011-11-15/'> <requestId>e86ff3c8-2400-45e3-a4e7-f158a69283d4</requestId> <reservationId>r-157ad274</reservationId> <ownerId>111122223333</ownerId> <groupSet/> <instancesSet> <item>

API Version 2012-05-01 373

Amazon Elastic Compute Cloud API Reference Examples

<instanceId>i-0ee0356c</instanceId> <imageId>ami-31814f58</imageId> <instanceState> <code>0</code> <name>pending</name> </instanceState> <privateDnsName/> <dnsName/> <reason/> <amiLaunchIndex>0</amiLaunchIndex> <productCodes/> <instanceType>m1.small</instanceType> <launchTime>2011-12-20T08:29:31.000Z</launchTime> <placement> <availabilityZone>us-east-1b</availabilityZone> <groupName/> <tenancy>default</tenancy> </placement> <kernelId>aki-805ea7e9</kernelId> <monitoring> <state>disabled</state> </monitoring> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <privateIpAddress>10.0.0.142</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item> </groupSet> <stateReason> <code>pending</code> <message>pending</message> </stateReason> <architecture>i386</architecture> <rootDeviceType>ebs</rootDeviceType> <rootDeviceName>/dev/sda1</rootDeviceName> <blockDeviceMapping/> <virtualizationType>paravirtual</virtualizationType> <clientToken/> <hypervisor>xen</hypervisor> <networkInterfaceSet> <item> <networkInterfaceId>eni-c6bb50ae</networkInterfaceId> <subnetId>subnet-b2a249da</subnetId> <vpcId>vpc-1ea24976</vpcId> <description/> <ownerId>111122223333</ownerId> <status>in-use</status> <privateIpAddress>10.0.0.142</privateIpAddress> <sourceDestCheck>true</sourceDestCheck> <groupSet> <item> <groupId>sg-050c1369</groupId> <groupName>default</groupName> </item>

API Version 2012-05-01 374

Amazon Elastic Compute Cloud API Reference Examples

</groupSet> <attachment> <attachmentId>eni-attach-0326646a</attachmentId> <deviceIndex>0</deviceIndex> <status>attaching</status> <attachTime>2011-12-20T08:29:31.000Z</attachTime> <deleteOnTermination>true</deleteOnTermination> </attachment> </item> </networkInterfaceSet> </item> </instancesSet> </RunInstancesResponse>

Related Operations
DescribeInstances (p. 175) StopInstances (p. 378) StartInstances (p. 376) TerminateInstances (p. 380) AuthorizeSecurityGroupIngress (p. 34) RevokeSecurityGroupIngress (p. 363) DescribeSecurityGroups (p. 229) CreateSecurityGroup (p. 79) CreateKeyPair (p. 63) ImportKeyPair (p. 305)

API Version 2012-05-01 375

Amazon Elastic Compute Cloud API Reference StartInstances

StartInstances
Description
Starts an Amazon EBS-backed AMI that you've previously stopped. Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When an instance is stopped, the compute resources are released and you are not billed for hourly instance usage. However, your root partition Amazon EBS volume remains, continues to persist your data, and you are charged for Amazon EBS volume usage. You can restart your instance at any time. Each time you transition an instance from stopped to started, we charge a full instance hour, even if transitions happen multiple times within a single hour.

Note
Before stopping an instance, make sure it is in a state from which it can be restarted. Stopping an instance does not preserve data stored in RAM. Performing this operation on an instance that uses an instance store as its root device returns an error.

For more information, go to Using Amazon EBS-Backed AMIs and Instances.

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a StartInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of instance state changes. Each change's information is wrapped in an item element. Type: InstanceStateChangeType (p. 425)

instancesSet

Examples
Example Request
This example starts the i-10a64379 instance.

API Version 2012-05-01 376

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=StartInstances &InstanceId.1=i-10a64379 &AUTHPARAMS

Example Response
<StartInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instancesSet> <item> <instanceId>i-10a64379</instanceId> <currentState> <code>0</code> <name>pending</name> </currentState> <previousState> <code>80</code> <name>stopped</name> </previousState> </item> </instancesSet> </StartInstancesResponse>

Related Operations
StopInstances (p. 378) RunInstances (p. 366) DescribeInstances (p. 175) TerminateInstances (p. 380)

API Version 2012-05-01 377

Amazon Elastic Compute Cloud API Reference StopInstances

StopInstances
Description
Stops an Amazon EBS-backed instance. Each time you transition an instance from stopped to started, we charge a full instance hour, even if transitions happen multiple times within a single hour.

Important
Although Spot Instances can use Amazon EBS-backed AMIs, they don't support Stop/Start. In other words, you can't stop and start Spot Instances launched from an AMI with an Amazon EBS root device.

Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started. When an instance is stopped, the compute resources are released and you are not billed for hourly instance usage. However, your root partition Amazon EBS volume remains, continues to persist your data, and you are charged for Amazon EBS volume usage. You can restart your instance at any time.

Note
Before stopping an instance, make sure it is in a state from which it can be restarted. Stopping an instance does not preserve data stored in RAM. Performing this operation on an instance that uses an instance store as its root device returns an error.

You can stop, start, and terminate EBS-backed instances. You can only terminate S3-backed instances. What happens to an instance differs if you stop it or terminate it. For example, when you stop an instance, the root device and any other devices attached to the instance persist. When you terminate an instance, the root device and any other devices attached during the instance launch are automatically deleted. For more information about the differences between stopping and terminating instances, go to the "Stop/Start" and "Instance Termination" in Basics of Amazon EBS-Backed AMIS and Instances in the Amazon EC2 User Guide.

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: None

Required Yes

Force

Forces the instance to stop. The instance will not have an No opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures. This option is not recommended for Windows instances. Type: Boolean Default: False

API Version 2012-05-01 378

Amazon Elastic Compute Cloud API Reference Response Elements

Response Elements
The elements in the following table are wrapped in a StopInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of instance state changes. Each change's information is wrapped in an item element. Type: InstanceStateChangeType (p. 425)

instancesSet

Examples
Example Request
This example stops the i-10a64379 instance without using the "force" option.
https://ec2.amazonaws.com/?Action=StopInstances &InstanceId.1=i-10a64379 &AUTHPARAMS

Example Response
<StopInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instancesSet> <item> <instanceId>i-10a64379</instanceId> <currentState> <code>64</code> <name>stopping</name> </currentState> <previousState> <code>16</code> <name>running</name> </previousState> </instancesSet> </StopInstancesResponse>

Related Operations
StartInstances (p. 376) RunInstances (p. 366) DescribeInstances (p. 175) TerminateInstances (p. 380)

API Version 2012-05-01 379

Amazon Elastic Compute Cloud API Reference TerminateInstances

TerminateInstances
Description
Shuts down one or more instances. This operation is idempotent; if you terminate an instance more than once, each call will succeed. Terminated instances will remain visible after termination (approximately one hour).

Note
By default, Amazon EC2 deletes all Amazon EBS volumes that were attached when the instance launched. Amazon EBS volumes attached after instance launch continue running.

You can stop, start, and terminate EBS-backed instances. You can only terminate S3-backed instances. What happens to an instance differs if you stop it or terminate it. For example, when you stop an instance, the root device and any other devices attached to the instance persist. When you terminate an instance, the root device and any other devices attached during the instance launch are automatically deleted. For more information about the differences between stopping and terminating instances, go to the "Stop/Start" and "Instance Termination" in Basics of Amazon EBS-Backed AMIS and Instances in the Amazon EC2 User Guide.

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in a TerminateInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of instance state changes. Each change's information is wrapped in an item element. Type: InstanceStateChangeType (p. 425)

instancesSet

Examples
Example Request
This example terminates the i-3ea74257 instance.

API Version 2012-05-01 380

Amazon Elastic Compute Cloud API Reference Related Operations

https://ec2.amazonaws.com/?Action=TerminateInstances &InstanceId.1=i-3ea74257 &AUTHPARAMS

Example Response
<TerminateInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instancesSet> <item> <instanceId>i-3ea74257</instanceId> <currentState> <code>32</code> <name>shutting-down</name> </currentState> <previousState> <code>16</code> <name>running</name> </previousState> </item> </instancesSet> </TerminateInstancesResponse>

Related Operations
DescribeInstances (p. 175) RunInstances (p. 366) StopInstances (p. 378) StartInstances (p. 376)

API Version 2012-05-01 381

Amazon Elastic Compute Cloud API Reference UnmonitorInstances

UnmonitorInstances
Description
Disables monitoring for a running instance. For more information about monitoring instances, go to Monitoring Your Instances and Volumes in the Amazon Elastic Compute Cloud User Guide.

Request Parameters
Name
InstanceId.n

Description One or more instance IDs. Type: String Default: None

Required Yes

Response Elements
The elements in the following table are wrapped in an UnmonitorInstancesResponse structure. Name
requestId

Description The ID of the request. Type: xsd:string List of monitoring information for one or more instances. Each set of information is wrapped in an item element. Type: MonitorInstancesResponseSetItemType (p. 433)

instancesSet

Examples
Example Request
This example disables monitoring for i-43a4412a and i-23a3397d.
https://ec2.amazonaws.com/?Action=UnmonitorInstances &InstanceId.1=i-43a4412a &InstanceId.2=i-23a3397d &AUTHPARAMS

Example Response
<UnmonitorInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2012-05-01/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <instancesSet> <item> <instanceId>i-43a4412a</instanceId> <monitoring>

API Version 2012-05-01 382

Amazon Elastic Compute Cloud API Reference Related Operations

<state>disabled</state> </monitoring> </item> <item> <instanceId>i-23a3397d</instanceId> <monitoring> <state>disabled</state> </monitoring> </item> </instancesSet> </UnmonitorInstancesResponse>

Related Operations
MonitorInstances (p. 322) RunInstances (p. 366)

API Version 2012-05-01 383

Amazon Elastic Compute Cloud API Reference

Data Types
Topics AttachmentSetItemResponseType (p. 386) AttachmentType (p. 387) AvailabilityZoneItemType (p. 388) AvailabilityZoneMessageType (p. 388) BlockDeviceMappingItemType (p. 389) BundleInstanceS3StorageType (p. 390) BundleInstanceTaskErrorType (p. 391) BundleInstanceTaskStorageType (p. 391) BundleInstanceTaskType (p. 392) CancelSpotInstanceRequestsResponseSetItemType (p. 393) ConversionTaskType (p. 393) CreateVolumePermissionItemType (p. 394) CustomerGatewayType (p. 395) DescribeAddressesResponseItemType (p. 396) DescribeImagesResponseItemType (p. 397) DescribeKeyPairsResponseItemType (p. 399) DescribeReservedInstancesOfferingsResponseSetItemType (p. 399) DescribeReservedInstancesResponseSetItemType (p. 400) DescribeSnapshotsSetItemResponseType (p. 402) DescribeVolumesSetItemResponseType (p. 403) DhcpConfigurationItemType (p. 404) DhcpOptionsType (p. 404)

DhcpValueType (p. 405) DiskImageDescriptionType (p. 406) DiskImageVolumeDescriptionType (p. 406) EbsBlockDeviceType (p. 407) EbsInstanceBlockDeviceMappingResponseType (p. 408) ExportTaskResponseType (p. 409) ExportToS3TaskResponseType (p. 410) GroupItemType (p. 410)

API Version 2012-05-01 384

Amazon Elastic Compute Cloud API Reference

IcmpTypeCodeType (p. 411) ImportInstanceTaskDetailsType (p. 412) ImportInstanceVolumeDetailItemType (p. 412) ImportVolumeTaskDetailsType (p. 413) InstanceBlockDeviceMappingItemType (p. 414) InstanceBlockDeviceMappingResponseItemType (p. 415) InstanceEbsBlockDeviceType (p. 415) InstanceExportTaskResponseType (p. 416) InstanceStatusEventsSetType (p. 417) InstanceStatusEventType (p. 417) InstanceStatusItemType (p. 418) InstanceStatusSetType (p. 419) InstanceStatusDetailsSetType (p. 419) InstanceStatusType (p. 420) InstanceMonitoringStateType (p. 420) InstanceNetworkInterfaceSetItemRequestType (p. 421) InstanceNetworkInterfaceSetItemType (p. 422) InstanceNetworkInterfaceSetRequestType (p. 423) InstanceNetworkInterfaceSetType (p. 423) InstanceStateChangeType (p. 425) InstanceStateType (p. 425) InternetGatewayAttachmentType (p. 426) InternetGatewayType (p. 427) IpPermissionType (p. 428) IpRangeItemType (p. 429) LaunchPermissionItemType (p. 429) LaunchSpecificationRequestType (p. 430) LaunchSpecificationResponseType (p. 431) MonitoringInstanceType (p. 432) MonitorInstancesResponseSetItemType (p. 433) NetworkAclEntryType (p. 433) NetworkAclType (p. 434)

NetworkAclAssociationType (p. 435) NetworkInterfaceAssociationType (p. 436) NetworkInterfaceSet (p. 437) NetworkInterfaceAttachmentType (p. 438) NetworkInterfaceType (p. 438) PlacementGroupInfoType (p. 439) PlacementRequestType (p. 440) PlacementResponseType (p. 440) PortRangeType (p. 441) ProductCodeItemType (p. 442) ProductCodesSetItemType (p. 442) ProductDescriptionSetItemType (p. 443) RecurringChargesSetItemType (p. 443) RegionItemType (p. 444)

API Version 2012-05-01 385

Amazon Elastic Compute Cloud API Reference AttachmentSetItemResponseType

ReservationInfoType (p. 444) ResourceTagSetItemType (p. 445) RouteTableAssociationType (p. 446) RouteTableType (p. 447) RouteType (p. 447) RunningInstancesItemType (p. 448) SecurityGroupIdSetItemType (p. 451) SecurityGroupItemType (p. 452) SpotDatafeedSubscriptionType (p. 453) SpotInstanceRequestSetItemType (p. 454) SpotInstanceStateFaultType (p. 455) SpotPriceHistorySetItemType (p. 456) StateReasonType (p. 457) SubnetType (p. 458) TagSetItemType (p. 459) UserDataType (p. 459) UserIdGroupPairType (p. 460) ValueType (p. 461) VolumeStatusItemType (p. 461) VolumeStatusInfoType (p. 462) VolumeStatusDetailsItemType (p. 463) VolumeStatusEventItemType (p. 463) VolumeStatusActionItemType (p. 464) VpcType (p. 465) VpnConnectionType (p. 466) VpnGatewayType (p. 467) VpnTunnelTelemetryType (p. 468)

AttachmentSetItemResponseType
The AttachmentSetItemResponseType data type.

Ancestors
AttachmentSetResponseType

Relevant Operations
DescribeVolumes

Contents
The following table describes the elements contained in AttachmentSetItemResponseType.

API Version 2012-05-01 386

Amazon Elastic Compute Cloud API Reference AttachmentType

Name
volumeId

Description The ID of the volume. Type: xsd:string The ID of the instance. Type: xsd:string How the device is exposed to the instance (e.g., /dev/sdh). Type: xsd:string Attachment state. Type: xsd:string Valid Values: attaching | attached | detaching | detached Time stamp when the attachment initiated. Type: xsd:dateTime Whether the Amazon EBS volume is deleted on instance termination. Type: xsd:boolean

instanceId

device

status

attachTime

deleteOnTermination

AttachmentType
The AttachmentType data type.

Ancestors
AttachmentSetType AttachVpnGatewayResponse

Relevant Operations
CreateVpnGateway DescribeVpnGateways AttachVpnGateway

Contents
The following table describes the elements contained in AttachmentType. Name
vpcId

Description The ID of the VPC the virtual private gateway is attached to. Type: String

API Version 2012-05-01 387

Amazon Elastic Compute Cloud API Reference AvailabilityZoneItemType

Name
state

Description The current state of the attachment. Type: String Valid Values: attaching | attached | detaching | detached

AvailabilityZoneItemType
The AvailabilityZoneItemType data type.

Ancestors
AvailabilityZoneSetType

Relevant Operations
DescribeAvailabilityZones

Contents
The following table describes the elements contained in AvailabilityZoneItemType. Name
zoneName

Description Name of the Availability Zone. Type: xsd:string State of the Availability Zone. Type: xsd:string Name of the Region. Type: xsd:string A list of messages about the Availability Zone. Each message is wrapped in an item element. Type: AvailabilityZoneMessageType (p. 388)

zoneState

regionName

messageSet

AvailabilityZoneMessageType
The AvailabilityZoneMessageType data type.

Ancestors
AvailabilityZoneMessageSetType

API Version 2012-05-01 388

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
DescribeAvailabilityZones

Contents
The following table describes the elements contained in AvailabilityZoneMessageType. Name
message

Description The Availability Zone message. Type: xsd:string

BlockDeviceMappingItemType
The BlockDeviceMappingItemType data type.

Ancestors
BlockDeviceMappingType

Relevant Operations
DescribeImageAttribute DescribeImages RequestSpotInstances DescribeSpotInstanceRequests RequestSpotInstances RegisterImage RunInstances

Contents
The following table describes the elements contained in BlockDeviceMappingItemType. Name
deviceName

Description The device name (e.g., /dev/sdh). Type: xsd:string The virtual device name. Type: xsd:string

virtualName

API Version 2012-05-01 389

Amazon Elastic Compute Cloud API Reference BundleInstanceS3StorageType

Name
ebs

Description Parameters used to automatically set up Amazon EBS volumes when the instance is launched. Type: EbsBlockDeviceType (p. 407) Include this empty element to indicate that you want to suppress the specified device from the mapping.

noDevice

BundleInstanceS3StorageType
The BundleInstanceS3StorageType data type.

Ancestors
BundleInstanceTaskStorageType (p. 391)

Relevant Operations
BundleInstance DescribeBundleTasks CancelBundleTask BundleInstance

Contents
The following table describes the elements contained in BundleInstanceS3StorageType. Name
awsAccessKeyId

Description The Access Key ID of the owner of the Amazon S3 bucket. Type: xsd:string The bucket in which to store the AMI. You can specify a bucket that you already own or a new bucket that Amazon EC2 creates on your behalf. If you specify a bucket that belongs to someone else, Amazon EC2 returns an error. Type: xsd:string The beginning of the file name of the AMI. Type: xsd:string A Base64-encoded Amazon S3 upload policy that gives Amazon EC2 permission to upload items into Amazon S3 on the user's behalf. Type: xsd:string The signature of the Base64 encoded JSON document. Type: xsd:string

bucket

prefix

uploadPolicy

uploadPolicySignature

API Version 2012-05-01 390

Amazon Elastic Compute Cloud API Reference BundleInstanceTaskErrorType

BundleInstanceTaskErrorType
The BundleInstanceTaskErrorType data type.

Ancestors
BundleInstanceTaskType (p. 392)

Relevant Operations
BundleInstance DescribeBundleTasks CancelBundleTask

Contents
The following table describes the elements contained in BundleInstanceTaskErrorType. Name
code

Description Error code. Type: xsd:string Error message. Type: xsd:string

message

BundleInstanceTaskStorageType
The BundleInstanceTaskStorageType data type.

Ancestors
BundleInstanceTaskType (p. 392) BundleInstanceType

Relevant Operations
BundleInstance DescribeBundleTasks CancelBundleTask BundleInstance

API Version 2012-05-01 391

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in BundleInstanceTaskStorageType. Name
S3

Description Amazon S3 storage location. Type: BundleInstanceS3StorageType (p. 390)

BundleInstanceTaskType
The BundleInstanceTaskType data type.

Ancestors
BundleInstanceResponseType BundleInstanceTasksSetType CancelBundleTaskResponseType

Relevant Operations
BundleInstance DescribeBundleTasks CancelBundleTask

Contents
The following table describes the elements contained in BundleInstanceTaskType. Name
instanceId

Description Instance associated with this bundle task. Type: xsd:string Identifier for this task. Type: xsd:string The state of the task. Type: xsd:string Valid Values: pending | waiting-for-shutdown | bundling | storing | cancelling | complete | failed The time this task started. Type: xsd:dateTime The time of the most recent update for the task. Type: xsd:dateTime

bundleId

state

startTime

updateTime

API Version 2012-05-01 392

Amazon Elastic Compute Cloud API Reference CancelSpotInstanceRequestsResponseSetItemType

Name
storage

Description Amazon S3 storage locations. Type: BundleInstanceTaskStorageType (p. 391) The level of task completion, in percent (e.g., 20%). Type: xsd:string If the task fails, a description of the error. Type: BundleInstanceTaskErrorType (p. 391)

progress

error

CancelSpotInstanceRequestsResponseSetItemType
The CancelSpotInstanceRequestsResponseSetItemType data type.

Ancestors
CancelSpotInstanceRequestsResponseSetType

Relevant Operations
CancelSpotInstanceRequests

Contents
The following table describes the elements contained in CancelSpotInstanceRequestsResponseSetItemType. Name
spotInstanceRequestId

Description The ID of the Spot Instance request. Type: xsd:string The state of the Spot Instance request. Type: xsd:string Valid Values: active | open | closed | cancelled | failed

state

ConversionTaskType
The ConversionTaskType data type.

Ancestors
ConversionTaskSetType ImportInstanceResponse ImportVolumeResponse
API Version 2012-05-01 393

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
DescribeConversionTasks ImportInstance ImportVolume

Contents
The following table describes the elements contained in ConversionTaskType. Name
conversionTaskId

Description ID of the conversion task Type: xs:string When the task expires. If the upload isn't complete before the expiration time, we automatically cancel the task. Type: xs:string If the task is for importing a volume, this contains information about the import volume task. Type: ImportVolumeTaskDetailsType (p. 413) If the task is for importing an instance, this contains information about the import instance task. Type: ImportInstanceTaskDetailsType (p. 412) State of the conversion task. Type: xs:string Valid Values: active | cancelling | cancelled | completed Status message related to the conversion task. Type: xs:string

expirationTime

importVolume

importInstance

state

statusMessage

CreateVolumePermissionItemType
The CreateVolumePermissionItemType data type.

Ancestors
CreateVolumePermissionListType

Relevant Operations
ModifySnapshotAttribute DescribeSnapshotAttribute

API Version 2012-05-01 394

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in CreateVolumePermissionItemType. Name
userId

Description ID of an AWS account that can create volumes from the snapshot. Type: xsd:string Group that is allowed to create volumes from the snapshot. Type: xsd:string Valid Value: all

group

CustomerGatewayType
The CustomerGatewayType data type.

Ancestors
CreateCustomerGatewayResponse CustomerGatewaySetType

Relevant Operations
CreateCustomerGateway DescribeCustomerGateways

Contents
The following table describes the elements contained in CustomerGatewayType. Name
customerGatewayId

Description The ID of the customer gateway. Type: String The current state of the customer gateway. Type: String Valid Values: pending | available | deleting | deleted The type of VPN connection the customer gateway supports (ipsec.1). Type: String The Internet-routable IP address of the customer gateway's outside interface. Type: String

state

type

ipAddress

API Version 2012-05-01 395

Amazon Elastic Compute Cloud API Reference DescribeAddressesResponseItemType

Name
bgpAsn

Description The customer gateway's Border Gateway Protocol (BGP) Autonomous System Number (ASN). Type: Integer Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

tagSet

DescribeAddressesResponseItemType
The DescribeAddressesResponseItemType data type.

Ancestors
DescribeAddressesResponseInfoType

Relevant Operations
DescribeAddresses

Contents
The following table describes the elements contained in DescribeAddressesResponseItemType. Name
publicIp

Description The public IP address. Type: xsd:string The ID representing the allocation of the address for use with Amazon VPC. Type: xsd:string Whether this Elastic IP address is for EC2 instances (i.e., standard) or VPC instances. Type: xsd:string Valid Values: standard | vpc The ID of the instance the address is associated with (if any). Type: xsd:string The ID representing the association of a VPC Elastic IP address with an instance in a VPC. Type: xsd:string The ID of the network interface. Type: xsd:string

allocationId

domain

instanceId

associationId

networkInterfaceId

API Version 2012-05-01 396

Amazon Elastic Compute Cloud API Reference DescribeImagesResponseItemType

Name
networkInterfaceOwnerId

Description The ID of the AWS account that owns the network interface. Type: xsd:string

DescribeImagesResponseItemType
The DescribeImagesResponseItemType data type.

Ancestors
DescribeImagesResponseInfoType

Relevant Operations
DescribeImages

Contents
The following table describes the elements contained in DescribeImagesResponseItemType. Name
imageId

Description The ID of the AMI. Type: xsd:string The location of the AMI. Type: xsd:string Current state of the AMI. If the operation returns available, the image is successfully registered and available for launching. Type: xsd:string available | pending | failed AWS account ID of the image owner. Type: xsd:string Returns true if this image has public launch permissions. Returns false if it only has implicit and explicit launch permissions. Type: xsd:boolean Product codes associated with the AMI. Each code's information is wrapped in an item element. Type: ProductCodesSetItemType (p. 442) The architecture of the image. Type: xsd:string

imageLocation

imageState

imageOwnerId

isPublic

productCodes

architecture

API Version 2012-05-01 397

Amazon Elastic Compute Cloud API Reference Contents

Name
imageType

Description The type of image (machine, kernel, or RAM disk). Type: xsd:string The kernel associated with the image, if any. Only applicable for machine images. Type: xsd:string The RAM disk associated with the image, if any. Only applicable for machine images. Type: xsd:string Value is Windows for Windows AMIs; otherwise blank. Type: xsd:string The reason for the state change. See StateReasonType (p. 457) for a list of supported state change codes. Type: StateReasonType (p. 457) The AWS account alias (e.g., amazon, self, etc.) or AWS account ID that owns the AMI. Type: xsd:string The name of the AMI that was provided during image creation. Type: xsd:string The description of the AMI that was provided during image creation. Type: xsd:string The root device type used by the AMI. The AMI can use an Amazon EBS or instance store root device. Type: xsd:string Valid Values: ebs | instance-store The root device name (e.g., /dev/sda1, or xvda). Type: xsd:string A list of block device mappings for the image. Each mapping's information is wrapped in an item element. Type: BlockDeviceMappingItemType (p. 389) The type of virtualization of the AMI. Type: xsd:string Valid Values: paravirtual | hvm Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445) The image's hypervisor type. Type: xsd:string Valid Values: ovm | xen

kernelId

ramdiskId

platform

stateReason

imageOwnerAlias

name

description

rootDeviceType

rootDeviceName

blockDeviceMapping

virtualizationType

tagSet

hypervisor

API Version 2012-05-01 398

Amazon Elastic Compute Cloud API Reference DescribeKeyPairsResponseItemType

DescribeKeyPairsResponseItemType
The DescribeKeyPairsResponseItemType data type.

Ancestors
DescribeKeyPairsResponseInfoType

Relevant Operations
DescribeKeyPairs

Contents
The following table describes the elements contained in DescribeKeyPairsResponseItemType. Name
keyName

Description Name of the key pair. Type: xsd:string If you used CreateKeyPair to create the key pair, this is the SHA-1 digest of the DER encoded private key. If you used ImportKeyPair to provide AWS the public key, this is the MD5 public key fingerprint as specified in section 4 of RFC4716. Type: xsd:string

keyFingerprint

DescribeReservedInstancesOfferingsResponseSetItemType
The DescribeReservedInstancesOfferingsResponseSetItemType data type.

Ancestors
DescribeReservedInstancesOfferingsResponseSetType

Relevant Operations
DescribeReservedInstancesOfferings

Contents
The following table describes the elements contained in DescribeReservedInstancesOfferingsResponseSetItemType.

API Version 2012-05-01 399

Amazon Elastic Compute Cloud API Reference DescribeReservedInstancesResponseSetItemType

Name
reservedInstancesOff eringId instanceType

Description The ID of the Reserved Instance offering. Type: xsd:string The instance type on which the Reserved Instance can be used. Type: xsd:string The Availability Zone in which the Reserved Instance can be used. Type: xsd:string The duration of the Reserved Instance, in seconds. Type: xs:long The purchase price of the Reserved Instance. Type: xs:double The usage price of the Reserved Instance, per hour. Type: xs:double The Reserved Instance description. Type: xsd:string Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC) The tenancy of the reserved instance. Type: xs:string The currency of the Reserved Instance offering you are purchasing. It's specified using ISO 4217 standard currency codes (e.g., USD, JPY). At this time, the only supported currency is USD. Type: xs:string The Reserved Instance offering type. Type: xsd:string The recurring charge tag assigned to the resource. Type: RecurringChargesSetItemType (p. 443)

availabilityZone

duration

fixedPrice

usagePrice

productDescription

instanceTenancy

currencyCode

offeringType

recurringCharges

DescribeReservedInstancesResponseSetItemType
The DescribeReservedInstancesResponseSetItemType data type.

Ancestors
DescribeReservedInstancesResponseSetType

Relevant Operations
DescribeReservedInstances

API Version 2012-05-01 400

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in DescribeReservedInstancesResponseSetItemType. Name
reservedInstancesId

Description The ID of the Reserved Instance. Type: xsd:string The instance type on which the Reserved Instance can be used. Type: xsd:string The Availability Zone in which the Reserved Instance can be used. Type: xsd:string The date and time the Reserved Instance started. Type: xsd:dateTime The duration of the Reserved Instance, in seconds. Type: xs:long The purchase price of the Reserved Instance. Type: xs:double The usage price of the Reserved Instance, per hour. Type: xs:double The number of Reserved Instances purchased. Type: xs:integer The Reserved Instance description. Type: xsd:string Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC) The state of the Reserved Instance purchase. Type: xsd:string Valid Values: payment-pending | active | payment-failed | retired Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445) The tenancy of the reserved instance. Type: xsd:string Valid Values: default | dedicated The currency of the Reserved Instance. It's specified using ISO 4217 standard currency codes. Type: xsd:string Valid Values: As specified in ISO 4217 (e.g., USD, JPY)

instanceType

availabilityZone

start

duration

fixedPrice

usagePrice

instanceCount

productDescription

state

tagSet

instanceTenancy

currencyCode

API Version 2012-05-01 401

Amazon Elastic Compute Cloud API Reference DescribeSnapshotsSetItemResponseType

Name
offeringType

Description The Reserved Instance offering type. Type: xs:string The recurring charge tag assigned to the resource. Type: RecurringChargesSetItemType (p. 443)

recurringCharges

DescribeSnapshotsSetItemResponseType
The DescribeSnapshotsSetItemResponseType data type.

Ancestors
DescribeSnapshotsSetResponseType

Relevant Operations
DescribeSnapshots

Contents
The following table describes the elements contained in DescribeSnapshotsSetItemResponseType. Name
snapshotId

Description The ID of the snapshot. Type: xsd:string The ID of the volume. Type: xsd:string Snapshot state. Type: xsd:string Valid Values: pending | completed | error Time stamp when the snapshot was initiated. Type: xsd:dateTime The progress of the snapshot, in percentage. Type: xsd:string ID of the AWS account that owns the snapshot. Type: xsd:string The size of the volume, in GiB. Type: xsd:string

volumeId

status

startTime

progress

ownerId

volumeSize

API Version 2012-05-01 402

Amazon Elastic Compute Cloud API Reference DescribeVolumesSetItemResponseType

Name
description

Description Description of the snapshot. Type: xsd:string The AWS account alias (amazon, self, etc.) or AWS account ID that owns the AMI. Type: xsd:string Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

ownerAlias

tagSet

DescribeVolumesSetItemResponseType
The DescribeVolumesSetItemResponseType data type.

Ancestors
ItemType-DescribeVolumesSetResponseType

Relevant Operations
DescribeVolumes

Contents
The following table describes the elements contained in DescribeVolumesSetItemResponseType. Name
volumeId

Description The ID of the volume. Type: xsd:string The size of the volume, in GiBs. Type: xsd:string Snapshot from which the volume was created (optional). Type: xsd:string Availability Zone in which the volume was created. Type: xsd:string State of the volume. Type: xsd:string Valid Values: creating | available | in-use | deleting | deleted | error

size

snapshotId

availabilityZone

status

API Version 2012-05-01 403

Amazon Elastic Compute Cloud API Reference DhcpConfigurationItemType

Name
createTime

Description Time stamp when volume creation was initiated. Type: xsd:dateTime Volume attachment information, wrapped in an item element. Type: AttachmentSetItemResponseType (p. 386) Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

attachmentSet

tagSet

DhcpConfigurationItemType
The DhcpConfigurationItemType data type.

Ancestors
DhcpConfigurationItemSetType

Relevant Operations
CreateDhcpOptions CreateDhcpOptions DescribeDhcpOptions

Contents
The following table describes the elements contained in DhcpConfigurationItemType. Name
key

Description The name of a DHCP option. Type: String A set of values for a DHCP option. Each value is wrapped in an item element. Type: DhcpValueType (p. 405)

valueSet

DhcpOptionsType
The DhcpOptionsType data type.

Ancestors
CreateDhcpOptionsResponse
API Version 2012-05-01 404

Amazon Elastic Compute Cloud API Reference Relevant Operations

DhcpOptionsSetType

Relevant Operations
CreateDhcpOptions DescribeDhcpOptions

Contents
The following table describes the elements contained in DhcpOptionsType. Name
dhcpOptionsId

Description The ID of the set of DHCP options. Type: String The list of options in the set. Each option's key and set of values are wrapped in an item element. Type: DhcpConfigurationItemType (p. 404) Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

dhcpConfigurationSet

tagSet

DhcpValueType
The DhcpValueType data type.

Ancestors
DhcpValueSetType

Relevant Operations
CreateDhcpOptions CreateDhcpOptions DescribeDhcpOptions

Contents
The following table describes the elements contained in DhcpValueType.

API Version 2012-05-01 405

Amazon Elastic Compute Cloud API Reference DiskImageDescriptionType

Name
value

Description A value for the DHCP option. Type: String

DiskImageDescriptionType
The DiskImageDescriptionType data type.

Ancestors
ImportInstanceVolumeDetailItemType (p. 412) ImportVolumeTaskDetailsType (p. 413)

Relevant Operations
DescribeConversionTasks ImportInstance ImportVolume

Contents
The following table describes the elements contained in DiskImageDescriptionType. Name
format

Description Disk image format. Type: xs:string Size of the disk image. Type: xs:long A presigned URL for the import manifest stored in Amazon S3. For information about creating a presigned URL for an Amazon S3 object, read the "Query String Request Authentication Alternative" section of the Authenticating REST Requests topic in the Amazon Simple Storage Service Developer Guide. Type: xs:string Checksum computed for the disk image. Type: xs:string

size

importManifestUrl

checksum

DiskImageVolumeDescriptionType
The DiskImageVolumeDescriptionType data type.

API Version 2012-05-01 406

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
ImportInstanceVolumeDetailItemType (p. 412) ImportVolumeTaskDetailsType (p. 413)

Relevant Operations
DescribeConversionTasks ImportInstance ImportVolume

Contents
The following table describes the elements contained in DiskImageVolumeDescriptionType. Name
size

Description Size of the volume. Type: xs:integer Volume identifier. Type: xs:string

id

EbsBlockDeviceType
The EbsBlockDeviceType data type.

Ancestors
BlockDeviceMappingItemType (p. 389)

Relevant Operations
DescribeImageAttribute DescribeImages RequestSpotInstances DescribeSpotInstanceRequests RequestSpotInstances RegisterImage RunInstances

API Version 2012-05-01 407

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in EbsBlockDeviceType. Name
snapshotId

Description The ID of the snapshot. Type: xsd:string The size of the volume, in GiBs. If you're specifying a block device mapping, this is required if you're not creating a volume from a snapshot. Type: integer Whether the Amazon EBS volume is deleted on instance termination. Type: xsd:boolean

volumeSize

deleteOnTermination

EbsInstanceBlockDeviceMappingResponseType
The EbsInstanceBlockDeviceMappingResponseType data type.

Ancestors
InstanceBlockDeviceMappingResponseItemType (p. 415)

Relevant Operations
DescribeInstanceAttribute DescribeInstances RunInstances

Contents
The following table describes the elements contained in EbsInstanceBlockDeviceMappingResponseType. Name
volumeId

Description The ID of the Amazon EBS volume. Type: xsd:string Attachment state. Type: xsd:string Valid Values: attaching | attached | detaching | detached Time stamp when the attachment initiated. Type: xsd:dateTime

status

attachTime

API Version 2012-05-01 408

Amazon Elastic Compute Cloud API Reference ExportTaskResponseType

Name
deleteOnTermination

Description Whether the Amazon EBS volume is deleted on instance termination. Type: xsd:boolean

ExportTaskResponseType
The ExportTaskResponseType data type.

Ancestors
CreateInstanceExportTaskResponseType DescribeExportTasksResponseType ExportTaskSetResponseType

Relevant Operations
CreateInstanceExportTask DescribeExportTasks

Contents
The following table describes the elements contained in DescribeExportTasksResponseType. Name
exportTaskId

Description The ID of the export task. Type: xs:string Description of the resource being exported. Type: xs:string State of the conversion task. Type: xs:string Valid Values: active | cancelling | cancelled | completed Status message related to the export task. Type: xs:string Information about the instance being exported. Type: InstanceExportTaskResponseType (p. 416) Information about the destination Amazon S3 bucket. Type: ExportToS3TaskResponseType (p. 410)

description

state

statusMessage

instanceExport

exportToS3

API Version 2012-05-01 409

Amazon Elastic Compute Cloud API Reference ExportToS3TaskResponseType

ExportToS3TaskResponseType
The ExportToS3TaskResponseType data type.

Ancestors
CreateInstanceExportTaskResponseType DescribeExportTasksResponseType ExportTaskSetResponseType ExportTaskResponseType

Relevant Operations
CreateInstanceExportTask DescribeExportTasks

Contents
The following table describes the elements contained in ExportToS3TaskResponseType. Name
diskImageFormat

Description The format for the exported image. Type: xs:string Valid Values: vmdk | vhd The container format used to combine disk images with metadata (such as OVF). Type: xs:string Valid Values: ova Amazon S3 bucket for the destination image. Type: xs:string Image written to a single object in s3bucket at the S3 key s3prefix + exportTaskId + . +diskImageFormat. Type: xs:string

containerFormat

s3Bucket

s3Key

GroupItemType
The GroupItemType data type.

Ancestors
GroupSetType

API Version 2012-05-01 410

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
DescribeInstanceAttribute DescribeInstances RequestSpotInstances DescribeSpotInstanceRequests RequestSpotInstances RunInstances CreateNetworkInterface

Contents
The following table describes the elements contained in GroupItemType. Name
groupId

Description ID of the security group. In API versions before 2011-01-01, this field returned the name of the security group. Type: xsd:string Name of the security group. Type: xsd:string

groupName

IcmpTypeCodeType
The IcmpTypeCodeType data type.

Ancestors
NetworkAclEntryType

Relevant Operations
CreateNetworkAcl DescribeNetworkAcls

Contents
The following table describes the elements contained in IcmpTypeCodeType.

API Version 2012-05-01 411

Amazon Elastic Compute Cloud API Reference ImportInstanceTaskDetailsType

Name
code

Description The ICMP code. A value of -1 means all codes for the given ICMP type. Type: Integer The ICMP type. A value of -1 means all types. Type: Integer

type

ImportInstanceTaskDetailsType
The ImportInstanceTaskDetailsType data type.

Ancestors
ConversionTaskType (p. 393)

Relevant Operations
DescribeConversionTasks ImportInstance ImportVolume

Contents
The following table describes the elements contained in ImportInstanceTaskDetailsType. Name
volumes

Description A list of instance volumes for import. Each volume's information is wrapped in an item element. Type: ImportInstanceVolumeDetailItemType (p. 412) The ID of the resulting instance in Amazon EC2. Type: xs:string Instance operating system. Type: xs:string Valid Value: Windows Optional description of the instance. Type: xs:string

instanceId

platform

description

ImportInstanceVolumeDetailItemType
The ImportInstanceVolumeDetailItemType data type.
API Version 2012-05-01 412

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
ImportInstanceVolumeDetailSetType

Relevant Operations
DescribeConversionTasks ImportInstance ImportVolume

Contents
The following table describes the elements contained in ImportInstanceVolumeDetailItemType. Name
bytesConverted

Description Number of bytes converted so far. Type: xs:long The Availability Zone where the resulting instance will reside. Type: xs:string Information about the image. Type: DiskImageDescriptionType (p. 406) Description you provided when starting the import instance task. Type: xs:string Information about the volume. Type: DiskImageVolumeDescriptionType (p. 406) Status of the import of this particular disk image. Type: xs:string Status information or errors related to the disk image. Type: xs:string

availabilityZone

image

description

volume

status

statusMessage

ImportVolumeTaskDetailsType
The ImportVolumeTaskDetailsType data type.

Ancestors
ConversionTaskType (p. 393)

API Version 2012-05-01 413

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
DescribeConversionTasks ImportInstance ImportVolume

Contents
The following table describes the elements contained in ImportVolumeTaskDetailsType. Name
bytesConverted

Description Number of bytes converted so far. Type: xs:long The Availability Zone where the resulting volume will reside. Type: xs:string Description you provided when starting the import volume task. Type: xs:string Information about the image. Type: DiskImageDescriptionType (p. 406) Information about the volume. Type: DiskImageVolumeDescriptionType (p. 406)

availabilityZone

description

image

volume

InstanceBlockDeviceMappingItemType
The InstanceBlockDeviceMappingItemType data type.

Ancestors
InstanceBlockDeviceMappingType

Relevant Operations
ModifyInstanceAttribute

Contents
The following table describes the elements contained in InstanceBlockDeviceMappingItemType.

API Version 2012-05-01 414

Amazon Elastic Compute Cloud API Reference InstanceBlockDeviceMappingResponseItemType

Name
deviceName

Description The device name (e.g., /dev/sdh, or xvdh). Type: xsd:string The virtual device name. Type: xsd:string Parameters used to automatically set up Amazon EBS volumes when the instance is launched. Type: InstanceEbsBlockDeviceType (p. 415) Include this empty element to indicate that you want to suppress the specified device from the mapping.

virtualName

ebs

noDevice

InstanceBlockDeviceMappingResponseItemType
The InstanceBlockDeviceMappingResponseItemType data type.

Ancestors
InstanceBlockDeviceMappingResponseType

Relevant Operations
DescribeInstanceAttribute DescribeInstances RunInstances

Contents
The following table describes the elements contained in InstanceBlockDeviceMappingResponseItemType. Name
deviceName

Description How the device is exposed to the instance (e.g., /dev/sdh, or xvdh). Type: xsd:string Parameters used to automatically set up Amazon EBS volumes when the instance is launched. Type: EbsInstanceBlockDeviceMappingResponseType (p. 408)

ebs

InstanceEbsBlockDeviceType
The InstanceEbsBlockDeviceType data type.

API Version 2012-05-01 415

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
InstanceBlockDeviceMappingItemType (p. 414)

Relevant Operations
ModifyInstanceAttribute

Contents
The following table describes the elements contained in InstanceEbsBlockDeviceType. Name
deleteOnTermination

Description Whether the Amazon EBS volume is deleted on instance termination. Type: xsd:boolean The ID of the Amazon EBS volume. Type: xsd:string

volumeId

InstanceExportTaskResponseType
The InstanceExportTaskResponseType data type.

Ancestors
CreateInstanceExportTaskResponseType DescribeExportTasksResponseType ExportTaskSetResponseType ExportTaskResponseType

Relevant Operations
CreateInstanceExportTask DescribeExportTasks

Contents
The following table describes the elements contained in InstanceExportTaskResponseType. Name
instanceId

Description EC2 identifier of the resource being exported. Type: xs:string

API Version 2012-05-01 416

Amazon Elastic Compute Cloud API Reference InstanceStatusEventsSetType

Name
targetEnvironment

Description The target virtualization environment. Type: xs:string Valid Values: vmware | citrix

InstanceStatusEventsSetType
The InstanceStatusEventsSetType data type.

Relevant Operations
DescribeInstanceStatus (p. 186)

Contents
The following table describes the elements contained in InstanceStatusEventsSetType. Name
item

Description Information about scheduled events for the instance. Type: InstanceStatusEventType

InstanceStatusEventType
The InstanceStatusEventType data type.

Ancestors
DescribeInstanceStatus InstanceStatusEventsSetType

Relevant Operations
DescribeInstanceStatus (p. 186)

Contents
The following table describes the elements contained in InstanceStatusEventType.

API Version 2012-05-01 417

Amazon Elastic Compute Cloud API Reference InstanceStatusItemType

Name
code

Description The associated code of the event. Type: String Valid parameters: instance-reboot |system-reboot| instance-retirement A description of the event. Type: String The earliest scheduled start time for the event. Type: dateType The latest scheduled end time for the event. Type: dateType

description

notBefore

notAfter

InstanceStatusItemType
The InstanceStatusItemType data type.

Ancestors
DescribeInstanceStatus InstanceStatusSetType

Relevant Operations
DescribeInstanceStatus (p. 186)

Contents
The following table describes the elements contained in InstanceStatusItemType. Name
instanceId

Description The ID of the Amazon EC2 instance. Type: String The Amazon EC2 instance's availability zone. Type: String Extra information regarding events associated with the instance. Type: InstanceStatusEventsSetType (p. 417) The intended state of the instance. Calls to DescribeInstanceStatus require that an instance be in the running state. Type: InstanceStateType (p. 425)

availabilityZone

eventsSet

instanceState

API Version 2012-05-01 418

Amazon Elastic Compute Cloud API Reference InstanceStatusSetType

Name
systemStatus

Description Reports impaired functionality that stems from issues related to the systems that support an instance, such as hardware failures and network connectivity problems. Type: InstanceStatusType (p. 420) Reports impaired functionality that arises from problems internal to the instance.The DescribeInstanceStatus (p. 186) response elements report such problems as impaired reachability. Type: InstanceStatusType (p. 420)

instanceStatus

InstanceStatusSetType
The InstanceStatusSetType data type.

Relevant Operations
DescribeInstanceStatus (p. 186)

Contents
The following table describes the elements contained in InstanceStatusSetType. Name
item

Description Information about the status of the instance. Type: InstanceStatusItemType

InstanceStatusDetailsSetType
The InstanceStateType data type.

Ancestors
InstanceStatusItemType (p. 418) InstanceStatusType (p. 420)

Relevant Operations
DescribeInstanceStatus (p. 186)

Contents
The following table describes the elements contained in InstanceStatusDetailsSetType.
API Version 2012-05-01 419

Amazon Elastic Compute Cloud API Reference InstanceStatusType

Name
name

Description The type of instance status detail. Type: String Valid Values: reachability Type: String Valid Values: passed | failed | insufficient-data The time when a status check failed. For an instance that was launched and impaired, this is the time when the instance was launched. Type: xsd:dateTime

status

impairedSince

InstanceStatusType
The InstanceStateType data type.

Ancestors
InstanceStatusItemType (p. 418)

Relevant Operations
DescribeInstanceStatus (p. 186)

Contents
The following table describes the elements contained in InstanceStatusType. Name
status

Description Type: String Valid Values: ok | impaired | insufficient-data | not-applicable Specific information about system instance health or application instance health. Type: InstanceStatusDetailsSetType (p. 419)

details

InstanceMonitoringStateType
The InstanceMonitoringStateType data type.

Ancestors
MonitorInstancesResponseSetItemType (p. 433)

API Version 2012-05-01 420

Amazon Elastic Compute Cloud API Reference Relevant Operations

RunningInstancesItemType (p. 448)

Relevant Operations
MonitorInstances UnmonitorInstances DescribeInstances RunInstances

Contents
The following table describes the elements contained in InstanceMonitoringStateType. Name
state

Description State of monitoring for the instance. The disabled state means that Detailed Monitoring is disabled for the instance. The enabled state means that Detailed Monitoring is enabled for the instance. The pending state means that the instance is launching or that you recently enabled Detailed Monitoring for the instance. Type: xsd:string Valid Values: disabled | enabled | pending

InstanceNetworkInterfaceSetItemRequestType
The InstanceNetworkInterfaceSetItemRequestType data type.

Ancestors
DescribeSpotInstanceRequests RequestSpotInstances

Contents
The following table describes the elements contained in InstanceNetworkInterfaceSetItemRequestType. Name
networkInterfaceId

Description The ID of the network interface. Type: xsd:string Required. The index of the device on the instance for the network interface attachment. Type: int

deviceIndex

API Version 2012-05-01 421

Amazon Elastic Compute Cloud API Reference InstanceNetworkInterfaceSetItemType

Name
subnetId

Description The ID of the subnet associated with the network string. Type: xsd:string The description of the network interface. Type: xsd:string The private IP address of the network interface. Type: xsd:string The group IDs for use by the network interface. Type: SecurityGroupIdSetItemType (p. 451) If set to true, the interface will be deleted when the instance is terminated. Type: Boolean

description

privateIpAddress

groupSet

deleteOnTermination

InstanceNetworkInterfaceSetItemType
The InstanceNetworkInterfaceSetItemType data type.

Contents
The following table describes the elements contained in InstanceNetworkInterfaceSetItemType. Name
networkInterfaceId

Description The ID of the network interface. Type: xsd:string The ID of the subnet. Type: xsd:string The ID of the VPC. Type: xsd:string The description of the network interface. Type: xsd:string The ID of the customer who created the network interface. Type: xsd:string The network interface's status listed as "available" or "in-use". Type: xsd:string The IP address of the network interface within the subnet. Type: xsd:string The private DNS name assigned to the instance. Type: xsd:string

subnetId

vpcId

description

ownerId

status

privateIpAddress

privateDnsName

API Version 2012-05-01 422

Amazon Elastic Compute Cloud API Reference InstanceNetworkInterfaceSetRequestType

Name
sourceDestCheck

Description Flag indicating whether to validate network traffic to or from this network interface. Type: xsd:boolean Type: GroupItemType (p. 410) Type: NetworkInterfaceAttachmentType (p. 438) Type: NetworkInterfaceAssociationType (p. 436)

groupSet attachment association

InstanceNetworkInterfaceSetRequestType
The InstanceNetworkInterfaceSetRequestType data type.

Contents
The following table describes the elements contained in InstanceNetworkInterfaceSetRequestType. Name
networkInterfaceId

Description The ID of the network interface. Type: xsd:string The index of the device. Type: int The ID of the subnet. Type: xsd:string The description. Type: xsd:string The private IP address. Type: xsd:string Contains security group information. Type: SecurityGroupIdType Whether to delete the network interface when the instance is terminated. Type: boolean

deviceIndex

subnetId

description

privateIpAddress

groupSet

deleteOnTermination

InstanceNetworkInterfaceSetType
The InstanceNetworkInterfaceSetType data type.

API Version 2012-05-01 423

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
InstanceNetworkInterfaceSetType (p. 423)

Relevant Operations
DescribeInstances RunInstances

Contents
The following table describes the elements contained in InstanceNetworkInterfaceSetType. Name
networkInterfaceId

Description The ID of the network interface. Type: xsd:string The ID of the subnet. Type: xsd:string The ID of the VPC. Type: xsd:string The description. Type: xsd:string The ID of the customer who created the network interface. Type: xsd:string The network interface's status listed as "available" or "in-use". Type: xsd:string The IP address of the network interface within the subnet. Type: xsd:string The private DNS name. Type: xsd:string Flag to indicate whether to validate network traffic to or from this network interface. Type: xsd:boolean Type: GroupItemType Type: NetworkInterfaceAttachmentType (p. 438) Type: NetworkInterfaceAssociationType (p. 436) The address of the elastic IP address bound to the network interface. Type: xsd:string

subnetId

vpcId

description

ownerId

status

privateIpAddress

privateDnsName

sourceDestCheck

groupSet.item attachment association publicIp

API Version 2012-05-01 424

Amazon Elastic Compute Cloud API Reference InstanceStateChangeType

Name
ipOwnerId

Description The ID of the Elastic IP address owner. Type: xsd:string

InstanceStateChangeType
The InstanceStateChangeType data type.

Ancestors
InstanceStateChangeSetType

Relevant Operations
StartInstances StopInstances TerminateInstances

Contents
The following table describes the elements contained in InstanceStateChangeType. Name
instanceId

Description The instance ID. Type: xsd:string The current state of the instance. Type: InstanceStateType (p. 425) The previous state of the instance. Type: InstanceStateType (p. 425)

currentState

previousState

InstanceStateType
The InstanceStateType data type.

Ancestors
InstanceStateChangeType (p. 425) InstanceStateChangeType (p. 425) RunningInstancesItemType (p. 448)

API Version 2012-05-01 425

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
StartInstances StopInstances TerminateInstances DescribeInstances DescribeInstanceStatus RunInstances

Contents
The following table describes the elements contained in InstanceStateType. Name
code

Description A 16-bit unsigned integer. The high byte is an opaque internal value and should be ignored. The low byte is set based on the state represented. Type: integer Valid Values: 0 (pending) | 16 (running) | 32 (shutting-down) | 48 (terminated) | 64 (stopping) | 80 (stopped)

Note
A code of 272 typically indicates a problem with the host running the instance. A reboot might resolve the problem (be aware that for a Windows system, a reboot is a hard reboot that might result in data corruption). If a reboot doesn't work, post a message to the EC2 forums with the instance ID. Typically someone from the EC2 team can get your instance back to a normal state.

name

The current state of the instance. Type: xsd:string Valid Values: pending | running | shutting-down | terminated | stopping | stopped

InternetGatewayAttachmentType
The InternetGatewayAttachmentType data type.

Ancestors
InternetGatewayAttachmentSetType AttachInternetGatewayResponse

API Version 2012-05-01 426

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
CreateInternetGateway DescribeInternetGateways AttachInternetGateway

Contents
The following table describes the elements contained in InternetGatewayAttachmentType. Name
vpcId

Description The ID of the VPC the Internet gateway is attached to. Type: String The current state of the attachment. Type: String Valid Values: attaching | attached | detaching | detached

state

InternetGatewayType
The VpnGatewayType data type.

Ancestors
CreateInternetGatewayResponse InternetGatewaySetType

Relevant Operations
CreateInternetGateway DescribeInternetGateways

Contents
The following table describes the elements contained in InternetGatewayType. Name
internetGatewayId

Description The ID of the Internet gateway. Type: String A list of VPCs attached to the Internet gateway. Each VPC's information is wrapped in an item element. Type: InternetGatewayAttachmentType (p. 426)

attachmentSet

API Version 2012-05-01 427

Amazon Elastic Compute Cloud API Reference IpPermissionType

Name
tagSet

Description Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

IpPermissionType
The IpPermissionType data type.

Ancestors
IpPermissionSetType

Relevant Operations
AuthorizeSecurityGroupIngress RevokeSecurityGroupIngress DescribeSecurityGroups

Contents
The following table describes the elements contained in IpPermissionType. Name
ipProtocol

Description Protocol. When you call DescribeSecurityGroups, the protocol value returned is the number. Exception: For TCP, UDP, and ICMP, the value returned is the name (e.g., tcp, udp, or icmp). For a list of protocol numbers, go to Protocol Numbers. Type: xsd:string Start of port range for the TCP and UDP protocols, or an ICMP type number. A value of -1 indicates all ICMP types. Type: integer End of port range for the TCP and UDP protocols, or an ICMP code. A value of -1 indicates all ICMP codes for the given ICMP type. Type: integer A list of security group and AWS account ID pairs. Each pair is wrapped in an item element. Type: UserIdGroupPairType (p. 460) A list of IP ranges. Each range is wrapped in an item element. Type: IpRangeItemType (p. 429)

fromPort

toPort

groups

ipRanges

API Version 2012-05-01 428

Amazon Elastic Compute Cloud API Reference IpRangeItemType

IpRangeItemType
The IpRangeItemType data type.

Ancestors
IpRangeSetType

Relevant Operations
AuthorizeSecurityGroupIngress RevokeSecurityGroupIngress DescribeSecurityGroups

Contents
The following table describes the elements contained in IpRangeItemType. Name
cidrIp

Description CIDR range. Cannot be used when specifying a source security group. Type: xsd:string

LaunchPermissionItemType
The LaunchPermissionItemType data type.

Ancestors
LaunchPermissionListType

Relevant Operations
DescribeImageAttribute ModifyImageAttribute

Contents
The following table describes the elements contained in LaunchPermissionItemType.

API Version 2012-05-01 429

Amazon Elastic Compute Cloud API Reference LaunchSpecificationRequestType

Name
group

Description Name of the group. Type: xsd:string Valid Value: all AWS account ID. Type: xsd:string

userId

LaunchSpecificationRequestType
The LaunchSpecificationRequestType data type.

Ancestors
RequestSpotInstancesType

Relevant Operations
RequestSpotInstances

Contents
The following table describes the elements contained in LaunchSpecificationRequestType. Name
imageId

Description The AMI ID. Type: xsd:string The name of the key pair. Type: xsd:string A list of security groups. Each group's information is wrapped in an item element. Type: GroupItemType (p. 410) Base64-encoded MIME user data made available to the instance(s) in the reservation. Type: UserDataType (p. 459) Deprecated. Type: xsd:string The instance type. Type: xsd:string Placement information for the instance. Type: PlacementRequestType (p. 440)

keyName

groupSet

userData

addressingType

instanceType

placement

API Version 2012-05-01 430

Amazon Elastic Compute Cloud API Reference LaunchSpecificationResponseType

Name
kernelId

Description The ID of the kernel to select. Type: xsd:string The ID of the RAM disk to select. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk and search for the kernel ID. Type: xsd:string A list of block device mappings for the instance. Each mapping's information is wrapped in an item element. Type: BlockDeviceMappingItemType (p. 389) Whether to enable monitoring for the instance. Type: MonitoringInstanceType (p. 432) The Amazon VPC subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud. Type: xsd:string Type: InstanceNetworkInterfaceSetRequestType (p. 423)

ramdiskId

blockDeviceMapping

monitoring

subnetId

networkInterfaceSet

LaunchSpecificationResponseType
The LaunchSpecificationResponseType data type.

Ancestors
SpotInstanceRequestSetItemType (p. 454)

Relevant Operations
DescribeSpotInstanceRequests

Contents
The following table describes the elements contained in LaunchSpecificationResponseType. Name
imageId

Description The AMI ID. Type: xsd:string The name of the key pair. Type: xsd:string

keyName

API Version 2012-05-01 431

Amazon Elastic Compute Cloud API Reference MonitoringInstanceType

Name
groupSet

Description A list of security groups. Each group's information is wrapped in an item element. Type: GroupItemType (p. 410) Deprecated. Type: xsd:string The instance type. Type: xsd:string Placement information for the instance. Type: PlacementRequestType (p. 440) The ID of the kernel to select. Type: xsd:string The ID of the RAM disk to select. Some kernels require additional drivers at launch. Check the kernel requirements for information on whether you need to specify a RAM disk and search for the kernel ID. Type: xsd:string A list of block device mappings for the instance. Each mapping's information is wrapped in an item element. Type: BlockDeviceMappingItemType (p. 389) Whether to enable monitoring for the instance. Type: MonitoringInstanceType (p. 432) The Amazon VPC subnet ID within which to launch the instance(s) for Amazon Virtual Private Cloud. Type: xsd:string Type: InstanceNetworkInterfaceSetRequestType (p. 423)

addressingType

instanceType

placement

kernelId

ramdiskId

blockDeviceMapping

monitoring

subnetId

networkInterfaceSet

MonitoringInstanceType
The MonitoringInstanceType data type.

Ancestors
LaunchSpecificationRequestType (p. 430) LaunchSpecificationResponseType (p. 431) RunInstancesType

Relevant Operations
RequestSpotInstances
API Version 2012-05-01 432

Amazon Elastic Compute Cloud API Reference Contents

DescribeSpotInstanceRequests RequestSpotInstances RunInstances

Contents
The following table describes the elements contained in MonitoringInstanceType. Name
enabled

Description Whether monitoring is enabled for the instance. Type: xsd:boolean

MonitorInstancesResponseSetItemType
The MonitorInstancesResponseSetItemType data type.

Ancestors
MonitorInstancesResponseSetType

Relevant Operations
MonitorInstances UnmonitorInstances

Contents
The following table describes the elements contained in MonitorInstancesResponseSetItemType. Name
instanceId

Description Instance ID. Type: xsd:string Monitoring information. Type: InstanceMonitoringStateType (p. 420)

monitoring

NetworkAclEntryType
The NetworkAclEntryType data type.

API Version 2012-05-01 433

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
NetworkAclEntrySetType

Relevant Operations
CreateNetworkAcl DescribeNetworkAcls

Contents
The following table describes the elements contained in NetworkAclEntryType. Name
ruleNumber

Description Specific rule number for the entry. ACL entries are processed in ascending order by rule number. Type: Integer Protocol. A value of -1 means all protocols. Type: Integer Valid Values: Any protocol number (go to Protocol Numbers). Whether to allow or deny the traffic that matches the rule. Type: string Boolean flag to indicate an egress rule (rule is applied to traffic leaving the subnet). Value of true indicates egress. Type: boolean The network range to allow or deny, in CIDR notation. Type: String For the ICMP protocol, this is the ICMP type and code. Type: IcmpTypeCodeType (p. 411) For the TCP or UDP protocols, the range of ports the rule applies to. Type: PortRangeType (p. 441)

protocol

ruleAction

egress

cidrBlock

icmpTypeCode

portRange

NetworkAclType
The NetworkAclType data type.

Ancestors
CreateNetworkAclResponse NetworkAclSetType

API Version 2012-05-01 434

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
CreateNetworkAcl DescribeNetworkAcls

Contents
The following table describes the elements contained in NetworkAclType. Name
networkAclId

Description The network ACL's ID. Type: String The ID of the VPC the network ACL is in. Type: String Whether this is the default network ACL in the VPC. Type: Boolean Valid Values: true | false A list of entries (rules) in the network ACL. Each entry's information is wrapped in an item element. Type: NetworkAclEntryType (p. 433) A list of associations between the network ACL and one or more subnets. Each association's information is wrapped in an item element. Type: NetworkAclAssociationType (p. 435) Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

vpcId

default

entrySet

associationSet

tagSet

NetworkAclAssociationType
The NetworkAclAssociationType data type.

Ancestors
NetworkAclAssociationSetType

Relevant Operations
CreateNetworkAcl DescribeNetworkAcls

API Version 2012-05-01 435

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in NetworkAclAssociationType. Name
networkAclAssociationId

Description An identifier representing the association between a network ACL and a subnet. Type: xsd:string The ID of the network ACL in the association. Type: xsd:string The ID of the subnet in the association. Type: xsd:string

networkAclId

subnetId

NetworkInterfaceAssociationType
The NetworkInterfaceAssociationType data type.

Ancestors
InstanceNetworkInterfaceSetItemType

Relevant Operations
RunInstances DescribeInstances

Contents
The following table describes the elements contained in NetworkInterfaceAssociationType. Name
attachmentID

Description The ID of the network interface attachment. Type: xsd:string The ID of the instance attached to the network interface. Type: xsd:string The address of the Elastic IP address bound to the network interface. Type: xsd:string The ID of the Elastic IP address owner. Type: xsd:string

instanceID

publicIp

ipOwnerId

API Version 2012-05-01 436

Amazon Elastic Compute Cloud API Reference NetworkInterfaceSet

NetworkInterfaceSet
The NetworkInterfaceSet data type.

Ancestors
InstanceNetworkInterfaceSetType

Relevant Operations
DescribeInstances DescribeNetworkInterfaces RequestSpotInstances

Contents
The following table describes the elements contained in NetworkInterfaceSet. Name
networkInterfaceId

Description The ID of the network interface. Type: xsd:string The ID of the subnet. Type: xsd:string The ID of the VPC. Type: xsd:string The description. Type: xsd:string The ID of the customer who created the interface. Type: xsd:string "available" or "in-use" Type: xsd:string IP address of the interface within the subnet. Type: xsd:string The private DNS name. Type: xsd:string Flag indicating whether traffic to or from the instance is validated. Type: Boolean Type: GroupItemType Type: NetworkInterfaceAttachmentType (p. 438)

subnetId

vpcId

description

ownerId

status

privateIpAddress

privateDnsName

sourceDestCheck

groupSet attachment

API Version 2012-05-01 437

Amazon Elastic Compute Cloud API Reference NetworkInterfaceAttachmentType

Name
association

Description Type: NetworkInterfaceAssociationType (p. 436)

NetworkInterfaceAttachmentType
The NetworkInterfaceType data type.

Relevant Operations
DescribeNetworkInterfaces

Contents
The following table describes the elements contained in NetworkInterfaceAttachmentType. Name
attachmentID

Description The ID of the network interface attachment. Type: xsd:string The ID of the instance. Type: xsd:string

instanceID

NetworkInterfaceType
The NetworkInterfaceType data type.

Relevant Operations
DescribeNetworkInterfaces

Contents
The following table describes the elements contained in NetworkInterfaceType. Name
networkInterfaceId

Description The ID of the network interface. Type: xsd:string The ID of the subnet. Type: xsd:string The ID of the VPC. Type: xsd:string

subnetId

vpcId

API Version 2012-05-01 438

Amazon Elastic Compute Cloud API Reference PlacementGroupInfoType

Name
availabilityZone

Description The availability zone. Type: xsd:string The description. Type: xsd:string The ID of the customer who created the interface. Type: xsd:string ID of the entity that launched the instance on your behalf (e.g., AWS Management Console, Auto Scaling, etc.) Type: xsd:string Type: xsd:string "available" or "in-use" Type: xsd:string Type: xsd:string IP address of the interface within the subnet. Type: xsd:string The private DNS name. Type: xsd:string Flag indicating whether traffic to or from the instance is validated. Type: Boolean Type: GroupSetType Type: NetworkInterfaceAttachmentType (p. 438) Type: NetworkInterfaceAssociationType (p. 436) Type: ResourceTagSetType

description

ownerId

requesterId

requesterManaged status

macAddress privateIpAddress

privateDnsName

sourceDestCheck

groupSet attachment association tagSet

PlacementGroupInfoType
Relevant Operations
DescribePlacementGroups

Contents
The following table describes the elements contained in PlacementGroupInfoType.

API Version 2012-05-01 439

Amazon Elastic Compute Cloud API Reference PlacementRequestType

Name
groupName

Description Name of the placement group. Type: xsd:string The placement strategy. Type: xsd:string Valid Values: cluster Status of the placement group. Type: xsd:string Valid Values: pending | available | deleting | deleted

strategy

state

PlacementRequestType
The PlacementRequestType data type.

Ancestors
LaunchSpecificationRequestType (p. 430) LaunchSpecificationResponseType (p. 431) RunInstancesType

Relevant Operations
RequestSpotInstances DescribeSpotInstanceRequests RequestSpotInstances RunInstances

Contents
The following table describes the elements contained in PlacementRequestType. Name
availabilityZone

Description Availability Zone for launching the instance. Type: xsd:string The name of a placement group for the instance. Type: xsd:string

groupName

PlacementResponseType
The PlacementResponseType data type.
API Version 2012-05-01 440

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
RunningInstancesItemType (p. 448)

Relevant Operations
DescribeInstances RunInstances

Contents
The following table describes the elements contained in PlacementResponseType. Name
availabilityZone

Description The Availability Zone of the instance. Type: xsd:string The name of the placement group the instance is in (for cluster compute instances). Type: xsd:string The tenancy of the instance (if the instance is running within a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware. Type: xsd:string

groupName

tenancy

PortRangeType
The PortRangeType data type.

Ancestors
NetworkAclEntryType

Relevant Operations
DescribeNetworkAcls

Contents
The following table describes the elements contained in PortRangeType.

API Version 2012-05-01 441

Amazon Elastic Compute Cloud API Reference ProductCodeItemType

Name
from

Description The first port in the range. Type: xsd:integer The last port in the range. Type: xsd:integer

to

ProductCodeItemType
The ProductCodeItemType data type.

Ancestors
ProductCodeListType

Relevant Operations
DescribeImageAttribute ModifyImageAttribute

Contents
The following table describes the elements contained in ProductCodeItemType. Name
productCode

Description Product code. Type: xsd:string

ProductCodesSetItemType
The ProductCodesSetItemType data type.

Ancestors
ProductCodesSetType

Relevant Operations
DescribeImages DescribeImageAttribute DescribeInstances DescribeInstanceAttribute
API Version 2012-05-01 442

Amazon Elastic Compute Cloud API Reference Contents

DescribeSnapshotAttribute DescribeVolumeAttribute RunInstances

Contents
The following table describes the elements contained in ProductCodesSetItemType. Name
productCode

Description Product code. Type: xsd:string The type of product code. Type: xsd:string Valid values: devpay | marketplace

type

ProductDescriptionSetItemType
The ProductDescriptionSetItemType data type.

Ancestors
ProductDescriptionSetType

Relevant Operations
DescribeSpotPriceHistory

Contents
The following table describes the elements contained in ProductDescriptionSetItemType. Name
productDescription

Description The description of the AMI. Type: xsd:string Valid Values: Linux/UNIX | SUSE Linux | Windows

RecurringChargesSetItemType
The RecurringChargesSetItemType data type.

API Version 2012-05-01 443

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
DescribeReservedInstances DescribeReservedInstanceOfferings

Contents
The following table describes the elements contained in RecurringChargesSetItemType. Name
frequency

Description The frequency of the recurring charge. Type: xsd:string Valid value: Hourly The amount of the recurring charge. Type: double

amount

RegionItemType
The RegionItemType data type.

Ancestors
RegionSetType

Relevant Operations
DescribeRegions

Contents
The following table describes the elements contained in RegionItemType. Name
regionName

Description Name of the Region. Type: xsd:string Region service endpoint. Type: xsd:string

regionEndpoint

ReservationInfoType
The ReservationInfoType data type.
API Version 2012-05-01 444

Amazon Elastic Compute Cloud API Reference Ancestors

Ancestors
ReservationSetType

Relevant Operations
DescribeInstances

Contents
The following table describes the elements contained in ReservationInfoType. Name
reservationId

Description Unique ID of the reservation. Type: xsd:string ID of the AWS account that owns the reservation. Type: xsd:string A list of security groups. Each group's information is wrapped in an item element. Type: GroupItemType (p. 410) A list of instances. Each instance's information is wrapped in an item element. Type: RunningInstancesItemType (p. 448) ID of the requester that launched the instances on your behalf (e.g., AWS Management Console, Auto Scaling). Type: xsd:string

ownerId

groupSet

instancesSet

requesterId

ResourceTagSetItemType
The ResourceTagSetItemType data type.

Relevant Operations
DescribeImages DescribeInstances DescribeVolumes DescribeSnapshots DescribeSpotInstanceRequests

API Version 2012-05-01 445

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in ResourceTagSetItemType. Name
key

Description Tag key. Type: xsd:string Tag value. Type: xsd:string

value

RouteTableAssociationType
The RouteTableAssociationType data type.

Ancestors
RouteTableAssociationSetType

Relevant Operations
CreateRouteTable DescribeRouteTables

Contents
The following table describes the elements contained in NetworkAclAssociationType. Name
routeTableAssociationId

Description An identifier representing the association between a route table and a subnet. Type: xsd:string The ID of the route table in the association. Type: xsd:string The ID of the subnet in the association. Type: xsd:string Whether this is the main route table. Type: xsd:boolean

routeTableId

subnetId

main

API Version 2012-05-01 446

Amazon Elastic Compute Cloud API Reference RouteTableType

RouteTableType
The RouteTableType data type.

Ancestors
CreateRouteTableResponse RouteTableSetType

Relevant Operations
CreateRouteTable DescribeRouteTables

Contents
The following table describes the elements contained in RouteTableType. Name
routeTableId

Description The route table's ID. Type: String The ID of the VPC the route table is in. Type: String A list of routes in the route table. Each route's information is wrapped in an item element. Type: RouteType (p. 447) A list of associations between the route table and one or more subnets. Each association's information is wrapped in an item element. Type: RouteTableAssociationType (p. 446) Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

vpcId

routeSet

associationSet

tagSet

RouteType
The RouteType data type.

Ancestors
RouteSetType

API Version 2012-05-01 447

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
CreateRouteTable DescribeRouteTables

Contents
The following table describes the elements contained in RouteType. Name
destinationCidrBlock

Description The CIDR address block used for the destination match. For example: 0.0.0.0/0. Type: String The ID of a gateway attached to your VPC. Type: String The ID of a NAT instance in your VPC. Type: String The owner of the instance. Type: String The network interface ID. Type: String The state of the route. The blackhole state indicates that the route's target isn't available (e.g., the specified gateway isn't attached to the VPC, the specified NAT instance has been terminated, etc.). Type: String Valid Values: active | blackhole

gatewayId

instanceId

instanceOwnerId

networkInterfaceId

state

RunningInstancesItemType
The RunningInstancesItemType data type.

Ancestors
RunningInstancesSetType

Relevant Operations
DescribeInstances RunInstances

API Version 2012-05-01 448

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in RunningInstancesItemType. Name
instanceId

Description Unique ID of the instance launched. Type: xsd:string Image ID of the AMI used to launch the instance. Type: xsd:string The current state of the instance. Type: InstanceStateType (p. 425) The private DNS name assigned to the instance. This DNS name can only be used inside the Amazon EC2 network. This element remains empty until the instance enters a running state. Type: xsd:string The public DNS name assigned to the instance. This DNS name is contactable from outside the Amazon EC2 network. This element remains empty until the instance enters a running state. Type: xsd:string Reason for the most recent state transition. This might be an empty string. Type: xsd:string If this instance was launched with an associated key pair, this displays the key pair name. Type: xsd:string The AMI launch index, which can be used to find this instance within the launch group. Type: xsd:string Product codes attached to this instance. Each product code's information is wrapped in an item element. Type: ProductCodesSetItemType (p. 442) The instance type (e.g., m1.small). Type: xsd:string The time the instance launched. Type: xsd:dateTime The location where the instance launched. Type: PlacementResponseType (p. 440) Kernel associated with this instance. Type: xsd:string

imageId

instanceState

privateDnsName

dnsName

reason

keyName

amiLaunchIndex

productCodes

instanceType

launchTime

placement

kernelId

API Version 2012-05-01 449

Amazon Elastic Compute Cloud API Reference Contents

Name
ramdiskId

Description RAM disk associated with this instance. Type: xsd:string Platform of the instance (e.g., Windows). Type: xsd:string Whether monitoring is enabled for the instance. Type: InstanceMonitoringStateType (p. 420) The Amazon VPC subnet ID in which the instance is running. Type: xsd:string The Amazon VPC in which the instance is running. Type: xsd:string The private IP address assigned to the instance. Type: xsd:string The IP address of the instance. Type: xsd:string This attribute exists to enable a Network Address Translation (NAT) instance in a VPC to perform NAT. The attribute controls whether source/destination checking is enabled on the instance. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the instance to perform NAT. For more information, go to NAT Instances in the Amazon Virtual Private Cloud User Guide. Type: xsd:boolean A list of VPC security groups the instance is in. Each group's information is wrapped in an item element. Type: GroupItemType (p. 410) The reason for the most recent state transition. See StateReasonType (p. 457) for a listing of supported state change codes. Type: StateReasonType (p. 457) The architecture of the image. Type: xsd:string Valid Values: i386 | x86_64 The root device type used by the AMI. The AMI can use an Amazon EBS or instance store root device. Type: xsd:string Valid Values: ebs | instance-store The root device name (e.g., /dev/sda1). Type: xsd:string

platform

monitoring

subnetId

vpcId

privateIpAddress

ipAddress

sourceDestCheck

groupSet

stateReason

architecture

rootDeviceType

rootDeviceName

API Version 2012-05-01 450

Amazon Elastic Compute Cloud API Reference SecurityGroupIdSetItemType

Name
blockDeviceMapping

Description A list of block device mappings for the instance. Each mapping's information is wrapped in an item element. Type: InstanceBlockDeviceMappingResponseItemType (p. 415) Whether this is a Spot Instance. Type: xsd:string Valid Values: spot | blank (no value) The ID of the Spot Instance request. Type: xsd:string The instance's virtualization type. Type: xsd:string Valid Values: paravirtual | hvm Idempotency token you provided when you launched the instance. Type: xsd:string Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445) The instance's hypervisor type. Type: xsd:string Valid Values: ovm | xen Type: InstanceNetworkInterfaceSetType (p. 423)

instanceLifecycle

spotInstanceRequestId

virtualizationType

clientToken

tagSet

hypervisor

networkInterfaceSet

SecurityGroupIdSetItemType
The SecurityGroupIdSetItemType data type.

Ancestors
LaunchSpecificationResponseType LaunchSpecificationRequestType InstanceNetworkInterfaceSetItemRequestType

Relevant Operations
CreateNetworkInterface ModifyNetworkInterfaceAttribute ModifyInstanceAttribute RequestSpotInstances DescribeSpotInstanceRequests

API Version 2012-05-01 451

Amazon Elastic Compute Cloud API Reference Contents

RunInstances

Contents
The following table describes the elements contained in SecurityGroupItemType. Name
groupId

Description ID of the security group associated with the network interface. Type: xsd:string

SecurityGroupItemType
The SecurityGroupItemType data type.

Ancestors
SecurityGroupSetType

Relevant Operations
DescribeSecurityGroups

Contents
The following table describes the elements contained in SecurityGroupItemType. Name
ownerId

Description AWS account ID of the owner of the security group. Type: xsd:string ID of the security group. Type: xsd:string Name of the security group. Type: xsd:string Description of the security group. Type: xsd:string ID of the VPC the security group is in (for VPC security groups). Type: xsd:string A list of inbound rules associated with the security group. Each permission is wrapped in an item element. Type: IpPermissionType (p. 428)

groupId

groupName

groupDescription

vpcId

ipPermissions

API Version 2012-05-01 452

Amazon Elastic Compute Cloud API Reference SpotDatafeedSubscriptionType

Name
ipPermissionsEgress

Description A list of outbound rules associated with the security group (for VPC security groups). Each permission is wrapped in an item element. Type: IpPermissionType (p. 428) Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

tagSet

SpotDatafeedSubscriptionType
The SpotDatafeedSubscriptionType data type.

Ancestors
CreateSpotDatafeedSubscriptionResponseType DescribeSpotDatafeedSubscriptionResponseType

Relevant Operations
CreateSpotDatafeedSubscription DescribeSpotDatafeedSubscription

Contents
The following table describes the elements contained in SpotDatafeedSubscriptionType. Name
ownerId

Description The AWS account ID of the account. Type: xsd:string The Amazon S3 bucket where the Spot Instance datafeed is located. Type: xsd:string Prefix that is prepended to datafeed files. Type: xsd:string The state of the Spot Instance datafeed subscription. Type: xsd:string Valid Values: Active | Inactive Fault codes for the Spot Instance request, if any. Type: SpotInstanceStateFaultType (p. 455)

bucket

prefix

state

fault

API Version 2012-05-01 453

Amazon Elastic Compute Cloud API Reference SpotInstanceRequestSetItemType

SpotInstanceRequestSetItemType
The SpotInstanceRequestSetItemType data type.

Ancestors
SpotInstanceRequestSetType

Relevant Operations
DescribeSpotInstanceRequests RequestSpotInstances

Contents
The following table describes the elements contained in SpotInstanceRequestSetItemType. Name
spotInstanceRequestId

Description The ID of the Spot Instance request. Type: xsd:string The maximum hourly price for any Spot Instance launched to fulfill the request. Type: xsd:string The Spot Instance request type. Type: xsd:string Valid Values: one-time | persistent The state of the Spot Instance request. Type: xsd:string Valid Values: open | closed | cancelled | failed Fault codes for the Spot Instance request, if any. Type: SpotInstanceStateFaultType (p. 455) Start date of the request. If this is a one-time request, the request becomes active at this date and time and remains active until all instances launch, the request expires, or the request is canceled. If the request is persistent, the request becomes active at this date and time and remains active until it expires or is canceled. Type: xsd:dateTime End date of the request. If this is a one-time request, the request remains active until all instances launch, the request is canceled, or this date is reached. If the request is persistent, it remains active until it is canceled or this date is reached. Type: xsd:dateTime

spotPrice

type

state

fault

validFrom

validUntil

API Version 2012-05-01 454

Amazon Elastic Compute Cloud API Reference SpotInstanceStateFaultType

Name
launchGroup

Description The instance launch group. Launch groups are Spot Instances that launch together and terminate together. Type: xsd:string The Availability Zone group. If you specify the same Availability Zone group for all Spot Instance requests, all Spot Instances are launched in the same Availability Zone. Type: xsd:string

availabilityZoneGroup

launchedAvailabilityZone The Availability Zone in which the bid is launched. Type: xsd:string launchSpecification

Additional information for launching instances. Type: LaunchSpecificationResponseType (p. 431) The instance ID, if an instance has been launched to fulfill the Spot Instance request. Type: xsd:string Time stamp when the Spot Instance request was created. Type: xsd:dateTime The product description associated with the Spot Instance. Type: xsd:string Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

instanceId

createTime

productDescription

tagSet

SpotInstanceStateFaultType
The SpotInstanceStateFaultType data type.

Ancestors
SpotDatafeedSubscriptionType (p. 453) SpotInstanceRequestSetItemType (p. 454)

Relevant Operations
CreateSpotDatafeedSubscription DescribeSpotDatafeedSubscription DescribeSpotInstanceRequests RequestSpotInstances

API Version 2012-05-01 455

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in SpotInstanceStateFaultType. Name
code

Description Reason code for the Spot Instance state change. Type: xsd:string Message for the Spot Instance state change. Type: xsd:string

message

SpotPriceHistorySetItemType
The SpotPriceHistorySetItemType data type.

Ancestors
SpotPriceHistorySetType

Relevant Operations
DescribeSpotPriceHistory

Contents
The following table describes the elements contained in SpotPriceHistorySetItemType. Name
instanceType

Description The instance type. Type: xsd:string General description of the AMI. Type: xsd:string Valid Values: Linux/UNIX | SUSE Linux | Windows The maximum price you will pay to launch one or more Spot Instances. Type: xsd:string The date and time the request was created. Type: xsd:dateTime The Availability Zone. Type: xsd:string

productDescription

spotPrice

timestamp

availabilityZone

API Version 2012-05-01 456

Amazon Elastic Compute Cloud API Reference StateReasonType

StateReasonType
The StateReasonType data type.

Ancestors
DescribeImagesResponseItemType (p. 397) RunningInstancesItemType (p. 448)

Relevant Operations
DescribeImages DescribeInstances RunInstances

Contents
The following table describes the elements contained in StateReasonType. Name
code

Description Reason code for the state change. See the following table for a list of codes. Type: xsd:string Message for the state change. Type: xsd:string

message

The following table lists the currently supported state reason codes. Code
Server.SpotInstanceT ermination Server.InternalError

Description A Spot Instance was terminated due to an increase in the market price. An internal error occurred during instance launch, resulting in termination. There was insufficient instance capacity to satisfy the launch request.

Server.InsufficientI nstanceCapacity Client.InternalError Client.InstanceIniti atedShutdown Client.UserInitiated Shutdown

A client error caused the instance to terminate on launch. The instance initiated shutdown by a shutdown -h command issued from inside the instance. The instance was shutdown by a user via an API call.

API Version 2012-05-01 457

Amazon Elastic Compute Cloud API Reference SubnetType

Code
Client.VolumeLimitEx ceeded Client.InvalidSnapsh ot.NotFound

Description The volume limit was exceeded.

The specified snapshot was not found.

SubnetType
The SubnetType data type.

Ancestors
CreateSubnetResponse SubnetSetType

Relevant Operations
CreateSubnet DescribeSubnets

Contents
The following table describes the elements contained in SubnetType. Name
subnetId

Description The subnet's ID. Type: String The current state of the subnet. Type: String Valid Values: pending | available The ID of the VPC the subnet is in. Type: String The CIDR block assigned to the subnet. Type: String The number of unused IP addresses in the subnet (the IP addresses for any stopped instances are considered unavailable). Type: Integer The Availability Zone the subnet is in. Type: String

state

vpcId

cidrBlock

availableIpAddressCount

availabilityZone

API Version 2012-05-01 458

Amazon Elastic Compute Cloud API Reference TagSetItemType

Name
tagSet

Description Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

TagSetItemType
The TagSetItemType data type.

Relevant Operations
DescribeTags

Contents
The following table describes the elements contained in TagSetItemType. Name
resourceId

Description The resource's ID. For example, ami-1a2b3c4d. Type: String Type of resource. Type: String Valid Values: customer-gateway | dhcp-options | image | instance | internet-gateway | network-acl | reserved-instances | route-table | security-group | snapshot | spot-instances-request | subnet | volume | vpc | vpn-connection | vpn-gateway The tag's key. Type: String The tag's value. Type: String

resourceType

key

value

UserDataType
The UserDataType data type.

Ancestors
LaunchSpecificationRequestType (p. 430) RunInstancesType

API Version 2012-05-01 459

Amazon Elastic Compute Cloud API Reference Relevant Operations

Relevant Operations
RequestSpotInstances DescribeSpotInstanceRequests RequestSpotInstances RunInstances

Contents
The following table describes the elements contained in UserDataType. Name
data

Description Base64-encoded MIME user data made available to the instance(s) in the reservation. Type: xsd:string

UserIdGroupPairType
The UserIdGroupPairType data type.

Ancestors
UserIdGroupPairSetType

Relevant Operations
AuthorizeSecurityGroupEgress AuthorizeSecurityGroupIngress RevokeSecurityGroupEgress RevokeSecurityGroupIngress DescribeSecurityGroups

Contents
The following table describes the elements contained in UserIdGroupPairType. Name
userId

Description ID of an AWS account. Cannot be used when specifying a CIDR IP address range. Type: xsd:string

API Version 2012-05-01 460

Amazon Elastic Compute Cloud API Reference ValueType

Name
groupId

Description ID of the security group in the specified AWS account. Cannot be used when specifying a CIDR IP address range. Type: xsd:string Name of the security group in the specified AWS account. Cannot be used when specifying a CIDR IP address range. Type: xsd:string

groupName

ValueType
The ValueType data type.

Ancestors
ValueSetType

Relevant Operations
DescribeVpcs DescribeSubnets DescribeVpnGateways DescribeCustomerGateways DescribeVpnConnections

Contents
The following table describes the elements contained in ValueType. Name
value

Description An individual value. Type: String

VolumeStatusItemType
The VolumeStatusItemType data type.

Ancestors
VolumeStatusSetType

API Version 2012-05-01 461

Amazon Elastic Compute Cloud API Reference Relevant Operation

Relevant Operation
DescribeVolumeStatus

Contents
The following table describes the elements contained in VolumeStatusItemType. Name
volumeId

Description The volume ID. Type: String Availability Zone of the volume. Type: String Status of the volume. The status of each volume is wrapped in an item element. Type: VolumeStatusInfoType (p. 462). A list of events associated with the volume. Each event is wrapped in an item element. Type: VolumeStatusEventItemType (p. 463). Details of the action. Each action is wrapped in an item element. Type: VolumeStatusActionItemType (p. 464).

availabilityZone

volumeStatus

eventSet

actionSet

VolumeStatusInfoType
The VolumeStatusInfoType data type.

Ancestors
VolumeStatusItemType

Relevant Operation
DescribeVolumeStatus

Contents
The following table describes the elements contained in VolumeStatusInfoType.

API Version 2012-05-01 462

Amazon Elastic Compute Cloud API Reference VolumeStatusDetailsItemType

Name
status

Description The status of the volume. Type: String Valid Values : ok | impaired |insufficient-data Details of the volume status. The volume status details are wrapped in an item type. Type: VolumeStatusDetailsItemType (p. 463).

details

VolumeStatusDetailsItemType
The VolumeStatusDetailsItemType data type.

Ancestors
VolumeStatusInfoType

Relevant Operation
DescribeVolumeStatus

Contents
The following table describes the elements contained in VolumeStatusDetailsItemType. Name
name

Description The name of the volume's status. Type: String The intended status of the volume status. Type: String

status

VolumeStatusEventItemType
The VolumeStatusEventItemType data type.

Ancestors
VolumeStatusItemType

Relevant Operation
DescribeVolumeStatus
API Version 2012-05-01 463

Amazon Elastic Compute Cloud API Reference Contents

Contents
The following table describes the elements contained in VolumeStatusEventItemType. Name
eventType

Description The type of this event. Type: String The ID of this event. Type: String A description of the event. Type: String The earliest start time of the event. Type: dateTime The latest end time of the event. Type: dateTime

eventId

description

notBefore

notAfter

VolumeStatusActionItemType
The VolumeStatusActionItemType data type.

Ancestors
VolumeStatusItemType

Relevant Operation
DescribeVolumeStatus

Contents
The following table describes the elements contained in VolumeStatusActionItemType. Name
code

Description The code identifying the action. Type: String The event type associated with this action. Type: String The ID of the event associated with this action. Type: String

eventType

eventId

API Version 2012-05-01 464

Amazon Elastic Compute Cloud API Reference VpcType

Name
description

Description A description of the action. Type: String

VpcType
The VpcType data type.

Ancestors
CreateVpcResponse VpcSetType

Relevant Operations
CreateVpc DescribeVpcs

Contents
The following table describes the elements contained in VpcType. Name
vpcId

Description The VPC's ID. Type: String The current state of the VPC. Type: String Valid Values: pending | available The CIDR block the VPC covers. Type: String The ID of the set of DHCP options you've associated with the VPC (or "default" if the default options are associated with the VPC). Type: String Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445) The allowed tenancy of instances launched into the VPC. Type: String

state

cidrBlock

dhcpOptionsId

tagSet

instanceTenancy

API Version 2012-05-01 465

Amazon Elastic Compute Cloud API Reference VpnConnectionType

VpnConnectionType
The VpnConnectionType data type.

Ancestors
CreateVpnConnectionResponse VpnConnectionSetType

Relevant Operations
CreateVpnConnection DescribeVpnConnections

Contents
The following table describes the elements contained in VpnConnectionType. Name
vpnConnectionId

Description The ID of the VPN connection. Type: String The current state of the VPN connection. Type: String Valid Values: pending | available | deleting | deleted

state

customerGatewayConfiguration Configuration information for the VPN connection's customer gateway (in the native XML format). This element is always present in the CreateVpnConnection response; however, it's present in the DescribeVpnConnections response only if the VPN connection is in the pending or available state. Type: String type

The type of VPN connection (ipsec.1). Type: String ID of the customer gateway at your end of the VPN connection. Type: String ID of the virtual private gateway at the VPC end of the VPN connection. Type: String Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

customerGatewayId

vpnGatewayId

tagSet

API Version 2012-05-01 466

Amazon Elastic Compute Cloud API Reference VpnGatewayType

Name
vgwTelemetry

Description Information about the virtual private gateway. Each gateway's information is wrapped in an item element. Type: VpnTunnelTelemetryType (p. 468)

VpnGatewayType
The VpnGatewayType data type contains information about a virtual private gateway.

Ancestors
CreateVpnGatewayResponse VpnGatewaySetType

Relevant Operations
CreateVpnGateway DescribeVpnGateways

Contents
The following table describes the elements contained in VpnGatewayType. Name
vpnGatewayId

Description The ID of the virtual private gateway. Type: String The current state of the virtual private gateway. Type: String Valid Values: pending | available | deleting | deleted The type of VPN connection the virtual private gateway supports (ipsec.1). Type: String The Availability Zone where the virtual private gateway was created. Type: String A list of VPCs attached to the virtual private gateway. Each VPC's information is wrapped in an item element. Type: AttachmentType (p. 387) Tags assigned to the resource. Each tag's information is wrapped in an item element. Type: ResourceTagSetItemType (p. 445)

state

type

availabilityZone

attachments

tagSet

API Version 2012-05-01 467

Amazon Elastic Compute Cloud API Reference VpnTunnelTelemetryType

VpnTunnelTelemetryType
The VpnTunnelTelemetryType data type.

Ancestors
VgwTelemetryType

Relevant Operations
CreateVpnConnection DescribeVpnConnections

Contents
The following table describes the elements contained in VpnTunnelTelemetryType. Name
outsideIpAddress

Description The Internet-routable IP address of the virtual private gateway's outside interface. Type: String The status of the VPN tunnel. Type: String Valid Values: UP | DOWN The date and time of the last change in status. Type: dateTime If an error occurs, a description of the error. Type: String The number of accepted routes. Type: int

status

lastStatusChange

statusMessage

acceptedRouteCount

API Version 2012-05-01 468

Amazon Elastic Compute Cloud API Reference

Common Query Parameters

All Query actions share a set of common parameters that must be present in each call. Name
Action

Description Indicates the action to perform. Example: RunInstances The API version to use, as specified in the WSDL. Example: 2012-05-01

Required Yes

Version

Yes

AWSAccessKeyId

The Access Key ID for the request sender. This identifies Yes the account which will be charged for usage of the service. The account with which the Access Key ID is associated must be signed up for Amazon EC2, or requests will not be accepted. AKIAIOSFODNN7EXAMPLE The date and time at which the request is signed, in the format YYYY-MM-DDThh:mm:ssZ. For more information, go to ISO 8601. Example: 2006-07-07T15:04:56Z Yes

Timestamp

Expires

The date and time at which the signature included in the Yes request expires, in the format YYYY-MM-DDThh:mm:ssZ. Example: 2006-07-07T15:04:56Z The temporary security token obtained through a call to No AWS Security Token Service. For more information, go to Using Temporary Security Credentials in the Amazon Elastic Compute Cloud User Guide. Default: None Type: String The request signature. For more information, go to Making Yes Query Requests in the Amazon Elastic Compute Cloud User Guide. Example: Qnpl4Qk/7tINHzfXCiT7VEXAMPLE

SecurityToken

Signature

API Version 2012-05-01 469

Amazon Elastic Compute Cloud API Reference

Name
SignatureMethod

Description The hash algorithm you use to create the request signature. Valid values: HmacSHA256 | HmacSHA1. For more information, go to Making Query Requests in the Amazon Elastic Compute Cloud User Guide. Example: HmacSHA256

Required Yes

SignatureVersion

The signature version you use to sign the request. Set this Yes value to 2. For more information, go to Making Query Requests in the Amazon Elastic Compute Cloud User Guide. Example: 2

Note
The Timestamp parameter can be used instead of Expires. Requests must include either Timestamp or Expires, but cannot contain both.

Parameter values must be URL-encoded. This is true for any Query parameter passed to Amazon EC2 and is typically necessary in the Signature parameter. Some clients do this automatically, but this is not the norm.

API Version 2012-05-01 470

Amazon Elastic Compute Cloud API Reference Overview

Error Codes
Overview
There are two types of error codes: client and server. Client error codes suggest that the error was caused by something the client did, such as an authentication failure or an invalid AMI identifier. In the SOAP API, these error codes are prefixed with Client. For example: Client.AuthFailure. In the Query API, these errors are accompanied by a 400-series HTTP response code. Server error codes suggest a server-side issue caused the error and should be reported. In the SOAP API, these error codes are prefixed with Server. For example: Server.Unavailable. In the Query API, these errors are accompanied by a 500-series HTTP response code.

Summary of Client Error Codes

Error Code
AddressLimitExceeded

Description You've reached the limit on the number of elastic IP addresses your account can have.

Notes Each AWS account has an EC2 elastic IP address limit. For new accounts, this limit is 5. If you need more than 5 EC2 elastic IP addresses, please complete the Amazon EC2 Elastic IP Address Request Form. We will ask you to think through your use case and help us understand your need for additional addresses. You have a separate limit for VPC elastic IP addresses (5). To request to increase the limit, complete the Amazon VPC Limits form.

API Version 2012-05-01 471

Amazon Elastic Compute Cloud API Reference Summary of Client Error Codes

Error Code
AttachmentLimitExceeded

Description You've reached the limit on the number of Amazon EBS volumes that can be attached to a single instance. User not authorized.

Notes

AuthFailure

You might be trying to run an AMI for which you do not have permission. Contact [email protected] if you have questions.

Blocked

The account is currently blocked. You've reached the limit on the number of customer gateways you can create. The specified object has dependent resources. The disk image exceeds the allowed limit (for instance or volume import). Request uses too many filters or too many total filter values. Specified gateway isn't attached, so it can't be detached. Request uses the same client token as a previous, but non-identical request. Instance is in an incorrect state so the attempted action cannot occur. Volume is in an incorrect state. Account has maximum allowed concurrent running instances.

CustomerGatewayLimitExceeded

DependencyViolation

DiskImageSizeTooLarge

FilterLimitExceeded

Gateway.NotAttached

IdempotentParameterMismatch

Do not reuse a client token with different requests, unless the requests are identical.

IncorrectInstanceState

IncorrectState

To attach to an instance, it must be in the 'available' state. Each AWS account has a concurrent running instance limit. For new accounts, this limit is 20. If you need more than 20 instances, please complete the Amazon EC2 Instance Request Form and your request will be considered.

InstanceLimitExceeded

InsufficientInstanceCapacity

There is insufficient capacity The returned message gives available for the requested guidance on how to solve the instance type. problem.

API Version 2012-05-01 472

Amazon Elastic Compute Cloud API Reference Summary of Client Error Codes

Error Code
InsufficientReservedInstancesC apacity InternetGatewayLimitExceeded

Description Insufficient Reserved Instances capacity. You've reached the limit on the number of Internet gateways you can create. The value of an item added to, or removed from, an image attribute is invalid. Specified AMI ID is not valid. Specified AMI ID does not exist. Specified AMI ID has been deregistered and is no longer available. Specified association ID does not exist. The instance cannot detach from a volume to which it is not attached. Specified conversion task ID (for instance or volume import) is invalid. Conflict among chosen gateway IP addresses. The specified customer gateway ID does not exist. The device to which you are trying to attach (i.e. /dev/sdh) is already in use on the instance. Specified DHCP options ID does not exist. Specified disk format (for instance or volume import) is invalid. Specified filter is invalid. Specified gateway ID does not exist. Attempt to create a duplicate group. Specified group ID is invalid.

Notes

InvalidAMIAttributeItemValue

If you are specifying a userId, check that it is in the form of an AWS account ID.

InvalidAMIID.Malformed InvalidAMIID.NotFound

InvalidAMIID.Unavailable

InvalidAssociationID.NotFound

InvalidAttachment.NotFound

InvalidConversionTaskId

InvalidCustomerGateway.Duplica teIpAddress InvalidCustomerGatewayID.NotFo und InvalidDevice.InUse

InvalidDhcpOptionsID.NotFound

InvalidFormat

InvalidFilter InvalidGatewayID.NotFound

InvalidGroup.Duplicate

InvalidGroupId.Malformed

API Version 2012-05-01 473

Amazon Elastic Compute Cloud API Reference Summary of Client Error Codes

Error Code
InvalidGroup.InUse

Description Specified group cannot be deleted because it is in use. Specified group name does not exist. Specified group name is a reserved name. Specified instance ID is not valid. Specified instance ID does not exist.

Notes

InvalidGroup.NotFound

InvalidGroup.Reserved

InvalidInstanceID.Malformed

InvalidInstanceID.NotFound

InvalidInternetGatewayID.NotFound Specified Internet gateway ID does not exist. InvalidIPAddress.InUse

Specified IP address is currently in use. Attempt to create a duplicate key pair. Format of the public key you've attempted to import is invalid. Specified key pair name does not exist. Specified AMI has an unparsable manifest. Specified network ACL entry does not exist. Specified network ACL ID does not exist. Example: RunInstances was called with both minCount and maxCount set to 0, or minCount > maxCount. The value supplied for a parameter was invalid. Requests that could cause this error include (for example) supplying an invalid image attribute to the DescribeImageAttribute request or an invalid version or encoding value for the userData in a RunInstances request.

InvalidKeyPair.Duplicate

InvalidKeyPair.Format

InvalidKeyPair.NotFound

InvalidManifest

InvalidNetworkAclEntry.NotFound

InvalidNetworkAclID.NotFound

InvalidParameterCombination

InvalidParameterValue

InvalidPermission.Duplicate

Attempt to authorize a permission that has already been authorized.

API Version 2012-05-01 474

Amazon Elastic Compute Cloud API Reference Summary of Client Error Codes

Error Code
InvalidPermission.Malformed

Description Specified permission is invalid. Specified reservation ID is invalid. Specified reservation ID does not exist. Specified route does not exist in the route table. Specified route table ID does not exist. The difference between the request timestamp and the AWS server time is greater than 5 minutes. The snapshot ID that was passed as an argument was malformed. The specified snapshot does not exist. The user ID is neither in the form of an AWS account ID or one of the special values accepted by the owner or executableBy flags in the DescribeImages call. Reserved Instances ID not found. Reserved Instances Offering ID not found. Specified subnet ID does not exist. Volume already exists in the system. Specified volume ID was malformed. Specified volume ID and instance ID are in different Availability Zones. Specified volume does not exist. Specified VPC ID does not exist.

Notes

InvalidReservationID.Malformed

InvalidReservationID.NotFound

InvalidRoute.NotFound

InvalidRouteTableID.NotFound

InvalidSecurity.RequestHasExpi red

Ensure that your system clock is accurate and configured to use the correct time zone.

InvalidSnapshotID.Malformed

InvalidSnapshot.NotFound

InvalidUserID.Malformed

InvalidReservedInstancesId

InvalidReservedInstancesOfferi ngId InvalidSubnetID.NotFound

InvalidVolumeID.Duplicate

InvalidVolumeID.Malformed

InvalidVolumeID.ZoneMismatch

InvalidVolume.NotFound

InvalidVpcID.NotFound

API Version 2012-05-01 475

Amazon Elastic Compute Cloud API Reference Summary of Client Error Codes

Error Code
InvalidVpnConnectionID.NotFound

Description The specified VPN connection ID does not exist. Specified virtual private gateway ID does not exist. The specified zone does not exist. You must delete the 2009-07-15-default security group before you can attach an Internet gateway. The request is missing a required parameter. Specified rule number already exists in this network ACL. You've reached the limit on the number of network ACL entries you can add to the ACL. You've reached the limit on the number of network ACLs you can create.

Notes

InvalidVpnGatewayID.NotFound

InvalidZone.NotFound

LegacySecurityGroup

MissingParameter

NetworkAclEntryAlreadyExists

NetworkAclEntryLimitExceeded

NetworkAclLimitExceeded

NonEBSInstance

The instance specified does Please restart the instance not support EBS. and try again. This will ensure that the code is run on an instance with updated code. You've reached the limit on the number of Amazon EBS snapshots you can have in the pending state. The account is pending verification. Contact [email protected] if you have questions.

PendingSnapshotLimitExceeded

PendingVerification

OptInRequired

The user is not authorized to This error message can use the requested product. apply to Amazon EC2 or individual AWS Marketplace product codes. The maximum request rate permitted by the Amazon EC2 APIs has been exceeded for your account. Retry your request after a few seconds.

RequestLimitExceeded

API Version 2012-05-01 476

Amazon Elastic Compute Cloud API Reference Summary of Client Error Codes

Error Code
ReservedInstancesLimitExceeded

Description Your current quota does not allow you to purchase the required number of reserved instances. Specified gateway is already attached, or specified subnet is already associated with another object. Exceeded an EC2 resource limit. A route for the specified CIDR block already exists in this route table. You've reached the limit on the number of routes you can add to a route table. You've reached the limit on the number of route tables you can create. You've reached the limit on the number of rules you can add to a security group. You've reached the limit on the number of security groups you can create. You've reached the limit on the number of security groups you can put an instance into. You've reached the limit on the number of Amazon EBS snapshots you can create. You've reached the limit on the number of subnets you can create for the VPC.

Notes

Resource.AlreadyAssociated

ResourceLimitExceeded

Example: You reached the maximum number of import conversion tasks allowed.

RouteAlreadyExists

RouteLimitExceeded

RouteTableLimitExceeded

RulesPerSecurityGroupLimitExce eded

SecurityGroupLimitExceeded

SecurityGroupsPerInstanceLimit Exceeded

SnapshotLimitExceeded

SubnetLimitExceeded

UnknownParameter

An unknown or unrecognized Requests that could cause parameter was supplied. this error include supplying a misspelled parameter or a parameter that is not supported for the specified API version.

API Version 2012-05-01 477

Amazon Elastic Compute Cloud API Reference Summary of Server Error Codes

Error Code
UnsupportedOperation

Description

Notes

The instance type or feature The returned message gives is not supported in your guidance on how to solve the requested Availability Zone problem. or with the requested configuration. You've reached the limit on the number of Amazon EBS volumes you can create. You've reached the limit on the number of VPCs you can create. You've reached the limit on the number of VPN connections you can create. You've reached the limit on the number of VPCs that can be attached to the given virtual private gateway. You've reached the limit on the number of virtual private gateways you can create.

VolumeLimitExceeded

VpcLimitExceeded

VpnConnectionLimitExceeded

VpnGatewayAttachmentLimitExcee ded

VpnGatewayLimitExceeded

Summary of Server Error Codes

Error Code
InsufficientAddressCapacity

Description Not enough available addresses to satisfy your minimum request.

Notes Reduce the number of addresses you are requesting or wait for additional capacity to become available. Reduce the number of instances in your request or wait for additional capacity to become available. The returned message might also give specific guidance on how to solve the problem. Reduce the number of Reserved Instances in your request or wait for additional capacity to become available.

InsufficientInstanceCapacity Not enough available instances to satisfy your minimum request.

InsufficientReservedInstanceCa Not enough available Reserved pacity Instances to satisfy your minimum request.

API Version 2012-05-01 478

Amazon Elastic Compute Cloud API Reference Request Error Response

Error Code
InternalError

Description Internal Error.

Notes This error should not occur. If this persists, please contact us with details by posting a message on the AWS forums.

Unavailable

The server is overloaded and cannot handle the request.

Request Error Response

The following shows the structure of a request error response.
<<Response> <Errors> <Error> <Code>Error code text</Code> <Message>Error message</Message> </Error> </Errors> <RequestID>request ID</RequestID> </Response>

Example Error Response Request

The following shows an example of an error response.
<Response> <Errors> <Error> <Code>InvalidInstanceID.NotFound</Code> <Message>The instance ID 'i-4cbc822a' does not exist</Message> </Error> </Errors> <RequestID>ea966190-f9aa-478e-9ede-cb5432daacc0</RequestID> </Response>

API Version 2012-05-01 479

Amazon Elastic Compute Cloud API Reference

Amazon EC2 Resources

The following table lists related resources that you'll find useful as you work with this service. Resource Description

Amazon Elastic Compute Cloud Getting Provides a quick tutorial of the service based on a simple use Started Guide case. Examples and instructions are included. Amazon Elastic Compute Cloud User Guide Amazon Elastic Compute Cloud Command Line Reference Amazon EC2 Technical FAQ Amazon EC2 Release Notes Provides conceptual information about Amazon EC2 and describes how to use Amazon EC2 features using the AWS Management Console, command line tools, and Query API. Contains a comprehensive description of all the command line tools and their options. Covers the top questions developers have asked about this product. Give a high-level overview of the current release. They specifically note any new features, corrections, and known issues. A central starting point to find documentation, code samples, release notes, and other information to help you build innovative applications with AWS. The console lets you perform most of the functions of Amazon EC2 and other AWS products without programming. A community-based forum for developers to discuss technical questions related to Amazon Web Services. The home page for AWS Technical Support, including access to our Developer Forums, Technical FAQs, Service Status page, and AWS Premium Support (if you are subscribed to this program). The primary web page for information about AWS Premium Support, a one-on-one, fast-response support channel to help you build and run applications on AWS Infrastructure Services.

AWS Developer Resource Center

AWS Management Console

Discussion Forums

AWS Support Center

AWS Premium Support Information

API Version 2012-05-01 480

Amazon Elastic Compute Cloud API Reference

Resource Amazon EC2 Product Information

Description The primary web page for information about Amazon EC2.

Form for questions related to your AWS This form is only for account questions. For technical account: Contact Us questions, use the Discussion Forums. Terms of Use Detailed information about the copyright and trademark usage at Amazon.com and other topics.

API Version 2012-05-01 481

Amazon Elastic Compute Cloud API Reference

Document History
The following table describes the important changes since the last release of the Amazon EC2 documentation set. API version: 2012-05-01. Latest documentation update: April 19, 2012. Change Support for AWS Marketplace and a New API Version Support Amazon EBS Volume Status Check Description Added support for AWS Marketplace AMIs and a new API version: 2012-04-01. Release Date 19 April 2012

18 April 2012 Starting with API version 2012-03-01, you can check the 12 March 2012 operational status of your Amazon EBS volume. The volume status check gives you information about the I/O, also known as read/write, capability of your EBS volumes. The volume status check lets you know when an EBS volumes data is potentially inconsistent. Amazon Web Services (AWS) gives you options to handle the potentially inconsistent volume. For information on the actions related to this release, see: DescribeVolumeStatus (p. 267) ModifyVolumeAttribute (p. 320) DescribeVolumeAttribute (p. 265) EnableVolumeIO (p. 295)

Instance Status Checks

Starting with API version 2011-12-15, you can use the 30 December DescribeInstanceStatus action to retrieve results of automated 2011 checks performed by Amazon EC2.These status checks detect problems that may impair an instances ability to run your applications. You can use ReportInstanceStatus to send us feedback or report an inaccurate instance status.

API Version 2012-05-01 482

Amazon Elastic Compute Cloud API Reference

Change Elastic Network Interfaces (ENIs) for Amazon EC2 Instances in Amazon Virtual Private Cloud

Description

Release Date

Starting with API version 2011-12-01, you can attach an elastic 21 December network interface (ENI) to an EC2 instance in a VPC. For more 2011 information, see: AttachNetworkInterface (p. 24) DetachNetworkInterface (p. 285) CreateNetworkInterface (p. 70) DeleteNetworkInterface (p. 112) DescribeNetworkInterfaces (p. 205) DescribeNetworkInterfaceAttribute (p. 203) ModifyNetworkInterfaceAttribute (p. 316) ResetNetworkInterfaceAttribute (p. 356)

New Offering Types for Amazon EC2 Reserved Instances

Starting with API version 2011-11-01, you can use the new 01 December offering-type parameter of 2011 DescribeReservedInstancesOfferings to identify the Reserved Instance offerings that address your projected use: Heavy Utilization, Medium Utilization, and Light Utilization. See DescribeReservedInstancesOfferings (p. 221). The Request Parameters (p. 188) API action allows you to view 14 November the status of your instances and any upcoming scheduled 2011 events.

Support for Amazon EC2 Instance Status

Support for Amazon The RequestSpotInstances (p. 346) action is updated with the 11 October EC2 Spot Instances in subnet option, which enables you to specify an Amazon VPC 2011 Amazon VPC subnet into which to launch your Spot Instances. Support for VHD file format added to the 2011-07-15 API version Updates for the 2011-07-15 API version Temporary Security Credentials We've added VHD as one of the VM file formats supported for 24 August import into Amazon EC2. See the API actions ImportInstance 2011 and ImportVolume, and the CLI commands ec2-import-instance and ec2-import-volume. We've added one new data type, VpnTunnelTelemetryType (p. 468), for the 2011-07-15 API release. 03 August 2011

We've added one new common request parameter, 03 August SecurityToken, that supports temporary security credentials. 2011 For more information, see Common Query Parameters (p. 469) or go to Using Temporary Security Credentials in the Amazon Elastic Compute Cloud User Guide. We've updated several actions that explain API changes for 26 May 2011 the Spot Instances Availability Zone pricing feature. We've also added new Availability Zone pricing options as part of the information returned by Spot Instance Requests and Spot Price History API calls. We've updated several existing actions for the 2011-05-15 API 26 May 2011 release.

Spot Instances Availability Zone pricing changes

Updates for the 2011-05-15 API Version

API Version 2012-05-01 483

Amazon Elastic Compute Cloud API Reference

Change Dedicated Instances

Description

Release Date

As part of the Dedicated Instances feature release, we've 27 March 2011 added new options related to the tenancy attribute of instances, and the instance tenancy attribute of VPCs. We've updated several existing actions for the 2011-02-28 API 27 March 2011 release.

Updates for the 2011-02-28 API version Updates for the 2011-01-01 API version

We've added new actions and updated several existing actions 11 March 2011 for the 2011-01-01 API release. The new and updated actions are related to these Amazon VPC objects: Internet gateways, route tables, network ACLs, VPC security groups, and VPC Elastic IP addresses. 11 March 2011

Merged Amazon VPC We've merged the Amazon VPC actions into this guide. Documentation VM Import Added the following new actions, which allow you to import a virtual machine or volume into Amazon EC2: ImportInstance (p. 301) ImportVolume (p. 307) DescribeConversionTasks (p. 150) CancelConversionTask (p. 43)

15 December 2010

Consolidated Documentation

We've consolidated the Query and SOAP API topics. See Actions (p. 9).

06 December 2010 20 November 2010

Parameters for Updated the list of Query parameters for ModifyImageAttribute ModifyImageAttribute (p. 310) and for and ModifyInstanceAttribute (p. 313). ModifyInstanceAttribute Modifying Block Device Mapping

Removed information from ModifyInstanceAttribute (p. 313) 20 November about modifying an instance's block device mapping attribute. 2010 You currently can't modify an instance's block device mapping with this action. Added information about filters to many of the describe actions. 19 September 2010 Added information about creating, describing, and deleting tags. For more information about the API actions for tags, see CreateTags (p. 88), DeleteTags (p. 127), and DescribeTags (p. 256). Updated RunInstances to include a ClientToken parameter 19 September 2010 to ensure idempotency. For more information about the change to RunInstances, see RunInstances (p. 366). Added ImportKeyPair . For more information, see ImportKeyPair (p. 305). 19 September 2010

Filters and Tags

Idempotent Instance Launch

Import Key Pair

API Version 2012-05-01 484

Amazon Elastic Compute Cloud API Reference

Change

Description

Release Date 12 July 2010

Placement Groups for Added information about placement groups, which you use Cluster Compute with cluster compute instances. Instances For more information about the API actions for placement groups, see CreatePlacementGroup (p. 72), DescribePlacementGroups (p. 211), and DeletePlacementGroup (p. 114). Amazon VPC IP Address Designation

Amazon VPC users can now specify the IP address to assign 12 July 2010 an instance launched in a VPC. For information about using the PrivateIpAddress parameter with the RunInstances action, see RunInstances (p. 366). Updated the list of errors to include Client.Blocked, Client.InsufficientInstanceCapacity, Client.PendingVerification, and Client.Unsupported. For more information, see Error Codes (p. 471). Clarified the information about authorizing security group permissions. For more information, see AuthorizeSecurityGroupIngress (p. 34). Amazon EC2 now supports the Asia Pacific (Singapore) Region. The new endpoint for requests to this Region is ec2.ap-southeast-1.amazonaws.com. 21 May 2010

Error List Update

Security Group Permissions

28 April 2010

New Region

28 April 2010

Clarification about Spot Instances

Clarified that you can't stop and start Spot Instances that use 1 February an Amazon EBS root device. For more information about 2010 stopping instances, see StopInstances (p. 378). To support customers that use Amazon EC2 instances, but 14 December have more flexible usage requirements (e.g., when instances 2009 run, how long they run, or whether usage completes within a specific timeframe), Amazon EC2 now provides Spot Instances. A Spot Instance is an instance that Amazon EC2 automatically runs for you when its maximum price is greater than the Spot Price. For conceptual information about Spot Instances, go to the Amazon Elastic Compute Cloud User Guide.

Spot Instances

API Version 2012-05-01 485