Getting Started

This section describes how to set up AWS Transform custom and run your first transformation.

Prerequisites

Before installing AWS Transform custom, ensure you have the following:

Supported Platforms

AWS Transform custom supports the following operating systems:

Required Software

Network Requirements

An internet connection with access to the following endpoints is required:

If you are working in an internet-restricted environment, update firewall rules to allowlist these URLs.

Installing the AWS Transform CLI

The recommended installation method is using the installation script.

To install the AWS Transform CLI

Configuring Authentication

AWS Transform custom requires AWS credentials to authenticate with the service. Configure authentication using one of the following methods.

Environment Variables

Set the following environment variables:

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token

You can also specify a profile using the AWS_PROFILE environment variable:

export AWS_PROFILE=your_profile_name

AWS Credentials File

Configure credentials in ~/.aws/credentials:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

IAM Permissions

Your AWS credentials must have permissions to call the AWS Transform service. At minimum, you need transform-custom:* permissions.

The following IAM policy provides full access to AWS Transform custom:

{
  "Version": "2012-10-17"		 	 	 ,
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "transform-custom:*"
      ],
      "Resource": "*"
    }
  ]
}

For more granular control, you can assign specific permissions:

Running Your First Transformation

The fastest way to get started is to use an AWS-managed transformation. AWS-managed transformations are pre-built, AWS-vetted transformations that are ready to use without any setup.

To run an AWS-managed transformation interactively:

atx

Then ask the agent to execute a transformation:

Execute the AWS/java-version-upgrade transformation on the codebase at ./my-java-project

To run a transformation non-interactively:

atx custom def exec -n AWS/java-version-upgrade -p ./my-java-project -c "mvn clean install" -x -t

For detailed information about execution modes, configuration options, and command flags, see Command Reference.

Understanding Transformation Results

When a transformation completes, AWS Transform custom provides a report describing the results. If the transformation was not validated (e.g. successful build for a Java applications), the report provides recommendations for further actions.

Most transformations are performed in multiple steps, using Git to commit intermediate ones. You can review the changes made by the transformation using standard Git commands:

git status
git diff

Creating a Custom Transformation

When AWS-managed transformations don't meet your needs, you can create custom transformations tailored to your specific requirements.

To create a custom transformation

For detailed instructions on creating custom transformations, see Workflows.

AWS Transform Web Application (Optional)

The AWS Transform web application is an optional interface for monitoring large-scale transformation campaigns across multiple repositories. Before using AWS Transform web application, you need to have a user identity enabled to access AWS Transform in your organization. For information about enabling AWS Transform, see Setting up AWS Transform.

To use the AWS Transform web application:

The web application is designed for enterprise-scale operations where you need centralized monitoring of transformations across multiple codebases.