Upgrading AWS CLI From v1 to v2 Using the Migration Tool

Upgrading from AWS Command Line Interface (AWS CLI) v1 to AWS CLI v2 brings valuable improvements, but requires attention to several changes that may affect your existing workflows, such as failing commands, or misconfiguration.

The AWS CLI v1-to-v2 Migration Tool helps you identify and resolve issues before upgrading, making transition easier. It analyzes bash scripts containing AWS CLI v1 commands where behavior differs in AWS CLI v2. The tool will either suggest a change to a command or guide you to resolve a potential risk. It can also automatically create an updated version of the script with implemented changes. Where applicable, the migration tool will change the commands in a way that preserves AWS CLI version 1 behavior.

The AWS CLI v1-to-v2 Migration Tool is a standalone tool compatible with any version of AWS CLI v1, and does not require executing AWS CLI commands. Compared to Upgrade Debug Mode, an alternative solution built into AWS CLI version 1.44.0 or later, the Migration Tool offers broader compatibility and works independently of your CLI installation. For a thorough comparison between the Upgrade Debug Mode and the AWS CLI v1-to-v2 Migration Tool see Choosing Between Upgrade Debug Mode and AWS CLI v1-to-v2 Migration Tool in our Migration guide for the AWS CLI version 2.

In this post, we’ll walk you through using AWS CLI v1-to-v2 Migration Tool to identify potential breaking changes, resolve compatibility issues, and safely transition your scripts to v2.

Prerequisites

Before you begin, you’ll need Python version 3.9 or later, and pip installed on your machine. See the Prerequisites in Using AWS CLI v1-to-v2 Migration Tool to upgrade AWS CLI version 1 to AWS CLI version 2 for instructions to install these prerequisites.

Getting Started

You’ll start by installing the AWS CLI v1-to-v2 Migration Tool. Then, you’ll use this tool to analyze bash scripts for AWS CLI v1 commands that may need to be updated before upgrading to AWS CLI v2. Then, you’ll review the AWS CLI v2 breaking changes list in the Migration guide for the AWS CLI version 2 to manually verify whether your workflows may be broken by upgrading, and safely upgrade to AWS CLI v2.

Step 1: Install the AWS CLI v1-to-v2 Migration Tool

See Installation in Using AWS CLI v1-to-v2 Migration Tool to upgrade AWS CLI version 1 to AWS CLI version 2 for instructions to install the AWS CLI v1-to-v2 Migration Tool.

Step 2: Lint a bash script using interactive mode

Next, you’ll run the migration tool in interactive mode. Interactive mode walks you through each flagged command one at a time. For each detection, it will suggest a change to make the command have the same behavior in AWS CLI v2.

For this blog post, we’ll use the following example bash script, which uses AWS CLI v1 to upload an AWS CloudFormation template to Amazon Simple Storage Service (Amazon S3), copy the template to a backup Amazon S3 bucket, and create a CloudFormation stack from the template.

#!/bin/bash
set -e

TEMPLATE="$1"
BUCKET="$2"
BACKUP="$3"
STACK_NAME="$4"

if [ -z "$TEMPLATE" ] || [ -z "$BUCKET" ] || [ -z "$BACKUP" ] || [ -z "$STACK_NAME" ]; then
    echo "Usage: $0 <template-file> <bucket> <backup-bucket> <stack-name>"
    exit 1
fi

TMPKEY="cloudformation/$(basename "$TEMPLATE")"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BACKUP_KEY="cloudformation/$TIMESTAMP-$(basename "$TEMPLATE")"

# Upload template
aws s3 cp $TEMPLATE s3://$BUCKET/$TMPKEY

# Copy template to backup bucket
aws s3 cp s3://$BUCKET/$TMPKEY s3://$BACKUP/$BACKUP_KEY

# Create a stack from the template
aws cloudformation create-stack \
  --stack-name "$STACK_NAME" \
  --template-body "https://s3.amazonaws.com/$BUCKET/$TMPKEY"

echo "Stack creation initiated. Stack ID: $(
  aws cloudformation describe-stacks \
    --stack-name "$STACK_NAME" \
    --query 'Stacks[0].StackId' \
    --output text \
    --cli-input-json file://describe_stacks_input.json
)"

You will use the command below to use the migration tool to analyze the bash script upload_s3_files.sh, suggest fixes, and write the modified script to the path upload_s3_files_v2.sh in interactive mode. For the sake of demonstration, this blog post does not include every finding that gets detected in the example script:

$ migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh \
  --interactive
  
19 19│ aws s3 cp $TEMPLATE s3://$BUCKET/$TMPKEY
20 20│ 
21 21│ # Copy template to backup bucket
22   │-aws s3 cp s3://$BUCKET/$TMPKEY s3://$BACKUP/$BACKUP_KEY
   22│+aws s3 cp s3://$BUCKET/$TMPKEY s3://$BACKUP/$BACKUP_KEY --copy-props none
23 23│ 
24 24│ # Create a stack from the template
25 25│ aws cloudformation create-stack \

script.sh:22 [s3-copy] In AWS CLI v2, object properties will be copied from the 
source in multipart copies between S3 buckets. If a copy is or becomes multipart 
after upgrading to AWS CLI v2, extra API calls will be made. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-s3-copy-metadata.

