アップグレードデバッグモードを使用して AWS CLI バージョン 1 を AWS CLI バージョン 2 にアップグレードする - AWS Command Line Interface
仕組み制限アップグレードデバッグモードを設定する

アップグレードデバッグモードを使用して AWS CLI バージョン 1 を AWS CLI バージョン 2 にアップグレードする

AWS CLI バージョン 1 のユーザーは、AWS CLI バージョン 2 にアップグレードして、新機能と強化されたパフォーマンスを利用することをお勧めします。このトピックでは、AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の動作の変更について説明します。この変更では、同じ動作をするために、スクリプトまたはコマンドを更新する必要があるものについて述べます。AWS CLI バージョン 1 のアップグレードデバッグモードは、AWS CLI バージョン 2 で動作が異なる機能を使用する場合に警告を出力します。この機能は、予期しない問題を防ぐために AWS CLI バージョン 2 にアップグレードする前に変更する必要がある AWS CLI バージョン 1 コマンドを自動的に検出することで、アップグレードエクスペリエンスを向上させます。

詳細については、以下を参照してください。AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更

AWS CLI バージョン 1 からバージョン 2 にアップグレードすると、既存のスクリプトやワークフローに影響する AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更 が生じることがあります。アップグレードデバッグモードは、移行を完了する前にこれらの問題を特定するのに役立ちます。

アップグレードデバッグモードは、AWS CLI バージョン 2 で下位互換性のない変更がある機能を使用する場合に検出します。アップグレード後に破損するコマンドを実行すると、モードは問題を解決するための特定のステップを含む警告を表示します。これにより、コードを手動で検索するのではなく、潜在的な問題を自動的に検出できるため、時間を節約できます。

仕組み

有効にすると、アップグレードデバッグモードは、AWS CLI バージョン 2 の更新で下位互換性のない変更が生じる機能が使用されている場合、それを検出します。AWS CLI バージョン 2 にアップグレードした後に AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更 にリストされているコマンドまたは機能を使用すると、出力に警告が表示されます。互換性のない変更の検出は、使用されるコマンド、指定された引数、実行環境 (環境変数、構成設定など)、および場合によっては、使用される AWS アカウントのリソースの内容または構成に基づいています。

次の例は、これらの警告がどのように表示されるかを示しています。このコマンドは警告の例を示しています。すべての警告テキストは「AWS CLI V2 UPGRADE WARNING」で始まり、その後に特定の警告メッセージが続きます。この場合、コマンドは、AWS CLI で URL の内容を取得し、その内容を --template-body パラメータ値として使用しており、これは AWS CLI バージョン 2 で削除された機能であるため、警告が出力されます。

以下は、警告の例です。

$ aws cloudformation create-stack \
  --stack-name "stack012345" \
  --template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"

AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or 
https://, AWS CLI v2 will not automatically request the content of the URL for 
the parameter, and the `cli_follow_urlparam` option has been removed. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.

次の表は、すべての下位互換性のない変更と、AWS CLI バージョン 2 の更新で下位互換性のない変更が発生しないようにする方法を示しています。デバッグモードで警告を解決する修復アクションは太字です。

