Migrate from AWS to Build
Moving from AWS is less a migration of your application than a replacement of the services around it. A containerized application usually deploys from its existing Dockerfile without a rewrite. The work is in everything you assembled to run it.
The same approach applies to GCP and Azure.
There are two parts: your application and the platform services it depends on, and your data.
For a fuller comparison, see Compare Build & AWS.
1. Map what you are replacing
Section titled “1. Map what you are replacing”List what your application touches today. Most of it has a platform equivalent on Build rather than a service you provision:
| On AWS | On Build |
|---|---|
| EC2, ECS | Dynos |
| RDS, ElastiCache | Managed add-ons |
| VPC, load balancers, Route 53 | Platform networking, private by default |
| IAM | Platform-level role-based access control |
| CloudWatch | Built-in metrics, logs and activity history |
| CodePipeline, CodeDeploy | Pipelines, review apps and one-click rollback |
Anything left over after this exercise is the real scope of your migration: specialist services with no equivalent, which either stay on AWS alongside Build or need replacing with a third-party service.
2. Create the app on Build
Section titled “2. Create the app on Build”Open the team you are deploying into and click New app. Set the team, the pipeline, and the stage.
Connect your GitHub repository and point Build at your Dockerfile. If your application was built by a CI pipeline rather than from a Dockerfile, a Buildpack may be simpler. See Deploying applications.
3. Define your processes
Section titled “3. Define your processes”Whatever ran as its own ECS task definition or service, or as a process on an EC2 instance, becomes a process in your application’s Procfile: a web process for the application itself, worker processes for queue consumers, and scheduled jobs for anything on a timer.
4. Bring your configuration across
Section titled “4. Bring your configuration across”Move your environment variables into the Build app’s config vars. Where configuration lived in Parameter Store or Secrets Manager, it becomes config vars on Build.
IAM policies do not carry over. Access control on Build is role-based and configured once for the account rather than per service.
5. Deploy and check
Section titled “5. Deploy and check”Scale your web process to one dyno, then open the app and confirm it serves as it did on AWS.
Check the things your AWS setup was doing around the application: health checks, log destinations, and any networking rules that were enforced by a security group rather than by your code.
Your database
Section titled “Your database”RDS is replaced by a managed add-on. Postgres becomes Schema To Go.
- Provision the database on Build. Set
import_urlto your RDS instance when you create it, and Build pulls the data across for you. The instance needs to be reachable for this. - Attach it to your app. In the add-on’s Attachments section, choose Attach to App and set the attached-as name to
DATABASE, so your app seesDATABASE_URL. - Redeploy.
A large production database usually wants a replication-based approach rather than an import, so that cutover is a short switch rather than a long copy.
Engineer-led migration support is included on Enterprise plans. Talk to us before you move production data.
6. Cut over
Section titled “6. Cut over”When you are satisfied, move traffic by pointing DNS at Build. Your AWS environment keeps running, so you can point DNS back if you need to. Decommission it once you are confident, not before.
Need help
Section titled “Need help”See Get support, or talk to an engineer about your migration.
