AWS CLI のコンフィグファイルと環境変数とコマンドラインオプションで指定できる内容をまとめて確認してみた

~/.aws/config の中で credential_process とか使ったことある人はいるんでしょうか。

コンバンハ、千葉(幸)です。

~/.aws/config、いじってますか?

~/.aws/configの例

[default]
region = ap-northeast-1
output = json

[profile chiba]
region = ap-northeast-1
output = json
role_arn = arn:aws:iam::999999999999:role/chibayuki-role
source_profile = jump-account
mfa_serial = arn:aws:iam::000000000000:mfa/cm-chiba.yukihiro

~/.aws/configデフォルトリージョン出力形式スイッチロールのための設定などを行う機会は多いかと思います。ここで設定可能な項目は他にもたくさんあり、その数は30個以上にのぼります。

今回はその一覧をまとめてみました。以下一覧をベースとしています。

設定項目に対応する環境変数やコマンドライオプションがある(場合がある)ので、それも一緒にまとめています。

AWS CLI コンフィグファイルの基本をおさらい

一覧の確認の前に、基本的な考え方を押さえておきましょう。

~/.aws/config と ~/.aws/credentials

以下のように aws configure を実行したとします。(アクセスキーの値はドキュメントに載っているサンプルのものです。)

$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json

このコマンドを実行すると以下のように二つのファイルに設定が行われます。

~/.aws/credentials

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

~/.aws/config

[default]
region=us-west-2
output=json

認証情報(アクセスキーとシークレットアクセスキー)のみ別ファイルに保存され、それ以外の設定は~/.aws/configに保存されます。

こういった(両ファイルにまたがった)設定内容の集まりをプロファイルと呼びます。ここではdefaultプロファイルを使用しているということになります。

名前付きプロファイル

プロファイルを複数持つこともできます。先程の aws configure に--profileオプションを指定し、プロファイル名にSampleを指定したとします。

$ aws configure --profile Sample
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json

各設定ファイルにはSampleという名称でプロファイルが追加されます。

~/.aws/credentials

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
[Sample]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

~/.aws/config

[default]
region=us-west-2
output=json
[Sample]
region=us-west-2
output=json

(ここではdefaultSampleに同じ値を入れましたが、一般的には別の設定値を入れます。)

このように複数プロファイルを持てます。aws configure を使用せずに設定ファイルを直接編集しても設定できます。

コンフィグ設定と優先順位

~/.aws/configの設定内容は環境変数やコマンドラインオプションによって上書きされます。

プロファイルでデフォルトリージョンとしてus-west-2が指定されていたとします。

~/.aws/config

[default]
region=us-west-2
output=json

この状態で特に指定なしに AWS CLI を実行するとコマンド実行対象のリージョンはus-wast-2となります。

ここで環境変数AWS_DEFAULT_REGIONを設定すれば、設定は上書きされます。(環境変数が有効な間のみ)

$ export AWS_DEFAULT_REGION=ap-northeast-1

さらにその状態でコマンドラインオプション--regionを使用すれば、その指定が優先されます。(オプションを付与したコマンド一回のみ)

$ aws ec2 describe-vpcs\
  --region ap-northeast-3

今回取り上げた項目では以下順に優先されます。

  1. コマンドラインオプション
  2. 環境変数
  3. AWS CLI コンフィグファイル

とは言え、すべての設定項目においてそれに対応するコマンドラインオプションや環境変数が存在するわけではないことに注意してください。

また、その他にもいくつか優先順位が考慮される要素があります。詳細は以下を参照してください。

AWS CLI コンフィググローバル設定の一覧

~/.aws/configで設定できる項目の一覧をまとめました。

AWS CLI のバージョンによって使用できるか否かが異なるため、「v1,v2」の列で表現しています。また、設定項目を上書きできる環境変数やコマンドラインオプションがあるものはそれを記載しています。

