.. meta::
   :description: Create, update or delete an AWS EC2 VPC Subnet.

.. _ec2_subnet_module:

ec2_subnet -- Manage EC2 VPC Subnets
====================================

Create, update or delete an AWS EC2 VPC Subnet.


Examples
--------

.. code-block:: yaml+jinja

   
   - name: Create a subnet in the default VPC
     ec2_subnet:
       name: my-subnet-in-default-vpc
       cidr: 10.0.0.0/16

   - name: Create a subnet in a non-default VPC and specific availability zone
     ec2_subnet:
       name: my-subnet
       vpc: vpc-123456
       cidr: 10.0.0.0/16
       availability_zone: use2-az2
     register: my_subnet

   - name: Update the subnet's setting for auto assigning public IPs to instances
     ec2_subnet:
       id: "{{ my_subnet.object.id }}"
       auto_assign_ip: true

   - name: Clear all the subnet's tags
     ec2_subnet:
       id: "{{ my_subnet.object.id }}"
       clear_tags: true

   - name: Delete a subnet
     ec2_subnet:
       id: "{{ my_subnet.object.id }}"
       state: absent

   - name: Delete a subnet in a non-default VPC by providing a VPC ID and subnet CIDR block
     ec2_subnet:
       vpc: vpc-123456
       cidr: 10.0.0.0/16
       state: absent

   - name: Delete a subnet in the default VPC by providing its CIDR block
     ec2_subnet:
       cidr: 10.0.0.0/16
       state: absent





See Also
--------

.. seealso::

   - :ref:`ec2_subnet_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


auto_assign_ip (optional)
  Whether a public IPv4 address should be assigned to ENIs attached to instances launched from this subnet.

  | **type**: bool

availability_zone (optional)
  ID of the availability zone to create the AWS resource in.

  If omitted, the availability zone will be selected by AWS.

  | **type**: str

cidr (optional)
  IPv4 network range to assign to the subnet, in CIDR notation.

  This parameter is required unless *id* is provided.

  In the absence of *id*, the value of this parameter will be used to uniquely identify the subnet within the desired *vpc* or default VPC.

  | **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 of the subnet.

  This parameter is required when first creating the subnet.

  | **type**: str

state (optional)
  Target state of the AWS resource.

  | **type**: str
  | **default**: present
  | **choices**: present, 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 for the target subnet.

  In the absence of *id*, the value of this parameter will be used to uniquely identify the subnet together with *cidr*.

  If omitted, the default VPC is assumed.

  | **type**: str





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

object (success and I(state=present)), dict, {'object': {'id': 'subnet-123456', 'vpc': 'vpc-123456', 'availability_zone': 'eun-az1', 'cidr': '192.0.2.0/24', 'auto_assign_ip': True, 'tags': {'mycompany-public': True}, 'available_ip_address_count': 15}}
  An object representing an EC2 subnet.


  id (always), str, 
    The ID of the subnet.


  vpc (always), str, 
    The ID of the VPC the subnet belongs to.


  availability_zone (always), str, 
    The ID of the availability zone the subnet is in.


  cidr (always), str, 
    The CIDR block of the subnet.


  auto_assign_ip (always), bool, 
    Whether a public IPv4 address is automatically assigned to instances in this subnet.


  tags (always), dict, 
    The tags assigned to the subnet.


  available_ip_address_count (always), int, 
    The number of remaining private IPv4 addresses in the range of the subnet.