Merge pull request #184 from clopca/release/v4.8

v4.8: BYOIP NAT support, role-based outputs, Cloud WAN & IPAM fixes, CI

Author: pablo19sc

.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI - Lint & Validate
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_wrapper: false
+
+      - name: Terraform Format Check
+        run: terraform fmt -check -recursive
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          tflint_version: v0.53.0
+          tflint_wrapper: false
+
+      - name: Init TFLint
+        run: tflint --init --config .tflint.hcl
+
+      - name: Run TFLint
+        run: tflint --config "$GITHUB_WORKSPACE/.tflint.hcl" --recursive
+
+      - name: Setup terraform-docs
+        uses: jaxxstorm/action-install-gh-release@v2.1.0
+        with:
+          repo: terraform-docs/terraform-docs
+          tag: v0.19.0
+
+      - name: Check docs are up to date
+        run: |
+          terraform-docs --config .terraform-docs.yaml .
+          if ! git diff --exit-code README.md; then
+            echo "::error::README.md is out of date. Run 'terraform-docs .' locally and commit."
+            exit 1
+          fi
+
+  validate:
+    name: Validate (${{ matrix.target }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - root
+          - examples/basic
+          - examples/advanced
+          - examples/ipam
+          - examples/transit_gateway
+          - examples/cloud_wan
+          - examples/vpc_lattice
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_wrapper: false
+
+      - name: Terraform Init
+        working-directory: ${{ matrix.target == 'root' && '.' || matrix.target }}
+        run: terraform init -backend=false
+
+      - name: Terraform Validate
+        working-directory: ${{ matrix.target == 'root' && '.' || matrix.target }}
+        run: terraform validate

.header.md

@@ -247,6 +247,63 @@ Terraform Plan:
 ...
 ```
 
+# BYOIP (Bring Your Own IP) for NAT Gateway EIPs
+
+You can control how Elastic IPs are sourced for NAT Gateways using the `nat_gateway_eip_configuration` variable. Three modes are available:
+
+## Default (create)
+
+When `nat_gateway_eip_configuration` is not set (or `mode = "create"`), EIPs are allocated from Amazon's default pool. This is the existing behaviour — no changes required for current users.
+
+## BYOIP Pool
+
+Allocate EIPs from a customer-owned public IPv4 address pool:
+
+```hcl
+module "vpc" {
+  source  = "aws-ia/vpc/aws"
+  version = ">= 4.6.0"
+
+  name       = "byoip-vpc"
+  cidr_block = "10.0.0.0/16"
+  az_count   = 3
+
+  subnets = {
+    public = {
+      netmask                   = 24
+      nat_gateway_configuration = "all_azs"
+    }
+    private = {
+      netmask                 = 24
+      connect_to_public_natgw = true
+    }
+  }
+
+  nat_gateway_eip_configuration = {
+    mode             = "byoip_pool"
+    public_ipv4_pool = "ipv4pool-ec2-xxxxxxxxxxxxxxxxx"
+  }
+}
+```
+
+## Existing EIPs
+
+Use pre-allocated EIP allocation IDs (e.g., managed outside this module):
+
+```hcl
+nat_gateway_eip_configuration = {
+  mode = "existing"
+  allocation_ids = {
+    "us-east-1a" = "eipalloc-0123456789abcdef0"
+    "us-east-1b" = "eipalloc-0123456789abcdef1"
+  }
+}
+```
+
+When `mode = "existing"`, the module does **not** create `aws_eip` resources — it attaches the provided allocation IDs directly to the NAT Gateways. Keys must match the AZ names where NAT Gateways will be deployed.
+
+Credit: Inspired by community PR#179 ([@hminaee-tc](https://github.com/hminaee-tc)).
+
 # Common Errors and their Fixes
 
 ## Error creating routes to Core Network
@@ -297,6 +354,28 @@ subnets = {
 
 * Alternatively, you can also not configure any subnet route (`var.core_network_routes`) to the Core Network until the attachment gets accepted.
 
+## Production Recommendation: Explicit `cidrs` over `netmask`
+
+For production deployments, prefer explicit `cidrs` over calculated `netmask` to avoid subnet replacement on changes.
+
+When using `netmask`, CIDRs are calculated positionally based on lexicographic ordering of subnet key names. Adding or removing a subnet type (e.g., adding `database = { netmask = 26 }`) can shift CIDRs assigned to existing subnets — causing Terraform to destroy and recreate them, resulting in downtime.
+
+```hcl
+# ⚠️ Development only — CIDRs shift if you add/remove subnet types
+subnets = {
+  private = { netmask = 24 }
+  public  = { netmask = 24 }
+}
+
+# ✅ Production-safe — CIDRs are pinned regardless of key changes
+subnets = {
+  private = { cidrs = ["10.0.0.0/24", "10.0.1.0/24", "10.0.2.0/24"] }
+  public  = { cidrs = ["10.0.3.0/24", "10.0.4.0/24", "10.0.5.0/24"] }
+}
+```
+
+This is particularly important when using multiple private subnet roles (e.g., `private`, `isolated`, `database`) since alphabetical ordering determines CIDR allocation.
+
 # Contributing
 
 Please see our [developer documentation](https://github.com/aws-ia/terraform-aws-vpc/blob/main/contributing.md) for guidance on contributing to this module.