Apply this fix? [y] yes, [n] no, [a] accept all of type, [r] reject all of type, 
[u] update all, [s] save and exit, [q] quit:

In the preceding finding, the associated breaking change is Improved Amazon S3 handling of file properties and tags for multipart copies. The suggested fix, given in a form similar to a Git diff, is to add the --copy-props none flag to the command. Adding the suggested flag will preserve AWS CLI v1 behavior in AWS CLI v2.

The following output snippet shows another finding:

16 16│ BACKUP_KEY="cloudformation/$TIMESTAMP-$(basename "$TEMPLATE")"
17 17│ 
18 18│ # Upload template
19   │-aws s3 cp $TEMPLATE s3://$BUCKET/$TMPKEY
   19│+aws s3 cp $TEMPLATE s3://$BUCKET/$TMPKEY --cli-binary-format raw-in-base64-out
20 20│ 
21 21│ # Copy template to backup bucket
22 22│ aws s3 cp "s3://$BUCKET/$TMPKEY" "s3://$BACKUP/$BACKUP_KEY"

examples/upload_s3_files.sh:19 [binary-params-base64] In AWS CLI v2, an input 
parameter typed as binary large object (BLOB) expects the input to be base64-encoded. 
If using a BLOB-type input parameter, retain v1 behavior after upgrading to AWS CLI 
v2 by adding `--cli-binary-format raw-in-base64-out`. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-binaryparam.

Apply this fix? [y] yes, [n] no, [a] accept all of type, [r] reject all of type, 
[u] update all, [s] save and exit, [q] quit:

In the preceding detection, the associated breaking change is that Binary parameters are passed as base64-encoded strings by default. The suggested fix, is to add the --cli-binary-format raw-in-base64-out flag to the command. Adding the suggested flag will preserve AWS CLI v1 behavior in AWS CLI v2.

Note that in this particular case, we are not using a binary-type parameter in the aws s3 cp command. This highlights a core behavior of the migration tool: by design, it errs on the side of caution when detecting potential issues, flagging changes that might be breaking even when uncertain, provided the suggested fix won’t alter the code’s behavior.

The following output snippet shows another finding:

27 27│  --template-body "https://s3.amazonaws.com/$BUCKET/$TEMPLATE_KEY" --cli-binary-format raw-in-base64-out --no-cli-pager
28 28│
29 29│echo "Stack creation initiated. Stack ID: $(
30 30│  aws cloudformation describe-stacks \
31 31│    --stack-name "$STACK_NAME" \
32 32│    --query 'Stacks[0].StackId' \
33 33│    --output text \
34 34│    --cli-input-json file://describe_stacks_input.json --cli-binary-format raw-in-base64-out --no-cli-pager
35 35│)"

examples/upload_s3_files.sh:30 [MANUAL REVIEW REQUIRED] [cli-input-json] In AWS CLI 
v2, specifying pagination parameters via `--cli-input-json` turns off automatic 
pagination. If pagination-related parameters are present in the input JSON specified 
with `--cli-input-json`, remove the pagination parameters from the input JSON to 
retain v1 behavior. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-skeleton-paging.

[n] next, [s] save, [q] quit:

In the preceding detection, the detected breaking change is AWS CLI version 2 is more consistent with paging parameters. The migration tool cannot automatically modify the script in this case, so the detection is flagged with [MANUAL REVIEW REQUIRED].

For detections that require manual fixes, such as the example, you’ll enter n and manually address the finding after the migration tool finishes executing.

After all detections are displayed, a summary is printed, including the number of issues found and the path to the modified script:

Found 10 issue(s). 9 fixed. 1 require(s) manual review.
Changes written to: upload_s3_files_v2.sh

To resolve the detections that were flagged for manual review, follow the guidance in the suggested actions.

Step 3: Upgrade to AWS CLI v2

Customers are responsible for safely migrating their scripts; using the migration tool does not guarantee that all commands will have the same behavior in AWS CLI v2. To complete a manual review, reference the breaking changes list in the AWS CLI v2 Migration Guide.

After going through and applying any required changes identified in the previous steps, you are now ready to upgrade to AWS CLI v2 following the installation guide.

Step 4: Uninstall migration tool if no longer needed

After migration, you can uninstall the migration tool and remove original scripts if no longer needed.

Important Considerations

The AWS CLI v1-to-v2 Migration Tool uses static analysis to identify most compatibility considerations in your scripts. However, some scenarios—such as parameters stored in variables or determined at runtime—fall outside the tool’s detection scope and require manual review.

For more details on the limitations of the AWS CLI v1-to-v2 Migration Tool, see Limitations in Using AWS CLI v1-to-v2 Migration Tool to upgrade AWS CLI version 1 to AWS CLI version 2.

We strongly recommend customers understand our breaking changes list published in our AWS CLI v2 Migration Guide.

Conclusion

In this blog post, we showed you how to get started with the new AWS CLI v1-to-v2 Migration Tool to assist your upgrade from AWS CLI v1 to AWS CLI v2. To learn more, visit Using AWS CLI v1-to-v2 Migration Tool to upgrade AWS CLI version 1 to AWS CLI version 2. We would love your feedback! You can also open a discussion or issue on GitHub. Thank you for using the AWS CLI!

Have you encountered challenges migrating from AWS CLI v1 to AWS CLI v2? Share your experience in the comments below.