Skip to content

Commit 886228b

Browse files
davidfsmithclaude
davidfsmith
and
claude
committed
Update migration docs: fix param count, add breaking change warning, add PR2/PR3 guides
- Fix SSM parameter count from 14 to 19 (lambda layers and WAF ACL added) - Add prominent BREAKING CHANGE notice: sequential upgrade required for existing deployments — cannot skip directly to latest release - Add full PR 2 and PR 3 testing guide (testing-ssm-cross-stack-migration-pr2.md) - Reference PR 3 (restore base-first ordering) in the migration overview Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent ab78756 commit 886228b

File tree

2 files changed

+189
-61
lines changed

2 files changed

+189
-61
lines changed

‎docs/testing-ssm-cross-stack-migration-pr2.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# SSM Migration — PR 2 and PR 3 Testing Guide
2+
3+
> Run this **after** PR 1 (`feat/ssm-cross-stack-sharing`) has been deployed and confirmed
4+
> working. See [`testing-ssm-cross-stack-migration.md`](testing-ssm-cross-stack-migration.md)
5+
> for PR 1 steps.
6+
7+
---
8+
9+
## PR 2 — Switch infra to SSM, remove T&C CDK infrastructure
10+
11+
PR 2 (`feat/ssm-infra-migration`) does two things:
12+
13+
1. Switches `DeepracerEventManagerStack` to read all shared values from SSM Parameter Store
14+
instead of `Fn::ImportValue`
15+
2. Removes the T&C CDK infrastructure (S3 bucket, CloudFront distribution, pipeline step)
16+
17+
### Why a single pipeline run cannot do both at once
18+
19+
With `Fn::ImportValue`, CloudFormation enforces: a stack cannot remove an export while
20+
another stack still imports it. If base and infra updated in the same pipeline run with
21+
base deploying first, the error would be:
22+
23+
```
24+
Delete canceled. Cannot delete export drem-backend-X-base:ExportsOutput...
25+
as it is in use by drem-backend-X-infrastructure.
26+
```
27+
28+
PR 2 solves this with **infra-first** pipeline ordering (`baseStack.addDependency(stack)`):
29+
30+
- **Infra deploys first** — drops all `Fn::ImportValue` references, reads from SSM instead.
31+
SSM parameters already exist from PR 1, so CloudFormation can resolve them at changeset
32+
creation time.
33+
- **Base deploys second** — can now safely remove the `CfnOutput` exports and T&C
34+
resources because infra no longer imports them.
35+
36+
### Deploy PR 2
37+
38+
Update `build.config`:
39+
40+
```
41+
source_repo = <your-fork>/guidance-for-aws-deepracer-event-management
42+
source_branch = feat/ssm-infra-migration
43+
```
44+
45+
```sh
46+
make install
47+
```
48+
49+
Approve `DeployDREM` when prompted. Expected: 45–90 min.
50+
51+
Watch the pipeline stage order — `infrastructure.deploy` must complete before
52+
`base.deploy` starts. This is the key difference from normal runs.
53+
54+
### Verify post-deploy state
55+
56+
#### No Fn::ImportValue in infra
57+
58+
```sh
59+
aws cloudformation get-template \
60+
--stack-name drem-backend-<label>-infrastructure \
61+
--region <region> \
62+
--query 'TemplateBody' \
63+
--output json \
64+
| python3 -c "
65+
import json, sys
66+
t = json.load(sys.stdin)
67+
count = sum(1 for r in t.get('Resources', {}).values() if 'Fn::ImportValue' in json.dumps(r))
68+
print(f'Fn::ImportValue count: {count}')
69+
"
70+
# Expected: Fn::ImportValue count: 0
71+
```
72+
73+
#### No CloudFormation exports from base
74+
75+
```sh
76+
aws cloudformation list-exports \
77+
--region <region> \
78+
--query 'Exports[?contains(Name, `drem-backend-<label>`)].Name' \
79+
--output table
80+
# Expected: empty table
81+
```
82+
83+
#### SSM parameters still present
84+
85+
```sh
86+
aws ssm get-parameters-by-path \
87+
--path /drem-backend-<label>-base/ \
88+
--region <region> \
89+
--query 'length(Parameters)' \
90+
--output text
91+
# Expected: 19
92+
```
93+
94+
#### Functional checks
95+
96+
> **Verify:**
97+
> - Website accessible and functional
98+
> - T&C page no longer accessible (CloudFront distribution removed)
99+
> - Sign-up and Create User still have no T&C checkbox
100+
101+
---
102+
103+
## PR 3 — Restore base-first pipeline ordering
104+
105+
PR 3 (`feat/restore-base-first-ordering`) is a one-line change: it restores
106+
`stack.addDependency(baseStack)` so that base deploys before infrastructure in all
107+
future pipeline runs.
108+
109+
This is necessary for ongoing development: when a new SSM parameter is added to
110+
`BaseStack` and consumed by `DeepracerEventManagerStack` in the same PR, base must
111+
deploy first so the parameter exists when CloudFormation resolves it for infra's
112+
changeset.
113+
114+
### Deploy PR 3
115+
116+
Update `build.config`:
117+
118+
```
119+
source_repo = <your-fork>/guidance-for-aws-deepracer-event-management
120+
source_branch = feat/restore-base-first-ordering
121+
```
122+
123+
```sh
124+
make install
125+
```
126+
127+
Approve `DeployDREM` when prompted. Both stacks will show no resource changes —
128+
only the pipeline ordering updates. Expected: 30–60 min (mostly pipeline self-mutation).
129+
130+
### Verify
131+
132+
```sh
133+
aws cloudformation describe-stacks \
134+
--stack-name drem-backend-<label>-infrastructure \
135+
--region <region> \
136+
--query 'Stacks[0].StackStatus' \
137+
--output text
138+
# Expected: UPDATE_COMPLETE
139+
140+
aws cloudformation describe-stacks \
141+
--stack-name drem-backend-<label>-base \
142+
--region <region> \
143+
--query 'Stacks[0].StackStatus' \
144+
--output text
145+
# Expected: UPDATE_COMPLETE
146+
```
147+
148+
The migration is complete. All future deployments will use SSM for cross-stack sharing
149+
with base deploying before infrastructure.

