adding support for regional nat to have availability_mode and eip_allocation types

Author: balvinder-cxnpl

README.md

@@ -67,9 +67,33 @@ Note that in the example we allocate 3 IPs because we will be provisioning 3 NAT
 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 two variables `reuse_nat_ips = true` and `external_nat_ip_ids = "${aws_eip.nat.*.id}"`.
 
+**For Regional NAT Gateways:**
+When using Regional NAT Gateway with `nat_gateway_connectivity_type.eip_allocation = "manual"`, the module will allocate one EIP per Availability Zone. For example, if you have 3 AZs:
+
+```hcl
+resource "aws_eip" "regional_nat" {
+  count = 3  # One per AZ
+
+  vpc = true
+}
+
+module "vpc" {
+  source = "terraform-aws-modules/vpc/aws"
+
+  enable_nat_gateway = true
+  nat_gateway_connectivity_type = {
+    availability_mode = "regional"
+    eip_allocation    = "manual"
+  }
+  reuse_nat_ips       = false
+}
+```
+
+Alternatively, you can use `eip_allocation = "auto"` to let AWS automatically manage EIPs for the Regional NAT Gateway.
+
 ## NAT Gateway Scenarios
 
-This module supports three scenarios for creating NAT gateways. Each will be explained in further detail in the corresponding sections.
+This module supports four scenarios for creating NAT gateways. Each will be explained in further detail in the corresponding sections.
 
 - One NAT Gateway per subnet (default behavior)
   - `enable_nat_gateway = true`
@@ -83,9 +107,15 @@ This module supports three scenarios for creating NAT gateways. Each will be exp
   - `enable_nat_gateway = true`
   - `single_nat_gateway = false`
   - `one_nat_gateway_per_az = true`
+- Regional NAT Gateway
+  - `enable_nat_gateway = true`
+  - `nat_gateway_connectivity_type.availability_mode = "regional"`
+  - `nat_gateway_connectivity_type.eip_allocation = "auto"` or `"manual"`
 
 If both `single_nat_gateway` and `one_nat_gateway_per_az` are set to `true`, then `single_nat_gateway` takes precedence.
 
+> **Note**: Regional NAT Gateway requires Terraform AWS provider >= 6.24.0.
+
 ### One NAT Gateway per subnet (default)
 
 By default, the module will determine the number of NAT Gateways to create based on the `max()` of the private subnet lists (`database_subnets`, `elasticache_subnets`, `private_subnets`, and `redshift_subnets`). The module **does not** take into account the number of `intra_subnets`, since the latter are designed to have no Internet access via NAT Gateway. For example, if your configuration looks like the following:
@@ -111,6 +141,43 @@ If `one_nat_gateway_per_az = true` and `single_nat_gateway = false`, then the mo
 - The variable `var.azs` **must** be specified.
 - The number of public subnet CIDR blocks specified in `public_subnets` **must** be greater than or equal to the number of availability zones specified in `var.azs`. This is to ensure that each NAT Gateway has a dedicated public subnet to deploy to.
 
+### Regional NAT Gateway
+
+Regional NAT Gateway is a highly available NAT solution that automatically scales across multiple Availability Zones within your VPC. It provides a single NAT Gateway that serves all Availability Zones, eliminating the need for multiple zonal NAT Gateways.
+
+**Key Features:**
+- **Single NAT Gateway**: One NAT Gateway serves all Availability Zones in your VPC
+- **Automatic High Availability**: Automatically expands and contracts across AZs based on workload distribution
+- **No Public Subnets Required**: Regional NAT Gateways operate without requiring public subnets (though public subnets can still be created for other purposes)
+- **Simplified Management**: Single NAT Gateway ID for consistent route entries across all subnets
+- **Increased Capacity**: Supports up to 32 Elastic IP addresses per AZ (compared to 8 for zonal NAT Gateways)
+
+**Configuration:**
+
+```hcl
+enable_nat_gateway = true
+nat_gateway_connectivity_type = {
+  availability_mode = "regional" # "regional" or "zonal"
+  eip_allocation    = "auto"     # "auto" or "manual"
+}
+```
+
+**EIP Allocation Options:**
+- `"auto"`: AWS automatically provisions and manages EIPs for the Regional NAT Gateway
+- `"manual"`: You provide EIPs via `external_nat_ip_ids` (one EIP per AZ). The module will create EIPs based on the number of AZs if `reuse_nat_ips = false`
+
+**Important Notes:**
+1. **Expansion Timing**: When deploying workloads in a new AZ, the regional NAT Gateway typically takes 15-20 minutes (up to 60 minutes) to expand to that AZ. During this period, traffic may be temporarily routed through existing AZs.
+2. **Private Connectivity**: Regional NAT Gateways do not support private connectivity. For workloads requiring private connectivity, continue using zonal NAT Gateways.
+3. **Availability**: This feature is available in all commercial AWS Regions, except for AWS GovCloud (US) Regions and China Regions.
+4. **Cost Considerations**: Regional NAT Gateways are charged per hour and per GB processed, similar to zonal NAT Gateways, but you only pay for one NAT Gateway instead of multiple.
+
+**Requirements:**
+- Terraform AWS provider >= 6.24.0
+- The variable `var.azs` **must** be specified
+
+See the [regional-nat example](examples/regional-nat/) for a complete working example.
+
 ## "private" versus "intra" subnets
 
 By default, if NAT Gateways are enabled, private subnets will be configured with routes for Internet traffic that point at the NAT Gateways configured by use of the above options.
