[Documentation] fast/stages-aw README misdescribes the networking stage: it advertises VPN connectivity neither option implements, and calls VPC-level firewall rules and subnets "YAML-based factories" when both are plain tfvars variables

[JohnHales]

Description of Documentation Need

fast/stages-aw/README.md describes the networking stage as:

Manages centralized network resources in a separate stage, and is typically owned by the networking team. This stage implements a hub-and-spoke design, and includes connectivity via VPN to on-premises, and YAML-based factories for firewall rules (hierarchical and VPC-level) and subnets. Currently, two networking options (IL5/IL4 and FedRAMP High/Moderate Compliant) are available.

That sentence makes four claims about what the stage ships. Three of them are wrong, and they are wrong in the same direction — each describes a capability the reader would plan around.

1. Neither option implements VPN connectivity to on-premises

Verified across every .tf file in both stages: there is no VPN gateway, Cloud Router, Interconnect attachment or Network Connectivity Center hub in either one.

• 2-networking-a-fedramp (FedRAMP High / Moderate) — main.tf, net-vdss.tf, branch-net-envs.tf, nva.tf, psc.tf, connectivity-tests.tf, log-metric-alerts.tf, outputs.tf, variables.tf: no hybrid-connectivity resource of any kind.
• 2-networking-b-il5-ngfw (IL5/IL4) — same result.

The only peering present is VPC peering between the hub and the environment spokes (module.peering-envs, branch-net-envs.tf), which is internal to the landing zone and is not on-premises connectivity. The one hybrid-shaped resource in the tree, google_network_connectivity_internal_range (branch-net-envs.tf, ~lines 117-133), is commented out.

2. VPC-level firewall rules are not a YAML factory — they come from tfvars

Every net-vpc-firewall call in both networking options passes its rules from the firewall_rules Terraform variable, and not one of them sets factories_config.

2-networking-a-fedramp — three calls:

• net-vdss.tf:76 module "dmz-firewall" → :84-85 ingress_rules = try(var.firewall_rules.dmz.ingress, {}), egress_rules = try(var.firewall_rules.dmz.egress, {})
• net-vdss.tf:108 module "vdss-firewall" → :116-117, against var.firewall_rules.vdss
• branch-net-envs.tf:138 module "env-spoke-firewall" → :148-149, against var.firewall_rules[lower(each.key)]

2-networking-b-il5-ngfw — four calls, the same pattern plus the management VPC that option adds:

• net-vdss.tf:72 module "dmz-firewall" → :80-81
• net-vdss.tf:104 module "vdss-firewall" → :112-113
• net-vdss.tf:135 module "mgmt-firewall" → :143-144, against var.firewall_rules.mgmt
• branch-net-envs.tf:138 module "env-spoke-firewall" → :148-149

firewall_rules is declared as an ordinary variable in each stage's variables.tf (variables.tf:303 in the FedRAMP option — "Firewall rules for each VPC / environment spoke"), so these rules are written in terraform.tfvars, not in YAML files.

The hierarchical half of the claim is correct and is worth keeping: main.tf:44-50 builds module "firewall-policy-default" from net-firewall-policy with cidr_file_path = "${var.factories_config.data_dir}/cidrs.yaml" and ingress_rules_file_path = "${var.factories_config.data_dir}/hierarchical-ingress-rules.yaml". That is a genuine YAML factory, and it is present in both options (main.tf:44-49 in the IL5/IL4 one).

3. Subnets are not a YAML factory either — same pattern, both options

2-networking-a-fedramp:

• net-vdss.tf:73 — subnets = try(var.subnets.dmz, [])
• net-vdss.tf:96 — subnets = try(var.subnets.landing, [])
• branch-net-envs.tf:104 — subnets = try(var.subnets[lower(each.key)], [])

2-networking-b-il5-ngfw:

• net-vdss.tf:69 (dmz), :92 (landing), :123 (mgmt) and branch-net-envs.tf:104 (spokes) — all try(var.subnets.<key>, [])

Every subnet in both options comes from the subnets variable, i.e. from terraform.tfvars.

Net: of the three things the sentence calls "YAML-based factories", exactly one is — and this is not specific to one regime. Both networking options are affected identically, so the sentence is wrong for FedRAMP High, FedRAMP Moderate, IL4 and IL5 alike. The VPN clause looks inherited from the generic upstream FAST 2-networking stage, where hybrid connectivity genuinely is part of the design. Neither clause describes the stages-aw variants as built.

Target Audience

