KickStart Migration

A serverless application built on AWS technologies to accelerate cloud migration planning and execution.

Overview

KickStart Migration is a serverless application built on AWS technologies, specifically tailored to assist migration planning teams in gathering crucial information about applications slated for cloud migration. By facilitating communication between application owners, technical stakeholders, and migration engineers, this tool paves the way for smoother, more efficient cloud transitions, in turn increasing migration velocity.

Key Features

• Centralized Migration Planning: Collect and organize application data in one place
• Stakeholder Collaboration: Connect application owners with migration engineers
• Customizable Question Bank: Tailor information gathering to your organization's needs
• Role-Based Access Control: Secure access management through AWS Cognito
• Serverless Architecture: Fully managed, scalable infrastructure

Architecture

The application is built using:

• Frontend: React.js web application
• Backend: AWS Lambda functions
• Authentication: AWS Cognito
• Storage: Amazon DynamoDB and S3
• API Layer: Amazon API Gateway
• Infrastructure as Code: AWS CDK (Python)

Prerequisites

• Node.js: v14.x or later (latest version recommended)
• Python: v3.11 or compatible version
• AWS CDK CLI: Installed and configured
• AWS CLI: Configured with appropriate credentials
• AWS Account: With permissions to deploy resources
• CDK Bootstrap: AWS account/region bootstrapped for CDK deployment

This serverless tool is built on AWS Cloud Development Kit (CDK) Python (version 3.11). To deploy the tool you should have:

1. Programmatic access to the AWS account where you are planning to deploy the tool. To learn about programmatic access visit https://docs.aws.amazon.com/workspaces-web/latest/adminguide/getting-started-iam-user-access-keys.html
2. Permission to deploy the CDK stack. To learn more, visit https://docs.aws.amazon.com/cdk/v2/guide/permissions.html

Deployment Guide

Step 1: Prepare Your Environment

1. Clone the repository

   git clone https://github.com/aws-samples/sample-kickstart-migration.git
   cd sample-kickstart-migration

2. Create and activate a Python virtual environment

   python3 -m venv .venv
   source .venv/bin/activate

3. Update AWS account ID and region in cdk.json (line 65)

   "dev": {
     "account": "YOUR_ACCOUNT_ID",
     "region": "us-east-1"
   }

   Important: This tool currently supports deployment only in the us-east-1 region due to AWS SDK Pandas layer availability limitations.

Step 2: Deploy Backend Infrastructure

Note: If you're using a specific AWS profile (not the default), add --profile YOUR_PROFILE_NAME to all AWS CLI and CDK commands below.

1. Install Python dependencies (ensure virtual environment is activated)

   source .venv/bin/activate
   pip install -r requirements.txt

2. Synthesize CloudFormation template (ensure code synthesizes without error)

   source .venv/bin/activate
   cdk synth
   # Or with profile: cdk synth --profile YOUR_PROFILE_NAME

3. Bootstrap your AWS environment (if not already done)

   source .venv/bin/activate
   cdk bootstrap
   # Or with profile: cdk bootstrap --profile YOUR_PROFILE_NAME

4. Deploy the CDK stacks (this will deploy two CloudFormation stacks: one for the application and another for AWS Cognito)

   source .venv/bin/activate
   cdk deploy --all --method=direct --require-approval never
   # Or with profile: cdk deploy --all --profile YOUR_PROFILE_NAME --method=direct --require-approval never

   Important: The --method=direct flag is required because the CloudFormation template exceeds the standard size limit. The --require-approval never flag prevents interactive prompts during deployment.

Step 3: Configure and Deploy Frontend

Note: These deployment steps are for development environment.

1. Note the CloudFormation outputs from the AWS Console:

   • UserPoolClientId
   • UserPoolId
   • ApiHostUrl
   • CloudFrontDistributionId
   • KickStartWebsiteBucketName

2. Navigate to the frontend directory:

   cd kickstart-web-app

3. Install frontend dependencies:

   npm install

4. Edit .env-cmdrc with the values from CloudFormation outputs (replace only the URL, do not replace "/dev"):

   {
     "dev": {
       "API_GW_BASE_URL": "YOUR_API_GATEWAY_URL",
       "COGNITO_REDIRECT_URL": "YOUR_CLOUDFRONT_URL",
       "USER_POOL_ID": "YOUR_USER_POOL_ID",
       "USER_POOL_WEB_CLIENT_ID": "YOUR_CLIENT_ID",
       "REGION": "YOUR_REGION"
     }
   }

5. Update Cognito configuration in:

   • src/components/signin.tsx
   • src/store/authSlice.tsx

   Replace the userPoolId and userPoolClientId with the "User pool ID" and "Client ID" from Cognito (available in CloudFormation outputs).

6. Build and deploy the frontend:

   npm run build:dev
   cd dist
   aws s3 cp . s3://YOUR_WEBSITE_BUCKET_NAME --recursive
   # Or with profile: aws s3 cp . s3://YOUR_WEBSITE_BUCKET_NAME --recursive --profile YOUR_PROFILE_NAME

   Note: Use the S3 bucket name containing "website" from the CloudFormation outputs.

