AWS CLI V1-to-V2 移行ツールを使用して AWS CLI バージョン 1 を AWS CLI バージョン 2 にアップグレードする

このトピックでは、AWS CLI V1-to-V2 移行ツールについて説明します。

AWS CLI バージョン 1 のユーザーは、AWS CLI バージョン 2 にアップグレードして、新機能と強化されたパフォーマンスを利用することをお勧めします。このトピックでは、AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の動作の変更について説明します。この変更では、同じ動作をするために、スクリプトまたはコマンドを更新する必要があるものについて述べます。AWS CLI V1-to-V2 移行ツールは、AWS CLI バージョン 1 コマンドを含む bash スクリプトを分析し、AWS CLI バージョン 2 の重大な変更で更新された機能の使用を検出します。さらに、このツールはスクリプトを自動的に変更して、検出したほとんどの問題を修正できます。このツールは、bash スクリプト内の AWS CLI バージョン 1 コマンドを自動的に検出して変更し、バージョン 2 へのアップグレード時に予期しない問題が発生することを防ぐことで、アップグレードエクスペリエンスを向上させます。

アップグレードデバッグモードと比較すると、AWS CLI V1-to-V2 移行ツールはスタンドアロンツールであり、AWS CLI コマンドの実行を必要としません。アップグレードデバッグモードと AWS CLI V1-to-V2 移行ツールの詳細な比較については、「AWS CLI バージョン 2 の移行ガイド」の「CLI AWS 移行ツールを使用して破損を軽減する」を参照してください。

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

仕組み

AWS CLI V1-to-V2 移行ツールは、CLI バージョン 1 を使用する bash スクリプトをリントできる AWS Python パッケージです。静的リンターであるため、マシンにインストールした AWS CLI バージョン 1 のバージョンには依存しません。このリンターはコマンドラインから呼び出され、bash スクリプトへのローカルファイルパスがパラメータとして提供されます。

移行ツールは、スクリプトで使用される AWS CLI バージョン 1 コマンドを変更することで、検出したほとんどの検出結果を解決する変更された bash スクリプトを自動的に生成することもできます。移行ツールは、AWS バージョン 2 との互換性を保ちながら、バージョン 1 の動作を保持するようにコマンドを変更します。

一部の検出結果については、AWS CLI V1-to-V2 移行ツールで検出できますが、自動修正は提供されません。このような場合、移行ツールは手動レビューが必要な検出としてフラグを付けます。

AWS CLI V1-to-V2 移行ツールがサポートする重大な変更と自動修正の詳細なリストについては、「制限」を参照してください。

前提条件

Python

このツールを使用するには、Python 3.9 以降がインストールされている必要があります。

正しい Python バージョンがインストールされていることを確認するには、ターミナルで次のコマンドを実行し、出力に 3.9 以上の Python バージョンが表示されていることを確認します。

$ python3 --version

古いバージョンの Python がある場合、または Python がインストールされていない場合は、公式の Python ダウンロードページから互換性のあるバージョンをダウンロードできます。

pip

互換性のあるバージョンの Python がインストールされていることに加えて、pip がインストールされている必要があります。

pip がインストールされていることを確認するには、次のコマンドを実行します。

$ python3 -m pip --version

pip がインストールされている場合は、次のような出力が表示されます。

pip 25.0.1 from ~/.local/lib/python3.13/site-packages (python 3.13)

pip がインストールされていない場合は、「pip のインストール」を参照してください。

インストール

AWS CLI V1-to-V2 移行ツールを新しい仮想環境にインストールします。

$ python3 -m venv .venv
$ source .venv/bin/activate
$ python3 -m pip install aws-cli-migrate

Usage

ドライランモード (デフォルト)

ドライランモードでは、入力スクリプトを変更せずに、重大な変更の対象となる AWS CLI バージョン 1 コマンドを自動的に検出できます。

$ migrate-aws-cli --script upload_s3_files.sh

自動修正モード

自動修正モードでは、入力スクリプトで AWS CLI バージョン 1 コマンドを自動的に検出して更新し、可能な場合は AWS CLI バージョン 2 で導入された変更による破損を軽減できます。

$ migrate-aws-cli --script upload_s3_files.sh --fix

必要に応じて、--output パラメータを介して出力パスを指定して、入力スクリプトを更新するのではなく、更新されたスクリプトを書き込むこともできます。

$ migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix

インタラクティブモード

インタラクティブモードでは、重大な変更の対象となる AWS CLI バージョン 1 コマンドを自動的に検出できます。ほとんどの検出結果には、AWS CLI バージョン 2 での破損を軽減するための修正案が表示されます。提案された修正を確認し、適用するかどうかを決定できます。必要に応じて、--output パラメータを介して出力パスを指定して、更新されたスクリプトを書き込む場所を制御します。

$ migrate-aws-cli --script upload_s3_files.sh --interactive \
--output upload_s3_files_v2.sh

次の出力スニペットは、インタラクティブモードでの検出結果の例です。

14 14│ 
15 15│ aws s3 ls s3://mybucket
16 16│ 
17   │-aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive
   17│+aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive --copy-props none
18 18│ 
19 19│ TEMPLATE_KEY="cloudformation/$(basename "$TEMPLATE_FILE")"
20 20│ 

examples/upload_s3_files.sh:17 [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: 

推奨される修正は、Git の diff に似た形式で表示されます。移行ツールは、- で始まる行の削除を提案し、+ で始まる行の追加を提案します。前の例では、提案は、Amazon S3 コピーを実行する AWS CLI バージョン 1 コマンドに --copy-props none パラメータを追加するものとして解釈できます。

推奨される修正ごとに、次のいずれかのコントロールを入力できます。

一部の検出結果は、修正案が提示されずに手動レビューのフラグが立てられる場合があります。これらの検出結果を確認し、参照されている重大な変更の影響を受けるかどうかを検証する必要があります。これらの検出結果の影響を受ける場合は、検出結果の説明で指定されたガイダンスに従って、AWS CLI バージョン 2 で導入された重大な変更を回避または準備するために必要な変更を行う必要があります。

制限

AWS CLI V1-to-V2 移行ツールは現在、AWS CLI バージョン 2 で導入されたすべての重大な変更をサポートしているわけではなく、重大な変更が実際に発生していなくてもコマンドの検出を出力する誤検出のケースがあります。

「AWS CLI バージョン 2 の新機能と変更点」に記載されている「AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更」について理解することを強くお勧めします。

テキストベースの分析

移行ツールは、スクリプトを実行せずに分析します。これにより、重大な変更を検出する AWS CLI コマンドの検出方法が制限されます。移行ツールは AWS CLI コマンドのテキストのみを調べることができます。非推奨のパラメータを AWS CLI に直接渡す代わりに変数に保存するなど、実行時に発生する問題を検出することはできません。

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

移行ツールにおける重大な変更に対するサポート範囲を以下の表にまとめます。