Skip to content

feat(cli): add the stellar command with preflight checks - #305

Merged
aghassemlouei merged 8 commits into
google:mainfrom
digitalresistor:feat/cli-preflight
Oct 20, 2026
Merged

aghassemlouei merged 8 commits into
google:mainfrom
digitalresistor:feat/cli-preflight

Conversation

@digitalresistor

@digitalresistor digitalresistor commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

This change adds the stellar command line tool and its first subcommand, stellar preflight. Preflight tells an operator whether the workstation, identity and organization meet every prerequisite in the docs/ddg.md guide 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.

  • Stage 0 manages several organization roles authoritatively, so its first apply removes every grant on those roles that is not in code. Preflight compares each role's current members with the members that the organization-iam.tf file keeps on that role, and lists every grant the apply removes.
  • Stage 0 creates organization-wide custom roles, custom constraints and log sinks. Preflight warns when they already exist from another deployment in the same organization.
  • A deleted project keeps its ID for 30 days, so Stage 0 fails when a soft-deleted project still holds one of its project IDs. Preflight reports those projects with the undelete command or a new prefix as the fix. This is the preflight check for [Feature Request] Automate Project ID randomization for soft-delete mitigation #50, which tracks the soft-delete collision problem.
  • Stage 0 always grants the bootstrap_user value as a user: principal. Terraform itself can run as a service account, so preflight accepts a --bootstrap-user flag that names the user account, prints the matching -var bootstrap_user argument, and fails only when no user account is available.