7. Configure CloudFront Origin Access Control (if needed):

   • Go to CloudFront Console → Security → Origin Access Control
   • Create Control Setting with name, select "Sign requests" and "S3"
   • Go to Origins, select origin and click Edit
   • Change Origin access to "Origin access control settings (recommended)"
   • Select the newly created Origin access control

8. Create CloudFront Invalidation:

   Option A - AWS CLI (Recommended):

   aws cloudfront create-invalidation \
     --distribution-id <CloudFrontDistributionId> \
     --paths "/*"
   # Or with profile: aws cloudfront create-invalidation --distribution-id <CloudFrontDistributionId> --paths "/*" --profile YOUR_PROFILE_NAME

   Option B - AWS Console:

   • Navigate to CloudFront in the AWS Console
   • Click on the KickStart distribution
   • Click on the "Invalidations" tab
   • Create a new invalidation with path /* to refresh the distribution cache

Step 4: Configure Email Settings

Important: The application sends email notifications for migration acceptance and reminders. You need to configure Amazon SES for email functionality to work.

1. Update Sender Email Address:

   Edit the SENDER_EMAIL environment variable in kickstart/kickstart_stack.py:

   "SENDER_EMAIL": "your-organization-email@company.com"  # Replace with your email

2. Verify Email Address in Amazon SES:

   Option A - AWS CLI:

   aws ses verify-email-identity --email-address your-organization-email@company.com
   # Or with profile: aws ses verify-email-identity --email-address your-organization-email@company.com --profile YOUR_PROFILE_NAME

   Option B - AWS Console:

   • Navigate to Amazon SES in the AWS Console
   • Click "Verified identities" → "Create identity"
   • Select "Email address" and enter your organization email
   • Check your email and click the verification link

3. Redeploy the Application:

   source .venv/bin/activate
   cdk deploy MIGRATION-KICKSTART-APP-dev --require-approval never
   # Or with profile: cdk deploy MIGRATION-KICKSTART-APP-dev --profile YOUR_PROFILE_NAME --require-approval never

Note: By default, Amazon SES operates in sandbox mode where you can only send emails to verified addresses. For production use, you may need to request production access through AWS Support.

Step 5: User Setup

1. Access the application at your CloudFront URL: https://YOUR_CLOUDFRONT_URL/index.html

2. Create users (Admin only):

   Option A - AWS Console (Recommended):

   • Navigate to AWS Cognito in the AWS Console
   • Click on the KickStart user pool
   • Click "Users" tab, then "Create user"
   • Enter user details (email, temporary password)
   • User will receive an invitation email

   Option B - AWS CLI:

   aws cognito-idp admin-create-user \
     --user-pool-id <UserPoolId> \
     --username <email@example.com> \
     --user-attributes Name=email,Value=<email@example.com> Name=name,Value="<Full Name>" \
     --temporary-password "<TempPassword123!>" \
     --message-action SEND
   # Or with profile: add --profile YOUR_PROFILE_NAME

3. Assign users to groups:

   • In Cognito Console, click on the "Groups" tab
   • Add users to appropriate groups:
     • migration-planner: Upload app migration data and manage the process
     • migration-application-owner: View/edit assigned applications
     • migration-execution-engineer: View application forms and details

4. User first login:

   • Users access the CloudFront URL and sign in with their email and temporary password
   • They will be prompted to set a permanent password
   • No sign-up option is available - users must be created by administrators

Note: You can find sample data to upload to KickStart Migration under sample-data/AppMigrationData_AWSKickStart.xlsx. Only users assigned to the migration-planner group can upload data files. If you upload this file, data should be visible in the DynamoDB table after one or two minutes of processing. If your email address is not in the sample data, you cannot see the sample applications. If upload does not work on the first time, please try to upload the file one more time.

Customizing the Question Bank

The KickStart Migration tool includes a customizable question bank for gathering migration-relevant information. These questions can be customized as per your organization's needs.

To modify the questions:

1. Edit kickstart-web-app/src/config/questions.json
2. Use the following template structure:

{
  "question_type": "text | select | selectWithFollowup | radio-group",
  "question_text": "Your question here",
  "placeholder_text": "Placeholder text for the UI component",
  "isRequired": true | false,
  "question_followUps": [
    {
      "question_type": "text | select",
      "question_text": "Follow-up question text",
      "question_options": ["Option 1", "Option 2", "..."]
    }
  ]
}

3. Rebuild and redeploy the frontend after making changes

Sample Data

Sample migration data is provided in sample-data/AppMigrationData_AWSKickStart.xlsx to help you get started with the KickStart Migration tool.

Testing

The application includes unit tests with 100% code coverage for the infrastructure components:

# Install test dependencies
pip install pytest pytest-cov

# Run tests with coverage report
python -m pytest --cov=kickstart tests/unit/

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Security

See CODE_OF_CONDUCT.md for our code of conduct and security policies.

License

This project is licensed under the MIT License - see the LICENSE file for details.