@@ -488,7 +555,7 @@ No modules.
 | <a name="input_map_public_ip_on_launch"></a> [map\_public\_ip\_on\_launch](#input\_map\_public\_ip\_on\_launch) | Specify true to indicate that instances launched into the subnet should be assigned a public IP address. Default is `false` | `bool` | `false` | no |
 | <a name="input_name"></a> [name](#input\_name) | Name to be used on all the resources as identifier | `string` | `""` | no |
 | <a name="input_nat_eip_tags"></a> [nat\_eip\_tags](#input\_nat\_eip\_tags) | Additional tags for the NAT EIP | `map(string)` | `{}` | no |
-| <a name="input_nat_gateway_connectivity_type"></a> [nat\_gateway\_connectivity\_type](#input\_nat\_gateway\_connectivity\_type) | Connectivity type for the NAT Gateway. Valid values are:<br/>- 'zonal' (default): Traditional AZ-specific NAT gateways that require public subnets<br/>- 'regional': A single NAT Gateway that automatically scales across all AZs (does not require public subnets)<br/><br/>Regional NAT Gateway support requires Terraform AWS provider >= 6.24.0.<br/>When using 'regional' mode, only one NAT Gateway is created for the entire VPC. | `string` | `"zonal"` | no |
+| <a name="input_nat_gateway_connectivity_type"></a> [nat\_gateway\_connectivity\_type](#input\_nat\_gateway\_connectivity\_type) | Configuration block for NAT Gateway connectivity type.<br/>- availability_mode: "zonal" (default) or "regional"<br/>  - 'zonal': Traditional AZ-specific NAT gateways that require public subnets<br/>  - 'regional': A single NAT Gateway that automatically scales across all AZs (does not require public subnets)<br/>- eip_allocation: "auto" (default) or "manual"<br/>  - 'auto': Automatically provision EIPs for the NAT Gateway<br/>  - 'manual': Use existing EIPs provided via external_nat_ip_ids<br/><br/>Regional NAT Gateway support requires Terraform AWS provider >= 6.24.0.<br/>When using 'regional' mode, only one NAT Gateway is created for the entire VPC. | `object({ availability_mode = string, eip_allocation = optional(string, "auto") })` | `{ availability_mode = "zonal", eip_allocation = "auto" }` | no |
 | <a name="input_nat_gateway_destination_cidr_block"></a> [nat\_gateway\_destination\_cidr\_block](#input\_nat\_gateway\_destination\_cidr\_block) | Used to pass a custom destination route for private NAT Gateway. If not specified, the default 0.0.0.0/0 is used as a destination route | `string` | `"0.0.0.0/0"` | no |
 | <a name="input_nat_gateway_tags"></a> [nat\_gateway\_tags](#input\_nat\_gateway\_tags) | Additional tags for the NAT gateways | `map(string)` | `{}` | no |
 | <a name="input_one_nat_gateway_per_az"></a> [one\_nat\_gateway\_per\_az](#input\_one\_nat\_gateway\_per\_az) | Should be true if you want only one NAT Gateway per availability zone. Requires `var.azs` to be set, and the number of `public_subnets` created to be greater than or equal to the number of availability zones specified in `var.azs` | `bool` | `false` | no |

examples/regional-nat/README.md

@@ -38,8 +38,11 @@ Note that this example may create resources which can cost money (AWS Elastic IP
 The key configuration for Regional NAT Gateway is:
 
 ```hcl
-enable_nat_gateway            = true
-nat_gateway_connectivity_type = "regional"
+enable_nat_gateway = true
+nat_gateway_connectivity_type = {
+  availability_mode = "regional" # "regional" or "zonal"
+  eip_allocation    = "auto"     # "auto" or "manual"
+}
 ```
 
 ## Comparison: Regional vs Zonal NAT Gateway

examples/regional-nat/main.tf

@@ -31,7 +31,10 @@ module "vpc" {
 
   # Regional NAT Gateway Configuration
   # Requires Terraform AWS provider >= 6.24.0
-  enable_nat_gateway            = true
-  nat_gateway_connectivity_type = "regional"
-  tags                          = local.tags
+  enable_nat_gateway = true
+  nat_gateway_connectivity_type = {
+    availability_mode = "regional" # "regional" or "zonal"
+    eip_allocation    = "auto"     # "auto" or "manual", for availablility_mode = "zonal", eip_allocation won't be used
+  }
+  tags = local.tags
 }

main.tf

@@ -1207,21 +1207,25 @@ resource "aws_route" "private_ipv6_egress" {
 ################################################################################
 
 locals {
-  nat_gateway_is_regional = var.nat_gateway_connectivity_type == "regional"
-  nat_gateway_count       = local.nat_gateway_is_regional ? 1 : var.single_nat_gateway ? 1 : var.one_nat_gateway_per_az ? length(var.azs) : local.max_subnet_length
+  nat_gateway_is_regional = var.nat_gateway_connectivity_type.availability_mode == "regional"
+  nat_gateway_count       = local.nat_gateway_is_regional ? 1 : var.single_nat_gateway || var.nat_gateway_connectivity_type.availability_mode == "zonal" ? 1 : var.one_nat_gateway_per_az ? length(var.azs) : local.max_subnet_length
   nat_gateway_ips         = var.reuse_nat_ips ? var.external_nat_ip_ids : aws_eip.nat[*].id
+
+  # Regional NAT Gateway EIP handling
+  # Always create EIPs automatically based on the number of AZs
+  regional_nat_gateway_eip_count = local.nat_gateway_is_regional ? length(var.azs) : 0
 }
 
 resource "aws_eip" "nat" {
-  count = local.create_vpc && var.enable_nat_gateway && !var.reuse_nat_ips ? local.nat_gateway_count : 0
+  count = local.create_vpc && var.enable_nat_gateway && !local.nat_gateway_is_regional && !var.reuse_nat_ips && (var.nat_gateway_connectivity_type.availability_mode == "zonal" || var.nat_gateway_connectivity_type.availability_mode == null) ? local.nat_gateway_count : 0
 
   region = var.region
 
   domain = "vpc"
 
   tags = merge(
     {
-      "Name" = local.nat_gateway_is_regional ? var.name : format(
+      "Name" = format(
         "${var.name}-%s",
         element(var.azs, var.single_nat_gateway ? 0 : count.index),
       )
@@ -1233,6 +1237,27 @@ resource "aws_eip" "nat" {
   depends_on = [aws_internet_gateway.this]
 }
 
+resource "aws_eip" "regional_nat" {
+  count = local.create_vpc && var.enable_nat_gateway && local.nat_gateway_is_regional && var.nat_gateway_connectivity_type.eip_allocation == "manual" && var.nat_gateway_connectivity_type.availability_mode == "regional" ? local.regional_nat_gateway_eip_count : 0
+
+  region = var.region
+
+  domain = "vpc"
+
+  tags = merge(
+    {
+      "Name" = format(
+        "${var.name}-%s",
+        element(var.azs, count.index),
+      )
+    },
+    var.tags,
+    var.nat_eip_tags,
+  )
+
+  depends_on = [aws_internet_gateway.this]
+}
+
 resource "aws_nat_gateway" "this" {
   count = local.create_vpc && var.enable_nat_gateway && !local.nat_gateway_is_regional ? local.nat_gateway_count : 0
 
@@ -1268,7 +1293,17 @@ resource "aws_nat_gateway" "regional" {
   vpc_id = aws_vpc.this[0].id
 
   connectivity_type = "public"
-  availability_mode = "regional"
+  availability_mode = var.nat_gateway_connectivity_type.availability_mode
+
+  dynamic "availability_zone_address" {
+    for_each = var.nat_gateway_connectivity_type.eip_allocation == "manual" && var.nat_gateway_connectivity_type.availability_mode == "regional" ? {
+      for idx, az in var.azs : az => aws_eip.regional_nat[idx].id
+    } : {}
+    content {
+      allocation_ids    = toset([availability_zone_address.value])
+      availability_zone = availability_zone_address.key
+    }
+  }
 
   tags = merge(
     {

outputs.tf

@@ -511,12 +511,15 @@ output "intra_network_acl_arn" {
 
 output "nat_ids" {
   description = "List of allocation ID of Elastic IPs created for AWS NAT Gateway"
-  value       = aws_eip.nat[*].id
+  value       = concat(aws_eip.nat[*].id, aws_eip.regional_nat[*].id)
 }
 
 output "nat_public_ips" {
   description = "List of public Elastic IPs created for AWS NAT Gateway"
-  value       = var.reuse_nat_ips ? var.external_nat_ips : aws_eip.nat[*].public_ip
+  value = concat(
+    var.reuse_nat_ips ? var.external_nat_ips : aws_eip.nat[*].public_ip,
+    var.nat_gateway_connectivity_type.availability_mode == "regional" ? aws_eip.regional_nat[*].public_ip : []
+  )
 }
 
 output "natgw_ids" {

variables.tf

@@ -1236,19 +1236,27 @@ variable "one_nat_gateway_per_az" {
 
 variable "nat_gateway_connectivity_type" {
   description = <<-EOT
-    Connectivity type for the NAT Gateway. Valid values are:
-    - 'zonal' (default): Traditional AZ-specific NAT gateways that require public subnets
-    - 'regional': A single NAT Gateway that automatically scales across all AZs (does not require public subnets)
-
-    Regional NAT Gateway support requires Terraform AWS provider >= 6.24.0.
-    When using 'regional' mode, only one NAT Gateway is created for the entire VPC.
+    Configuration block for NAT Gateway connectivity type.
+    - availability_mode: "zonal" (default) or "regional"
+      - 'zonal': Traditional AZ-specific NAT gateways that require public subnets
+      - 'regional': A single NAT Gateway that automatically scales across all AZs (does not require public subnets)
+    - eip_allocation: "auto" (default) or "manual"
+      - 'auto': Automatically provision EIPs for the NAT Gateway
+      - 'manual': Will create the set of EIPs based on the number of AZs
   EOT
-  type        = string
-  default     = "zonal"
-  validation {
-    condition     = contains(["zonal", "regional"], var.nat_gateway_connectivity_type)
-    error_message = "The nat_gateway_connectivity_type must be either 'zonal' or 'regional'."
-  }
+  type = object({
+    availability_mode = string # "zonal" or "regional"
+    eip_allocation    = string # "auto" or "manual"
+  })
+  default = { availability_mode = null, eip_allocation = null }
+  # validation {
+  #   condition     = contains(["zonal", "regional"], var.nat_gateway_connectivity_type.availability_mode)
+  #   error_message = "The availability_mode must be either 'zonal' or 'regional'."
+  # }
+  # validation {
+  #   condition     = contains(["auto", "manual"], var.nat_gateway_connectivity_type.eip_allocation)
+  #   error_message = "The eip_allocation must be either 'auto' or 'manual'."
+  # }
 }
 
 variable "reuse_nat_ips" {
@@ -1264,7 +1272,7 @@ variable "external_nat_ip_ids" {
 }
 
 variable "external_nat_ips" {
-  description = "List of EIPs to be used for `nat_public_ips` output (used in combination with reuse_nat_ips and external_nat_ip_ids)"
+  description = "List of EIPs to be used for `nat_public_ips` output (used in combination with reuse_nat_ips and external_nat_ip_ids). For regional NAT gateways, EIPs will be mapped to availability zones in order."
   type        = list(string)
   default     = []
 }

wrappers/main.tf

@@ -232,7 +232,7 @@ module "wrapper" {
   map_public_ip_on_launch                                     = try(each.value.map_public_ip_on_launch, var.defaults.map_public_ip_on_launch, false)
   name                                                        = try(each.value.name, var.defaults.name, "")
   nat_eip_tags                                                = try(each.value.nat_eip_tags, var.defaults.nat_eip_tags, {})
-  nat_gateway_connectivity_type                               = try(each.value.nat_gateway_connectivity_type, var.defaults.nat_gateway_connectivity_type, "zonal")
+  nat_gateway_connectivity_type                               = try(each.value.nat_gateway_connectivity_type, var.defaults.nat_gateway_connectivity_type, { availability_mode = null, eip_allocation = null })
   nat_gateway_destination_cidr_block                          = try(each.value.nat_gateway_destination_cidr_block, var.defaults.nat_gateway_destination_cidr_block, "0.0.0.0/0")
   nat_gateway_tags                                            = try(each.value.nat_gateway_tags, var.defaults.nat_gateway_tags, {})
   one_nat_gateway_per_az                                      = try(each.value.one_nat_gateway_per_az, var.defaults.one_nat_gateway_per_az, false)