# 設定項目名 概要 デフォルト値 v1 v2 環境変数 コマンドラインオプション
1 api_versions 旧 API バージョンを指定する際に使用 なし(最新Ver) - なし なし
2 aws_access_key_id AWS アクセスキーの指定 なし AWS_ACCESS_KEY_ID なし
3 aws_secret_access_key AWS シークレットアクセスキーの指定 なし AWS_SECRET_ACCESS_KEY なし
4 aws_session_token AWS セッショントークンの指定 なし AWS_SESSION_TOKEN なし
5 ca_bundle SSL 証明書を検証するために使用される CA 証明書バンドルを指定 なし(ツール標準) AWS_CA_BUNDLE --ca-bundle
6 cli_auto_prompt 自動プロンプト(各種補完)の指定 off - AWS_CLI_AUTO_PROMPT --cli-auto-prompt--no-cli-auto-prompt
7 cli_binary_format バイナリインプットパラメータをどう解釈するかを指定 base64 - なし なし
8 cli_follow_urlparam URL リンク先のコンテンツをパラメータ値として使用するかどうかを指定 true - なし なし
9 cli_pager 出力に使用されるページャープログラムを指定 なし(OS準拠) - AWS_PAGER --no-cli-pager
10 cli_timestamp_format 出力に含まれるタイムスタンプの形式を指定 iso8601(v2),wire(v1) なし なし
11 credential_process 認証情報を生成・取得するための外部コマンドを指定 なし なし なし
12 credential_source IAM ロールを引き受けるために使用する認証情報を検索する場所を指定 なし なし なし
13 duration_seconds ロールセッションの最大期間を秒単位で指定 3600 なし なし
14 external_id サードパーティーがロールを引き受けるために使用される独自の識別子を指定 なし なし なし
15 max_attempts AWS CLI 再試行ハンドラが使用する最大再試行回数を指定 retry_mode 準拠 AWS_MAX_ATTEMPTS なし
16 mfa_serial ロールを引き受けるときに使用する MFA デバイスの ID を指定 なし なし なし
17 output コマンドのデフォルトの出力形式を指定 json AWS_DEFAULT_OUTPUT --output
18 parameter_validation クライアント側でパラメータの検証をするかどうかを指定 true なし なし
19 region コマンドのリクエスト送信先の AWS リージョンを指定 なし AWS_DEFAULT_REGION --region
20 retry_mode AWS CLI が使用する再試行モードを指定 standard(v2),legacy(v1) AWS_RETRY_MODE なし
21 role_arn コマンドの実行に使用する IAM ロールの ARN を指定 なし AWS_ROLE_ARN なし
22 role_session_name ロールを引き受けたセッションに適用する名前を指定 なし AWS_ROLE_SESSION_NAME なし
23 source_profile IAM ロールを引き受けるために使用する名前付きプロファイルを指定 なし なし なし
24 sso_account_id AWS SSO ユーザー用の IAM ロールがある AWS アカウント ID を指定 なし - なし なし
25 sso_region AWS SSO ポータルホストを含む AWS リージョンを指定 なし - なし なし
26 sso_role_name AWS SSO 用の IAM ロール名を指定 なし - なし なし
27 sso_start_url AWS SSO ユーザーポータルを指す URL を指定 なし - なし なし
28 sts_regional_endpoints AWS STS との通信に使用するサービスエンドポイントを指定 regional(v2),legacy(v1) AWS_STS_REGIONAL_ENDPOINTS なし
29 web_identity_token_file Web ID トークンファイルのパスを指定 なし AWS_WEB_IDENTITY_TOKEN_FILE なし
30 tcp_keepalive クライアントが TCP キープアライブバケットを使用するかどうかを指定 true なし なし

AWS CLI コンフィグ S3 カスタムコマンド設定

ここまで見てきたのは AWS CLI コンフィグのグローバル設定であり AWS サービスを問わず適用されます。S3 に限定して適用が可能な設定項目があるため、それを取り上げます。

設定項目は以下のようにs3の中でネストして使用します。

[profile development]
s3 =
  max_concurrent_requests = 20
  max_queue_size = 10000
  multipart_threshold = 64MB
  multipart_chunksize = 16MB
  max_bandwidth = 50MB/s
  use_accelerate_endpoint = true
  addressing_style = path

すべての項目はv1v2の両方で使用できます。

# 設定項目名 概要 デフォルト v1 v2
1 addressing_style パス形式か仮想ホスト形式かを指定 auto
2 payload_signing_enabled sigv4ペイロードをSHA256署名するかどうかを指定 false
3 use_dualstack_endpoint S3 デュアル IPv4 / IPv6エンドポイントを使用するかを指定 false
4 use_accelerate_endpoint アクセラレートエンドポイントを使用するかを指定 false
5 max_bandwidth S3との通信の最大帯域幅を指定 制限なし
6 max_concurrent_requests 同時リクエストの最大数を指定 10
7 max_queue_size タスクキュー内のタスクの最大数を指定 1000
8 multipart_chunksize マルチパート転送に使用するチャンクサイズを指定 8MB
9 multipart_threshold マルチパート転送を行うサイズのしきい値を指定 8MB

AWS CLI の環境変数

ここまで確認してきたコンフィグの設定項目に対応するものがない環境変数もあるため、ここで取り上げます。

環境変数名 概要 デフォルト v1 v2 コマンドラインオプション
AWS_CLI_FILE_ENCODING テキストファイルに使用されるエンコーディングを指定 ロケールに一致 - なし
AWS_CONFIG_FILE コンフィグファイルのパスを指定 ~/.aws/config なし
AWS_EC2_METADATA_DISABLED IMDSの使用を無効化するかどうかを指定 false なし
AWS_PROFILE AWS CLI プロファイルを指定 default --profile
AWS_SHARED_CREDENTIALS_FILE クレデンシャルファイルのパスを指定 ~/.aws/credentials なし

AWS CLI コマンドラインオプション

同じように、コンフィグ設定項目にも環境変数にも対応するものがないコマンドラインオプションがあるため、ここで取り上げます。

# オプション名 概要 デフォルト v1 v2
1 --cli-connect-timeout ソケット接続のタイムアウトを秒数で指定 なし
2 --cli-read-timeout ソケット読み取りのタイムアウトを秒数で指定 なし
3 --color カラー出力のサポートを指定 auto
4 --debug デバッグログの出力を指定 なし
5 --endpoint-url エンドポイントの URL を指定 なし
6 --no-paginate ページ遷移を無効化を指定 なし
7 --no-sign-request クレデンシャルファイルの読み込みを指定 なし
8 --query JMESPath query によるフィルタリングを指定 なし
10 --version AWS CLI のバージョンを表示 なし

終わりに

AWS CLI のコンフィグファイル、環境変数、コマンドラインオプションで指定できる内容をまとめてみました。

改めて見てみると設定項目の数がかなり多く、細かい部分まで設定変更ができることが分かりました。全部を使いこなす必要はありませんが、「こういう設定もできたな」ということを覚えておくと役に立つ時が来るかもしれません。

特に、 S3 まわりで転送のパフォーマンスが出ていない……という時のチューニングに思い出したりすると幸せになりそうです。

ご参考ください。

以上、 チバユキ (@batchicchi) がお送りしました。

参考