破壊的変更 - AWS CLI バージョン 1 からバージョン 2 への移行

このトピックでは、AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の動作における変更について説明します。これらの変更により、バージョン 1 と同じ動作をバージョン 2 で実行するために、スクリプトまたはコマンドを変更する必要が生じる場合があります。

AWS CLI バージョン 2 では、テキストファイルエンコーディングの設定に環境変数が使用されるようになりました

デフォルトでは、テキストファイルはインストールされたロケールと同じエンコードを使用します。テキストファイルのエンコードをロケールと異なるように設定するには、AWS_CLI_FILE_ENCODING 環境変数を使用します。次の例では、Windows で UTF-8 を使用してテキストファイルを開くように CLI を設定します。

AWS_CLI_FILE_ENCODING=UTF-8

詳細については、「AWS CLI を設定する環境変数」を参照してください。

AWS CLI バージョン 2 では、デフォルトでバイナリパラメータが base64 でエンコードされた文字列として渡されるようになりました

AWS CLI バージョン 1 では、中間処理を使用しなければ、1 つのコマンドの出力から別のコマンドの入力にバイナリパラメータを簡単に渡せない場合もありました。コマンドには、base64 でエンコードされた文字列が必要なものもあれば、UTF8 でエンコードされたバイト文字列が必要なものもありました。AWS CLI バージョン 2 では、バイナリパラメータの処理の一貫性を向上させて、1 つのコマンドから別のコマンドへの値の受け渡しをより確実に行えるようになっています。

AWS CLI バージョン 2 では、デフォルトですべてのバイナリ入力パラメータとバイナリ出力パラメータが base64 でエンコードされた文字列として渡されるようになりました バイナリ入力を必要とするパラメータは、ドキュメントで blob (バイナリラージオブジェクト) として指定された型を持っています。AWS CLI バージョン 2 では、AWS CLI パラメータにバイナリデータをファイルとして渡すために、次のプレフィックスを使用してファイルを指定できます。

• file:// – AWS CLI は、ファイルのコンテンツを base64 でエンコードされたテキストとして扱います。例: --some-param file://~/my/path/file-with-base64.txt

• fileb:// – AWS CLI は、ファイルのコンテンツをエンコードされていないバイナリとして扱います。例: --some-param fileb://~/my/path/file-with-raw-binary.bin

プロファイル用の ~/.aws/config ファイルで次の行を指定することによって、AWS CLI バージョン 2 を AWS CLI バージョン 1 の動作に戻すことができます。

cli_binary_format=raw-in-base64-out

また、コマンドラインにパラメータ --cli-binary-format raw-in-base64-out を含めることで、アクティブなプロファイル設定を上書きして、個々のコマンドの設定を元に戻すこともできます。

AWS CLI バージョン 1 の動作に戻し、file:// または fileb:// を使用してバイナリパラメータのファイルを指定する場合、AWS CLI はファイルコンテンツをエンコードされていない raw バイナリとして扱います。

AWS CLI バージョン 2 では、マルチパートコピーの実行時におけるファイルプロパティとタグの Amazon S3 処理が改善されます

1 つの Amazon S3 バケットの場所から別の Amazon S3 バケットの場所にファイルをコピーするために aws s3 名前空間で AWS CLI バージョン 1 のコマンドバージョンを使用しており、そのオペレーションがマルチパートコピーを使用する場合は、コピー先にソースオブジェクトのファイルプロパティがコピーされません。

デフォルトで、マルチパートコピーを実行する s3 名前空間の AWS CLI バージョン 2 コマンドは、ソースのすべてのタグと、content-type、content-language、content-encoding、content-disposition、cache-control、expires、および metadata のプロパティ一式をコピー先に転送するようになりました。

これにより、AWS CLI バージョン 1 を使用する場合には行われなかった追加の AWS API コールが Amazon S3 エンドポイントに対して実行されることになる場合があります。これには、HeadObject、GetObjectTagging、および PutObjectTagging が含まれます。

AWS CLI バージョン 2 コマンドでこのデフォルト動作を変更する必要がある場合は、--copy-props パラメータを使用して次のオプションのいずれかを指定します。

• default - デフォルト値。コピーに、ソースオブジェクトにアタッチされたすべてのタグと、マルチパートコピー以外に使用される --metadata-directive パラメータの次のプロパティが含まれることを指定します。content-type、content-language、content-encoding、content-disposition、cache-control, expires、metadata。

• metadata-directive - --metadata-directive マルチパートコピー以外に使用されるパラメータによって包含されるプロパティのみがコピーに含まれることを指定します。タグはコピーされません。

• none - コピーにソースオブジェクトのプロパティを含みません。

AWS CLI バージョン 2 では、パラメータの http:// または https:// URL が自動的に取得されなくなりました

AWS CLI バージョン 2 では、パラメータ値が http:// または https:// で始まる場合に GET オペレーションを実行して、返されたコンテンツをパラメータの値として使用することがなくなりました。URL を取得し、その URL から読み込んだ内容をパラメータの値として渡す必要がある場合は、curl または同様のツールを使用して URL の内容をローカルファイルにダウンロードすることをお勧めします。次に、file:// 構文を使用してそのファイルの内容を読み込み、パラメータの値として使用します。

たとえば、次のコマンドでは、http://www.google.com で見つかったページの内容を取得し、その内容をパラメータとして渡そうとしなくなりました。代わりに、リテラルテキスト文字列 https://google.com をパラメータとして渡します。

$ aws ssm put-parameter --value http://www.google.com --name prod.microservice1.db.secret --type String 2

ウェブ URL の内容をパラメータとして取得して使用する場合は、バージョン 2 で次の操作を実行できます。

$ curl https://my.example.com/mypolicyfile.json -o mypolicyfile.json
$ aws iam put-role-policy --policy-document file://./mypolicyfile.json --role-name MyRole --policy-name MyReadOnlyPolicy

前の例では、-o パラメータは、ソースファイルと同じ名前で現在のフォルダーにファイルを保存するよう curl に指示します。2 番目のコマンドは、ダウンロードしたファイルの内容を取得し、その内容を --policy-document の値として渡します。

AWS CLI バージョン 2 はデフォルトで、すべての出力にページングプログラムを使用します。

AWS CLI バージョン 2 はデフォルトで、すべての出力をオペレーティングシステムのデフォルトページャープログラム経由で返します。デフォルトでは、このプログラムは Linux および macOS では less プログラム、Windows では more プログラムです。これにより、出力を一度に 1 ページずつ表示することで、サービスからの大量の出力内を簡単に移動できます。ただし、スクリプトを実行しているときなどに、キーを押して各ページを取得することは不要で、すべての出力が必要な場合があります。これを行うには、別のページングプログラムを使用するか、まったく使用しないように AWS CLI バージョン 2 を設定できます。そのためには、AWS_PAGER ファイルに cli_pager 環境変数または ~/.aws/config 設定を含め、使用するコマンドを指定します。検索パスにあるコマンドを指定するか、コンピュータで使用可能なコマンドのフルパスとファイル名を指定できます。

以下の例に示すように、変数を空の文字列に設定することで、外部ページングプログラムの使用を完全に無効にすることができます。

~/.aws/config ファイルにオプションを設定する

以下の例は、default プロファイルの設定を示していますが、~/.aws/config ファイル内の任意のプロファイルにその設定を追加できます。

[default]
cli_pager=

環境変数を設定する

Linux または macOS:

$ export AWS_PAGER=""

Windows の場合:

C:\> setx AWS_PAGER ""

AWS CLI バージョン 2 では、すべてのタイムスタンプ出力値が ISO 8601 形式で返されるようになりました

AWS CLI バージョン 2 はデフォルトで、すべてのタイムスタンプレスポンス値を ISO 8601 形式で返します。AWS CLI バージョン 1 では、コマンドによって返されるタイムスタンプ値が HTTP API レスポンスによって返された値の形式になっており、これはサービスによって異なる可能性がありました。

