Back-end migrations can be a tricky task if you're going in blind, and it may take a few attempts before you know the ins and outs of a specific technology being used. Those with experience in AWS will understand that sometimes things don't always go according to plan when performing even the most common tasks in Amplify, and migration of an app from one app ID to another can seem like a huge undertaking.
In this guide, we'll look at how to:
- Reference a new app
- Create a new back-end environment for the migration
- And verify our deployment works
This guide assumes you have an existing application created.
Before Attempting a Migration
Migration can be seen as a refactor of sorts, except it's the entire project that needs to move and work. In any refactoring effort, taking into account all the moving parts is key. But with Amplify, these parts are all tied to policies while creating the environment. What this means for Amplify is that with an existing app, we have the option to use already generated policies or perform a manual shifting of resources.
With the first option, policies and references are already mapped for how the BE would rebuild. However, in option two, there may not be an easy transition of resources especially if the application is large and/or is being upgraded as part of the migration processes. In the case of an older application, it may be easier to manually migrate because the upgrade process might not take into account some older pattern.
We'll use the first option of a simpler migration by referencing the new app id.
Initial Setup
Amplify behaves similarly to git. To get started, first follow a git-like workflow by fetching the latest:
$ amplify pull
It's recommended to commit the latest stable code to your source control of choice in case the migration goes wrong.
In the new AWS account, where this app will live, we need to create a space for it to live. Thankfully, Amplify docs give a step-by-step guide on configuring a new app space.
Referencing the New AWS App
At this point, if you've created a new app in a new account, then there should be a default staging environment. We won't use that one because we want at least one working, clean environment in case we need to start over (by deleting the environment).
Clear old environments
Take a look at the contents of team-provider-info.json and look for AmplifyAppId under any existing environments. Depending on the current environment selected, Amplify Actions will be performed against that environment at that app id.
This isn't useful to use because generating a new develop environment will have:
- A name conflict in this file
- New environments created in the same app
If you used the wrong credentials creating the env, a new app under the old account will be created at the new app id.
Generate an env at the new app id
Typically we'd perform amplify env add to add an environment to an existing app. However, we need to reference the new app. So we'll initialize a new app instead:
$ amplify init --appId <Amplify-Service-Project-AppId>
Found in the Amplify Docs for commands amplify-cli here
The Amplify-Service-Project-AppId can be found by:
- Navigating to AWS Amplify
- Selecting the app
- Selecting App settings > General
- Selecting the end part of the App ARN
Because there won't be environments to read from team-provider-info.json, it won't prompt for using an existing environment. Follow the interactive prompts for your configuration needs.
Verify the new environment and push
To verify that everything went well, look again AmplifyAppId in team-provider-info.json under the new environment. This should match with the Amplify Console.
Now we push:
$ amplify push
Verify Successful Deployment
All's that's left now is to wait while Amplify recreates the policies for all your back-end parts. If it all went well, you should have no failures in the terminal, and see the deployment success in Amplify Console with references to your API, functions, etc. like:
If you have a front-end, re-attach the source control of choice.
Cleanup
The final step after everything is working is to remove references to the old application. We did this partially by deleting old environments in team-provider-info.json. Now we have to delete the old app from the old account, and we're done!
