aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(bootstrap): live-account preflight validator
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Parent
Sub-issue 6 of #120 (RFC: Least-privilege CDK bootstrap policies as code)
## Branch strategy
`feat/bootstrap-preflight` → targets `feat/bootstrap-aspect`
## Estimated review time: ~30 min
## Summary
Implement a validator that checks the deployed CDKToolkit stack's CloudFormation outputs against the required bootstrap version/hash before deploying. This prevents the "pull latest, deploy, fail 15 minutes later" failure mode.
## Deliverables
- [ ] Create `cdk/src/bootstrap/preflight/validator.ts`:
- Reads CDKToolkit stack CF outputs (`BootstrapPolicyVersion`, `BootstrapPolicyHash`) via `CloudFormation.describeStacks`
- Compares against required version/hash from the app's policy code
- Returns structured result:
- **PASS**: version matches, hash matches → safe to deploy
- **WARN**: version compatible but hash mismatch → possible console drift, recommend re-bootstrap
- **FAIL**: version too old → lists missing permissions, provides exact remediation command
- **FAIL**: no outputs found → default bootstrap detected (AdministratorAccess), provide bootstrap command
- Outputs both structured JSON (for CI parsing) and human-readable summary (for terminal)
- [ ] Create `cdk/test/bootstrap/validator.test.ts`:
- Mock `CloudFormation.describeStacks` responses for each scenario
- Version match → PASS
- Hash mismatch with compatible version → WARN with advisory message
- Version too old → FAIL with specific missing actions listed
- No CDKToolkit stack → FAIL with "not bootstrapped" message
- No version/hash outputs → FAIL with "default bootstrap detected" message
- AWS SDK error (permissions, network) → clear error message
- [ ] Add `mise //cdk:preflight` task in `cdk/mise.toml`:
- Runs the validator
- Exits 0 on PASS or WARN
- Exits 1 on FAIL
- Prints remediation: exact `mise //cdk:bootstrap` command to fix
## Key design decisions
- Requires only `cloudformation:DescribeStacks` permission (read-only, safe for CI with minimal credentials)
- WARN does **not** block deploy — hash drift from console edits is advisory, not fatal
- FAIL prints the exact `mise //cdk:bootstrap` command needed (copy-paste friendly)
- Validator is importable as a library (for integration tests) and runnable as a CLI entry point (for mise task)
- Uses `@aws-sdk/client-cloudformation` (already a transitive dep via CDK)
## Acceptance criteria
- All test scenarios pass with mocked AWS responses
- `mise //cdk:preflight` exits cleanly when CDKToolkit outputs match
- `mise //cdk:preflight` exits 1 with actionable message when versions mismatch
- Error messages include the exact command to run (no guessing for operators)
Contributor guide
Assessment
This issue has not been assessed yet.