AWS Cloud Operations & Migrations Blog
Deep Dive on an AWS Migration Hub Refactor Spaces Environment
Refactor Spaces, an Amazon Web Services (AWS) Migration Hub feature, eliminates the undifferentiated work of building and operating AWS infrastructure for incremental application refactoring (typically to microservices using the strangler fig pattern). Building and operating this infrastructure also becomes more complex when making use of multiple AWS accounts (a best practice).
While Refactor Spaces saves you time by provisioning the AWS infrastructure needed for your refactor environment, troubleshooting this environment can become challenging without a solid understanding of the AWS resources that were created, why they were created, and how these resources connect and relate to one another.
In this post I will highlight and summarize many of the AWS resources that are provisioned during each phase of the creation of a complete Refactor Spaces environment. The goal is to give you a clear understanding of the resources that make up a Refactor Spaces environment so that you can manage your environment with confidence. With this understanding, you will also see how much time and effort can be saved by using Refactor Spaces for your next application refactoring project.
For reference as you read this post, below is an example of a multi-account Refactor Spaces environment:
A Refactor Spaces environment consisting of three AWS accounts.
Environment
The first step in using Refactor Spaces is to create an environment. A Refactor Spaces environment contains applications, services, and routes.
The makeup of a Refactor Spaces environment: applications, services, and routes spanning one or more AWS accounts.
A Refactor Spaces environment can be made up of a single AWS account or multiple AWS accounts. While you can use a single AWS account (ideally for testing only), once you are ready to start refactoring we recommend that you start with the following three AWS accounts:
-One account to act as the refactor environment owner, in which Refactor Spaces configures cross-account networking and routes traffic.
-One account for the existing application that you are refactoring.
-One account for the first new microservice.
Click here for a breakdown of some of the benefits of using multiple AWS accounts.
The recommended starting point for a new Refactor Spaces environment: one AWS account for your existing application, one AWS account for your first new microservice, and one AWS account for the environment owner.
The AWS account in which you create the Refactor Spaces environment is called the environment owner. The environment owner has cross-account visibility into applications, services, and routes created in the Refactor Spaces environment.
When you create an environment, the following AWS resources are provisioned:
Note: Refactor Spaces can be used through the AWS Management Console (within AWS Migration Hub), AWS CDK, SDK, CLI, or CloudFormation. All resources orchestrated by Refactor Spaces can be viewed in their appropriate AWS account(s), just as if you had created them manually.
Service-Linked Role
The first time you create a Refactor Spaces environment, a service-linked AWS Identity and Access Management (IAM) role is created in the environment owner AWS account with the all the permissions that Refactor Spaces requires. Refactor Spaces uses this service-linked role to connect to AWS services to orchestrate them on your behalf.
Role Name: AWSServiceRoleForMigrationHubRefactorSpaces
Click here for information on this service-linked role and the permissions attached to it.
Click here for information on how AWS Migration Hub Refactor Spaces works with IAM.
Transit Gateway
One AWS Transit Gateway is created in the environment owner AWS account for each Refactor Spaces environment that is created. The Transit Gateway is used to interconnect the Amazon Virtual Private Clouds (Amazon VPC) within your Refactor Spaces environment (same account or cross-account). If you’d like to peer this Transit Gateway with another Transit Gateway in your environment, take a look at this blog post for guidance.
Transit Gateway Name: refactor-spaces_tgw_env-ID
(ID is replaced with your Refactor Spaces environment ID)
The Transit Gateway provisioned by Refactor Spaces, shown in the AWS Management Console.
Resource Share in AWS Resource Access Manager (RAM)
A resource share is created in AWS Resource Access Manager in the environment owner AWS account. The Transit Gateway provisioned by Refactor Spaces is listed as a shared resource within this resource share. This is the first step in preparing the Transit Gateway to be shared with other AWS accounts in your Refactor Spaces environment (details on sharing an environment with other AWS accounts are below).
Resource Share Name: env-ID-resource-share
(ID is replaced with your Refactor Spaces environment ID)
Click here for more information on AWS Resource Access Manager (RAM).
Sharing a Refactor Spaces Environment
Application refactoring usually involves multiple teams and services. Providing each team or service with its own AWS account(s) helps ensure team and deployment independence.
When creating a Refactor Spaces environment using the AWS Management Console, you will be given the option to share the environment with other AWS accounts.
The sharing of an environment can be done during or after the creation of an environment. By sharing the environment with other AWS accounts, users in those accounts are able to create applications, services, and routes within the environment, unless you use IAM to restrict access.
The option to add AWS accounts to the Refactor Spaces environment, shown in the AWS Management Console.
Environments are shared with other AWS accounts using AWS Resource Access Manager. AWS Resource Access Manager supports sharing environments with other AWS accounts, organizational units in AWS Organizations, or an entire Organization. You will see these options when selecting a principal type.
Selecting a principal type for sharing a Refactor Spaces environment, shown in the AWS Management Console.
If you want to share an environment with an entire Organization or OU, you must enable sharing with the organization in Resource Access Manager before trying to share in Refactor Spaces.
After the environment is shared, the account you shared with can accept the share request in the Refactor Spaces console (in Notifications) or in the Resource Access Manager console (Resource Shares). There is a 12-hour time limit to accept before the request expires.
Once the share request has been accepted, the account you shared with can view the Refactor Spaces environment from its AWS Management Console and can add applications, services, and routes to the shared environment.
Once the environment is shared, a resource share is created in Resource Access Manager. The Refactor Spaces environment is listed as a shared resource within this resource share. The name of this resource share will be what you named your Refactor Spaces environment when you created it.
To view a walkthrough of creating a Refactor Spaces environment, click here.
Applications
After creating an environment (and optionally sharing the environment with other AWS accounts), you will create an application. An application can be created from any AWS account in the Refactor Spaces environment. You’ll be asked to select the environment in which you want the application to reside, to name the application, and to select a proxy VPC and proxy endpoint type.
Naming your application, selecting a proxy VPC, and selecting a proxy endpoint type.
When you create an application, the following AWS resources are provisioned:
API Gateway
One Amazon API Gateway (REST) API is created for each Refactor Spaces application that is created. It is created in the AWS account that created the application. This API Gateway API will serve as the proxy/front door for your application. The API name is the name of your Refactor Spaces application.
The API Gateway API provisioned by Refactor Spaces, shown in the AWS Management Console.
When creating the application, you must select the proxy endpoint type (regional or private). This is how you choose whether your API Gateway API should be accessible through the public internet or only through your VPC.
Regional: Can be accessed publicly. Take a look here if you’d like guidance on how to allow only specific IP addresses access to your API.
Private: Can only be accessed from your Amazon Virtual Private Cloud (VPC) using an interface VPC endpoint. For more information on creating a VPC endpoint for a private API, go here.
More information on API endpoint types can be found here.
Network Load Balancer
A Network Load Balancer is launched in the proxy VPC you selected when creating the application. This load balancer is used for the VPC link that will be leveraged if you need to route traffic to any private HTTP/HTTPS endpoints. Each application you create has its own load balancer. The load balancer is tagged with the application ID.
The Network Load Balancer provisioned by Refactor Spaces, shown in the AWS Management Console.
VPC link
A VPC link is created in the AWS account where the application was created. Each application you create has its own VPC link. This VPC link can be viewed in the API Gateway console in the AWS Management Console. As you can see, the VPC link is using our Network Load Balancer that was created when we created our application in Refactor Spaces (under Target NLB).
The VPC link provisioned by Refactor Spaces, shown in the AWS Management Console.
VPC links enable the API Gateway to forward traffic to private endpoints. For more information on VPC links, take a look at this blog post:
Security group
A security group is created in each AWS account in your Refactor Spaces environment. The inbound rules of this security group allow all IPv4 traffic from the VPC CIDR blocks being used in your Refactor Spaces environment across all the accounts in your environment. A simple way to view these VPC CIDR blocks is to go to Refactor Spaces console in the environment owner account and to select the Networking tab from the environment.
The Networking tab from the Refactor Spaces Environments page in the AWS Management Console. This shows us the VPCs that are part of the Refactor Spaces environment.
Below is a security group created by Refactor Spaces:
The security group, along with its inbound rules, provisioned by Refactor Space. Shown in the AWS Management Console.
This security group can be attached to resources to allow for communication between the services in your environment. Note that this security group can be modified if you would like it to be more restrictive. Additional inbound rules will be added to this security group as VPCs are added to your Refactor Spaces environment.
Security Group Name: RefactorSpacesSecurityGroup
Important: By default, this security group is not associated with any resources by Refactor Spaces. If you would like to use this security group, you will need to associate it with the appropriate resources.
Services
Now that you have created an environment and an application, it’s time to create your services. Services provide the application’s business capabilities. Your application is represented by one or more services (for example, one service for your monolith and one service for your first microservice). Each service has an endpoint – either an HTTP/HTTPS URL or an AWS Lambda function (aliases are supported). For HTTPS URLs, publicly-signed certificates are supported. Private Certificate Authorities (CAs) are permitted only if the CA’s domain is publicly resolvable.
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.
When creating a service, you’ll be asked to select the environment, application and service endpoint type.
Selecting a service endpoint type when creating a service.
If you are using a multi-AWS account Refactor Spaces environment, you will create your services from the AWS accounts in which your HTTP/HTTPS endpoints and Lambda functions reside. You cannot add services across AWS accounts (for example, you cannot add a service from an environment owner AWS account which does not own the service). As you can see below, when you select the VPC or Lambda function to create a service, you will notice that the VPC or Lambda function must reside in the current AWS account.
A reminder that the service must be added from the AWS account which hosts the Lambda function.
Here’s a summary of endpoint types and the type of integration that is used with API Gateway:
VPC URL Endpoint (Public) – If the service has a URL endpoint, and the endpoint resolves to a public IP address, Refactor Spaces routes traffic over the public internet. Traffic does not pass through the Transit Gateway or the load balancer.
VPC URL Endpoint (Private) – If the service has a URL endpoint, and the endpoint resolves to a private IP address, Refactor Spaces routes traffic using the API Gateway VPC link. Click here for more information on VPC link and API Gateway private integrations.
Lambda – If the service has a Lambda function endpoint, Refactor Spaces configures the Lambda function’s resource policy to allow the application’s API Gateway to invoke the function. Click here for more information.
When you create a service, the following AWS resources are provisioned:
Transit Gateway VPC Attachment
A Transit Gateway attachment (VPC) is associated with the Refactor Spaces environment’s Transit Gateway using the VPC you selected when creating the service endpoint. This will allow for connectivity between this service and the other resources in your Refactor Spaces environment.
This attachment is created in the AWS account in which you created the service. It can be viewed from both the account you created the service and in the environment owner account (as shared) in the VPC console in the AWS Management Console.
Route (Added to Route Tables)
After adding a VPC service endpoint, a new route containing the CIDR block of our new VPC endpoint is added to all the route tables associated with the VPCs in the Refactor Spaces environment. Since the Transit Gateway is the central hub of our Refactor Spaces environment, this route sets the Transit Gateway as the target for any traffic destined for the VPC CIDR block of our new service.
Routes
To complete our setup, we need to add routes to our services. You’ll select an environment, application, and service when creating a route.
Selecting an environment, application, and service when creating a new route.
Next, you’ll need to specify the source path and the verb (HTTP method).
Selecting a source path and whether you would like the route to be created in an active or inactive state.
We can create our route in an active state or an inactive state. This determines whether traffic will immediately be sent to this route upon creation.
Once this is complete, you’ll see that the appropriate configuration was made (including the creation of resources and methods) on your application’s API Gateway API in order to route your selected traffic to the appropriate service endpoint. As mentioned previously, Refactor Spaces handles all of the appropriate API integrations for you (VPC link, Lambda proxy integration, etc).
Viewing our API Gateway API from the AWS Management console, we can see the corresponding configurations were made on the API Gateway API.
Some important notes about routes:
-If an application does not have any routes, then the first route must be created as a default route (all traffic will be routed there).
-A one-time health check is performed on the service when the route is created. If the health check fails, the route transitions to a failed status, and no traffic is sent to the service.
-For a public URL health check, a connection is opened to the public endpoint. If the URL is not reachable, the health check fails.
-For a private URL health check, a target group is created and associated with the network load balancer that was provisioned when the application was created. A target group health check is then run.
-For a Lambda function health check, the Lambda function state is checked. If the function is not active, the function configuration is updated so that Lambda resources are provisioned. If the Lambda state is failed, then the route creation fails.
Deleting an Environment
If you would like to delete your Refactor Spaces environment, you will first need to delete the routes, services, and applications within the environment. Once the environment is deleted, the resources provisioned by Refactor Spaces (such as the Transit Gateway, Network Load Balancer, and API Gateway API) are also deleted.
Conclusion
In this blog post, I went into detail on many of the AWS resources that are provisioned and orchestrated by Refactor Spaces to set up a refactor environment for incremental application refactoring. These resources include Transit Gateway, Network Load Balancer, API Gateway API, security groups, and more. By using Refactor Spaces, all of this can be accomplished in minutes.
To view a walkthrough of creating a Refactor Spaces environment, click here.
Also, see below for a video breakdown of some of the provisioned resources referenced in this blog post:
About the author: