重要な変更 – 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 では、あるコマンドの出力から別のコマンドの入力にバイナリパラメータを渡す場合に、常に中間処理を必要とせずに簡単にできるとは限りませんでした。base64 でエンコードされた文字列が必要なコマンドもあれば、UTF8 でエンコードされたバイト文字列が必要なコマンドもありました。AWS CLI バージョン 2 では、あるコマンドから別のコマンドへの値の受け渡しをより確実に行えるように、バイナリパラメータの処理の一貫性を高めています。

AWS CLI バージョン 2 は、デフォルトではすべてのバイナリ入力パラメータとバイナリ出力パラメータを base64 エンコード文字列として渡すようになりました。バイナリ入力を必要とするパラメータは、ドキュメントで blob (バイナリラージオブジェクト) として指定された型を持っています。AWS CLI バージョン 2 では、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 バージョン 1 の動作に戻すように AWS CLI バージョン 2 に指示できます。

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 のファイルプロパティとタグの処理を改良

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

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

これにより、AWS CLI バージョン 1 を使用した場合には行われなかった Amazon S3 エンドポイントへの追加の AWS API コールが行われる可能性があります。たとえば、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 を自動的に取得しなくなりました。

パラメータ値が http:// または https:// で始まり、返されたコンテンツをパラメータの値として使用する場合、AWS CLI バージョン 2 は 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/config ファイルに AWS_PAGER 環境変数または cli_pager 設定を含め、使用するコマンドを指定します。検索パスにあるコマンドを指定するか、コンピュータで使用可能なコマンドのフルパスとファイル名を指定できます。

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

~/.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 でグローバルエンドポイントを使用するように強制するには、コマンドの Region を 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 バージョン 1 から移行するのを支援することを目的としています。特定のプラグインまたは CLI プラグインインターフェイスでさえ、AWS CLI バージョン 2 の将来のバージョンでサポートされる保証はありません。プラグインに依存している場合は、特定のバージョンの CLI にロックして、アップグレード時にプラグインの機能をテストしてください。

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

[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