.. meta::
   :description: Allocate, associate or release an AWS EC2 VPC address (Elastic IP).

.. _ec2_vpc_address_module:

ec2_vpc_address -- Manage EC2 VPC addresses
===========================================

Allocate, associate or release an AWS EC2 VPC address (Elastic IP).


Examples
--------

.. code-block:: yaml+jinja

   
   - name: Allocate a new VPC address without associating it
     ec2_vpc_address:
       state: allocated
     register: first_address

   - name: Associate a previously allocated VPC address with a network interface
     ec2_vpc_address:
       ip: "{{ first_address.object.ip }}"
       network_interface: eni-0206c72e4ee240662
     register: first_address_associated

   - name: Dissociate a VPC address
     ec2_vpc_address:
       ip: "{{ first_address_associated.object.ip }}"
       state: allocated
     register: first_address_dissociated

   - name: Release a VPC address
     ec2_vpc_address:
       ip: "{{ first_address_dissociated.object.ip }}"
       state: absent

   - name: Try to reclaim a previously released VPC address
     ec2_vpc_address:
       ip: "{{ first_address.object.ip }}"
       network_interface: eni-0206c72e4ee240662
     register: reclaimed_address

   - name: Allocate & associate a new VPC address with a network interface
     ec2_vpc_address:
       network_interface: eni-04f3354b9b75ec51d
     register: another_address

   - name: Re-associate an existing VPC address with the primary
           network interface of an instance
     vpc_address:
       ip: "{{ another_address.object.ip }}"
       instance: i-0c79884ded545df1a

   - name: Release an associated VPC address
     ec2_vpc_address:
       ip: "{{ another_address.object.ip }}"
       state: absent





See Also
--------

.. seealso::

   - :ref:`ec2_vpc_address_info_module`



Parameters
----------

auth (optional)
  Parameters for authenticating with the AWS service. Each of them may be defined via environment variables.

  | **type**: dict

  access_key (optional)
    The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked.

    Mutually exclusive with *profile*.

    | **type**: str

  profile (optional)
    The name of the AWS profile configured with ``aws configure``.

    Can be used instead of explicitly specifying your access credentials and region.

    Use ``default`` to use the default profile.

    Mutually exclusive with *access_key* and *secret_key*.

    | **type**: str

  region (optional)
    The name of the AWS region.

    If not set, the value of the AWS_REGION environment variable will be checked.

    If you set a *profile* that specifies a default region, that region is used and you can omit this parameter. Use this parameter to override the profile's default region.

    | **type**: str

  secret_key (optional)
    The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked.

    Mutually exclusive with *profile*.

    | **type**: str

  url (optional)
    The URL to the AWS service related to the resource. By default, this is automatically determined through the region parameter.

    If not set explicitly, the value of the AWS_<SERVICE>_URL environment variable will be used.

    The services currently supported are EC2 and S3.

    | **type**: str


clear_tags (optional)
  Whether to clear any existing tags on the resource that are not explicitly stated in *tags*.

  By default, existing tags are kept on the resource.

  When this parameter is set to ``true``, any pre-existing tags on the resource are removed.

  | **type**: bool

instance (optional)
  ID of the instance whose primary network interface the VPC address will be associated with.

  The value of this parameter is only relevant when *state* is ``associated``.

  Exactly one of *instance*, *network_interface* is required.

  When updating an existing VPC address that is already associated, the module will perform re-association.

  | **type**: str

ip (optional)
  The public (Elastic) IP address.

  You can use this parameter to uniquely identify the VPC address.

  If *state* is ``present`` and the VPC address with the specified public IP does not exist, the module will attempt to reclaim the specified public IP.

  | **type**: str

network_interface (optional)
  ID of the network interface to associate the VPC address with.

  VPC address will be associated with the primary private IP of the specified network interface.

  The value of this parameter is only relevant when *state* is ``associated``.

  Exactly one of *network_interface*, *instance* is required.

  When updating an existing VPC address that is already associated, the module will perform re-association.

  | **type**: str

state (optional)
  The desired state of the VPC address.

  *state* ``associated`` if not already, it will allocate address, and associated it with instance or network interface.

  If *state* is ``allocated``, the VPC address will be allocated or if already associated with an instance it will be disassociated, but not released.

  If *state* is ``absent``, the VPC address will be automatically disassociated from the network interface or instance, if necessary.

  | **type**: str
  | **default**: associated
  | **choices**: associated, allocated, absent

tags (optional)
  Metadata for the AWS resource as key/value pairs.

  Keys and values are case-sensitive.

  | **type**: dict





Return Values
-------------

object (success and I(state=present)), complex, 
  An object representing an EC2 VPC address.


  ip (always), str, 3.20.251.70
    The Elastic IP address.


  allocation_id (always), str, eipalloc-04bed816a62ae64b1
    Allocation ID of the VPC address.


  network_interface (always), str, eni-0a6d3406ea74e7bab
    ID of the network interface VPC address is associated with.


  instance (always), str, i-0c79884ded545df1a, None
    ID of the instance to which the network interface associated with the VPC address is attached (if any).


  tags (always), dict, {'Name': 'my-vpc-address'}
    Tags associated with the VPC address.