破壊的変更 - AWS CLI バージョン 1 からバージョン 2 への移行
このトピックでは、AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の動作における変更について説明します。これらの変更により、バージョン 1 と同じ動作をバージョン 2 で実行するために、スクリプトまたはコマンドを変更する必要が生じる場合があります。
トピック
- AWS CLI バージョン 2 では、テキストファイルエンコーディングの設定に環境変数が使用されるようになりました
- AWS CLI バージョン 2 では、デフォルトでバイナリパラメータが base64 でエンコードされた文字列として渡されるようになりました
- AWS CLI バージョン 2 では、マルチパートコピーの実行時におけるファイルプロパティとタグの Amazon S3 処理が改善されます
- AWS CLI バージョン 2 では、パラメータの http:// または https:// URL が自動的に取得されなくなりました
- AWS CLI バージョン 2 はデフォルトで、すべての出力にページングプログラムを使用します。
- AWS CLI バージョン 2 では、すべてのタイムスタンプ出力値が ISO 8601 形式で返されるようになりました
- AWS CLI バージョン 2 で、変更を行わない AWS CloudFormation デプロイの処理が改善されました
- AWS CLI バージョン 2 は us-east-1 リージョンに正しい Amazon S3 リージョンエンドポイントを使用します
- AWS CLI バージョン 2 はデフォルトでリージョン AWS STS エンドポイントを使用します
- AWS CLI バージョン 2 は ecr get-login を ecr get-login-password に置き換えます
- AWS CLIプラグインに対する バージョン 2 のサポートが変更されます
- AWS CLI バージョン 2 では、「非表示」エイリアスがサポートされなくなりました
- AWS CLI バージョン 2 では、api_versions 設定ファイルの設定がサポートされなくなりました。
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
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
オペレーションを実行して、返されたコンテンツをパラメータの値として使用することがなくなりました。その結果、関連するコマンドラインのオプション cli_follow_urlparam
が削除されます。
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
more
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
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 は 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 を呼び出すようになりました。