Skip to content

feat(cli): configure and render stages 0 and 1 - #357

Merged
aghassemlouei merged 15 commits into
google:mainfrom
digitalresistor:feat/cli-configure-render
Oct 27, 2026
Merged

aghassemlouei merged 15 commits into
google:mainfrom
digitalresistor:feat/cli-configure-render

Conversation

@digitalresistor

@digitalresistor digitalresistor commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Description

Record the answers of a deployment once and render ready-to-run Terraform workspaces for the 0-bootstrap and 1-resman stages, so operators stop copying samples and editing tfvars by hand.

This is the second CLI pull request in the series that issue #306 tracks, after the stellar preflight command in #305. It adds the following to the cli/ project.

  • The stellar init command validates every answer against the repository before it saves the answers.yaml file.
  • The wizard walks through eleven sections, offers the organizations and billing accounts it can see, and keeps the current answers as defaults on a rerun.
  • The --set and --non-interactive flags of the stellar init command support scripted runs.
  • The --answers-from and --from-config-env flags seed the answers from another environment or from the scripts/config.env file.
  • The --new-prefix flag suggests a fresh prefix.
  • The stellar env list, stellar env use, and stellar env show commands manage several environments in one home folder.
  • The --home flag and the STELLAR_HOME environment variable select the home folder, so each deployment can live in its own folder outside the checkout.
  • The stellar render command builds each stage workspace from symlinks to the engine checkout and writes the tfvars file from the stage sample.
  • The stellar render command never writes a key that a *.auto.tfvars.json file provides.
  • The command fails when a <placeholder> value survives in the rendered tfvars file.
  • The command asks before it replaces a tfvars file that someone edited by hand.
  • The stage0_phase answer owns the Stage 0 phase, so the stellar render command writes the 0-bootstrap-phase.auto.tfvars file with the bootstrap_user variable for the first apply and removes it for the final apply.
  • Every Stage 0 Terraform command then runs without the -var bootstrap_user option, so a plain terraform apply can no longer run the wrong mode.
  • The imports answer writes Terraform import blocks that adopt the Stage 0 projects and the Assured Workloads workload that an administrator creates in advance.
  • The stellar imports scan command records the existing organization policies, so the final Stage 0 apply imports them in place of the import.sh script.
  • The keep_imported_projects answer keeps pre-created projects on destroy through the project_deletion_policies variable that feat(0-bootstrap): support pre-created projects and workloads #355 added to the fast/stages-aw/0-bootstrap/ stage.
  • The stellar preflight command now reads the answers.yaml file of the current environment.
  • Preflight also checks the Stage 1 tenant project IDs and the imported project IDs.
  • The new billing.precreate preflight check lists the resources that someone with billing access must create in advance.
  • A lab run motivated that check, because Stage 0 cannot create the Assured Workloads workload without access to the billing account.
  • Adopting a pre-created workload relies on the Stage 0 change in feat(0-bootstrap): support pre-created projects and workloads #355.
  • The cli/README.md file describes the Stage 0 operator flow end to end.
  • The cli-tests job in .github/workflows/ci.yml installs Terraform, so the tests that run the real binary also run in CI.

The import and pre-create support stays in this pull request, because a rendered Stage 0 workspace cannot apply in an organization without billing access otherwise.

The CLI writes the answers and the generated files with 0600 permissions, because they hold organization identifiers and principals.

Part of #306. The prefix suggestion of the --new-prefix flag and the soft-deleted tenant project check address the redeploy problem in #50.

A Stage 0 apply in a lab organization succeeds with these workspaces on main. The lab run found the Stage 0 bugs that #358, #359, and #361 fixed, and #355 and #356 added the support for pre-created resources.

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. The CLI renders the existing stage inputs and changes no control implementation.

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/stages-aw/ can be leveraged for this change.
  • My code follows the established naming conventions outlined in docs/naming-convention.md.

Documentation

  • I have updated the README.md of the modified module or blueprint.
  • 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, IL4, IL5, etc.).

Testing

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