‎docs/testing-ssm-cross-stack-migration.md‎

Lines changed: 40 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,25 @@
1-
# Testing Guide: SSM Parameter Store — Cross-Stack Sharing (PR 1 of 2)
1+
# SSM Parameter Store — Cross-Stack Sharing Migration Guide
22

33
## Overview
44

5-
This is the first of two PRs that together eliminate CloudFormation `Fn::ImportValue`
6-
hard dependencies between `BaseStack` and `DeepracerEventManagerStack`.
5+
This is **PR 1 of 3** that together eliminate CloudFormation `Fn::ImportValue` hard
6+
dependencies between `BaseStack` and `DeepracerEventManagerStack` and remove the
7+
Terms & Conditions feature.
8+
9+
> **BREAKING CHANGE — Sequential upgrade required**
10+
>
11+
> If you have an **existing deployment**, you must apply these three PRs **in order**.
12+
> Skipping directly to the latest release will break your deployment with:
13+
> ```
14+
> Delete canceled. Cannot delete export drem-backend-X-base:ExportsOutput...
15+
> as it is in use by drem-backend-X-infrastructure.
16+
> ```
17+
> The three PRs must be deployed as separate pipeline runs in sequence:
18+
> 1. **PR 1** `feat/ssm-cross-stack-sharing` — adds SSM parameters + removes T&C frontend (this PR)
19+
> 2. **PR 2** `feat/ssm-infra-migration` — switches infra to SSM, removes T&C CDK infrastructure
20+
> 3. **PR 3** `feat/restore-base-first-ordering` — restores correct base-first pipeline ordering
21+
>
22+
> Fresh installations (no existing stacks) can apply any single PR or all three in one go.
723
824
**Why this matters:** `Fn::ImportValue` creates a CloudFormation lock between stacks
925
that blocks independent updates. The symptom is:
@@ -15,16 +31,22 @@ as it is in use by drem-backend-X-infrastructure.
1531
1632
### What this PR does (additive only — safe for fresh installs and upgrades)
1733
18-
- Adds 14 SSM parameters to `BaseStack` under `/${stackName}/<key>`
34+
- Adds 19 SSM parameters to `BaseStack` under `/${stackName}/<key>`
1935
- Removes T&C checkbox/link from sign-up flow and admin Create User form
2036
- No changes to `DeepracerEventManagerStack`, the pipeline stage, or any cross-stack
2137
references — existing `Fn::ImportValue` dependencies are untouched
2238
23-
### What PR 2 does (follow-up — requires two-pipeline migration, documented below)
39+
### What PR 2 does (follow-up — requires two-pipeline migration run from PR 1)
2440
25-
- Switches `DeepracerEventManagerStack` to read all 14 values from SSM instead of
41+
- Switches `DeepracerEventManagerStack` to read all values from SSM instead of
2642
via `Fn::ImportValue`
2743
- Removes T&C CDK infrastructure (S3 bucket, CloudFront distributions, pipeline step)
44+
- Deploys infra before base so infra can drop `Fn::ImportValue` while base still exports
45+
46+
### What PR 3 does (one-liner after PR 2 is deployed)
47+
48+
- Restores `stack.addDependency(baseStack)` (base-first ordering) for ongoing development
49+
- Ensures new SSM parameters created in BaseStack exist before infra reads them
2850
2951
---
3052
@@ -103,15 +125,15 @@ make install
103125

