Upgrade AWS CLI from v1 to v2 using upgrade debug mode

Upgrading from AWS Command Line Interface (AWS CLI) v1 to AWS CLI v2 can be challenging and time-consuming due to changes introduced in AWS CLI v2 that can potentially break your existing workflows. If you don’t properly address breaking changes in your scripts or workflows, then executing these workflows after upgrading to AWS CLI v2 may result in unintended consequences, such as failing commands or misconfiguring resources in your AWS account.

AWS CLI v1’s upgrade debug mode helps you identify and resolve these issues before upgrading, for a safer and seamless transition. This mode detects usage of features in AWS CLI v1 that have been updated with breaking changes in AWS CLI v2, and outputs a warning for each detection.

In this post, we’ll walk you through using AWS CLI v1’s upgrade debug mode to identify potential breaking changes, resolve compatibility issues, and safely transition your workflows to v2.

Getting Started

You’ll start by verifying you have the correct version of AWS CLI v1 to use upgrade debug mode, then you’ll use this mode to test commands in AWS CLI v1 for usage of features that were updated with breaking changes in 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. Finally, you’ll follow guidance to mitigate breaking your workflows and safely upgrade to AWS CLI v2.

AWS CLI v1

The following steps walk you through using upgrade debug mode to identify potential breaking changes in your existing AWS CLI v1 usage, resolve compatibility issues, and safely transition to AWS CLI v2.

Step 1: Verify you are using AWS CLI v1 version 1.44.0 or higher.

We released the upgrade debug mode feature to the AWS CLI in version 1.44.0.

Using AWS CLI v1, run aws --version, and verify that the AWS CLI version is 1.44.0 or higher.

If the version is older than 1.44.0, see our Developer Guide for instructions to update to a later version.

Step 2: Test your AWS CLI v1 usage with AWS CLI upgrade debug mode

Set the AWS_CLI_UPGRADE_DEBUG_MODE environment variable to true to detect usage of features broken in AWS CLI v2. Alternatively, you can enable this functionality at the command-level using the --v2-debug command line option. If you are upgrading the AWS CLI in existing scripts or workflows to use v2, we recommend testing each AWS CLI command used with this functionality enabled before upgrading them to use AWS CLI v2.

We recommend performing this step in the same environment that you will upgrade to use AWS CLI v2, since the execution environment determines whether commands will experience breaking changes.

For example, suppose you have a script that executes the AWS CLI command below:

aws secretsmanager update-secret --secret-id SECRET-NAME \
  --secret-binary file://BINARY-SECRET.json

Execute the command with the AWS_CLI_UPGRADE_DEBUG_MODE set to true—or with the --v2-debug flag—and check the output for the text “AWS CLI v2 UPGRADE WARNING”. Example output with the environment variable configured is shown below:

$ aws secretsmanager update-secret --secret-id SECRET-NAME \
  --secret-binary file://BINARY-SECRET.json

AWS CLI v2 UPGRADE WARNING: When specifying a blob-type parameter, AWS CLI v2 will 
assume the parameter value is base64-encoded. This is different from v1 behavior, 
where the AWS CLI will automatically encode the value to base64. To retain v1 
behavior in AWS CLI v2, set the `cli_binary_format` configuration variable to 
`raw-in-base64-out`. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-binaryparam.

{
    "ARN": "ARN",
    "Name": "SECRET-NAME",
    "VersionId": "VERSION-ID"
}

Step 3: Use the warnings to prepare for AWS CLI v2

If breaking changes were detected in step 2, the warnings provide guidance for preparing for the AWS CLI v2 upgrade. Some breaking changes can be mitigated prior to upgrading to AWS CLI v2 by modifying the command or execution environment; the warnings identified in step 2 include links to our AWS CLI v2 breaking changes list that details options to mitigate the breakage.

In the previous example, the warning explains that AWS CLI v2 will assume that the contents of BINARY-SECRET.json will be encoded in base64.

Following the instructions in the warning, you’ll configure the cli_binary_format variable to raw-in-base64-out in the configuration file. Even though cli_binary_format is not a valid configuration setting in AWS CLI v1, it prepares your environment for AWS CLI v2 by configuring AWS CLI v2 to retain the same behavior as AWS CLI v1.

You’ll configure cli_binary_format according to the instructions using the following command:

aws configure set cli_binary_format raw-in-base64-out

Step 4: Verify resolution of warnings

For breaking changes mitigated in step 3, you’ll re-run the command to verify the warning is no longer printed.

Proceeding with the example, you configured the cli_binary_format variable to raw-in-base64-out in step 3. You’ll now re-run the command to verify the mitigation warning is resolved:

aws secretsmanager update-secret --secret-id SECRET-NAME \
    --secret-binary file://BINARY-SECRET.json 
{
    "ARN": "ARN",
    "Name": "SECRET-NAME",
    "VersionId": "VERSION-ID"
}

The warning is no longer printed, signaling that this command is now compatible with AWS CLI v2.

If you used the --v2-debug argument instead of the AWS_CLI_UPGRADE_DEBUG_MODE environment variable in step 2, remember to remove the flag from the command before upgrading to version 2.

Step 5: Manually review for breaking changes

After using upgrade debug mode to automatically detect usage of features that were updated with breaking changes, you will now manually review your AWS CLI usage by reviewing our breaking changes list and AWS CLI v2 Migration Guide.

Step 6: Upgrade to AWS CLI v2

After preparing for the breaking changes identified in the previous steps, you will now upgrade to AWS CLI v2 following the installation guide.

Limitations

The upgrade debug mode feature does not currently support every breaking change introduced with AWS CLI v2, and has false positive cases where it issues a warning even if no breaking changes are actually present.

Additionally, some of the detection depends on API responses, as well as the execution environment running the AWS CLI. For this reason, we recommend running this feature against an AWS account and execution environment that reflect your production workflows as close as possible.

For more details on the limitations of upgrade debug mode, see Using upgrade debug mode to upgrade AWS CLI version 1 to AWS CLI version 2 in Migration guide for the AWS CLI version 2.

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

The only breaking change not supported by the upgrade debug mode is that AWS CLI version 2 provides more consistent return codes across commands.

Conclusion

In this blog post, we showed you how to get started with the new upgrade debug mode. If you’re interested in using this feature to assist your upgrade from AWS CLI v1 to AWS CLI v2, try out upgrade debug mode. To learn more, visit Using upgrade debug mode to upgrade AWS CLI version 1 to AWS CLI version 2 in our AWS CLI v2 Migration Guide. We would love your feedback! You can reach out to us by creating a GitHub Issue.

AWS Developer Tools Blog