Amazon Elastic Compute Cloud
CLI 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...

ec2-associate-address

Description

Associates an Elastic IP address with an instance or a network interface. For more information, see Elastic IP Addresses in the Amazon Elastic Compute Cloud User Guide.

[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 do not 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 --allow-reassociation option.

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

The short version of this command is ec2assocaddr.

Syntax

ec2-associate-address [-i instance_id | -n interface_id] [ip_address | -a allocation_id] [--private-ip-address private_ip_address] [--allow-reassociation]

Options

NameDescription

-i, --instance instance_id

The ID of the instance.

Type: String

Default: None

Required: Conditional

Condition: Required for EC2-Classic. For EC2-VPC, you can specify either an instance ID or a network interface ID, but not both.

Example: -i i-43a4412a

ip_address

The Elastic IP address.

Type: String

Default: None

Required: Conditional

Condition: Required for EC2-Classic.

Example: 192.0.2.1

-a, --allocation-id allocation_id

[EC2-VPC] The allocation ID.

Type: String

Default: None

Required: Conditional

Condition: Required for EC2-VPC.

Example: -a eipalloc-5723d13e

-n, --network-interface interface_id

[EC2-VPC] The ID of the network interface. Association fails when specifying an instance ID unless exactly one interface is attached.

Type: String

Default: None

Required: Conditional

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

Example: -n eni-bc7299d4

-p, --private-ip-address private_ip_address

[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

Example: -p 10.0.0.45

--allow-reassociation

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

Type: Boolean

Default: The operation fails if the address is already associated.

Required: No

Example: --allow-reassociation

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. For more information, see Tell the Tools Who You Are.

Default: The value of the AWS_ACCESS_KEY environment variable. If AWS_ACCESS_KEY isn't set, you must specify this option.

Example: -O AKIAIOSFODNN7EXAMPLE

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

Default: The value of the AWS_SECRET_KEY environment variable. If AWS_SECRET_KEY isn't set, you must specify this option.

Example: -W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

-T, --security-token delegation_token

The AWS delegation token.

Default: The value of the environment variable (if set).

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

-H, --headers

Includes column headers in the command output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Omits tags for tagged resources.

--debug

Displays internal debugging information. This can assist us when helping you troubleshooting problems.

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-v, --verbose

Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to the Query API.

-

Reads arguments from standard input. This is useful when piping the output from one command to the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-K, --private-key ec2_private_key

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert ec2_cert

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following information:

  • The ADDRESS identifier

  • The Elastic IP address

  • The instance or network interface to which the Elastic IP address is associated

  • [EC2-VPC] The allocation ID

  • [EC2-VPC] If specified, the private IP address associated with the Elastic IP address

Amazon EC2 command line tools display errors on stderr.

Examples

Example 1

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

PROMPT> ec2-associate-address 203.0.113.0 -i i-43a4412a 
ADDRESS 203.0.113.0 i-43a4412a

Example 2

This example command associates an Elastic IP address with an instance in a VPC.

PROMPT> ec2-associate-address -a eipalloc-5723d13e -i i-4fd2431a 
ADDRESS   i-43a4412a   eipalloc-5723d13e   eipassoc-fc5ca095

Example 3

This example command associates an Elastic IP address with a network interface.

PROMPT> ec2-associate-address -a eipalloc-4a4c6c23 -n eni-1001fa78 
ADDRESS   i-1ae1ae78   eipalloc-4a4c6c23   eipassoc-1841907a

Example 4

This example command associates an Elastic IP address with a private IP address for the specified instance in a VPC. The allow-reassociation option 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.

PROMPT> ec2-associate-address -a eipalloc-bf66dcd6 -i i-ba6a0dee  -p 10.0.0.85 --allow-reassociation

ADDRESS         i-ba6a0dee      eipalloc-bf66dcd6       eipassoc-9c66dcf5         10.0.0.85