The checks run in the order of the guide's prerequisites section.

  • Terraform meets the highest required_version floor in the modules/*/versions.tf files, and the Google Cloud SDK and jq are installed.
  • The gcloud account and the Application Default Credentials identity match, a user account is available for bootstrap_user, and the active gcloud project is the bootstrap project.
  • The organization exists, and its domain and directory customer ID match the operator's values.
  • The identity holds every role in the setIAM.yaml.sample file in the fast/stages-aw/0-bootstrap/ stage. The check tests effective permissions with testIamPermissions, 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.
  • The billing account is open and the bootstrap project bills to it.
  • A shared billing account can forbid IAM changes, which Stage 0 supports through no_iam = true in its billing_account variable. The --billing-no-iam flag matches that setting, so preflight skips the Billing Account Administrator check and tests only the billing.resourceAssociations.create permission that Stage 0 needs to link new projects.
  • The bootstrap project is active and has every API from the enableServices.sh script plus the Cloud Monitoring API that the guide requires.
  • The Stage 0 administrative groups exist in Cloud Identity, resolved from the groups variable the same way the Stage 0 main.tf file resolves them, with a manual fallback when the credentials cannot query Cloud Identity.
  • The region supports the compliance regime according to the Assured Workloads locations page, and the regime appears in the Stage 0 regime_mapping variable.
  • The prefix is valid, and no visible project, soft-deleted project, state bucket or Assured Workloads folder that Stage 0 creates already uses it.
  • Super Admin status, Access Transparency and project quota appear as manual confirmations.

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.py module fail when those files or the guide drift apart.

The docs/ddg.md guide and the docs/prerequisites.md checklist now tell operators to run preflight before Stage 0. Both documents replace the hard-coded Terraform version with a reference to the required_version constraints, following the version-agnostic documentation rule.

Part of #306, which tracks the full stellar tool 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

  • The cli/ directory is a self-contained uv project with a locked dependency set, so its dependencies and Python version stay separate from the tools/ scripts and the root test suite.
  • The CLI runs on exactly one Python version, 3.14, because requires-python in the cli/pyproject.toml file 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.
  • The tools/run_tests.sh script compiles every Python file with the system python3, which cannot parse the Python 3.14 except syntax that ruff writes. The script skips the cli/ directory, because the cli-tests job compiles, lints and tests it on Python 3.14.
  • The cli/src/stellar_engine/repo.py module 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.
  • The CLI tests live in the cli/tests/ directory rather than the root tests/ directory. The root suite runs on an older Python and replaces missing dependencies such as yaml with mocks in the tests/__init__.py module, so CLI tests there could pass without exercising real code.
  • The CLI code follows the Google Python Style Guide with 4-space indentation, 80-character lines and ruff, as style(repo): replace yapf with ruff and adopt the Google Python Style Guide's 4-space indent #302 proposes for the whole repository under issue Adopt the Google Python Style Guide and ruff for Python formatting #304. The yapf rule and 79-character limit in the .gemini/styleguide.md guide still apply to existing files until that pull request merges.
  • The cli-tests job runs ruff, whose F rules cover the pyflakes checks, so the root pyflakes step does not need to scan the cli/ directory.
  • Google Cloud access goes through a small CloudApi protocol in the cli/src/stellar_engine/gcp/api.py module, so unit tests use in-memory fakes and never touch the network.
  • The new cli-tests job in the .github/workflows/ci.yml workflow pins astral-sh/setup-uv to a commit SHA, like the other actions.
  • The tools/check_boilerplate.py, tools/check_links.py, tools/run_tests.sh and tests/scripts/test_shell_syntax.sh tools skip .venv directories so a synced cli/.venv does 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 the tools/check_boilerplate.py script, and refactor(tests): flatten test suite into tests/ and expand unit coverage #299 moves the tests/scripts/ directory, so this branch may need a rebase after either merges.

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 directly. The tool reads configuration and changes no Terraform resource. Its authoritative IAM warning supports reviews under AC-2 and AC-6 before Stage 0 changes organization access.

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/ 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 a config.env file, 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.
  • The sync tests in the cli/tests/test_repo.py module pass against this checkout. They compare the setIAM.yaml.sample roles with the guide's role list, the enableServices.sh APIs with the docs/prerequisites.md checklist, the prefix limit with the Stage 0 and Stage 1 validation blocks, the regimes with the Stage 0 regime_mapping variable, and every documentation link in the report with a real heading.
  • uv run ruff format --check, uv run ruff check and uv run pyright report no issues.
  • python3 tools/check_boilerplate.py cli/src cli/tests passes.
  • bash tests/scripts/run_shell_tests.sh and the root pytest suite pass unchanged.
  • The compile step of the tools/run_tests.sh script passes on Python 3.11.
  • With only uv-managed interpreters allowed and an empty cache, uv run --project cli downloads Python 3.14 and runs the tool.
  • The python-hcl2 parsing returns the same service accounts, project names, Terraform floor and authoritative bindings as the earlier regexes.
  • python3 tools/check_links.py --no-show-summary docs cli reports no new broken links. The existing /docs/artifacts/ failures in the docs/path-to-authorization.md file are unchanged.
  • A live run against a shared test organization used a service account identity with a separate --bootstrap-user value, because no user credentials were available for that organization, so the unit tests alone cover the user identity path.
    • The run completed in under a minute and confirmed 12 of the 13 roles, including about 14,000 testable roles/owner permissions.
    • It accepted the service account with the named bootstrap user and flagged the three APIs that the bootstrap project lacks.
    • It reported the disabled Cloud Billing and Cloud Identity APIs in the credentials' quota project, each with the exact gcloud services enable command.
    • It listed 45 existing grants that the first Stage 0 apply would remove from authoritative roles, including the identity's own direct grants that bootstrap_user does not keep.
    • After the organization enabled the APIs and created the groups, a rerun confirmed every group through Cloud Identity.
    • With the --billing-no-iam flag 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.
    • The live run also showed that Resource Manager answers 403 for project IDs that do not exist, so the project collision check searches for the exact IDs that Stage 0 creates instead of treating a 403 as a taken ID.

@digitalresistor

Copy link
Copy Markdown
Contributor Author

Example preflight output

This 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 bootstrap_user.

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.com
Local tools
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ Terraform version          │ Terraform 1.13.3 meets the 1.10.2 minimum.                         │
│ PASS     │ jq                         │ jq-1.8.2 is installed.                                             │
│ PASS     │ Google Cloud SDK           │ Google Cloud SDK 589.0.0 is installed.                             │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Identity
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ Active gcloud account      │ gcloud is signed in as                                             │
│          │                            │ deployer@my-bootstrap-project.iam.gserviceaccount.com.             │
│ PASS     │ Application Default        │ Terraform will run as                                              │
│          │ Credentials                │ deployer@my-bootstrap-project.iam.gserviceaccount.com.             │
│ PASS     │ gcloud and Terraform use   │ Both use the same account.                                         │
│          │ the same identity          │                                                                    │
│ PASS     │ Bootstrap user             │ Pass `-var bootstrap_user=admin@example.com` on the first Stage 0  │
│          │                            │ apply. Terraform runs as                                           │
│          │                            │ deployer@my-bootstrap-project.iam.gserviceaccount.com.             │
│ PASS     │ Active gcloud project      │ The active gcloud project is my-bootstrap-project.                 │
│ PASS     │ No stale service account   │ No impersonation environment variables are set.                    │
│          │ impersonation              │                                                                    │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Organization
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ Organization access        │ Organization 123456789012 is example.com.                          │
│ PASS     │ Organization domain        │ Organization domain is example.com.                                │
│ PASS     │ Directory customer ID      │ Directory customer ID is C01234567.                                │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Organization IAM roles
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ roles/logging.admin        │ The deploying identity holds all 80 testable permissions on the    │
│          │                            │ organization.                                                      │
│ PASS     │ roles/iam.organizationRole │ The deploying identity holds all 15 testable permissions on the    │
│          │ Admin                      │ organization.                                                      │
│ PASS     │ roles/resourcemanager.orga │ The deploying identity holds all 36 testable permissions on the    │
│          │ nizationAdmin              │ organization.                                                      │
│ PASS     │ roles/resourcemanager.proj │ The deploying identity holds all 2 testable permissions on the     │
│          │ ectCreator                 │ organization.                                                      │
│ PASS     │ roles/resourcemanager.tagA │ The deploying identity holds all 17 testable permissions on the    │
│          │ dmin                       │ organization.                                                      │
│ PASS     │ roles/owner                │ The deploying identity holds all 13902 testable permissions on the │
│          │                            │ organization.                                                      │
│ PASS     │ roles/assuredworkloads.adm │ The deploying identity holds all 46 testable permissions on the    │
│          │ in                         │ organization.                                                      │
│ PASS     │ roles/axt.admin            │ The deploying identity holds all 5 testable permissions on the     │
│          │                            │ organization.                                                      │
│ PASS     │ roles/orgpolicy.policyAdmi │ The deploying identity holds all 26 testable permissions on the    │
│          │ n                          │ organization.                                                      │
│ PASS     │ roles/iam.serviceAccountAd │ The deploying identity holds all 19 testable permissions on the    │
│          │ min                        │ organization.                                                      │
│ FAIL     │ roles/billing.admin        │ Cannot test this role on the billing account: The                  │
│          │                            │ cloudbilling.googleapis.com API is disabled in project             │
│          │                            │ 111111111111, which these credentials use for quota. Run `gcloud   │
│          │                            │ services enable cloudbilling.googleapis.com                        │
│          │                            │ --project=111111111111`.                                           │
│          │                            │ See: docs/prerequisites.md#initial-iam-grants                      │
│ PASS     │ roles/resourcemanager.proj │ The deploying identity holds the only testable permission on the   │
│          │ ectDeleter                 │ organization.                                                      │
│ PASS     │ roles/iam.serviceAccountTo │ The deploying identity holds all 9 testable permissions on the     │
│          │ kenCreator                 │ organization.                                                      │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Billing
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ FAIL     │ Billing account            │ Cannot read billing account 000000-AAAAAA-BBBBBB: The              │
│          │                            │ cloudbilling.googleapis.com API is disabled in project             │
│          │                            │ 111111111111, which these credentials use for quota. Run `gcloud   │
│          │                            │ services enable cloudbilling.googleapis.com                        │
│          │                            │ --project=111111111111`.                                           │
│          │                            │ See: docs/prerequisites.md#bootstrap-project                       │
│ FAIL     │ Bootstrap project billing  │ Cannot read the billing link of my-bootstrap-project: The          │
│          │                            │ cloudbilling.googleapis.com API is disabled in project             │
│          │                            │ 111111111111, which these credentials use for quota. Run `gcloud   │
│          │                            │ services enable cloudbilling.googleapis.com                        │
│          │                            │ --project=111111111111`.                                           │
│          │                            │ See: docs/prerequisites.md#bootstrap-project                       │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Bootstrap project
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ Bootstrap project          │ my-bootstrap-project is active.                                    │
│ FAIL     │ Required APIs              │ Not enabled: assuredworkloads.googleapis.com,                      │
│          │                            │ cloudbilling.googleapis.com, cloudkms.googleapis.com.              │
│          │                            │ Fix: Run `gcloud services enable cloudkms.googleapis.com           │
│          │                            │ assuredworkloads.googleapis.com cloudbilling.googleapis.com        │
│          │                            │ --project=my-bootstrap-project`.                                   │
│          │                            │ See: docs/prerequisites.md#required-apis                           │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Administrative groups
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ MANUAL   │ Administrative groups      │ Cloud Identity cannot be queried (The cloudidentity.googleapis.com │
│          │                            │ API is disabled in project 111111111111, which these credentials   │
│          │                            │ use for quota. Run `gcloud services enable                         │
│          │                            │ cloudidentity.googleapis.com --project=111111111111`.). Confirm    │
│          │                            │ that these groups exist: gcp-billing-admins@example.com,           │
│          │                            │ gcp-devops@example.com, gcp-organization-admins@example.com,       │
│          │                            │ gcp-security-admins@example.com,                                   │
│          │                            │ gcp-vpc-network-admins@example.com                                 │
│          │                            │ See: docs/prerequisites.md#administrative-groups                   │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Prefix and region
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ Region                     │ IL5 is available in us-east4.                                      │
│ PASS     │ Prefix format              │ tst1 is a valid prefix.                                            │
│ PASS     │ Project IDs                │ No existing projects use this prefix. Project IDs are global, so a │
│          │                            │ project outside this identity's view can still own one, which      │
│          │                            │ Stage 0 reports as a conflict.                                     │
│ PASS     │ State buckets              │ No existing buckets use this prefix.                               │
│ PASS     │ Assured Workloads folder   │ No existing folders use this prefix.                               │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Shared organization risks
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ PASS     │ Organization-wide names    │ No Stage 0 organization-wide resources exist yet.                  │
│ WARN     │ Authoritative IAM roles    │ The first Stage 0 apply removes 45 existing grants from roles it   │
│          │                            │ manages authoritatively: roles/assuredworkloads.admin              │
│          │                            │ serviceAccount:deployer@my-bootstrap-project.iam.gserviceaccount.c │
│          │                            │ om, roles/axt.admin                                                │
│          │                            │ serviceAccount:deployer@my-bootstrap-project.iam.gserviceaccount.c │
│          │                            │ om, roles/browser group:platform-team-1@example.com, roles/browser │
│          │                            │ group:platform-team-2@example.com, roles/browser                   │
│          │                            │ group:platform-team-3@example.com, roles/browser                   │
│          │                            │ group:platform-team-4@example.com, roles/browser                   │
│          │                            │ group:platform-team-5@example.com, roles/browser                   │
│          │                            │ group:platform-clients-1@example.com, roles/browser                │
│          │                            │ serviceAccount:automation-1@example-project.iam.gserviceaccount.co │
│          │                            │ m, roles/browser                                                   │
│          │                            │ serviceAccount:automation-2@example-project.iam.gserviceaccount.co │
│          │                            │ m, and 35 more.                                                    │
│          │                            │ Fix: Review these grants with the organization administrators      │
│          │                            │ before Stage 0, because Terraform removes them.                    │
│          │                            │ See: docs/prerequisites.md#initial-iam-grants                      │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Manual confirmations
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status   ┃ Check                      ┃ Detail                                                             ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ MANUAL   │ Super Admin                │ Confirm that the deploying user is a Google Workspace or Cloud     │
│          │                            │ Identity Super Admin at https://admin.google.com/ac/roles.         │
│          │                            │ See: docs/prerequisites.md#google-cloud-organization               │
│ MANUAL   │ Access Transparency        │ Confirm that Access Transparency is enabled at                     │
│          │                            │ https://console.cloud.google.com/iam-admin/settings.               │
│          │                            │ See: docs/prerequisites.md#organization-features-and-quotas        │
│ MANUAL   │ Project quota              │ Confirm that the project quota allows at least 13 new projects.    │
│          │                            │ See: docs/prerequisites.md#organization-features-and-quotas        │
└──────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────┘
Summary: 31 pass, 1 warn, 4 fail, 4 manual, 0 skip

What the run surfaced before any Terraform ran

  • The billing and Cloud Identity checks failed because those APIs are disabled in the project that the credentials use for quota, and each row prints the exact gcloud services enable command.
  • Three Stage 0 prerequisite APIs are missing on the bootstrap project, and the fix lists all three in one command.
  • The authoritative IAM warning lists 45 existing organization grants that the first Stage 0 apply would remove, including grants held by the platform's own automation accounts and the deploying identity's direct grants that bootstrap_user does not keep.
  • The role checks confirm effective permissions, including all 13,902 testable roles/owner permissions, regardless of how each role is granted.
  • Without preflight, each of these surfaces only as a Terraform error partway through Stage 0, or, for the IAM removals, not at all until access disappears.

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.
auto-merge was automatically disabled October 20, 2026 22:39

Head branch was pushed to by a user without write access

@aghassemlouei aghassemlouei added Enhancement New feature or request Priority - Medium Standard features and non-blocking bugs; important for the current milestone but not urgent Level of Effort - High Complex task taking a week or more; consider breaking this down into smaller issues. Scope - Fast Related to Fabric FAST deployment stages in the fast directory labels Oct 20, 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.

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.py on line 198 (except api.CloudError, requests.RequestException:) and cli/src/stellar_engine/tools.py on line 61 (except OSError, subprocess.SubprocessError:), unparenthesized multi-exception syntax requires Python 3.14 (PEP 758). That causes bash tools/run_tests.sh (which runs ast.parse across every .py file in the repository) to fail with SyntaxError on Python 3.11 through 3.13, and prevents operators on Cloud Shell or standard Linux workstations from running stellar without installing Python 3.14. Parenthesizing those two except (...) clauses and lowering requires-python in cli/pyproject.toml (and pythonVersion in [tool.pyright]) to >=3.11 (the enum.StrEnum floor) allows the CLI and tools/run_tests.sh to run on Python 3.11 through 3.14.
  • In cli/src/stellar_engine/repo.py, python-hcl2 is already loaded for _bootstrap_variables(), whereas _module_names(), authoritative_bindings(), and min_terraform_version() scrape .tf files with line and character regexes (_MODULE_RE, _NAME_RE, _HOLDER_RE, _DELETE_ROLES_RE). Using hcl2.load() for automation.tf, log-export.tf, billing.tf, and versions.tf avoids fragile line-order or bracket assumptions if a module block or role list is reformatted.

@digitalresistor

Copy link
Copy Markdown
Contributor Author

Python 3.11 is in end-stages of life: https://devguide.python.org/versions/ using Python 3.14 with uv IMHO means we can pin versions for dependencies and validate things function correctly on a single Python version instead of trying to support a range of them.

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 uv across the board allows us to avoid those pitfalls, have a single known good version that we can target and test against and know that everyone is running the exact same versions thereby reducing support requirements.

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.
@digitalresistor

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Both points are addressed in fc64200 and c02f39e.

Python version

  • The tools/run_tests.sh failure reproduces on Python 3.11. The script now skips cli/, as the root pyflakes step already does, because the cli-tests job compiles, lints and tests it on Python 3.14.
  • Parenthesizing the two except clauses does not hold, because ruff format with target-version = "py314" rewrites them back to the PEP 758 form, and the cli-tests job runs ruff format --check.
  • Operators do not need to install Python 3.14. uv downloads it when the workstation lacks it. With only uv-managed interpreters allowed and an empty cache, uv run --project cli stellar --version downloaded Python 3.14 and ran the tool.
  • That test also showed that requires-python = ">=3.14" let uv pick 3.15, so the range now excludes 3.15. CI and every workstation run the same interpreter.

python-hcl2 parsing

  • _module_names(), authoritative_bindings() and min_terraform_version() now read automation.tf, log-export.tf, billing.tf, organization-iam.tf and the module versions.tf files with python-hcl2.
  • python-hcl2 returns the conditional cond ? {} : {...} bindings for the domain and the bootstrap user as expression strings, so the map literal in the else branch is parsed again with hcl2.loads.
  • An unknown principal in a binding map now raises instead of being skipped.
  • The results match the earlier regexes for every service account, project name, Terraform floor and binding. New tests cover compact one-line blocks and the conditional holders.

@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.

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.

@aghassemlouei
aghassemlouei merged commit 0fb5fcb into google:main Oct 20, 2026
7 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