google / google/stellar-engine
[Documentation] docs/ddg.md still reports Version v2.9.1 / Updated May 11, 2026 at v4.0.0, and has fallen behind the stages it documents
- Dominant language
- HCL
- Stars
- 49
- Forks
- 20
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 28
Description
## Description of Documentation Need
`docs/ddg.md` is the Detailed Deployment Guide operators follow stage by stage, and it is the
document a training class downloads on day one. At `v4.0.0` (`6d7d08c0`) its own header reads:
```
Updated: May 11, 2026
Version: v2.9.1
Most recent changes: Refresh to v2.9.1
```
Five releases have shipped since (v2.11.0, v2.12.0, v2.13.0, v3.0.0, v4.0.0), and the guide's
content has fallen behind the stages in ways an operator following it cannot see:
1. **Stage 2 directory.** Lines 429 and 639: *"Change directory into
**fast/stages-aw/2-networking-a-fedramp-high**"*. The directory is `fast/stages-aw/2-networking-a-fedramp`
(renamed in #214). Reported separately as #196; listed here because it is a symptom of the same
staleness.
2. **`kms_protection_level`.** Every FAST stage (`0-bootstrap`, `1-resman`, `2-networking-a-fedramp`,
`3-security`) declares this variable with no default, so `terraform apply` stops to ask for it;
the guide's variables table and every stage's tfvars section never mention it. The variable's
behavior is #231; the guide is what an operator has open when the prompt appears.
3. **`regions.secondary`.** `docs/ddg.md:78` documents a `secondary` region under `regions`, but
every stage declares `variable "regions"` as `object({ primary = string })` — no `secondary`
field exists at `v4.0.0` (`2-networking-a-fedramp/variables.tf:161-168` and the other three
stages). Supplying it changes nothing — no stage reads a `secondary` field — so an operator who
expects a second region for the NVAs and Cloud NAT does not get one (`net-vdss.tf:122-128`,
`nva.tf:12` iterate `var.regions`, whose only field is `primary`).
4. **The prerequisite groups.** The Prerequisites section lists nine `gcp-*` groups to create
(`docs/ddg.md:155-163`), but `0-bootstrap/variables.tf` (`groups`, mirrored in every later stage)
recognizes five of them — `gcp-billing-admins`, `gcp-devops`, `gcp-vpc-network-admins`,
`gcp-organization-admins`, `gcp-security-admins` (plus `gcp-support`, aliased to `gcp-devops`) —
and `docs/tdd.md`'s *GCP Initial Role Groups* table names a different nine (no
`gcp-hybrid-connectivity-admins`; logging and monitoring split three ways). Four of the nine
groups an operator creates from the guide — `gcp-developers`, `gcp-hybrid-connectivity-admins`,
`gcp-logging-monitoring-admins`, `gcp-logging-monitoring-viewers` — are never referenced by any
stage.
## Target Audience
Anyone deploying from the guide — the first prompt they meet that the guide does not explain is
where trust in the document ends.
## Proposed Location
`docs/ddg.md`: the header block, the Stage 2 directory lines, a `kms_protection_level` row in the
variables table plus a line in each stage's tfvars section, the `Secondary Region` row, and the
Prerequisites group list.
## Content Outline / Draft
* Header: `Updated` and `Version` set to the release the content was checked against, and kept in
step with each tag (a release checklist item).
* Stage 2: `2-networking-a-fedramp` in both places.
* Variables table: a `kms_protection_level` row (`HSM` for FedRAMP High and IL5; `SOFTWARE`
permitted for FedRAMP Moderate), with the note that every stage requires it.
* Variables table: drop the `Secondary Region` / `regions.secondary` row, or add the field to the
stages — today the row documents a value nothing reads.
* Prerequisites: list the groups the stages bind (`gcp-billing-admins`, `gcp-devops`,
`gcp-vpc-network-admins`, `gcp-organization-admins`, `gcp-security-admins`; `gcp-support` is
aliased to `gcp-devops`), and reconcile the list with `docs/tdd.md`'s *GCP Initial Role Groups*
table so the two documents name the same set.
## Compliance Context (if applicable)
The protection-level gap is the one with a compliance consequence: an operator who answers the
unexplained prompt with anything but `HSM` on a FedRAMP High deployment gets software-backed keys
for state, logs and NVA disks, and the guide gave them nothing to go on.
Contributor guide
Research direction
Start with docs/ddg.md and compare its header, stage paths, variables, and prerequisite groups against the four stage variables.tf files and docs/tdd.md. Check the referenced regions usage in net-vdss.tf and nva.tf before documenting the current behavior. Done means the guide accurately matches v4.0.0, explains required protection levels, and agrees with the stage definitions and TDD group table.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- google-cloud, terraform
- Domain
- cloud, documentation, infrastructure
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100