ISO 8601 形式のタイムスタンプは、次の例のようになります。最初の例は、時刻を UTC (協定世界時) で表し、時刻の後に Z を含めます。日付と時刻は T で区切られます。

2019-10-31T22:21:41Z

別のタイムゾーンを指定するには、Z ではなく、+ または - を指定し、目的のタイムゾーンが UTC より進んでいるまたは遅れている時間数を 2 桁の値として指定します。次の例では、前の例と同じ時刻を示していますが、UTC から 8 時間遅れている太平洋標準時刻に調整されています。

2019-10-31T14:21:41-08

HTTP API レスポンスから返された形式でタイムスタンプを表示するには、.aws/config プロファイルに次の行を追加します。

cli_timestamp_format = wire

AWS CLI バージョン 2 で、変更を行わない AWS CloudFormation デプロイの処理が改善されました

AWS CLI バージョン 1 では、変更を行わない AWS CloudFormation テンプレートをデプロイした場合、デフォルトで AWS CLI がエラーコードを伴って失敗していました。これをエラーとみなさず、スクリプトを続行したい場合は、これが問題になる可能性がありました。AWS CLI バージョン 1 では、0 を返し、エラーを引き起こさないフラグ -–no-fail-on-empty-changeset をスクリプトに追加することによってこの問題を回避できました。

これは一般的なケースシナリオであるため、AWS CLI バージョン 2 ではデフォルトで、デプロイによって変更が行われず、オペレーションが空の変更セットを返す場合に正常終了コード 0 が返されるようになりました。

AWS CLI バージョン 2 を元の動作に戻すには、新しいフラグ --fail-on-empty-changeset を追加する必要があります。

AWS CLI バージョン 2 では Amazon S3 キーがより一貫的に使用されます

s3名前空間内の Amazon S3 カスタマイズコマンドで、パスの表示方法の一貫性が向上しました。AWS CLI バージョン 2 では常に、関連するキーを基準にしてパスが表示されます。AWS CLI バージョン 1 は、絶対形式でパスを表示する場合と、相対形式でパスを表示する場合がありました。

AWS CLI バージョン 2 は us-east-1 リージョンに正しい Amazon S3 リージョンエンドポイントを使用します

リージョン us-east-1 を使用するように AWS CLI バージョン 1 を設定すると、AWS CLI は us-east-1 リージョンで物理的にホストされているグローバル s3.amazonaws.com エンドポイントを使用していました。AWS CLI バージョン 2 では、そのリージョンが指定される場合に、真のリージョンエンドポイント s3.us-east-1.amazonaws.com が使用されるようになりました。AWS CLI バージョン 2 によるグローバルエンドポイントの使用を強制するには、コマンドのリージョンを aws-global に設定できます。

AWS CLI バージョン 2 はデフォルトでリージョン AWS STS エンドポイントを使用します

AWS CLI バージョン 2 はデフォルトで、現在設定されている AWS リージョンのリージョンエンドポイントにすべての AWS STS API リクエストを送信します。

AWS CLI バージョン 1 はデフォルトで、AWS STS リクエストをグローバル AWS STS エンドポイントに送信します。この V1 のデフォルト動作は、sts_regional_endpoint 設定を使用して制御できます。

AWS CLI バージョン 2 は ecr get-login を ecr get-login-password に置き換えます

AWS CLI バージョン 2 はコマンド aws ecr get-login を、コンテナ認証との自動統合を改善する新しいコマンド aws ecr get-login-password に置き換えます。

aws ecr get-login-password コマンドでは、プロセスリスト、シェル履歴、またはその他のログファイル内の認証情報が公開されるリスクが減ります。また、docker login コマンドとの互換性が向上し、自動化が向上します。

aws ecr get-login-password コマンドは、AWS CLI バージョン 1.17.10 以降、および AWS CLI バージョン 2 で使用できます。下位互換性のため、古い aws ecr get-login コマンドは AWS CLI バージョン 1 で引き続き使用できます。

aws ecr get-login-password コマンドを使用すると、パスワードを取得する以下のコードを置き換えることができます。

$(aws ecr get-login --no-include-email)

