Repository navigation
feat(cli): add the stellar command with preflight checks - #305
Conversation
Example preflight outputThis report comes from a live, read-only run against a shared test organization. Every organization, project, billing account, domain, and principal identifier is replaced with a placeholder, and the counts and findings are unchanged. The run takes about 20 seconds, and the deploying identity is a service account with a separate user as uv run --project cli stellar preflight \
--org 123456789012 --domain example.com --customer-id C01234567 \
--project my-bootstrap-project --billing-account 000000-AAAAAA-BBBBBB \
--prefix tst1 --regime IL5 --region us-east4 \
--bootstrap-user admin@example.comWhat the run surfaced before any Terraform ran
|
Add a self-contained uv project under cli/ that provides the stellar command. The preflight subcommand validates the prerequisites in docs/ddg.md without changing any resource: local tools, the gcloud and ADC identity, effective organization role permissions, billing, the bootstrap project and its APIs, administrative groups, the region for the compliance regime, prefix collisions, and shared-organization risks such as grants that Stage 0 removes from authoritative roles. Role, API, group, sink, custom role and constraint lists are parsed from the repository so the CLI never drifts from setIAM.sh, enableServices.sh and the Stage 0 variables.
Add a cli-tests job that runs the license header check, ruff format, ruff check, pyright and pytest for the cli/ project with uv. Skip .venv directories in check_boilerplate.py and check_links.py, and prune .venv, venv, node_modules and __pycache__ in run_tests.sh and test_shell_syntax.sh, so a synced cli/.venv does not produce false failures.
Tell operators to run stellar preflight before Stage 0 and replace the hard-coded Terraform version with a reference to the modules' required_version constraints, which preflight enforces.
Terraform can run Stage 0 as a service account because the stage only needs a user account for the bootstrap_user variable. Replace the --allow-service-account flag with --bootstrap-user, which names that user, and keep that user when listing authoritative grants that Stage 0 removes. Drop the billing ID hint when the billing account lookup itself fails, and use singular wording for roles with one testable permission.
A deleted project keeps its ID for 30 days, so Stage 0 fails when a soft-deleted project still holds one of the IDs it creates, even on a redeploy. Search for each Stage 0 project ID in both the active and the DELETE_REQUESTED states, and report soft-deleted holders as a failure with the undelete command or a new prefix as the fix. Preflight check for google#50.
… IAM A shared billing account can forbid IAM changes, and Stage 0 supports it with billing_account.no_iam, which skips every billing IAM binding. Stage 0 then only needs to link new projects to the account. Add the --billing-no-iam flag, which drops the Billing Account Administrator check and tests billing.resourceAssociations.create on the billing account instead, with Billing Account User as the fix.
Head branch was pushed to by a user without write access
346fb1f to
2bb24fb
Compare
aghassemlouei
left a comment
There was a problem hiding this comment.
The stellar preflight design, read-only verification flow, and fake-backed test harness are well structured and directly address Stage 0 failure modes before Terraform runs. A few items worth addressing before merge so this works smoothly across developer workstations and the existing test runner.
- In
cli/src/stellar_engine/gcp/live.pyon line 198 (except api.CloudError, requests.RequestException:) andcli/src/stellar_engine/tools.pyon line 61 (except OSError, subprocess.SubprocessError:), unparenthesized multi-exception syntax requires Python 3.14 (PEP 758). That causesbash tools/run_tests.sh(which runsast.parseacross every.pyfile in the repository) to fail withSyntaxErroron Python 3.11 through 3.13, and prevents operators on Cloud Shell or standard Linux workstations from runningstellarwithout installing Python 3.14. Parenthesizing those twoexcept (...)clauses and loweringrequires-pythonincli/pyproject.toml(andpythonVersionin[tool.pyright]) to>=3.11(theenum.StrEnumfloor) allows the CLI andtools/run_tests.shto run on Python 3.11 through 3.14. - In
cli/src/stellar_engine/repo.py,python-hcl2is already loaded for_bootstrap_variables(), whereas_module_names(),authoritative_bindings(), andmin_terraform_version()scrape.tffiles with line and character regexes (_MODULE_RE,_NAME_RE,_HOLDER_RE,_DELETE_ROLES_RE). Usinghcl2.load()forautomation.tf,log-export.tf,billing.tf, andversions.tfavoids fragile line-order or bracket assumptions if a module block or role list is reformatted.
|
Python 3.11 is in end-stages of life: https://devguide.python.org/versions/ using Python 3.14 with Most Python versions installed on Linux are out of date, have installed python packages that are out of date, and or are not full featured due to the packagers splitting it up into multiple different packages. Standardizing on using I will make the change only if necessary. I don't have access to Cloud Shell or "standard Linux workstation". |
The CLI targets one Python version through uv, which downloads it when the workstation lacks it, so operators never install Python themselves. requires-python ">=3.14" still let uv pick a newer release, so cap it below 3.15 to run CI and every workstation on the same version. tools/run_tests.sh compiles every Python file with the system python3, which fails on the PEP 758 except clauses that ruff writes for Python 3.14. Skip the cli/ directory there, as the root pyflakes step already does, because the cli-tests job compiles and lints it on Python 3.14.
…n-hcl2 The module names, authoritative IAM bindings and Terraform version floors came from line and bracket regexes, which break when a block is reformatted. Parse automation.tf, log-export.tf, billing.tf, organization-iam.tf and the module versions.tf files with python-hcl2 instead. A conditional binding map is parsed again from its else branch, and an unknown principal now raises instead of being skipped.
|
Thanks for the review. Both points are addressed in fc64200 and c02f39e. Python version
python-hcl2 parsing
|
aghassemlouei
left a comment
There was a problem hiding this comment.
Pinning requires-python = ">=3.14,<3.15" for uv while skipping cli/ in tools/run_tests.sh and switching _module_names(), authoritative_bindings(), and min_terraform_version() in repo.py to python-hcl2 cleanly resolves both items.
Description
This change adds the
stellarcommand line tool and its first subcommand,stellar preflight. Preflight tells an operator whether the workstation, identity and organization meet every prerequisite in thedocs/ddg.mdguide before Stage 0, and it explains how to fix each gap. It only reads from Google Cloud and never changes a resource.Today operators verify the prerequisites by hand, and a missing role, disabled API or reused prefix surfaces only as a Terraform error partway through Stage 0. The checks also catch risks that the guide does not mention.
organization-iam.tffile keeps on that role, and lists every grant the apply removes.bootstrap_uservalue as auser:principal. Terraform itself can run as a service account, so preflight accepts a--bootstrap-userflag that names the user account, prints the matching-var bootstrap_userargument, and fails only when no user account is available.The checks run in the order of the guide's prerequisites section.
required_versionfloor in themodules/*/versions.tffiles, and the Google Cloud SDK and jq are installed.bootstrap_user, and the active gcloud project is the bootstrap project.setIAM.yaml.samplefile in thefast/stages-aw/0-bootstrap/stage. The check tests effective permissions withtestIamPermissions, so it accepts direct, group and inherited grants. It tests Billing Account Administrator on the billing account when one is given, because the guide allows that grant there.no_iam = truein itsbilling_accountvariable. The--billing-no-iamflag matches that setting, so preflight skips the Billing Account Administrator check and tests only thebilling.resourceAssociations.createpermission that Stage 0 needs to link new projects.enableServices.shscript plus the Cloud Monitoring API that the guide requires.groupsvariable the same way the Stage 0main.tffile resolves them, with a manual fallback when the credentials cannot query Cloud Identity.regime_mappingvariable.The tool reads the role, API, group, log sink, custom role and custom constraint lists from the repository instead of copying them. Sync tests in the
cli/tests/test_repo.pymodule fail when those files or the guide drift apart.The
docs/ddg.mdguide and thedocs/prerequisites.mdchecklist now tell operators to run preflight before Stage 0. Both documents replace the hard-coded Terraform version with a reference to therequired_versionconstraints, following the version-agnostic documentation rule.Part of #306, which tracks the full
stellartool and its remaining pull requests. This pull request does not close that issue. The tool also extends #49, which asks to automate part of the Stage 0 setup.Design notes
cli/directory is a self-contained uv project with a locked dependency set, so its dependencies and Python version stay separate from thetools/scripts and the root test suite.requires-pythonin thecli/pyproject.tomlfile excludes 3.15. uv downloads that version when a workstation lacks it, so operators on Cloud Shell or any Linux workstation only install uv, and CI tests the same interpreter that operators run.tools/run_tests.shscript compiles every Python file with the systempython3, which cannot parse the Python 3.14exceptsyntax that ruff writes. The script skips thecli/directory, because thecli-testsjob compiles, lints and tests it on Python 3.14.cli/src/stellar_engine/repo.pymodule reads the Stage 0 module names, authoritative IAM bindings and module Terraform version floors with python-hcl2, so reformatting a block or role list does not change the facts it extracts.cli/tests/directory rather than the roottests/directory. The root suite runs on an older Python and replaces missing dependencies such asyamlwith mocks in thetests/__init__.pymodule, so CLI tests there could pass without exercising real code..gemini/styleguide.mdguide still apply to existing files until that pull request merges.cli-testsjob runs ruff, whoseFrules cover the pyflakes checks, so the rootpyflakesstep does not need to scan thecli/directory.CloudApiprotocol in thecli/src/stellar_engine/gcp/api.pymodule, so unit tests use in-memory fakes and never touch the network.cli-testsjob in the.github/workflows/ci.ymlworkflow pinsastral-sh/setup-uvto a commit SHA, like the other actions.tools/check_boilerplate.py,tools/check_links.py,tools/run_tests.shandtests/scripts/test_shell_syntax.shtools skip.venvdirectories so a syncedcli/.venvdoes not produce false failures. Open pull request chore(repo): fix repo-wide lint failures and make tools/lint.sh fail closed #286 makes an overlapping change to thetools/check_boilerplate.pyscript, and refactor(tests): flatten test suite into tests/ and expand unit coverage #299 moves thetests/scripts/directory, so this branch may need a rebase after either merges.Type of Change
Deployment & Compliance Impact
Checklist
Code Quality & Reusability
modules/orfast/stages-aw/can be leveraged for this change.docs/naming-convention.md.Documentation
README.mdof the modified module or blueprint.Security
Testing
Testing Performed
uv run pytestin thecli/directory passes 160 tests. They cover every check with in-memory fakes for pass, fail, warn, manual and skip outcomes, the per-role authoritative IAM semantics, the input resolution from flags, environment variables and aconfig.envfile, the command line exit codes and JSON output, the user, service account and metadata server identity paths, a service account deployer with a separate bootstrap user, billing accounts without billing IAM, parsing that ignores the layout of the Stage 0 files, and the translation of Google API errors.cli/tests/test_repo.pymodule pass against this checkout. They compare thesetIAM.yaml.sampleroles with the guide's role list, theenableServices.shAPIs with thedocs/prerequisites.mdchecklist, the prefix limit with the Stage 0 and Stage 1 validation blocks, the regimes with the Stage 0regime_mappingvariable, and every documentation link in the report with a real heading.uv run ruff format --check,uv run ruff checkanduv run pyrightreport no issues.python3 tools/check_boilerplate.py cli/src cli/testspasses.bash tests/scripts/run_shell_tests.shand the rootpytestsuite pass unchanged.tools/run_tests.shscript passes on Python 3.11.uv run --project clidownloads Python 3.14 and runs the tool.python3 tools/check_links.py --no-show-summary docs clireports no new broken links. The existing/docs/artifacts/failures in thedocs/path-to-authorization.mdfile are unchanged.--bootstrap-uservalue, because no user credentials were available for that organization, so the unit tests alone cover the user identity path.roles/ownerpermissions.gcloud services enablecommand.bootstrap_userdoes not keep.--billing-no-iamflag against a shared billing account, the rerun skipped the Billing Account Administrator check and failed only the project linking check, with Billing Account User as the fix.