Using upgrade debug mode to upgrade Amazon CLI version 1 to Amazon CLI version 2
We recommend that users of Amazon CLI version 1 upgrade to Amazon CLI version 2 to access new features and enhanced performance. There are changes in behavior between Amazon CLI version 1 and Amazon CLI version 2 that might require you to update your scripts or commands to get the same behavior. The upgrade debug mode in Amazon CLI version 1 outputs warnings when you use features that have different behavior in Amazon CLI version 2. This feature improves the upgrade experience by automatically detecting which of your Amazon CLI version 1 commands need to be modified before upgrading to Amazon CLI version 2 to prevent unexpected issues.
For more details, see Breaking changes between Amazon CLI version 1 and Amazon CLI version 2.
When you upgrade from Amazon CLI version 1 to version 2, you might encounter Breaking changes between Amazon CLI version 1 and Amazon CLI version 2 that affect your existing scripts and workflows. The upgrade debug mode helps you identify these issues before you complete the migration.
Upgrade debug mode detects when you use features that have breaking changes in Amazon CLI version 2. When you run a command that will break after upgrading, the mode displays a warning with specific steps to fix the issue. This saves you time by automatically finding potential problems instead of manually searching through your code.
How it works
When you enable upgrade debug mode, it monitors your Amazon CLI commands for features that will break in version 2. The mode checks your command syntax, arguments, environment variables, configuration settings, and in some cases, your Amazon account state.
If you run a command that will have breaking changes in version 2, you see a warning message. The warning explains what will break and provides specific steps to fix the issue. After you make the recommended changes, run the command again to verify the warning disappears.
The following example shows what a warning looks like:
$ aws s3 ls Amazon CLI v2 MIGRATION WARNING: The Amazon CLI v2 does not support calling earlier versions of Amazon service APIs via the api_versions configuration file setting. To migrate to v2 behavior and resolve this warning, remove the api_versions setting in the configuration file. See https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-api-versions.
Resolving detections
The following table shows all breaking changes that upgrade debug mode can detect. For each breaking change, you can choose to either update your version 1 commands to work like version 2, or configure version 2 to work like version 1. The recommended actions are shown in bold.
| Breaking change | On v1, migrate to v2 behavior | On v2, retain v1 behavior |
|---|---|---|
| Environment variable added to set text file encoding | Unset the PYTHONUTF8 and
PYTHONIOENCODING environment variables. |
Set the AWS_CLI_FILE_ENCODING environment
variable to the encoding specified in v1. |
| Binary parameters are passed as base64-encoded strings by default | Encode the value of the parameter with base64. If the parameter is being loaded from a file, encode the file contents with base64. | Set the cli_binary_format setting to raw-in-base64-out. |
| Improved Amazon S3 handling of file properties and tags for multipart copies | N/A. Cannot migrate to version 2 behavior in version 1. | Use the --copy-props none parameter. |
| No automatic retrieval of http:// or https:// URLs for parameters | Use curl (or alternative tools) to download the contents of the URLs to a local file.
Then, load the file contents to the parameter with file://cli_follow_urlparam to false to specify the raw URL as the paramater value. |
N/A. Impossible to retain version 1 behavior in version 2. |
| Pager used for all output by default | N/A. Cannot migrate to version 2 behavior in version 1. | Set the cli_pager setting or AWS_PAGER variable to an empty string. |
| Timestamp output values are standardized to ISO 8601 format | Set the cli_timestamp_format setting to iso8601. |
Set the cli_timestamp_format setting to wire. |
| Improved handling of CloudFormation deployments that result in no changes | Use the --no-fail-on-empty-changeset parameter. |
Use the --fail-on-empty-changeset parameter. |
| Changed default behavior for Regional Amazon S3 endpoint for us-east-1 Region | Set the AWS_ENDPOINT_URL_S3 environment variable or the --endpoint-url command line option to the us-east-1
regional URL |
Use the --region aws-global command line option. |
| ecr get-login removed and replaced with ecr get-login-password | (1.17.10 or later) Use ecr get-login removed and replaced with ecr get-login-password and pipe the output into a docker command. | N/A. Impossible to retain version 1 behavior in version 2. |
| Amazon CLI version 2 support for plugins is changing | N/A. Cannot migrate to version 2 behavior in version 1. | Configure the cli_legacy_plugin_path[plugins] section of the configuration file. Test plugins in version 2, lock your version 2 version, and test your plugins each time you upgrade. |
| Hidden alias support removed | Switch from using the obsolete hidden alias to Hidden alias support removed that works in all versions. | N/A. Impossible to retain version 1 behavior in version 2. |
| The api_versions configuration file setting is not supported | Migrate and test your usage of older API versions to the latest API version,
and remove api_versions |
N/A. Impossible to retain version 1 behavior in version 2. |
| Amazon CLI version 2 uses only Signature v4 to authenticate Amazon S3 requests | Specify the Signature Version to version 4 (see Specifying the Signature Version
in request authentication) |
N/A. Impossible to retain version 1 behavior in version 2. |
| Amazon CLI version 2 is more consistent with paging parameters | Move the pagination parameters in the input JSON parameter to the command itself. | Remove the pagination parameters from the input JSON parameter. |
| Amazon CLI version 2 provides more consistent return codes across all commands | N/A. Cannot migrate to version 2 behavior in version 1. | N/A. Impossible to retain version 1 behavior in version 2. |
Limitations
We strongly recommend customers review our Breaking changes between Amazon CLI version 1 and Amazon CLI version 2.
Unsupported Breaking Change Detection
The upgrade debug mode feature supports every breaking change except that Amazon CLI version 2 provides more consistent return codes across all commands. This mode cannot account for how you use the error codes returned by the Amazon CLI downstream.
Conditional Breaking Change Detection
Detection of Timestamp output values are standardized to ISO 8601 format is the only case where detection depends on the state of the Amazon account, and may be subject to breaking changes if the account resources are updated later. If no timestamps are included in the API response from the service, no detections will be made for this breaking change.
If you rely on the timestamp format returned by Amazon CLI commands and have not already configured the Amazon CLI to use ISO 8601, take extra precaution to ensure your processing of the timestamp will not break after upgrading to version 2.
Unresolvable Breaking Change Detection
Some warnings output by upgrade debug mode cannot be resolved by modifying the command or environment. The following cases are cases where warnings would always be output by upgrade debug mode as long as you use the corresponding feature:
-
Amazon CLI version 2 support for plugins is changing - if you rely on plugins in your configuration file
, the upgrade debug mode will always output a warning that cannot be resolved. This mode cannot guarantee whether any of your plugins will work in Amazon CLI version 2. -
Improved Amazon S3 handling of file properties and tags for multipart copies - if
aws s3is used to perform a bucket-to-bucket Amazon Amazon S3 copy, the upgrade debug mode will always output a warning that cannot be resolved.
False detections
Warnings output by the upgrade debug mode do not guarantee that breaking changes will be faced after upgrading to Amazon CLI v2. Below are cases where warnings would be output by upgrade debug mode, despite there being no breaking change introduced in Amazon CLI v2:
-
Environment variable added to set text file encoding - if the
PYTHONUTF8orPYTHONIOENCODINGenvironment variables are specified to set the text file encoding, and the specified encoding already matches the installed locale, the warning might be a false detection since debug mode does not check if the encoding matches the installed locale. -
Improved Amazon S3 handling of file properties and tags for multipart copies - if
aws s3is used to perform a bucket-to-bucket Amazon Amazon S3 copy, and the copy is not multipart due to the source object being under the multipart threshold size, a false detection will be output. -
Timestamp output values are standardized to ISO 8601 format - if the cli_timestamp_format configuration setting is set to wire (default), and a timestamp in ISO 8601 format is returned by the service.
-
Improved handling of CloudFormation deployments that result in no changes - if the
--fail-on-empty-changesetflag is used with theaws cloudformation deploycommand, and the resulting changeset is empty, a false detection will be output. Also, if the changeset is non-empty, and--no-fail-on-empty-changesetis not used, a false detection will be output. -
Changed default behavior for Regional Amazon S3 endpoint for us-east-1 Region - if
aws s3oraws s3apiis used to perform an Amazon Amazon S3 operation, and the region is configured tous-east-1, and thes3.us_east_1_regional_endpointconfiguration is not configured to regional, and the global Amazon S3 endpoint is used for the request due to the endpoint configuration settings, then the warning might be a false detection, since debug mode does not check configured endpoint settings.
Configure upgrade debug mode
You can enable or disable upgrade debug mode using the following methods, listed in order of precedence:
-
Command line options enable or disable upgrade debug mode for a single command. Use --v2-debug
to use upgrade debug mode. -
Environment variables use the AWS_CLI_UPGRADE_DEBUG_MODE
variable.