fix(2-networking-a-fedramp): validate proxy_subnets and tenant subnets up front

[scottonix]

Description

Two inputs of fast/stages-aw/2-networking-a-fedramp read as optional but are required, and a plan that omits either one fails with Invalid index deep inside the module tree rather than at the input:

• proxy_subnets defaults to {}, but branch-net-envs.tf:109 indexes it with each environment key (var.proxy_subnets[each.key]) to create the spoke's proxy-only subnet.
• Every environment needs a subnet under subnets[lower(<env>)] with a non-null tenant in regions.primary: connectivity-tests.tf:79, nva.tf:31 and outputs.tf:23 all take the first such subnet with [...][0] and use it to index the spoke's subnet map. With no tenant subnet the try() returns an empty list and [0] fails; with the first tenant subnet in another region the map lookup fails.

This adds a validation block to each variable so the plan stops immediately with a message that names the missing input, and states in the proxy_subnets description that one entry per environment is required. Validation blocks may reference other variables since Terraform 1.9, and the shared modules already require >= 1.10.2. No resource or output changes; a configuration that planned before plans identically now.

Making both inputs genuinely optional (no proxy-only subnet, no connectivity test address for an environment without one) would be a larger change touching three files and the stage outputs consumed by later stages; happy to do that as a follow-up if that is the preferred direction.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Deployment & Compliance Impact

• Applicable Regimes:
  • US Region Restricted (e.g., Access Policy constraint)
  • FedRAMP Moderate
  • FedRAMP High
  • DoD IL4
  • DoD IL5
  • General / All
• NIST 800-53r5 Controls: none affected.

Checklist

Code Quality & Reusability

• My code adheres to the Maximize Reusability principle. I have not redefined common elements and have reused existing base configurations and modules where possible.
• I have checked that no existing module or configuration in modules/ or fast/ can be leveraged for this change.
• My code follows the established naming conventions outlined in documentation/naming-convention.md.

Documentation

• I have updated the README.md of the modified module or blueprint. (Variable description updated; the README variables table is tfdoc-generated.)
• I have added/updated documentation for inputs (variables) and outputs.

Security

• My change adheres to GCP security best practices and the principle of least privilege.
• I have ensured compliance with the targeted regime (FedRAMP Moderate, FedRAMP High, IL5, etc.).

Testing

• I have tested my changes locally.
• I have included details of my testing in this PR.

Testing Performed

Terraform 1.10.5, terraform fmt -check clean, terraform validate passes. Plans with placeholder inputs (-refresh=false, invalid credentials; one environment Prod, one tenant ten-1):

inputs	main (df47667)	this branch
proxy_subnets and a tenant subnet in us-east4 provided	plans 136 resources	plans the same 136 resources
proxy_subnets omitted	Error: Invalid index on branch-net-envs.tf line 109 (var.proxy_subnets is empty map of string)	Error: Invalid value for variable on proxy_subnets: proxy_subnets needs an entry for every key of envs_folders …
subnet list with no tenant	four separate errors: Invalid index on branch-net-envs.tf:221, Invalid template interpolation value on :222, Invalid index on connectivity-tests.tf:79 and on nva.tf:31	Error: Invalid value for variable on subnets: Every environment in envs_folders needs a subnet list … whose first subnet with a non-null tenant is in regions.primary …

Both failure modes were first hit on a live deployment of this stage (each cost a failed Cloud Build run before the cause was found in the module code).