Overhaul for IPv6 and flexiblity

README.yaml

@@ -49,9 +49,64 @@ related:
 description: |-
   Terraform module to provision public and private [`subnets`](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html) in an existing [`VPC`](https://aws.amazon.com/vpc)
 
-  **IMPORTANT:** This module provisions NAT instance with public IP.
+
   __Note:__ this module is intended for use with an existing VPC and existing Internet Gateway.
   To create a new VPC, use [terraform-aws-vpc](https://github.com/cloudposse/terraform-aws-vpc) module.
+
+  The core feature of this module is dividing up a given CIDR range so that a set of subnets each gets its own 
+  distinct CIDR range within that range, and then creating those subnets in the appropriate availability zones.
+  The intention is to keep this module relatively simple and easy to use for the most popular use cases. 
+  In its default configuration, this module creates 1 public subnet and 1 private subnet in each
+  of the specified availability zones. The public subnets are configured for bi-directional traffic to the
+  public internet, while the private subnets are configured for egress-only traffic to the public internet.
+  Rather than provide a wealth of configuration options allowing for numerous special cases, this module 
+  provides some common options and further provides the ability to suppress the creation of resources, allowing 
+  you to create and configure them as you like from outside this module. For example, rather than give you the
+  option to customize the Network ACL, the module gives you the option to create a completely open one (and control
+  access via Security Groups and other means) or not create one at all, allowing you to create and configure one yourself.
+
+  ### Public subnets
+
+  This module defines a public subnet as one that has direct access to an internet gateway and can accept incoming connection requests. 
+  In the simplest configuration, the module creates a single route table with a default route targeted to the
+  VPC's internet gateway, and associates all the public subnets with that single route table. 
+
+  Likewise it creates a single Network ACL with associated rules allowing all ingress and all egress, 
+  and associates that ACL with all the public subnets. 
+
+  ### Private subnets
+
+  A private subnet may be able to initiate traffic to the public internet through a NAT gateway,
+  a NAT instance, or an egress-only internet gateway, or it might only have direct access to other
+  private subnets. In the simple configuration, for IPv4 and/or IPv6 with NAT64 enabled via `public_dns64_enabled`
+  or `private_dns64_enabled`, the module creates 1 NAT Gateway or NAT Instance for each
+  private subnet (in the public subnet in the same availability zone), creates 1 route table for each private subnet, 
+  and adds to that route table a default route from the subnet to its NAT Gateway or Instance. For IPv6,
+  the module adds a route to the Egress-Only Internet Gateway configured via input.
+
+  As with the Public subnets, the module creates a single Network ACL with associated rules allowing all ingress and 
+  all egress, and associates that ACL with all the private subnets. 
+
+  ### Customization for special use cases
+
+  Various features are controlled by `bool` arguments with names ending in `_enabled`. By changing the default
+  values, you can enable or disable creation of public subnets, private subnets, route tables, 
+  NAT gateways, NAT instances, or Network ACLs. So for example, you could use this module to create only
+  private subnets and the open Network ACL, and then add your own route table associations to the subnets
+  and route all non-local traffic to a Transit Gateway or VPN.
+
+  ### CIDR allocation
+
+  For IPv4, you provide a CIDR and the module divides the address space into the largest CIDRs possible that are still
+  small enough to accommodate `max_subnet_count` subnets of each enabled type (public or private). When `max_subnet_count`
+  is left at the default `0`, it is set to the total number of availability zones in the region. Private subnets
+  are allocated out of the first half of the reserved range, and public subnets are allocated out of the second half.
+
+  For IPv6, you provide a `/56` CIDR and the module assigns `/64` subnets of that CIDR in consecutive order starting
+  at zero. (You have the option of specifying a list of CIDRs instead.) As with IPv4, enough CIDRs are allocated to 
+  cover `max_subnet_count` private and public subnets (when both are enabled, which is the default), with the private
+  subnets being allocated out of the lower half of the reservation and the public subnets allocated out of the upper half.
+
 # How to use this project
 usage: |-
   ```hcl