aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

feat(bootstrap): live-account preflight validator

Open
#126 2 comments 0 reactions 0 assignees View on GitHub
enhancement infra-cdk
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.