AWS Migration Hub Refactor Spaces is no longer open to new customers as of November 7, 2025. For capabilities similar to AWS Migration Hub Refactor Spaces, explore [AWS Transform](https://aws.amazon.com/transform).

# Getting started with Refactor Spaces
Getting started

This section describes how to get started with AWS Migration Hub Refactor Spaces.

**Topics**
+ [

# Prerequisites
](getting-started-prerequisites.md)
+ [

# Step 1: Create an environment
](getting-started-create-environment.md)
+ [

# Step 2: Create an application
](getting-started-create-application.md)
+ [

# Step 3: Share your environment
](getting-started-share-environment.md)
+ [

# Step 4: Create a service
](getting-started-create-service.md)
+ [

# Step 5: Create a route
](getting-started-create-route.md)

# Prerequisites


The following are the prerequisites for using AWS Migration Hub Refactor Spaces.
+ You must have one or more AWS accounts, and IAM users set up for these accounts. For more information, see [Setting up](setting-up.md).
+ Designate one of the IAM users as the Refactor Spaces environment owner.

The following steps describe how to use AWS Migration Hub Refactor Spaces in the Migration Hub console.

# Step 1: Create an environment


This step describes how to create an environment as part of the Refactor Spaces **Getting started** wizard. You can also create an environment by choosing **Environments** under **App Refactor** in the Refactor Spaces navigation pane.

A Refactor Spaces environment contains the applications, services, and the AWS infrastructure used to safely and incrementally refactor. Refactor Spaces provides a unified view across multiple AWS accounts and simplifies multi-account use cases to accelerate application refactoring. You can create an environment that orchestrates AWS Transit Gateway to bridge cross-account service communication. Alternatively, you can create an environment without a bridge and manage service-to-service communication with your own infrastructure. If you choose to use an environment's network bridge, you can achieve greater deployment independence across accounts and teams.

After an environment is created, you can share the environment with other AWS accounts, organizational units (OUs) in AWS Organizations, or an entire AWS organization. By sharing the environment with other AWS accounts, users in those accounts can create applications, services, and routes within the environment, unless you use AWS Identity and Access Management (IAM) to restrict access.

**To create an environment**

1. Using the AWS account that you created in [Setting up](setting-up.md), sign in to the AWS Management Console and open the Migration Hub console at [https://console.aws.amazon.com/migrationhub/](https://console.aws.amazon.com/migrationhub/).

1. In the Migration Hub console navigation pane, choose **Refactor Spaces**.

1. Choose **Getting started**.

1. Select **Create a refactor environment to start to incrementally modernize to microservices in multiple AWS accounts**.

1. Choose **Start**.

1. Enter a name for the environment.

1. (Optional) Add a description for the environment.

1. (Optional) If you select the **Provision Multi-account network bridge** check box, Refactor Spaces creates a Transit Gateway for your microservices to communicate with your monolith directly across AWS accounts. If you want to use your own network infrastructure for communication across accounts, don't select the check box.

1. Refactor Spaces uses a service-linked role to connect to AWS services to orchestrate them on your behalf. When you use Refactor Spaces for the first time, the service-linked role is created for you with the correct permissions. For more information about the service-linked role, see [Using service-linked roles for Refactor Spaces](using-service-linked-roles.md).

1. Choose **Next** to move to the **Create application** page.

# Step 2: Create an application


This step describes how to create an application as part of the Refactor Spaces **Getting started** wizard. You can also create an application by choosing **Create application** under **Quick actions** in the Refactor Spaces navigation pane.

Applications are containers of services and routes that provide multi-account traffic routing for services in the application. When you create an application, you must provide Refactor Spaces with a VPC to route traffic from the application to services with private URL endpoints. For each application, Refactor Spaces orchestrate a proxy with an Amazon API Gateway connected to a Network Load Balancer through a VPC link.

**To create an application**

1. On the **Create application** page, enter a name for your application.

1. Under **Proxy VPC**, choose a proxy virtual private cloud (VPC) or choose **Create VPC**.

   An application’s proxy needs a VPC. The proxy’s Network Load Balancer is launched in the VPC and an API Gateway VPC link is configured for the VPC and Network Load Balancer.

   When creating an application in an environment without a network bridge, you need to configure [VPC to VPC connectivity](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/amazon-vpc-to-amazon-vpc-connectivity-options.html) between your service VPCs and the Refactor Spaces application proxy VPC.

1. Under **Proxy endpoint type** select **Regional** or **Private**.

   The proxy’s endpoint can be either Regional or private. Regional API Gateway endpoints are accessible through the public internet, and private API Gateway endpoints are only accessible through VPCs.

1. Choose **Next** to move to the **Share environment** page.

# Step 3: Share your environment


This step describes how to share an environment as part of the Refactor Spaces **Getting started** wizard. You can also share an environment by choosing **Share environment** under **Quick actions** in the Refactor Spaces navigation pane.

Environments are shared with other AWS accounts using AWS Resource Access Manager (AWS RAM). An environment share must be accepted by the invited account within twelve hours. Otherwise, the environment must be shared again. If you’re in an AWS organization, then you can enable auto-accepting of shares. AWS RAM supports sharing environments with other AWS accounts, organizational units (OUs) in AWS Organizations, or an entire AWS organization.

Because environments are containers of applications, services, routes, and orchestrated AWS resources, sharing the environment provides some access to these resources from the invited accounts. After sharing with other accounts, users in those accounts can create applications, services, and routes within the environment, unless you use AWS Identity and Access Management (IAM) to restrict access.

When sharing an environment with another AWS account, Refactor Spaces also shares the environment’s transit gateway with the other account by orchestrating AWS RAM. 



**To share an environment**

1. Select one of the following principal types to share your environment with:
   + AWS account
   + Organization - entire AWS organization
   + Organizational unit (OU)

   AWS RAM supports sharing environments with other AWS accounts, organizational units (OUs) in AWS Organizations, or an entire AWS organization.

1. Environments are shared with other AWS accounts using AWS Resource Access Manager (AWS RAM). AWS RAM supports sharing environments with other AWS accounts, organizational units (OUs) in AWS Organizations, or an entire AWS organization. If you want to share an environment with an entire AWS organization or OU, you must enable sharing with the organization in AWS RAM before trying to share in Refactor Spaces. 

1. Enter the AWS account of the principal, and then choose **Add**. 

1. Choose **Next** to move to the **Review** page.

1. Review the information you entered in the previous steps.

1. If everything looks correct, choose **Create environment**. If you want to change something, choose **Previous**.

# Step 4: Create a service


Services provide the application’s business capabilities. Your existing application is represented by one or more services. Each service has an endpoint (either an HTTP/HTTPS URL or an AWS Lambda function).

After your environment is created, you view information about the environment on the environment details page (the page with the environment's name as the heading). The environment details page shows a summary of your environment and lists the applications in your environment.

The following procedure describes how to create a service starting from the environment details page. You can also create a service by choosing **Create service** under **Quick actions** in the Refactor Spaces navigation pane.

**To create a service from the environment details page**

1. From the list of applications, choose the name of the application that you want to add the service to. 

1. On the application details page (the page with the application's name as the heading), under **Services**, choose **Create service**.

1. Enter the name for the new service.

1. (Optional) Enter a description for the service.

1. Select one of the service endpoint types, **VPC** or **Lambda**.
   + Select **VPC** if the service is a URL endpoint in a VPC. 

     1. Select a VPC to be added to the environment network bridge.

     1. Enter the service URL endpoint.

        If you are creating a service in an environment without a network bridge and the URL is private, you must configure [VPC to VPC connectivity](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/amazon-vpc-to-amazon-vpc-connectivity-options.html) between your service VPC and the Refactor Spaces application proxy VPC. 

        VPC endpoint URLs can contain publicly resolvable DNS names (http://www.example.com) or an IP address. Private DNS names are not supported in service URLs, but you can use private IP addresses that are in the service’s VPC.

     1. (Optional) Enter a health check endpoint URL.
   + Select **Lambda** if the service is a Lambda function.

     1. Choose a Lambda function from your account. 

     1. (Optional) You can choose a Lambda function alias for the selected Lambda function, if one is available.

1. (Optional) Under **Route traffic to this service**, if you want to set this service as the application's default route, select the corresponding check box. 

   When you create a service, you can optionally route application traffic to it at the same time. If the application the service is being created in does not have any routes, you can make the service the application’s default route so that all traffic is routed to the service. If the application has existing routes, then you can add a route with a path to point to the service.

# Step 5: Create a route


This section describes how to create a route.

An application is used to incrementally re-route traffic away from an existing application to new services. You can also use it to launch new features without touching the existing application.

If the selected application does not have any routes, the new route becomes the application’s default route and all traffic is routed to the selected service. If the application has existing routes, then the route is scoped to a path and verb combination.

When created, the default route defaults to an active state. In this case, state is not a required input for default route at creation. However, like all other state values the state of the default route can be updated after creation to an inactive state, but only when all other routes are also inactive. Conversely, no route can be active without the default route also being active.

## Routes in environments without a network bridge


When you create a route to a service with a private URL endpoint in an environment without a network bridge, route creation fails if you don't configure [VPC to VPC connectivity](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/amazon-vpc-to-amazon-vpc-connectivity-options.html) between the service VPC and the application proxy VPC.

## Routes with path parameters


Refactor Spaces supports creating routes with path parameters. To include a path parameter in a route, add the variable in curly braces. For example: `/users/{id}`, where `{id}` represents the parameter that is forwarded to the service. For URL endpoints you must parse the path parameters. 

When using path parameters with Lambda services, the path parameters are parsed by API Gateway and are added to the Lambda [event object](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format). Also, path parameters simplify creating service routes to a higher level of granularity. For example:

```
/users => lambda1
/users/{userId} => lambda2
/users/{userId}/projects => lambda3
/users/{userId}/projects/{projectId} => lambda4
```

When using path parameters in Refactor Spaces avoid the following scenarios:
+ Duplicate path parameters in a route. For example: /users/\$1id\$1/version/\$1id\$1. Route creation fails due to duplicate ‘\$1id\$1’ parameter value.
+ Multiple parameters in same route level. For example: /users/\$1id\$1, /users/\$1name\$1 causes path parameters to collide. Route creation fails because paths can only have 1 path parameter at the same route level.
+ Parent-level paths with **Include child paths** selected. A route with path parameters will fail if the path parameter is at the same route level as another route with the same parent path. For example, creating a parent route of `/users/` with **Include child paths** selected, will collide if the desired nested route `/users/{id}` is at the same level as the parent route. A route at a different level than the parent route will not collide.

## Creating a route in Refactor Spaces


1. On the application details page (the page with the application's name as the heading), under **Routes**, choose **Create route**.

1. Choose a service for the route.

1. Choose **Create route**.