Elastic_IP_Address_Operations for the Amazon EC2 REST adapter - Documentation for BMC Atrium Orchestrator Content 20.16.03

This topic illustrates the adapter requests and responses for the Elastic IP Address operations.

An Elastic IP Address is a static IP address designed for dynamic cloud computing.

Allocate Address operation

The Allocate Address operation acquires an elastic IP address for use with your account either in the Amazon EC2 .

The following figure shows a sample <items> XML element for the Allocate Address operation.

Sample <items> XML element for the Allocate Address operation

<items> <item> <parameters> <domain></domain> </parameters> </item>
</items>

The following table describes the adapter request elements for this request.

Adapter request elements for the Allocate Address operation

Element	Definition	Required
`<access-key>`	Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Access Key is specified, the adapter ignores the value.
`<secret-key>`	Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Secret Access Key is specified, the adapter ignores the value.
`<region>`	Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values: us-east-1 us-west-2 (default) us-west-1 eu-west-1 ap-southeast-1 ap-northeast-1 ap-southeast-2 sa-east-1	No
`<operation-name>`	Contains the name of the operation: allocate-address	Yes
`<domain>`	Specifies whether to allocate the IP address to an EC2-Classic or to an EC2-virtual private cloud (VPC) platform Valid values: standard, vpc (default)	Conditional; required if you want to allocate the IP address to an EC2-VPC platform

The following figure shows a sample adapter request for the Allocate Address operation.

Sample adapter request for the Allocate Address operation

<amazon-ec2-rest-request> <operation-name>allocate-address</operation-name> <parameters> <domain>standard</domain> </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample adapter request for the Allocate Address operation.

Sample adapter response for the Allocate Address operation

<amazon-ec2-rest-response> <metadata> <status>success</status> </metadata> <AllocateAddressResponse> <allocationId /> <domain>standard</domain> <publicIp>23.21.226.192</publicIp> </AllocateAddressResponse>
</amazon-ec2-rest-response>

Associate Address operation

The Associate Address operation associates an elastic IP address with an instance. If the IP address is currently assigned to another instance, the IP address is assigned to a new instance. This is an idempotent operation (produces the same results no matter how many times it is performed). If you perform the operation more than once, Amazon EC2 does not return an error.

For the EC2-VPC, 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> element.

The following figure shows a sample <items> XML element for the Associate Address operation.

Sample <items> XML element for the Associate Address operation

<items> <item> <parameters> <public-ip></public-ip> <instance-id></instance-id> <allocation-id></allocation-id> <allow-reassociation></allow-reassociation> <network-interface-id></network-interface-id> <private-ip></private-ip> </parameters> </item>
</items>

The following table describes the adapter request elements for this request.

Adapter request elements for the Associate Address operation

Element	Definition	Required
`<access-key>`	Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Access Key is specified, the adapter ignores the value.
`<secret-key>`	Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Secret Access Key is specified, the adapter ignores the value.
`<region>`	Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values: us-east-1 us-west-2 (default) us-west-1 eu-west-1 ap-southeast-1 ap-northeast-1 ap-southeast-2 sa-east-1	No
`<operation-name>`	Contains the name of the operation: associate-address	Yes
`<public-ip>`	Specifies the IP address that you assign to the instance	Conditional; required if you are using EC2-Classic platform
`<instance-id>`	Specifies the instance to associate with the IP address Unless exactly one interface is attached, the association can fail when the `<instance-id>` is specified. For an EC2-VPC environment, you can either specify the `<instance-id>` or the `<network-interface-id>` only.	Conditional; required if you are using EC2-Classic platform
`<allocation-id>`	Specifies the allocation ID of the EC2-VPC elastic IP address	Conditional; required if you are using EC2-Classic platform
`<allow-reassociation>`	Allows an EC2-VPC 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 If not specified, the operation fails if the address is already associated. Valid values: true, false	No
`<network-interface-id>`	Specifies the elastic network interface ID to associate with the EC2-VPC elastic IP address	Conditional; required if the instance is attached to more than one elastic network interface
`<private-ip>`	Specifies the primary or secondary private IP address to associate with the EC2-VPC elastic IP address If no private IP address is specified, the Elastic IP address is associated with the primary private IP address.	No

The following figure shows a sample adapter request for the Associate Address operation for the EC2-Classic.