Operators and partner architects planning a landing-zone deployment — the people most likely to read this README while scoping how an existing data center will connect and how the network will be maintained day to day. Both errors cost them the same way. A partner sizing a FedRAMP High engagement can reasonably read the current text as "hybrid connectivity ships with the stage" and plan an architecture, a statement of work or a customer commitment around it; the same partner can promise a customer that firewall rules and subnets are managed as reviewable YAML data files, which is how a network team is usually persuaded to adopt a factory pattern in the first place, and then discover at implementation time that both are Terraform variables in terraform.tfvars.

Proposed Location

fast/stages-aw/README.md, the networking-stage paragraph quoted above. Optionally also a one-line note in each stage README (2-networking-a-fedramp/README.md, 2-networking-b-il5-ngfw/README.md) stating that hybrid connectivity is not included and which inputs are factory-driven.

Content Outline / Draft

Correct both clauses, and point at what an operator would actually use:

Manages centralized network resources in a separate stage, and is typically owned by the networking team. This stage implements a hub-and-spoke design, a YAML-based factory for hierarchical firewall policy rules, and Terraform variables for VPC-level firewall rules and subnets. Currently, two networking options (IL5/IL4 and FedRAMP High/Moderate Compliant) are available.

Hybrid connectivity is not deployed by this stage. Connectivity to on-premises or to another cloud is an additive design step: the repository ships modules/net-vpn-ha, modules/net-vpn-dynamic, modules/net-vpn-static, modules/net-ipsec-over-interconnect and modules/ncc-spoke-ra, none of which is instantiated by either networking option. Placement, route propagation through the NVAs, and firewall policy for the hybrid path have to be designed for the target environment.

On the factory clause, the fix belongs in the README rather than in the code. Both networking options are consistently tfvars-driven for these two inputs — every VPC firewall rule and every subnet in both.

Compliance Context (if applicable)

Applies equally to FedRAMP High, FedRAMP Moderate, IL4 and IL5, since both networking options are affected. No NIST control is misstated — this is a scoping and expectation-setting problem rather than a control gap. The VPN clause matters most during boundary definition, where an architect is deciding whether on-premises systems fall inside the authorization boundary and how traffic will reach them. The factory clause matters to change management rather than to any control text: how firewall rules are stored and reviewed is something assessors ask about, and "YAML files in a data directory" and "variables in a tfvars file" are different answers.

[JohnHales]

Correcting one thing in my own report above: I wrote that the hierarchical half of the factory claim is accurate and worth keeping. Having gone back through the history, that is wrong at v3.0.0, and the situation is simpler than I described — none of the three "YAML-based factories" in that sentence is operative.

The hierarchical policy factory is wired: 2-networking-a-fedramp/main.tf:44-50 passes cidr_file_path = "${var.factories_config.data_dir}/cidrs.yaml" and ingress_rules_file_path = "${var.factories_config.data_dir}/hierarchical-ingress-rules.yaml", with data_dir defaulting to "data" (variables.tf:73-77). But at f64ce6cd there is no data/ directory in either networking option, and neither file exists:

• data/cidrs.yaml was deleted by PR fixes warnings on variables for steps 1 2 3, removed yaml files from … #66 (429ab04d, 2026-05-22) — the same change that removed data/firewall-rules/** and data/subnets/** and introduced terraform.tfvars.sample plus the firewall_rules and subnets variables. That PR is the reason for the tfvars pattern the report describes; it just did not reach this README.
• hierarchical-ingress-rules.yaml does not exist anywhere in the repository and, as far as I can tell from the history, never has — the path in main.tf does not correspond to a file that was ever committed.

This fails silently rather than loudly. modules/net-firewall-policy/factory.tf:18-32 reads each path as coalesce(try(yamldecode(file(...)), {}), {}), so a missing file yields an empty map: terraform apply succeeds and the hierarchical policy is created carrying only whatever ingress_rules / egress_rules are passed inline, with no factory-sourced rules and no named CIDRs.

One related loose end from the same PR: factories_config.dns_policy_rules_file still defaults to "data/dns-policy-rules.yaml" (variables.tf:77), a file that PR #66 also deleted, and the field is referenced nowhere else in the stage — a dead default pointing at a dead path.

So the documentation fix is broader than I first wrote: the sentence should not describe any part of this stage as YAML-factory-driven. Whether the dangling cidrs.yaml / hierarchical-ingress-rules.yaml paths and the unused dns_policy_rules_file default should be removed from the code, or the data files restored, is a separate call — happy to open it separately if that is useful.