Document Transit Gateway egress mode

- README: "Transit Gateway egress" section — what it does, how to enable
  (enable_transit_gateway + transit_gateway_id, computed id allowed), the
  operator-side TGW prerequisites (RAM share/accept, egress + return routes),
  CIDR-uniqueness requirement, IPv6 opt-in, and reversibility.
- VARIABLES: rows for enable_transit_gateway, transit_gateway_id,
  transit_gateway_ipv6_egress.
- CHANGELOG: [Unreleased] entry for the feature.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: sir-sigurd

CHANGELOG.md

@@ -18,6 +18,8 @@ Optional release notice.
 
 ## [Unreleased] - YYYY-MM-DD
 
+- [Added] Transit Gateway egress mode for new VPCs: set `enable_transit_gateway = true` (+ `transit_gateway_id`) to route private-subnet egress through a Transit Gateway instead of NAT gateways; IPv6 egress is opt-in via `transit_gateway_ipv6_egress`. See [Transit Gateway egress](README.md#transit-gateway-egress) ([#115](https://github.com/quiltdata/iac/pull/115))
+
 ## [1.7.2] - 2026-06-08
 
 - [Fixed] Bump `modules/cnames` AWS provider constraint from `~> 5.0` to `~> 6.0` so it resolves alongside the `vpc` module's `aws >= 6.28` requirement — using `quilt` + `cnames` in one root previously failed `terraform init` ([#117](https://github.com/quiltdata/iac/pull/117))

README.md

@@ -771,6 +771,56 @@ resource "aws_vpc_endpoint" "api_gateway_endpoint" {
 }
 ```
 
+### Transit Gateway egress
+
+By default a new Quilt VPC reaches the internet through Quilt-created NAT
+gateways. If you operate a Transit Gateway (TGW) as your egress boundary, set
+`enable_transit_gateway = true` (only with `create_new_vpc = true`). Quilt still
+creates the VPC, subnets, and endpoints, but instead disables the NAT gateways
+and the IPv6 egress-only IGW, attaches the VPC to your TGW (in the intra
+subnets), and points each private route table's default route at the TGW. The
+S3 gateway endpoint is unchanged, so bulk S3 traffic stays on the endpoint and
+does **not** traverse the TGW — only genuinely external egress does.
+
+```hcl
+module "quilt" {
+  # ...
+  create_new_vpc         = true
+  enable_transit_gateway = true
+  transit_gateway_id     = "tgw-0123456789abcdef0" # an existing TGW, or one created in this same config
+  # transit_gateway_ipv6_egress = true             # only if your TGW carries IPv6 egress
+}
+```
+
+`transit_gateway_id` may be a value known only after apply (e.g. a TGW you
+create in the same Terraform configuration) — the toggle is the separate
+`enable_transit_gateway` bool, so this does not break planning.
+
+**You must provide the egress path.** Quilt owns only the VPC→TGW leg. Before
+apply, your TGW must:
+
+- be reachable from the deployment account — share it via AWS RAM and accept
+  the VPC attachment (or enable auto-accept) if the TGW lives in another
+  account;
+- have route tables that forward the VPC's egress out to the internet (e.g. via
+  a central egress VPC / NAT) **and** route return traffic back to the VPC's
+  CIDR.
+
+**CIDR uniqueness:** a TGW cannot route between overlapping CIDRs, so any VPCs
+attached to the same TGW must have non-overlapping ranges. Set `cidr`
+accordingly if more than one Quilt stack shares a TGW (the default is
+`10.0.0.0/16`).
+
+**IPv6** egress through the TGW is opt-in (`transit_gateway_ipv6_egress`,
+default `false`). Enable it only if your TGW actually carries IPv6 egress;
+otherwise leave it off — IPv6 then has no default route and falls back to IPv4,
+rather than being black-holed at a TGW that can't route it.
+
+**Reversibility:** removing `enable_transit_gateway` (or setting it `false`)
+restores the NAT gateways and IPv6 egress-only IGW. Toggling it on or off for an
+already-deployed VPC recreates/destroys NAT gateways and their Elastic IPs and
+briefly interrupts egress, so do it in a maintenance window.
+
 ### Profile
 You may wish to set a specific AWS profile before executing `terraform`
 commands.

VARIABLES.md

@@ -26,6 +26,9 @@ This document provides comprehensive documentation for all variables available i
 | `user_subnets` | `list(string)` | `null` | ALB subnet IDs (exactly 2 required for internal ALB with existing VPC) |
 | `user_security_group` | `string` | `null` | Security group ID for ALB access (required for existing VPC) |
 | `api_endpoint` | `string` | `null` | VPC endpoint ID for API Gateway (required for internal ALB with existing VPC) |
+| `enable_transit_gateway` | `bool` | `false` | Route private-subnet egress through a Transit Gateway instead of NAT gateways (`create_new_vpc = true` only). Disables NAT + the IPv6 egress-only IGW; requires `transit_gateway_id`. See [Transit Gateway egress](README.md#transit-gateway-egress). |
+| `transit_gateway_id` | `string` | `null` | Transit Gateway to attach to (required when `enable_transit_gateway = true`). May be a value known only after apply (e.g. a TGW created in the same configuration). |
+| `transit_gateway_ipv6_egress` | `bool` | `false` | Also route IPv6 (`::/0`) egress through the TGW. Leave off unless the TGW carries IPv6 egress, otherwise IPv6 traffic would be black-holed. |
 
 ### Database Configuration Variables