Testing Performed

  • uv run pytest in the cli/ project passes 875 tests.
  • The CLI tests live in the cli/tests/ directory, because the root suite runs without the CLI dependencies.
  • The 40 tests that carry the terraform marker run the real Terraform binary.
  • Those tests check that the rendered tfvars files pass terraform fmt.
  • They also run a variables-only terraform plan for every regime fixture.
  • They run terraform init and terraform validate in a symlinked Stage 0 workspace with generated import blocks.
  • Syrupy snapshots cover the rendered tfvars of each regime fixture and stage.
  • Sync tests compare the rendered keys with each variables.tf file and the CLI limits with the Terraform validation blocks.
  • ruff format --check, ruff check, pyright, and tools/check_boilerplate.py pass for the cli/ project.
  • The root test suite passes 103 tests.
  • In a lab organization, the CLI rendered a Stage 0 workspace with two imported projects, a kept list of existing organization grants, and 26 scanned organization policies.
  • The first-apply plan imports the two projects, removes no existing organization IAM member, and destroys nothing.
  • A preview of the final apply imports the existing organization policies instead of creating them.
  • The first apply stopped at the Assured Workloads workload, because the deployer has no access to the shared billing account of the lab.
  • The stellar preflight command ran against the lab organization and reported the resources to create in advance.
  • After the fixes in fix(fast): drop the size() guard from delegated grant conditions #358, fix(modules/folder): pass the folder number to the logging settings #359, and fix(0-bootstrap): let the Stage 0 folders inherit the logging settings #361, the Stage 0 apply in the lab organization completed, the state moved to the remote bucket, and a plan against the remote state reports no changes.
  • A render of the lab environment in the final phase writes no phase file and leaves the tfvars and import files unchanged.

@github-actions github-actions Bot added the Scope - Fast Related to Fabric FAST deployment stages in the fast directory label Oct 24, 2026
@aghassemlouei aghassemlouei added Enhancement New feature or request Level of Effort - High Complex task taking a week or more; consider breaking this down into smaller issues. Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent labels Oct 26, 2026

@aghassemlouei aghassemlouei left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ran the full cli verification suite including all 842 pytest unit, snapshot, and @pytest.mark.terraform tests against 0-bootstrap and 1-resman, ruff, and pyright, and reviewed the Stage 0 and Stage 1 configuration models, HCL renderer, and preflight checks. Everything passes cleanly.

#355 and #356 are now merged into main, so this branch can be rebased onto main whenever the lab Stage 0 apply completes.

@digitalresistor
digitalresistor force-pushed the feat/cli-configure-render branch from cef19d8 to 860d6f1 Compare October 26, 2026 17:16
Stage 0 switches between its first and final apply on whether
bootstrap_user is set, and the DDG passes it with -var on the first
apply only. A plain terraform apply then silently runs the final mode,
and a leftover value keeps the bootstrap mode.

- Add the stage0_phase answer, bootstrap by default and final after the
  state migration; --answers-from never carries it.
- In the bootstrap phase, render writes 0-bootstrap-phase.auto.tfvars
  with bootstrap_user, and in the final phase it removes the file.
- Require bootstrap_user in the bootstrap phase, refuse to replace a
  phase file stellar did not write, and warn when the bootstrap phase
  meets a remote backend.
- Print init, plan and apply hints without -var, and document the
  phase switch in the README.
@digitalresistor
digitalresistor force-pushed the feat/cli-configure-render branch from 57c8a06 to 6a69764 Compare October 26, 2026 21:51
@digitalresistor
digitalresistor marked this pull request as ready for review October 26, 2026 21:53
@digitalresistor

Copy link
Copy Markdown
Contributor Author

Rebased onto main with #355, #356, #358, #359, #361, and #362, and the lab Stage 0 apply completed. The state moved to the remote bucket, and a plan against the remote state reports no changes.

Two commits landed after your review, so the suite now has 875 tests:

  • feat(cli): own the Stage 0 phase with a generated phase file adds the stage0_phase answer. stellar render now writes 0-bootstrap-phase.auto.tfvars with bootstrap_user for the first apply and removes it for the final apply, so no Stage 0 command needs -var bootstrap_user. An environment that already ran a final apply needs stellar init --set stage0_phase=final before its next render, and render warns when it detects that case.
  • test(cli): follow Stage 0 support for pre-created workloads updates the tests now that feat(0-bootstrap): support pre-created projects and workloads #355 is on main.

Could you take a look at the phase file and stellar imports scan in particular? Those change how operators run Stage 0. The zizmor-scan failure is a 403 from the GitHub API on the fork token during the impostor-commit audit, so it needs a maintainer rerun.

@aghassemlouei aghassemlouei left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the stage0_phase phase file lifecycle (0-bootstrap-phase.auto.tfvars), stellar imports scan organization policy import generation, and the updated pre-created workload tests. All 875 CLI tests, ruff, pyright, and the root verification suite pass cleanly. LGTM!

@aghassemlouei
aghassemlouei merged commit f68b707 into google:main Oct 27, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Enhancement New feature or request Level of Effort - High Complex task taking a week or more; consider breaking this down into smaller issues. Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent Scope - Fast Related to Fabric FAST deployment stages in the fast directory

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants