Amazon Elastic Compute Cloud
API Reference (API Version 2014-06-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

AssociateAddress

Description

Associates an Elastic IP address with an instance or a network interface. For more information about Elastic IP addresses, see Elastic IP Addresses in the Amazon EC2 User Guide for Linux Instances.

[EC2-Classic, VPC in an EC2-VPC-only account] If the Elastic IP address is already associated with a different instance, it is disassociated from that instance and associated with the specified instance.

[VPC in an EC2-Classic account] If you don't specify a private IP address, the Elastic IP address is associated with the primary IP address. If the Elastic IP address is already associated with a different instance or a network interface, you get an error unless you specify the AllowReassociation parameter.

This is an idempotent operation. If you perform the operation more than once, Amazon EC2 doesn't return an error.

Request Parameters

For information about the common parameters that all actions use, see Common Query Parameters.

PublicIp

The Elastic IP address.

Type: String

Default: None

Required: Conditional

Condition: Required for Elastic IP addresses for use with instances in EC2-Classic.

InstanceId

The ID of the instance. The operation fails if you specify an instance ID unless exactly one network interface is attached.

Type: String

Default: None

Required: Conditional

Condition: Required for EC2-Classic. For a VPC, you can specify either InstanceID or NetworkInterfaceID, but not both.

AllocationId

[EC2-VPC] The allocation ID.

Type: String

Default: None

Required: Conditional

Condition: Required for EC2-VPC.

NetworkInterfaceId

[EC2-VPC] The ID of the network interface.

Type: String

Default: None

Required: Conditional

Condition: If the instance has more than one network interface, you must specify a network interface ID.

PrivateIpAddress

[EC2-VPC] The primary or secondary private IP address to associate with the Elastic IP address. If no private IP address is specified, the Elastic IP address is associated with the primary private IP address.

Type: String

Default: None

Required: No

AllowReassociation

[EC2-VPC] Allows an Elastic IP address that is already associated with an instance or network interface to be re-associated with the specified instance or network interface. Otherwise, the operation fails.

Type: Boolean

Default: false if not specified

Required: No

Response Elements

The following elements are returned in an AssociateAddressResponse element.

requestId

The ID of the request.

Type: xsd:string

return

Returns true if the request succeeds. Otherwise, returns an error.

Type: xsd:boolean

associationId

[EC2-VPC] The ID that represents the association of the Elastic IP address with an instance.

Type: xsd:string

Errors

The following are some of the client API errors you might encounter when using this request. For more information about common API errors, see Common Causes of Client Errors. For a summary of API error codes, see Client Error Codes.

Examples

Example Request

This example request associates an Elastic IP address with an instance in EC2-Classic.

https://ec2.amazonaws.com/?Action=AssociateAddress
&InstanceId=i-2ea64347
&PublicIp=192.0.2.1
&AUTHPARAMS

Example Response

<AssociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
  <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
  <return>true</return>
</AssociateAddressResponse>

Example Request

This example request associates a Elastic IP address with an instance in a VPC. The AllowReassignment parameter allows the Elastic IP address to be associated with the specified instance even if it's already associated with a different instance or a network interface.

https://ec2.amazonaws.com/?Action=AssociateAddress
&InstanceId=i-4fd2431a
&AllocationId=eipalloc-5723d13e
&AllowReassignment=true
&AUTHPARAMS

Example Response

<AssociateAddressResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
   <return>true</return>
   <associationId>eipassoc-fc5ca095</associationId>
</AssociateAddressResponse>