AWS Tools for PowerShellをProxy経由で使う場合の注意事項

しばたです。

同僚からの質問を受けた際に気が付いたのですが、Proxy経由でAWS Tools for PowerShellを使う際に気を付けるべきポイントがあるので本記事で注意喚起します。

Set-AWSProxy コマンドレット

AWS Tools for PowerShellをProxy環境下で利用する際はSet-AWSProxyコマンドレットを使いAWS Tools for PowerShell専用のプロキシ設定を指定・保存する必要があります。

このコマンドレットで設定した内容は$AWSProxyグローバル変数に保存され各種コマンドレットの実行時に参照されます。
$AWSProxyグローバル変数は永続保存されないため、PowerShellコンソールを起動しなおす都度Set-AWSProxyコマンドの実行が必要になります。

Set-AWSProxy コマンドレットのドキュメントは間違っている

Set-AWSProxyコマンドは基本的に-Hostname, -PortパラメーターでProxyサーバーの指定を行い、-BypassListや-BypassOnLocalパラメーターで除外設定を行います。
Proxyサーバー指定でよくあるパターンなので使うべきパラメーター自体は直感的に理解できると思います。

ただ、このうち-BypassListに関してはドキュメントに記載されている記述が思いっきり間違っており、PowerShellに慣れてない方だと誤解したまま利用してしまう可能性が高いです。 ^*1

この記述間違いがかなり凶悪なのでこれから解説していきます。

まちがい

間違っているのはドキュメント中のExample 4とExample 7になります。

まずはExample 4ですが、この-BypassListの書き方は完全に間違っており意図した挙動になりません。

Example 4 (誤った記述)

# Example 4 : この-BypassListの書き方は完全に間違っており、意図した挙動にならない
Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList 169.254.169.250;169.254.169.251;169.254.169.254

-BypassListの型はstring[]であり除外対象のIPアドレスおよびFQDNを配列の形で渡してやる必要があります。
PowerShellで配列を表現するのはカンマ(,)でありセミコロン(;)ではありません。

セミコロンは文の区切り文字のため、上記例は3つの文として解釈されてしまいます。

Example 4 (誤った記述)

# セミコロンで区切ると3つの文として解釈される
Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList 169.254.169.250; # 文1
169.254.169.251; # 文2 : 何も出力しない
169.254.169.254  # 文3 : 何も出力しない

そしてPowerShellにおいてクオート無しでIPv4アドレスを記述すると文字列ではなく(オブジェクトのプロパティを探索する)ScriptBlockとして解釈される場合があります。
このためコマンドを実行してもエラーとはならず最初のIPアドレス169.254.169.250だけがBypassListに設定される結果となります。

Example 4 (誤った記述)

# コマンドを実行してもエラーにはならない
PS C:\> Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList 169.254.169.250;169.254.169.251;169.254.169.254
# ただし、169.254.169.250 より後ろは別の文として解釈されるため BypassList の値が意図したものにならない
PS C:\> $AWSProxy

Hostname      : https://proxy.testserver.com
Port          : 80
Credentials   :
BypassList    : {169.254.169.250}
BypassOnLocal :

ちなみにSet-StrictModeコマンドを使い厳密モードにしてやればエラーを検知できます。

Example 4 (誤った記述)

# 厳密モードを指定してやればエラーを検知可能 : 以下はPowerShell 7環境での実行例
PS C:\> Set-StrictMode -Version Latest
PS C:\> Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList 169.254.169.250;169.254.169.251;169.254.169.254
PropertyNotFoundException: The property '169.251' cannot be found on this object. Verify that the property exists.
PropertyNotFoundException: The property '169.254' cannot be found on this object. Verify that the property exists.

Example 7の例も同様の結果となります。

Example 7 (誤った記述)

# この例も -BypassList をセミコロンで区切っているため意図した結果にならない
Set-AWSProxy -Port 8888 -Hostname 127.0.0.1 -BypassList "127.0.0.1";"ip-ranges.amazonaws.com"

実行結果はこんな感じ。

Example 7 (誤った記述)

# ip-ranges.amazonaws.com は文字列の出力と解釈され実行される
PS C:\> Set-AWSProxy -Port 8888 -Hostname 127.0.0.1 -BypassList "127.0.0.1";"ip-ranges.amazonaws.com"
ip-ranges.amazonaws.com

# BypassListに登録されるのは 127.0.0.1 だけ
PS C:\> $AWSProxy

Hostname      : 127.0.0.1
Port          : 8888
Credentials   :
BypassList    : {127.0.0.1}
BypassOnLocal :

せいかい

ここまでの説明で何が間違っているか理解できたと思います。
正しくは、

• 配列の引数はカンマ区切りに
• IPアドレスはクオートで囲うほうが安全

となるため、それぞれの以下の指定が正解となります。

正しい記述

#
# -BypassList はカンマ区切りで！ IPアドレスはクオートで囲む！
#

# 正しい Example 4
Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList "169.254.169.250", "169.254.169.251", "169.254.169.254"

# 正しい Example 7
Set-AWSProxy -Port 8888 -Hostname 127.0.0.1 -BypassList "127.0.0.1", "ip-ranges.amazonaws.com"

実行結果もこの様に意図した通りの結果です。

正しい記述

# 正しい Example 4
PS C:\> Set-AWSProxy -Hostname https://proxy.testserver.com -Port 80 -BypassList "169.254.169.250", "169.254.169.251", "169.254.169.254"
PS C:\> $AWSProxy

Hostname      : https://proxy.testserver.com
Port          : 80
Credentials   :
BypassList    : {169.254.169.250, 169.254.169.251, 169.254.169.254}
BypassOnLocal :

# 正しい Example 7
PS C:\> Set-AWSProxy -Port 8888 -Hostname 127.0.0.1 -BypassList "127.0.0.1", "ip-ranges.amazonaws.com"
PS C:\> $AWSProxy

Hostname      : 127.0.0.1
Port          : 8888
Credentials   :
BypassList    : {127.0.0.1, ip-ranges.amazonaws.com}
BypassOnLocal :

余談1 : HTTP ProxyとSOCKS Proxy

こちらは余談ですが、現状AWS Tools for PowerShellはHTTP ProxyのみサポートしておりSOCKS Proxyはサポート外なのでご注意ください。
なおAWS CLIも同様の制限があります。

余談2 : Clear-AWSProxy コマンドレット

設定ずみのProxy設定をクリアしたい場合はClear-AWSProxyを使います。
このコマンドレットを使うことにより設定済みの$AWSProxyグローバル変数を削除しProxy設定を無くします。

終わりに

以上となります。

今回のは流石に看過できない間違いだったのでGitHubにIssueを立てておきました。

なのでいずれ間違いは解消されると思います。
Set-AWSProxyコマンドをお使いの方は改めて設定内容を見直すと良いかもしれませんね。

脚注