Skip to content

Commit cc774ea

Browse files
josefaidtjosefaidt
committed
add notes
1 parent 1fba05c commit cc774ea

File tree

1 file changed

+168
-6
lines changed
  • src/pages/[platform]/start/migrate-to-gen2

1 file changed

+168
-6
lines changed

‎src/pages/[platform]/start/migrate-to-gen2/index.mdx‎

Lines changed: 168 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
22

33
export const meta = {
4-
title: 'Gen 2 for Gen 1 customers',
4+
title: 'Migrate to Gen 2',
55
description: 'Learn how to set up your AWS account and configure it locally for use with Amplify.',
66
platforms: [
77
'android',
@@ -16,9 +16,9 @@ export const meta = {
1616
]
1717
};
1818

19-
export const getStaticPaths = async () => {
19+
export function getStaticPaths () {
2020
return getCustomStaticPath(meta.platforms);
21-
};
21+
}
2222

2323
export function getStaticProps(context) {
2424
return {
@@ -29,12 +29,174 @@ export function getStaticProps(context) {
2929
};
3030
}
3131

32-
## Migrating from Gen 1 to Gen 2
32+
## Starting point
33+
34+
My app
35+
36+
- main branch --> prod BE
37+
- dev branch ---> dev BE
38+
- custom domain setup
39+
- main.myapp.com and dev.myapp.com
40+
41+
## Set up migration environment
42+
43+
1. git clone my-app
44+
2. git checkout -b migrate-to-gen2
45+
3. amplify init --envName prod to initialize the app locally
46+
4. amplify env add --envName migrate to create a temporary migration env
47+
1. this should prompt for any OAuth credentials, Function env vars, secrets, etc.
48+
5. amplify push to create the new environment
49+
6. deploy `migrate-to-gen2` branch in Console and connect it to `migrate` env.
50+
7. amplify migrate to initiate the migration
51+
52+
## Generate Gen 2 codegen
53+
54+
```console title="Terminal" showLineNumbers={false}
55+
> amplify migrate
56+
You are about to migrate to Amplify Gen 2: <Docs URL>
57+
✓ Move project/amplify to project/.amplify/gen-1
58+
✓ Transforming your auth and data backend definition to Gen 2 configuration:
59+
✔ amplify/auth/resource.ts
60+
✔ amplify/data/resource.ts
61+
✔ Updating .gitignore to remove Gen1 files
62+
✔ Update package.json with Gen 2 dependencies
63+
✔ Installing @aws-amplify/backend
64+
✔ Installing @aws-amplify/backend-cli
65+
66+
Run `npx ampx sandbox` to test whether your Gen 2 backend works.
67+
```
68+
69+
## Test whether Gen2 codegen works as expected in sandbox
70+
71+
```console title="Terminal" showLineNumbers={false}
72+
> npx ampx sandbox
73+
74+
# starts a cloudformation deploy
75+
76+
# new tab
77+
> npm run dev
78+
79+
# starts localhost
80+
81+
```
82+
83+
optionally run validation tool to compare resource configurations from live Gen 1 stack to CFN artifacts from Gen 2 synth
84+
85+
Now let's add an `amplify.yml` to your project. If you already have a YAML stored in the Console, go to the console and download the file and add it to the root of your project. Update the amplify.yml to look like
86+
87+
```diff title="amplify.yml"
88+
version: 1
89+
backend:
90+
phases:
91+
build:
92+
commands:
93+
- - "# Execute Amplify CLI with the helper script"
94+
- - amplifyPush --simple
95+
+ - npm ci
96+
+ - npx ampx pipeline-deploy --app-id $AWS_APP_ID --branch $AWS_BRANCH
97+
frontend:
98+
phases:
99+
build:
100+
commands:
101+
- npm run build
102+
artifacts:
103+
baseDirectory: build
104+
files:
105+
- "**/*"
106+
cache:
107+
paths:
108+
- node_modules/**/*
109+
```
110+
111+
## Now deploy the migrate-to-gen2 branch
112+
113+
First push this code to a Git branch
114+
115+
```bash title="Terminal" showLineNumbers={false}
116+
git add .
117+
git commit -m "migrate to gen2"
118+
git push -u origin migrate-to-gen2
119+
```
120+
121+
Now deploy the `migrate-to-gen2` branch in the Amplify Console as a new branch in the Gen 2 console. Now you should see:
122+
123+
- main branch --> prod BE
124+
- dev branch ---> dev BE
125+
- migrate-to-gen2 branch (gen2 stack) --> migrate BE (Gen 1 CF stack)
126+
127+
- custom domain setup
128+
- main.myapp.com and dev.myapp.com and migrate-to-gen2.myapp.com (with autosubdomains enabled)
129+
130+
Remove backend assooication between migrate-to-gen2 branch (gen2 stack) --> migrate BE (Gen 1 CF stack)
131+
Now you have a Gen 1 backend environment called "migrate" and a Gen 2 branch called "migrate-to-gen2". Go back to your terminal and execute:
132+
133+
```bash title="Terminal" showLineNumbers={false}
134+
# some command to generate the logical ID mapping, and any other prep
135+
amplify migrate --generate-mapping --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
136+
# this --continue can error if we don't have gen 2 artifacts
137+
```
138+
139+
```bash title="Terminal" showLineNumbers={false}
140+
# validate resource configurations between the stacks match
141+
amplify migrate --compare auth --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
142+
amplify migrate --compare auth,data,storage --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
143+
```
144+
145+
```bash title="Terminal" showLineNumbers={false}
146+
# some command to execute CFN stack refactoring with map
147+
amplify migrate --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
148+
```
149+
150+
## Apply changes to real environments
151+
152+
1. Remove backend association in console
153+
154+
1. Locally checkout branch you want to migrate
155+
156+
```bash title="Terminal" showLineNumbers={false}
157+
git checkout dev #apply to whatever branch
158+
159+
git merge migrate-to-gen2 -X theirs
160+
161+
git push
162+
```
163+
164+
```bash title="Terminal" showLineNumbers={false}
165+
# some command to generate the logical ID mapping, and any other prep
166+
amplify migrate --generate-mapping --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
167+
# this --continue can error if we don't have gen 2 artifacts
168+
```
169+
170+
```bash title="Terminal" showLineNumbers={false}
171+
# validate resource configurations between the stacks match
172+
amplify migrate --compare auth --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
173+
amplify migrate --compare auth,data,storage --from amplifymigratesoemgen1stackname --to amplify-gen1togen2-branch-12345
174+
```
175+
176+
---
33177

34-
We are actively developing migration tooling to aid in transitioning your project from Gen 1 to Gen 2. Until then, we recommend you continue working with your Gen 1 Amplify project. We remain committed to supporting both Gen 1 and Gen 2 for the foreseeable future. For new projects, we recommend adopting Gen 2 to take advantage of its [enhanced capabilities](/[platform]/how-amplify-works/concepts/). Meanwhile, customers on Gen 1 will continue to receive support for high-priority bugs and essential security updates.
178+
If anything fails in the flow above, customers can always run `git reset --hard HEAD` and they are back to Gen 2.
35179

180+
1. this prints a message about migrating to gen 2, including a link to migration docs
181+
2. this moves amplify/ to .amplify/gen-1 (this shouldn't be impacted by subsequent gen2 deployments)
182+
3. this codegen's gen2 backend resources — Auth, Data, Storage, Function resources
183+
4. this modifies gitignore, removes Gen 1 gitignore block, adds Gen 2 gitignore (e.g. .amplify/)
184+
1. print diff and prompt for confirmation
185+
5. this installs gen 2 tooling with package manager of choice
186+
1. print list of dependencies and prompt for confirmation
187+
2. Note: Gen 1 CLI does not have this detection built in, however we can always prompt with a list of package managers
188+
3. (see create-amplify for list of dependencies https://github.com/aws-amplify/amplify-backend/blob/main/packages/create-amplify/src/amplify_project_creator.ts#L15-L26)
189+
6. this writes amplify.yml with the default gen 2 template
190+
1. print diff and prompt for confirmation
191+
2. how do we handle existing, customized yml files?
192+
3. how do we handle complex frontend builds? should this get carried from the existing file?
193+
7. this prepares any artifacts needed for stack refactoring
194+
1. print a notice
195+
2. do we need to deploy gen 2 first?
196+
8. customer confirms changes by manually inspecting generated outputs, then commits to git
197+
9. ...
36198

37-
## Gen 1 vs. Gen 2 feature matrix
199+
## Feature matrix
38200

39201
The tables below present a feature matrix for Gen 1 customers who are considering Gen 2 for their apps. This will help determine the support availability for various features.
40202

0 commit comments

Comments
 (0)