Skip to content

docs: Clarify NAT gateway behavior and precedence of single_nat_gateway vs one_nat_gateway_per_az #1214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: Clarify NAT gateway behavior and precedence of single_nat_gateway vs one_nat_gateway_per_az #1214

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,22 +68,29 @@ Passing the IPs into the module is done by setting two variables `reuse_nat_ips

This module supports three 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`
- `single_nat_gateway = false`
- `one_nat_gateway_per_az = false`
- Single NAT Gateway
- **Single NAT Gateway** (cost-saving):
- `enable_nat_gateway = true`
- `single_nat_gateway = true`
- `one_nat_gateway_per_az = false`
- One NAT Gateway per availability zone
- `one_nat_gateway_per_az = false` (or true — has no effect)
- ✅ Creates one NAT Gateway shared across all private subnets

- **One NAT Gateway per Availability Zone** (high availability):
- `enable_nat_gateway = true`
- `single_nat_gateway = false`
- `one_nat_gateway_per_az = true`
- ✅ Creates one NAT Gateway in each AZ you specify in `var.azs`

- **Default (no special config):**
- `enable_nat_gateway = true`
- `single_nat_gateway = false`
- `one_nat_gateway_per_az = false`
- ✅ Behavior depends on private subnet layout — only one NAT Gateway is created unless multiple are required

If both `single_nat_gateway` and `one_nat_gateway_per_az` are set to `true`, then `single_nat_gateway` takes precedence.
> ⚠️ **Important:** If both `single_nat_gateway = true` and `one_nat_gateway_per_az = true` are set,
> the module will **only create one NAT Gateway**.
> The `single_nat_gateway` setting takes precedence and overrides `one_nat_gateway_per_az`.

### One NAT Gateway per subnet (default)
### NAT Gateway Behavior Overview

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:

Expand Down