You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -29,174 +29,113 @@ export function getStaticProps(context) {
29
29
};
30
30
}
31
31
32
-
## Starting point
32
+
Amplify migration tooling is available! In this guide we will walk through how to perform migrations for your backends from Amplify Gen 1 to Amplify Gen 2. The steps you will perform will be against a new Amplify Gen 1 backend environment, and a new Amplify Gen 2 environment. After the steps are performed, you will be able to merge the migration branch onto your existing branches to individually migrate with zero downtime.
33
33
34
-
My app
34
+
## Preparing for migration
35
+
36
+
The most notable change between Amplify Gen 1 backends and Gen 2 backends is the use of infrastructure as code with TypeScript. Preparing your environment for migration involves converting the configuration of your live Gen 1 backend resources to their Gen 2 equivalent written using TypeScript.
35
37
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.
**Note:** at any moment up until the migration is executed on your Gen 1 and Gen 2 backends, you can revert by discarding changes tracked by git.
75
51
76
-
# new tab
77
-
> npm run dev
52
+
</Callout>
78
53
79
-
# starts localhost
54
+
Then push your newly-created `migrate` environment to create a set of resources matching the configuration of your live environments:
80
55
56
+
```bash title="Terminal" showLineNumbers={false}
57
+
amplify push --yes
81
58
```
82
59
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"
After the push is successful, commit and push the changes to your git provider:
61
+
62
+
```bash title="Terminal" showLineNumbers={false}
63
+
git add .
64
+
git commit -m "create migration env"
65
+
git push --upstream origin migrate
109
66
```
110
67
111
-
## Now deploy the migrate-to-gen2 branch
68
+
During the migration for the new `migrate` environment, it is recommended to connect the new git branch to your build system to ensure changes continuously integrate with your live environment.
112
69
113
-
First push this code to a Git branch
70
+
Next, prepare your local codebase for migration execution by running the following command:
114
71
115
72
```bash title="Terminal" showLineNumbers={false}
116
-
git add .
117
-
git commit -m "migrate to gen2"
118
-
git push -u origin migrate-to-gen2
73
+
npx @aws-amplify/migrate@latest to-gen-2 prepare
119
74
```
120
75
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:
76
+
After this command completes successfully your `amplify/` directory is converted to an Amplify Gen 2 backend authored in TypeScript. In the next section we will walk through how to validate the generated code using [Amplify Gen 2's sandbox feature](/[platform]/deploy-and-host/sandbox-environments/setup/).
In order to execute the migration you will need to first deploy the Amplify Gen 2 backend, scaffolded by the TypeScript code generated by the preparation command. This will create a new CloudFormation stack with live resources, which will then be used to execute the migration against to migrate resources from your Amplify Gen 1 backend stack to the new stack.
153
101
154
-
1. Locally checkout branch you want to migrate
102
+
{/* picture of amplify console connecting new `migrate` branch */}
155
103
156
-
```bash title="Terminal" showLineNumbers={false}
157
-
git checkout dev #apply to whatever branch
104
+
{/* how to handle CDK bootstrap */}
105
+
{/* how to handle updating service role BEFORE AND AFTER migrations */}
158
106
159
-
git merge migrate-to-gen2 -X theirs
107
+
### Ensure validity of `amplify.yml`
160
108
161
-
git push
162
-
```
109
+
{/* maybe move this section up before deploying the branch -- otherwise it will likely error for frontend builds */}
110
+
{/* ensure package manager is correct */}
111
+
{/* tweak frontend build settings */}
163
112
164
-
```bash title="Terminal" showLineNumbers={false}
165
-
# some command to generate the logical ID mapping, and any other prep
After performing the post-migration tasks, commit your changes and allow your deployment pipeline to deploy changes without error.
129
+
130
+
{/* what happens when you experience an error */}
131
+
176
132
---
177
133
178
-
If anything fails in the flow above, customers can always run `git reset --hard HEAD` and they are back to Gen 2.
179
-
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. ...
198
-
199
-
## Feature matrix
134
+
## Migrating from Gen 1 to Gen 2
135
+
136
+
My app
137
+
138
+
## Gen 1 vs. Gen 2 feature matrix
200
139
201
140
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.
0 commit comments