Prerequisites
The following are the prerequisites for using AWS Migration Hub Refactor Spaces.
• You must have one or more AWS accounts, and AWS Identity and Access Management (IAM) users set up for these accounts. For more information, see Setting up (p. 4).
• Designate one of the IAM user accounts as the Refactor Spaces environment owner account.
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 environment simplifies multi-account use cases to accelerate application refactoring. When you create an environment, we orchestrate AWS Transit Gateway, virtual private clouds (VPCs), and AWS Resource Access Manager in your account.
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 are able to create applications, services, and routes within the environment, unless you use IAM to restrict access.
To create an environment
1. Using the AWS account that you created in Setting up (p. 4), sign in to the AWS Management Console and open the Migration Hub console at https://console.aws.amazon.com/migrationhub/.
2. In the Migration Hub console navigation pane, choose Refactor Spaces.
3. Choose Getting started.
4. Select Create a refactor environment to start to incrementally modernize to microservices in multiple AWS accounts.
5. Choose Start.
6. Enter a name for the environment.
Step 2: Create an application
7. (Optional) Add a description for the environment.
8. 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 linked role, see Using service-linked roles for Refactor Spaces (p. 30).
9. 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 provide multi-account traffic routing for services in the application. For each application, we orchestrate a proxy using Amazon API Gateway VPC links, a Network Load Balancer, and resource policies. Applications are containers of services and routes.
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.
To create an application
1. On the Create application page, enter a name for your application.
2. 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.
3. 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.
4. 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 are able to create applications, services, and routes within the environment, unless you use 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.
Step 4: Create a service
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.
2. 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.
3. Enter the AWS account of the principal, and then choose Add.
4. Choose Next to move to the Review page.
5. Review the information you entered in the previous steps.
6. 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.
2. On the application details page (the page with the application's name as the heading), under Services, choose Create service.
3. Enter the name for the new service.
4. (Optional) Enter a description for the service.
5. Select one of the service endpoint types.
6. Select VPC if the service is a URL endpoint in a VPC.
a. Select a VPC to be added to the environment network bridge.
b. Enter the service URL endpoint.
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.
c. (Optional) Enter a health check endpoint URL.
7. a. Select Lambda if the service is a Lambda function.
Step 5: Create a route
b. Choose a Lambda function from your account.
8. (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.
NoteA route is live immediately after being created and traffic is redirected away from the default route or an existing parent route.
To create a route
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.
2. Choose Create route.
Data protection
Security in AWS Migration Hub Refactor Spaces
Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.
Security is a shared responsibility between AWS and you. The shared responsibility model describes this as security of the cloud and security in the cloud:
• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the AWS Compliance Programs.
To learn about the compliance programs that apply to Refactor Spaces, see AWS Services in Scope by Compliance Program.
• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations.
This documentation helps you understand how to apply the shared responsibility model when using AWS Migration Hub Refactor Spaces. It shows you how to configure Refactor Spaces to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your Refactor Spaces resources.
Contents
• Data protection in AWS Migration Hub Refactor Spaces (p. 10)
• Identity and Access Management for AWS Migration Hub Refactor Spaces (p. 11)
• Compliance validation for AWS Migration Hub Refactor Spaces (p. 36)
Data protection in AWS Migration Hub Refactor Spaces
The AWS shared responsibility model applies to data protection in AWS Migration Hub Refactor Spaces.
As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. This content includes the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the Data Privacy FAQ. For information about data protection in Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.
For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management (IAM). That way each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:
• Use multi-factor authentication (MFA) with each account.
• Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later.
• Set up API and user activity logging with AWS CloudTrail.
• Use AWS encryption solutions, along with all default security controls within AWS services.
Encryption at rest
• Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3.
• If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see Federal Information Processing Standard (FIPS) 140-2.
We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form fields such as a Name field. This includes when you work with Refactor Spaces or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form fields used for names may be used for billing or diagnostic logs.
If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.
Encryption at rest
Refactor Spaces encrypts all data at rest.
Encryption in transit
Refactor Spaces internetwork communications support TLS 1.2 encryption between all components and clients.
Identity and Access Management for AWS Migration Hub Refactor Spaces
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be authenticated (signed in) and authorized (have permissions) to use Refactor Spaces resources. IAM is an AWS service that you can use with no additional charge.
Topics
• Audience (p. 11)
• Authenticating with identities (p. 12)
• Managing access using policies (p. 14)
• How AWS Migration Hub Refactor Spaces works with IAM (p. 15)
• AWS managed policies for AWS Migration Hub Refactor Spaces (p. 20)
• Identity-based policy examples for AWS Migration Hub Refactor Spaces (p. 26)
• Troubleshooting AWS Migration Hub Refactor Spaces identity and access (p. 28)
• Using service-linked roles for Refactor Spaces (p. 30)
Audience
How you use AWS Identity and Access Management (IAM) differs, depending on the work that you do in Refactor Spaces.
Service user – If you use the Refactor Spaces service to do your job, then your administrator provides you with the credentials and permissions that you need. As you use more Refactor Spaces features to do
Authenticating with identities
your work, you might need additional permissions. Understanding how access is managed can help you request the right permissions from your administrator. If you cannot access a feature in Refactor Spaces, see Troubleshooting AWS Migration Hub Refactor Spaces identity and access (p. 28).
Service administrator – If you're in charge of Refactor Spaces resources at your company, you probably have full access to Refactor Spaces. It's your job to determine which Refactor Spaces features and resources your employees should access. You must then submit requests to your IAM administrator to change the permissions of your service users. Review the information on this page to understand the basic concepts of IAM. To learn more about how your company can use IAM with Refactor Spaces, see How AWS Migration Hub Refactor Spaces works with IAM (p. 15).
IAM administrator – If you're an IAM administrator, you might want to learn details about how you can write policies to manage access to Refactor Spaces. To view example Refactor Spaces identity-based policies that you can use in IAM, see Identity-based policy examples for AWS Migration Hub Refactor Spaces (p. 26).
Authenticating with identities
Authentication is how you sign in to AWS using your identity credentials. For more information about signing in using the AWS Management Console, see Signing in to the AWS Management Console as an IAM user or root user in the IAM User Guide.
You must be authenticated (signed in to AWS) as the AWS account root user, an IAM user, or by assuming an IAM role. You can also use your company's single sign-on authentication or even sign in using Google or Facebook. In these cases, your administrator previously set up identity federation using IAM roles.
When you access AWS using credentials from another company, you are assuming a role indirectly.
To sign in directly to the AWS Management Console, use your password with your root user email address or your IAM user name. You can access AWS programmatically using your root user or IAM users access keys. AWS provides SDK and command line tools to cryptographically sign your request using your credentials. If you don't use AWS tools, you must sign the request yourself. Do this using Signature Version 4, a protocol for authenticating inbound API requests. For more information about authenticating requests, see Signature Version 4 signing process in the AWS General Reference.
Regardless of the authentication method that you use, you might also be required to provide additional security information. For example, AWS recommends that you use multi-factor authentication (MFA) to increase the security of your account. To learn more, see Using multi-factor authentication (MFA) in AWS in the IAM User Guide.
AWS account root user
When you first create an AWS account, you begin with a single sign-in identity that has complete access to all AWS services and resources in the account. This identity is called the AWS account root user and is accessed by signing in with the email address and password that you used to create the account. We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the root user only to create your first IAM user. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks.
IAM users and groups
An IAM user is an identity within your AWS account that has specific permissions for a single person or application. An IAM user can have long-term credentials such as a user name and password or a set of access keys. To learn how to generate access keys, see Managing access keys for IAM users in the IAM User Guide. When you generate access keys for an IAM user, make sure you view and securely save the key pair. You cannot recover the secret access key in the future. Instead, you must generate a new access key pair.
Authenticating with identities
An IAM group is an identity that specifies a collection of IAM users. You can't sign in as a group. You can use groups to specify permissions for multiple users at a time. Groups make permissions easier to manage for large sets of users. For example, you could have a group named IAMAdmins and give that group permissions to administer IAM resources.
Users are different from roles. A user is uniquely associated with one person or application, but a role is intended to be assumable by anyone who needs it. Users have permanent long-term credentials, but roles provide temporary credentials. To learn more, see When to create an IAM user (instead of a role) in the IAM User Guide.
IAM roles
An IAM role is an identity within your AWS account that has specific permissions. It is similar to an IAM user, but is not associated with a specific person. You can temporarily assume an IAM role in the AWS Management Console by switching roles. You can assume a role by calling an AWS CLI or AWS API operation or by using a custom URL. For more information about methods for using roles, see Using IAM roles in the IAM User Guide.
IAM roles with temporary credentials are useful in the following situations:
• Temporary IAM user permissions – An IAM user can assume an IAM role to temporarily take on different permissions for a specific task.
• Federated user access – Instead of creating an IAM user, you can use existing identities from AWS Directory Service, your enterprise user directory, or a web identity provider. These are known as federated users. AWS assigns a role to a federated user when access is requested through an identity provider. For more information about federated users, see Federated users and roles in the IAM User Guide.
• Cross-account access – You can use an IAM role to allow someone (a trusted principal) in a different
• Cross-account access – You can use an IAM role to allow someone (a trusted principal) in a different