重要な変更 V1 で V2 の動作に移行する V2 では、V1 の動作を保持します。
テキストファイルのエンコードを設定するために環境変数を追加 PYTHONUTF8 および PYTHONIOENCODING 環境変数を設定します。 AWS_CLI_FILE_ENCODING 環境変数を V1 で指定されたエンコードに設定します。
バイナリパラメータはデフォルトで base64 エンコードされた文字列として渡されるようになりました base64 で パラメータの値をエンコードします。パラメータがファイルからロードされている場合は、ファイルコンテンツを base64 でエンコードします。 cli_binary_format 設定を「raw-in-base64-out」に設定します。
マルチパートコピーのファイルプロパティとタグの Amazon S3 処理が改善されました 該当なし。バージョン 1 でバージョン 2 の動作に移行できません。 --copy-props none パラメータを使用します。
パラメータの http:// または https:// URL の自動取得の廃止 URL の内容をローカルファイルにダウンロードするには、curl (または代替ツール) を使用します。次に、file:// を使用してパラメータにファイルコンテンツをロードします。または、cli_follow_urlparam を false に設定して、raw URL をパラメータ値として指定します。 該当なし。バージョン 2 でバージョン 1 の動作を保持できません。
デフォルトですべての出力に使用されるページャー 該当なし。バージョン 1 でバージョン 2 の動作に移行できません。 cli_pager 設定または AWS_PAGER 変数を空の文字列に設定します。
タイムスタンプの出力値は ISO 8601 形式に標準化されています cli_timestamp_format 設定を iso8601 に設定します。 cli_timestamp_format 設定を wire に設定します。
変更のない、CloudFormation デプロイの処理の改善 --no-fail-on-empty-changeset パラメータを使用します。 --fail-on-empty-changeset パラメータを使用します。
us-east-1 リージョンの Amazon S3 エンドポイントのデフォルト動作を変更しました AWS_ENDPOINT_URL_S3 環境変数または --endpoint-url コマンドラインオプションを us-east-1 リージョン URL に設定します。 --region aws-global コマンドラインオプション。
ecr get-login を削除し、ecr get-login-password に置き換えました (1.17.10 以降) ecr get-login を削除し、ecr get-login-password に置き換えました を使用して出力を docker コマンドにパイプします。 該当なし。バージョン 2 でバージョン 1 の動作を保持できません。
AWS CLIプラグインに対する バージョン 2 のサポートが変更されます 該当なし。バージョン 1 でバージョン 2 の動作に移行できません。 設定ファイルの [plugins] セクションに cli_legacy_plugin_path を設定します。バージョン 2 でプラグインをテストし、バージョン 2 バージョンをロックして、アップグレードするたびにプラグインをテストします。
非表示エイリアスのサポートを削除しました 古い非表示エイリアスの使用から、すべてのバージョンで動作する 非表示エイリアスのサポートを削除しました に切り替えます。 該当なし。バージョン 2 でバージョン 1 の動作を保持できません。
api_versions 設定ファイルの設定はサポートされていません 古い API バージョンの使用を最新の API バージョンに移行してテストし、構成設定から api_versions を削除します。 該当なし。バージョン 2 でバージョン 1 の動作を保持できません。
AWS CLI バージョン 2 は、署名 V4 のみを使用して Amazon S3 リクエストを認証します 署名バージョンをバージョン 4 に指定します (「リクエスト認証の署名バージョンの指定」を参照)。 該当なし。バージョン 2 でバージョン 1 の動作を保持できません。
AWS CLI バージョン 2 はページングパラメータとの整合性が高くなっています 入力 JSON パラメータのページ分割パラメータをコマンド自体に移動します。 入力 JSON パラメータからページ分割パラメータを削除します。
AWS CLI バージョン 2 は、すべてのコマンドで一貫性のあるリターンコードを提供します。 該当なし。バージョン 1 でバージョン 2 の動作に移行できません。 該当なし。バージョン 2 でバージョン 1 の動作を保持できません。

制限

AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更 のレビューを強くお勧めします。

サポートされていない互換性のない変更の検出

アップグレードデバッグモード機能は、AWS CLI バージョン 2 は、すべてのコマンドで一貫性のあるリターンコードを提供します。 を除くすべての互換性のない変更をサポートします。このモードは、AWS CLI ダウンストリームから返されるエラーコードの使用方法を考慮できません。

条件付き互換性のない変更の検出

タイムスタンプの出力値は ISO 8601 形式に標準化されています の検出は、検出が AWS アカウントの状態に依存する唯一のケースであり、アカウントリソースが後で更新されると、下位互換性のない変更が発生する可能性があります。サービスからの API レスポンスにタイムスタンプが含まれていない場合、この互換性のない変更は検出されません。

AWS CLI コマンドによって返されるタイムスタンプ形式に依存していて、ISO 8601 を使用するように AWS CLI をまだ設定していない場合は、バージョン 2 へのアップグレード後にタイムスタンプの処理が中断されないように特に注意してください。

解決不可能な互換性のない変更の検出

アップグレードデバッグモードによる一部の警告出力は、コマンドまたは環境を変更しても解決できません。次のケースでは、対応する機能を使用している限り、警告がアップグレードデバッグモードで常に出力されます。

誤検出

アップグレードデバッグモードによる警告出力は、AWS CLI V2 へのアップグレード後に必ず下位互換性のない変更があるというものではありません。以下は、AWS CLI V2 で互換性のない変更が生じていないにもかかわらず、アップグレードデバッグモードで警告が出力される場合です。

アップグレードデバッグモードを設定する

アップグレードデバッグモードを有効または無効にするには、次の方法を使用します。優先順位は次のとおりです。