google / google/stellar-engine

[Documentation] FedRAMP Moderate networking: record whether a Moderate-specific network pattern was superseded, which regions it supports, and where IL2 lands

Open
#195 0 comments 0 reactions 0 assignees View on GitHub
documentation Level of Effort - Medium Priority - Medium
Dominant language
HCL
Stars
49
Forks
20
Avg merge
3d 14h
Merged PRs (30d)
28

Description

## Description of Documentation Need

`v3.0.0` folded FedRAMP Moderate into the FedRAMP High networking stage — `fast/stages-aw/2-networking-a-fedramp-high` became `fast/stages-aw/2-networking-a-fedramp`, and its README is now "FedRAMP High / Moderate Network". **The resulting pattern is documented**: `docs/tdd.md:946` states plainly that the FedRAMP High / Moderate pattern uses a VDSS topology (Landing + DMZ) with Network Virtual Appliances, and reading the stage confirms it — `net-vdss.tf` creates `vdss-dmz-0` (`:66`) and `vdss-landing-0` (`:93`) unconditionally, and `nva.tf` creates the NVA cluster and its `default-route-nva` route (`:185`) with no regime branch. So a Moderate deployment inherits FedRAMP High's boundary design in full, and the only regime-sensitive input in the stage is `kms_protection_level` (`variables.tf:239`), applied to the NVA keyring at `nva.tf:203`.

What is **not** recorded anywhere is that a different Moderate pattern was planned, and what became of it. Design material we were working from in June 2026 described a third networking option — `2-networking-c-fedramp-mod`, marked "coming soon", covering FedRAMP Moderate and IL2 — with a materially different design: Cloud NGFW endpoints in place of the NVA cluster, a **single** landing-zone VPC rather than the trust/untrust split, **no DMZ VPC**, and Cloud NAT in each VPC rather than egress through the appliances. Nothing resembling it exists at any tag we have checked, no `.tf` in the repository declares a Cloud NGFW firewall endpoint, and a code search for `2-networking-c` returns nothing. The diagram from that material:

Image

Side by side with what the stage builds today:

| Dimension | Planned Moderate pattern | Shipped FedRAMP High / Moderate stage |
|---|---|---|
| Perimeter | Cloud NGFW endpoints, Enterprise edition | NVA cluster on Compute Engine (`nva.tf`, no regime branch) |
| VPC design | One landing-zone VPC | Separate trust and untrust — `vdss-landing-0`, `vdss-dmz-0` |
| DMZ VPC | None | Always created, both regimes |
| Internet egress | Cloud NAT per VPC | Spoke → NVA → DMZ → Cloud NAT |
| Regions | US plus Europe, Asia, South America | No support statement |
| IL2 | Paired with Moderate | Not mentioned in any networking documentation |
| Regime lever | The whole topology | `kms_protection_level` only |

**To be clear: this is not a request to build that design.** Folding Moderate into the NVA pattern may well be the right call, and `docs/tdd.md` describes two supported patterns as settled fact. The request is that the decision be recorded, because as things stand an operator planning a Moderate deployment cannot answer three questions from the repository.

## Target Audience

Operators and architects choosing a compliance regime before they deploy — the topology decision drives both cost and the security-boundary story they will have to defend. Security auditors and SSP authors, who must describe the deployed boundary protection accurately per regime. Anyone estimating run cost, since an NVA cluster plus a DMZ VPC prices very differently from managed firewall endpoints.

## Proposed Location

A short **"Regime coverage"** paragraph appended to the existing *"FedRAMP High / Moderate Pattern (2-networking-a-fedramp)"* block in `docs/tdd.md` §3.6, which is where the pattern is already described, plus the same statement in `fast/stages-aw/2-networking-a-fedramp/README.md` for anyone who arrives at the stage directly rather than through the design doc.

## Content Outline / Draft

Three statements, none of which exists today:

1. **Was a Moderate-specific network pattern superseded, or is it deferred?** One sentence either way settles it. If it is on a roadmap, saying so is just as useful as saying it was dropped.
2. **Which regions are supported for a Moderate deployment of this stage?** The org-policy template already treats Moderate differently — `gcp.resourceLocations` allows `in:us-locations` for other regimes but only denies `in:asia-east2-locations` and `in:global` under `FEDRAMP_MODERATE` (`fast/stages-aw/0-bootstrap/data/custom-org-policies/platform_policy.yaml:151-164`), and `compute.managed.restrictProtocolForwardingCreationForTypes` is skipped under Moderate (`:103-111`). So policy permits regions the networking stage makes no support statement about, and an operator cannot tell whether the NVA path is expected to work in them.
3. **Where does IL2 land?** `IL2` is a recognized regime in `regime_mapping` (`fast/stages-aw/0-bootstrap/variables.tf:333`), but no networking stage README and no TDD section mentions it, so it is not clear which of the two patterns an IL2 deployment should use.

## Compliance Context (if applicable)

FedRAMP Moderate, FedRAMP High and IL2 — the question is precisely which of them this stage covers and on what terms. Control-wise, the topology *is* the boundary-protection control, so SC-7 and AC-4 are what an SSP describing a Moderate deployment has to get right; SC-12 and SC-13 are where `kms_protection_level`, the one regime-sensitive input in the stage, applies.

Whatever the answer turns out to be, please record it in a comment here before closing. [#101](https://github.com/google/stellar-engine/issues/101), the platform-level FedRAMP Moderate request, was closed as completed with no comment explaining what shipped — which is a large part of why this question has to be asked from the outside now rather than looked up.

Related: [#191](https://github.com/google/stellar-engine/issues/191) reports a separate accuracy problem in the same stage's documentation, and [#192](https://github.com/google/stellar-engine/issues/192) covers the workload-side half of this gap — the platform supports Moderate but no blueprint family targets it.

Contributor guide

Open the contributing guide

Research direction

Read the existing pattern sections in docs/tdd.md §3.6 and fast/stages-aw/2-networking-a-fedramp/README.md, then verify the referenced policy and regime-mapping entries under fast/stages-aw/0-bootstrap. Confirm with maintainers whether the Moderate pattern was superseded or deferred, which regions are supported, and where IL2 belongs; done means both documentation locations record those three decisions.

Written by the indexing model from the issue text.

Assessment

Tech stack
gcp, terraform
Domain
cloud, documentation, networking, security
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.