パスワードをシェルの履歴またはログに公開するリスクを減らすには、代わりに以下の例のコマンドを使用します。この例では、パスワードは docker login コマンドに直接パイプされ、そこで --password-stdin オプションによってパスワードパラメータに割り当てられます。

aws ecr get-login-password | docker login --username AWS --password-stdin MY-REGISTRY-URL

プラグインに対する AWS CLI バージョン 2 のサポートが変更されます

AWS CLI バージョン 2 でのプラグインサポートは完全に暫定的なもので、安定した新しいプラグインインターフェイスがリリースされるまで、ユーザーによる AWS CLI CLI バージョン 1 からの移行をサポートすることを目的としています。AWS CLI バージョン 2 の将来のバージョンで特定のプラグインまたは CLI プラグインインターフェイスがサポートされるという保証はありません。プラグインに依存している場合は、CLI の特定バージョンにロックして、アップグレード時にはプラグインの機能をテストするようにしてください。

プラグインサポートを有効にするには、[plugins] に ~/.aws/config セクションを作成します。

[plugins]
cli_legacy_plugin_path = <path-to-plugins>/python3.7/site-packages
<plugin-name> = <plugin-module>

[plugins] セクションで、cli_legacy_plugin_path 変数を定義し、その値を、プラグインモジュールが存在する Python サイトパッケージパスに設定することから始めます。次に、プラグインの名前 (plugin-name)、およびプラグインのソースコードを含む Python モジュールのファイル名 (plugin-module) を指定して、プラグインを設定できます。CLI は、各プラグインをロードするために、それぞれの plugin-module をインポートして awscli_initialize 関数を呼び出します。

AWS CLI バージョン 2 では、「非表示」エイリアスがサポートされなくなりました

AWS CLI バージョン 2 では、バージョン 1 でサポートされていた次の非表示エイリアスがサポートされなくなりました。

以下の表では、AWS CLI バージョン 2 を含めたすべてのバージョンで機能するサービス、コマンド、およびパラメータが最初の列に表示されています。2 番目の列には、AWS CLI バージョン 2 では機能しなくなったエイリアスが表示されています。

作業サービス、コマンド、パラメータ	廃止されたエイリアス
cognito-identity create-identity-pool open-id-connect-provider-arns	open-id-connect-provider-ar-ns
storagegateway describe-tapes tape-arns	tape-ar-ns
storagegateway.describe-tape-archives.tape-arns	tape-ar-ns
storagegateway.describe-vtl-devices.vtl-device-arns	vtl-device-ar-ns
storagegateway.describe-cached-iscsi-volumes.volume-arns	volume-ar-ns
storagegateway.describe-stored-iscsi-volumes.volume-arns	volume-ar-ns
route53domains.view-billing.start-time	start
deploy.create-deployment-group.ec2-tag-set	ec-2-tag-set
deploy.list-application-revisions.s3-bucket	s-3-bucket
deploy.list-application-revisions.s3-key-prefix	s-3-key-prefix
deploy.update-deployment-group.ec2-tag-set	ec-2-tag-set
iam.enable-mfa-device.authentication-code1	authentication-code-1
iam.enable-mfa-device.authentication-code2	authentication-code-2
iam.resync-mfa-device.authentication-code1	authentication-code-1
iam.resync-mfa-device.authentication-code2	authentication-code-2
importexport.get-shipping-label.street1	street-1
importexport.get-shipping-label.street2	street-2
importexport.get-shipping-label.street3	street-3
lambda.publish-version.code-sha256	code-sha-256
lightsail.import-key-pair.public-key-base64	public-key-base-64
opsworks.register-volume.ec2-volume-id	ec-2-volume-id

AWS CLI バージョン 2 では、api_versions 設定ファイルの設定がサポートされなくなりました。

AWS CLI バージョン 2 では、api_versions 設定ファイルの設定を使用した、古いバージョンの AWS サービス API の呼び出しがサポートされなくなりました。すべての AWS CLI コマンドは、エンドポイントで現在サポートされている最新バージョンのサービス API を呼び出すようになりました。