Sample adapter request for the Associate Address operation for the EC2-Classic

<amazon-ec2-rest-request> <operation-name>associate-address</operation-name> <access-key>AKIA************BT2Q</access-key> <secret-key>WQisk8Irh********************8AiJx3VQVd</secret-key> <region>us-east-1</region> <parameters> <public-ip>23.21.226.192</public-ip> <instance-id>i-1420b93a</instance-id> </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample adapter request for the Associate Address operation.

Sample adapter response for the Associate Address operation

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

Describe Addresses operation

The Describe Addresses operation describes one or more of your EC2-Classic or EC2-VPC Elastic IP addresses based on the given IPs or allocation IDs. You can also use filters to limit the results of the Describe Elastic IP operation.

To enable better results, use the following wild card characters with the filters:

Asterisk (*) to match any number of characters
Question mark (?) to match a single character

If you want to use any special characters or metacharacters such as *, +, (, ^, [, and so on that have a special meaning in searches, escape the special character by preceding it with a backslash (\ ).

The following table shows the available filters:

Filter name	Description
`<domain>`	Specifies whether the address is used in an EC2-Classic or EC2-VPC Valid values: standard, vpc
`<instance-id>`	Specifies the instance with which the address is associated (if any)
`<public-ip>`	Specifies the elastic IP address
`<allocation-id>`	Specifies the allocation ID for the elastic IP address (VPC only)
`<association-id>`	Specifies the association ID for the elastic IP address (VPC only)
`<network-interface-id>`	Specifies the network interface (if any) with which the address is associated (VPC only)
`<network-interface-owner-id>`	Specifies the owner ID
`<private-ip-address>`	Specifies the private IP address associated with the Elastic IP address (VPC only)

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

Sample <items> XML element for the Describe Addresses operation

<items> <item> <parameters> <public-ips-set> <!-Zero or more repetition-> <item> <public-ip></public-ip> </item> </public-ips-set> <allocation-id-set> <!-Zero or more repetition-> <item> <allocation-id></allocation-id> </item> </allocation-id-set> <!-Optional:-> <filter-set> <!-Zero or more repetition-> <item> <name></name> <value-set> <!-Zero or more repetition-> <item> <value></value> </item> </value-set> </item> </filter-set> </parameters> </item>
</items>

The following table describes the adapter request elements for this request.

Adapter request elements for the Describe Addresses operation

Element	Definition	Required
`<access-key>`	Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Access Key is specified, the adapter ignores the value.
`<secret-key>`	Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Secret Access Key is specified, the adapter ignores the value.
`<region>`	Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values: us-east-1 us-west-2 (default) us-west-1 eu-west-1 ap-southeast-1 ap-northeast-1 ap-southeast-2 sa-east-1	No
`<operation-name>`	Contains the name of the operation: describe-addresses	Yes
`<public-ips-set>`	Specifies the set of elastic IP addresses that you want to list	No
`<allocation-id-set>`	Specifies the set of allocation IDs based on which you want to describe the IP addresses	No
`<filter-set>`	Specifies the filter used to retrieve the elastic IP addresses	No

The following figure shows a sample adapter request for the Describe Addresses operation.

Sample adapter request for the Describe Addresses operation

<amazon-ec2-rest-request> <operation-name>describe-addresses</operation-name> <parameters> <public-ips-set> <!-Zero or more repetition-> <item> <public-ip></public-ip> </item> </public-ips-set> <allocation-id-set> <!-Zero or more repetition-> <item> <allocation-id></allocation-id> </item> </allocation-id-set> <!-Optional:-> <filter-set> <!-Zero or more repetition-> <item> <name>domain</name> <value-set> <!-Zero or more repetition-> <item> <value>standard</value> </item> </value-set> </item> </filter-set> </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample adapter request for the Describe Addresses operation.

Sample adapter response for the Describe Addresses operation

<amazon-ec2-rest-response> <metadata> <status>success</status> </metadata> <DescribeAddressesResponse> <addressesSet> <item> <publicIp>23.21.226.192</publicIp> <allocationId /> <domain>standard</domain> <instanceId>i-1420b93a</instanceId> <NetworkInterfaceId /> <privateIp /> </item> </addressesSet> </DescribeAddressesResponse>
</amazon-ec2-rest-response>

Disassociate Address operation

The Disassociate Address operation disassociates a specified EC2-Classic or EC2-VPC elastic IP address from an instance or the network interface to which it is assigned. This is an idempotent operation. If you perform the operation more than once, Amazon EC2 does not return an error.

The following figure shows a sample <items> XML element for the Disassociate Address operation.

Sample <items> XML element for the Disassociate Address operation

<items> <item> <parameters> <public-ip></public-ip> <association-id></association-id> </parameters> </item>
</items>

The following table describes the adapter request elements for this request.

Adapter request elements for the Disassociate Address operation

Element	Definition	Required
`<access-key>`	Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Access Key is specified, the adapter ignores the value.
`<secret-key>`	Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Secret Access Key is specified, the adapter ignores the value.
`<region>`	Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values: us-east-1 us-west-2 (default) us-west-1 eu-west-1 ap-southeast-1 ap-northeast-1 ap-southeast-2 sa-east-1	No
`<operation-name>`	Contains the name of the operation: disassociate-address	Yes
`<public-ip>`	Specifies the IP address that you are disassociating from an instance	Conditional; required for EC2-Classic
`<association-id>`	Specifies the EC2-VPC elastic IP association ID	Conditional; required for EC2-VPC

The following figure shows a sample adapter request for the Disassociate Address operation.

Sample adapter request for the Disassociate Address operation

<amazon-ec2-rest-request> <operation-name>disassociate-address</operation-name> <access-key>AKIAJIPCZJ2QWXN8BT2Q</access-key> <secret-key>WQisk8IrhPuRUouCFLi9dEWy0S7iL8AiJx3VQVd</secret-key> <region>us-east-1</region> <parameters> <public-ip>23.21.226.192</public-ip> </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample adapter request for the Disassociate Address operation.

Sample adapter response for the Disassociate Address operation

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

Release Address operation

The Release Address operation releases an elastic IP address associated with your account. Releasing an IP address automatically disassociates it from any instance with which it is associated. If you run this operation on an elastic IP address that is already released, the address might get assigned to another account causing Amazon EC2 to return an error.

The following figure shows a sample <items> XML element for the Release Address operation.

Sample <items> XML element for the Release Address operation

<items> <item> <parameters> <public-ip></public-ip> <allocation-id></allocation-id> </parameters> </item>
</items>

The following table describes the adapter request elements for this request.

Adapter request elements for the Release Address operation

Element	Definition	Required
`<access-key>`	Specifies the Amazon Web Services (AWS) access key You need to generate the AWS access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Access Key is specified, the adapter ignores the value.
`<secret-key>`	Specifies the AWS secret access key You need to generate the AWS secret access key by going to the Security Credentials tab in the AWS console.	Conditional; You must specify the Access Key and theSecret Key together in the configuration or the adapter request. If you specify both the keys in the adapter request and in the adapter configuration, the key values in the request override the values in the configuration. If only the Secret Access Key is specified, the adapter ignores the value.
`<region>`	Specifies the region with which you want the adapter to communicate Amazon EC2 is hosted in multiple locations world-wide. You must specify the region in which you want the adapter to perform the actions. Valid values: us-east-1 us-west-2 (default) us-west-1 eu-west-1 ap-southeast-1 ap-northeast-1 ap-southeast-2 sa-east-1	No
`<operation-name>`	Contains the name of the operation: release-address	Yes
`<public-ip>`	Specifies the IP address that you want to release	Conditional; required for EC2-Classic only
`<allocation-id>`	Specifies the allocation ID for the elastic IP address	Conditional; required for EC2-VPC only

The following figure shows a sample adapter request for the Release Address operation.

Sample adapter request for the Release Address operation

<amazon-ec2-rest-request> <operation-name>release-address</operation-name> <access-key>AKIAJIPCZJ2QWXN8BT2Q</access-key> <secret-key>WQisk8IrhPuRUouCFLi9dEWy0S7iL8AiJx3VQVd</secret-key> <region>us-east-1</region> <parameters> <public-ip>23.21.226.192</public-ip> <allocation-id></allocation-id> </parameters>
</amazon-ec2-rest-request>

The following figure shows the response for the sample adapter request for the Release Address operation.

Sample adapter response for the Release Address operation

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