.. meta::
   :description: Create, update or delete AWS EC2 Internet Gateway and its attachment to a VPC.

.. _ec2_internet_gateway_module:

ec2_internet_gateway -- Manage EC2 Internet Gateways
====================================================

Create, update or delete AWS EC2 Internet Gateway and its attachment to a VPC.


Examples
--------

.. code-block:: yaml+jinja

   
   - name: Create a detached internet gateway
     ec2_internet_gateway:
       name: detached-gateway
       state: detached
     register: detached_gateway

   - name: Attach a previously detached internet gateway to a VPC
     ec2_internet_gateway:
       id: "{{ detached_gateway.object.id }}"
       vpc: vpc-2w7hs924hss
     register: result

   - name: Detach and delete an internet gateway
     ec2_internet_gateway:
       id: "{{ result.object.id }}"
       state: absent

   - name: Create another internet gateway, this time with VPC attachment
     ec2_internet_gateway:
       name: attached-gateway
       vpc: vpc-2w7hs924hss
     register: attached_gateway

   - name: Detach an internet gateway from a VPC
     ec2_internet_gateway:
       id: "{{ attached_gateway.object.id }}"
       state: detached





See Also
--------

.. seealso::

   - :ref:`ec2_internet_gateway_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 (including the name tag) are removed. To clear all tags except the name tag, make sure to provide the *name* parameter.

  | **type**: bool

id (optional)
  ID of the resource to perform the task on.

  If specified, this parameter is used to identify the resource.

  Omit this parameter when you are first creating the resource.

  | **type**: str

name (optional)
  Name tag for the internet gateway.

  This parameter is required when creating the internet gateway.

  In the absence of *id*, the value of this parameter will be used to try to identify the internet gateway.

  | **type**: str

state (optional)
  The desired state of the internet gateway.

  To create and attach an internet gateway to a VPC, or to attach an existing internet gateway to a VPC, use *state* = ``attached``.

  To create an internet gateway without attaching it to a VPC, or to detach an existing internet gateway from a VPC, use *state* = ``detached``.

  To remove the internet gateway, use ``absent``. Note that if necessary, VPC will be detached prior to removing the internet gateway.

  | **type**: str
  | **default**: attached
  | **choices**: attached, detached, absent

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

  Keys and values are case-sensitive.

  | **type**: dict

vpc (optional)
  ID of the VPC to attach the internet gateway to.

  If the internet gateway is already attached to a VPC different to the one specified, the module will detach the gateway from the VPC and attach it to the specified one.

  Required if *state* is ``attached``.

  When *state* is ``detached`` or ``absent``, the value of this parameter is ignored.

  | **type**: str





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

object (success and I(state=attached) or I(state=detached)), complex, 
  An object representing an EC2 Internet Gateway.


  id (always), str, igw-841b9271gd
    ID of the internet gateway


  vpc (always), str, vpc-2w7hs924hs
    ID of the VPC the internet gateway is attached to, None otherwise.


  tags (always), dict, {'environment': 'staging', 'Name': 'my-gateway'}
    Tags associated with the internet gateway.