Document how to pass external IPs for NAT Gateways

README.md

@@ -9,11 +9,11 @@ These types of resources are supported:
 * [Subnet](https://www.terraform.io/docs/providers/aws/r/subnet.html)
 * [Route](https://www.terraform.io/docs/providers/aws/r/route.html)
 * [Route table](https://www.terraform.io/docs/providers/aws/r/route_table.html)
-* [Internet Gateway](https://www.terraform.io/docs/providers/aws/r/internet_gateway.html) 
+* [Internet Gateway](https://www.terraform.io/docs/providers/aws/r/internet_gateway.html)
 * [NAT Gateway](https://www.terraform.io/docs/providers/aws/r/nat_gateway.html)
 * [VPN Gateway](https://www.terraform.io/docs/providers/aws/r/vpn_gateway.html)
 * [VPC Endpoint](https://www.terraform.io/docs/providers/aws/r/vpc_endpoint.html) (S3 and DynamoDB)
-* [RDS DB Subnet Group](https://www.terraform.io/docs/providers/aws/r/db_subnet_group.html) 
+* [RDS DB Subnet Group](https://www.terraform.io/docs/providers/aws/r/db_subnet_group.html)
 * [ElastiCache Subnet Group](https://www.terraform.io/docs/providers/aws/r/elasticache_subnet_group.html)
 * [DHCP Options Set](https://www.terraform.io/docs/providers/aws/r/vpc_dhcp_options.html)
 
@@ -31,7 +31,7 @@ module "vpc" {
 
   name = "my-vpc"
   cidr = "10.0.0.0/16"
-  
+
   azs             = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
   private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
   public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
@@ -46,6 +46,55 @@ module "vpc" {
 }
 ```
 
+### External NAT Gateway IPs
+
+By default this module will provision new IPs for the VPC's NAT Gateways.
+This means that when creating a new VPC, new IPs are allocated, and when that VPC is destroyed those IPs are released.
+Sometimes it is handy to keep the same IPs even after the VPC is destroyed and re-created.
+To that end, it is possible to assign existing IPs to the NAT Gateways.
+This prevents the destruction of the VPC from releasing those IPs, while making it possible that a re-created VPC uses the same IPs.
+
+To achieve this, allocate the IPs outside the VPC module declaration.
+```hcl
+variable "nat_ip_count" {
+  default = 3
+}
+
+resource "aws_eip" "nat" {
+  count = "${var.nat_ip_count}"
+
+  vpc = true
+}
+```
+
+Then, pass the allocated IPs as a parameter to this module.
+```hcl
+module "vpc" {
+  source = "terraform-aws-modules/vpc/aws"
+
+  name = "my-vpc"
+  cidr = "10.0.0.0/16"
+
+  azs             = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
+  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
+  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
+
+  enable_nat_gateway = true
+  enable_vpn_gateway = true
+
+  external_nat_ip_ids = ["${data.aws_eip.nat.*.id}"]
+
+  tags = {
+    Terraform = "true"
+    Environment = "dev"
+  }
+}
+```
+
+Note that in the example we allocates 3 IPs because we will be provisioning 3 NAT Gateways (due to `single_nat_gateway = false` and having 3 subnets).
+If, on the other hand, `single_nat_gateway = true`, then `aws_eip.nat` would only need to allocate 1 IP.
+Passing the IPs into the module is done by setting variable `external_nat_ip_ids = ["${data.aws_eip.nat.*.id}"]`.
+
 Terraform version
 -----------------
 
@@ -66,4 +115,4 @@ Module managed by [Anton Babenko](https://github.com/antonbabenko).
 License
 -------
 
-Apache 2 Licensed. See LICENSE for full details.
+Apache 2 Licensed. See LICENSE for full details.