104126
Approve `DeployDREM` when prompted. Expected: 45–90 min.
105127

106-
This is a safe upgrade — the pipeline only **adds** 14 SSM parameters to the base
128+
This is a safe upgrade — the pipeline only **adds** 19 SSM parameters to the base
107129
stack. No exports are removed, no cross-stack references change.
108130

109131
### Step 4 — Verify post-deploy state
110132

111133
#### SSM Parameter Store console
112134

113135
Open [SSM Parameter Store](https://console.aws.amazon.com/systems-manager/parameters)
114-
and filter by `/drem-backend-<label>-base/`. Expect **14 parameters**:
136+
and filter by `/drem-backend-<label>-base/`. Expect **19 parameters**:
115137

116138
| Parameter | Contains |
117139
|-----------|---------|
@@ -129,6 +151,11 @@ and filter by `/drem-backend-<label>-base/`. Expect **14 parameters**:
129151
| `commentatorGroupRoleArn` | IAM Role ARN |
130152
| `registrationGroupRoleArn` | IAM Role ARN |
131153
| `authenticatedUserRoleArn` | IAM Role ARN |
154+
| `defaultUserRole` | IAM Role ARN |
155+
| `regionalWafWebAclArn` | WAF Web ACL ARN |
156+
| `appsyncHelpersLambdaLayerArn` | Lambda Layer ARN |
157+
| `helperFunctionsLambdaLayerArn` | Lambda Layer ARN |
158+
| `powertoolsLambdaLayerArn` | Lambda Layer ARN |
132159

133160
Or via CLI:
134161

@@ -153,66 +180,18 @@ make test.cdk
153180
> - Admin Create User form has no T&C checkbox
154181
> - T&C page still accessible at its CloudFront URL (CDK infrastructure not yet removed)
155182
156-
### Step 5 — Clean up
157-
158-
```sh
159-
make drem.clean
160-
```
161-
162-
---
163-
164-
## PR 2 Migration Guide (Fn::ImportValue removal)
165-
166-
> Run this **after** PR 1 has been deployed and confirmed working.
167-
168-
PR 2 switches `DeepracerEventManagerStack` from `Fn::ImportValue` to SSM reads, and
169-
removes the T&C CDK infrastructure. Because this removes CloudFormation exports that
170-
the infra stack currently imports, it **cannot be done in a single pipeline run** when
171-
upgrading from PR 1. Two pipeline runs are required.
172-
173-
### Why two pipeline runs are needed
174-
175-
With `Fn::ImportValue`, CloudFormation enforces: a stack cannot remove an export while
176-
another stack imports it. Even if both stacks update in the same pipeline run, the
177-
evaluation is against the **currently deployed** infra state.
178-
179-
- **Pipeline run 1** (infra-first ordering): Infra drops all `Fn::ImportValue` references
180-
(reads from SSM instead). Base unchanged.
181-
- **Pipeline run 2** (base-first ordering): Base removes the now-unused `CfnOutput`
182-
exports and the T&C CDK resources. Infra already uses SSM — no conflict.
183-
184-
### Pipeline run 1 — Drop Fn::ImportValue from infra
185-
186-
Switch `build.config` to the PR 2 branch with `stack.addDependency` temporarily
187-
**reversed** (infra first). SSM params already exist from PR 1, so infra can resolve
188-
them at changeset creation time.
189-
190-
After this pipeline run completes, infra no longer has any `Fn::ImportValue`:
191-
192-
```sh
193-
aws cloudformation get-template \
194-
--stack-name drem-backend-<label>-infrastructure \
195-
--region <region> \
196-
--query 'TemplateBody' \
197-
| grep -c 'Fn::ImportValue'
198-
# Expected: 0
199-
```
200-
201-
### Pipeline run 2 — Remove base exports and T&C infrastructure
202-
203-
Restore `stack.addDependency(baseStack)` (base first). Trigger a second pipeline run.
204-
Base can now safely remove its `CfnOutput` exports and T&C resources.
183+
### Step 5 — Continue to PR 2
205184

206-
> See `docs/testing-ssm-cross-stack-migration-pr2.md` (in the PR 2 branch) for the
207-
> full step-by-step guide.
185+
See [`docs/testing-ssm-cross-stack-migration-pr2.md`](testing-ssm-cross-stack-migration-pr2.md)
186+
for the PR 2 and PR 3 migration steps.
208187

209188
---
210189

211190
## Key Files Changed (PR 1)
212191

213192
| File | What changed |
214193
|------|-------------|
215-
| `lib/base-stack.ts` | Writes 14 SSM parameters at end of constructor |
194+
| `lib/base-stack.ts` | Writes 19 SSM parameters at end of constructor |
216195
| `lib/constructs/cdn.ts` | Added `comment` prop for CloudFront distribution descriptions |
217196
| `lib/constructs/leaderboard.ts` | Passes `comment` to Cdn construct |
218197
| `lib/constructs/streaming-overlay.ts` | Passes `comment` to Cdn construct |
@@ -221,7 +200,7 @@ Base can now safely remove its `CfnOutput` exports and T&C resources.
221200
| `website/public/locales/en/translation.json` | Removed T&C translation strings |
222201
| `scripts/generate_amplify_config_cfn.py` | Removed `termsAndConditionsUrl` from config |
223202
| `tsconfig.json` | Exclude `website*/` subdirs from CDK `tsc` compilation |
224-
| `test/deepracer-event-manager.test.ts` | CDK assertion test for the 14 SSM parameters |
203+
| `test/deepracer-event-manager.test.ts` | CDK assertion test for the SSM parameters |
225204
| `jest.config.ts` | Converted from `.js` to `.ts` |
226205
| `Makefile` | `make drem.clean`, Python venv fixes, `make test.cdk`, `--require-approval never` |
227206
| `CLAUDE.md` | Project overview, commands, and architecture notes |

0 commit comments

Comments
 (0)