切り分けの順番

つながらないときは、ローカル側から順に確認すると早い。エラーメッセージがどの段階で出ているかで、原因の範囲を絞り込める。

① ローカル:AWS CLI とプラグインは動くか?
 └─ aws sts get-caller-identity / session-manager-plugin
② IAM:自分に StartSession の権限があるか?
 └─ AccessDeniedException が出ていないか
③ エージェント:EC2はSSMに Online で登録されているか?
 └─ aws ssm describe-instance-information
④ トンネル:Waiting for connections... まで出るか?
⑤ 転送先:Connection accepted の後にDB接続がタイムアウトしないか?
 └─ 転送先のSG・NACL・名前解決を確認

エラー別の対処法

エラー・症状主な原因対処
SessionManagerPlugin is not found. Please refer to SessionManager Documentation here: ...Session Manager プラグインが未インストール、またはPATHが通っていないプラグインをインストールし、ターミナル(VS Code の場合はVS Code自体)を再起動する
An error occurred (TargetNotConnected) when calling the StartSession operation: i-xxxx is not connected.EC2がSSMに登録されていない(エージェント停止・IAMロールなし・SSMへの経路なし)、またはEC2が停止中EC2の状態、IAMロール(AmazonSSMManagedInstanceCore)、NAT Gateway またはVPCエンドポイント(SG・プライベートDNS含む)を確認。ロールを付けた直後は登録まで数分待つ
AccessDeniedException ... is not authorized to perform: ssm:StartSession接続するユーザーのIAMポリシーで、インスタンスまたはSSMドキュメントが許可されていないポリシーの Resource に、使うドキュメント(AWS-StartPortForwardingSessionToRemoteHost など)のARNが含まれているか確認
Error parsing parameter '--parameters'PowerShell で bash 向けの JSON をそのまま使っている"host=...,portNumber=5432,localPortNumber=15432" の短縮構文にする
Connection accepted は出るが、DBクライアントがタイムアウトする中継EC2から転送先へ届いていない(RDSのSG、NACL、ホスト名の誤り)RDSのSGで中継EC2のSGからのポートを許可。EC2にシェルで入れるなら nc -zv <RDSのエンドポイント> 5432 で疎通を確認
The specified RemotePort is not valid. Specify either 22 or 3389 as the RemotePortEICE で 22 / 3389 以外のポートを指定したSSH -L と組み合わせるか、SSM に切り替える(PART 03)
bind [127.0.0.1]:15432: Address already in use などローカルのポートが他のプロセスに使われている別のローカルポートを使うか、使用中のプロセスを止める(次の節)

ローカルポートの競合を調べる

ローカルにDBを入れている、前回のトンネルが残っている、といった理由でポートが使用中のことは多い。どのプロセスが使っているかは次のように調べる。

Windows(PowerShell)
Get-NetTCPConnection -LocalPort 15432 -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess
Get-Process -Id <上で表示された OwningProcess>

# コマンドプロンプトの場合
netstat -ano | findstr :15432
macOS / Linux
lsof -nP -iTCP:15432 -sTCP:LISTEN

残っているのが session-manager-plugin や ssh のプロセスなら、前回のトンネルの消し忘れだ。

接続が途中で切れる

方式切れる原因対処
SSMSession Manager の設定(アイドルタイムアウト・最大セッション時間)Systems Manager > Session Manager > 設定で、アイドルタイムアウト(1〜60分、既定20分)や最大セッション時間を見直す。DBクライアント側のキープアライブも有効にする
EICE最大接続時間(1時間)、またはIAMの maxTunnelDuration延長はできないため、再接続を前提にするか SSM に切り替える
SSH途中のNATやファイアウォールが無通信の接続を切るServerAliveInterval 60 を設定する

⚠️ 長時間のバッチや移行作業をトンネル経由で実行しない

トンネルが切れると処理が中途半端に止まる。数時間かかるデータ移行やダンプは、中継EC2上で tmux などを使って実行するか、ECSタスク・Step Functions などAWS内で完結させる。

誰が接続したかを監査する

SSMのポートフォワードは、セッションの中身(どんなSQLを流したか)は記録されない。記録されるのは「誰が・いつ・どのインスタンスに・どのドキュメントで」接続したかで、CloudTrail の StartSession イベントとして残る。

直近のStartSessionを確認
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=StartSession \
  --max-results 20 \
  --query "Events[].[EventTime,Username]" --output table

SQLの操作履歴まで残したい場合は、DB側の監査機能(RDS for PostgreSQL の pgaudit、MySQL の監査ログなど)を有効にする。EICEの場合は CloudTrail に OpenTunnel イベントが記録される。

チーム運用のTips

  • ローカルポートの割り当てを決めておく:環境ごとに「dev は 15432、stg は 25432」のように決めておくと、接続先の取り違えを防げる
  • 接続スクリプトをリポジトリで共有する:PART 02 のようなスクリプトをインフラのリポジトリに置き、手順書の代わりにする
  • IAMは「ポートフォワード専用」の権限を作る:AWS-StartSSHSession や SSM-SessionManagerRunShell(シェル)を許可せず、ポートフォワード用のドキュメントだけを許可する
  • 本番環境は時間を限って許可する:IAM Identity Center の許可セットを申請制にする、セッション時間を短くするなど、本番DBへの常時接続を避ける
  • 中継EC2は使うときだけ起動する:スクリプトの先頭で aws ec2 start-instances を実行し、終わったら停止する運用にするとコストを抑えられる

チェックリスト

  • ローカルに AWS CLI v2 と Session Manager プラグインが入っている
  • 中継EC2に AmazonSSMManagedInstanceCore 付きのIAMロールがある
  • 中継EC2からSSMへの経路(NAT Gateway または VPCエンドポイント)がある
  • describe-instance-information で PingStatus が Online
  • 接続するユーザーに、必要なSSMドキュメントだけの ssm:StartSession を許可している
  • 転送先(RDSなど)のSGで、中継EC2のSGからのポートを許可している
  • 中継EC2のSGのインバウンドは空(22番を開けていない)
  • ローカルポートの割り当てをチームで決めている
  • CloudTrail で StartSession を確認できる

シリーズのまとめ

やりたいこと方式記事
RDS・ElastiCache などへ転送したいSSM(リモートホスト転送)PART 02
エージェントを入れられないEC2へSSH / RDPしたいEC2 Instance Connect EndpointPART 03
scp・Remote-SSH・複数ポート転送も使いたいSSH over SSMPART 04
既存の踏み台を当面使い続けるSSH踏み台(22番は送信元IPを限定)PART 04

迷ったら、まずSSMで組んでみるのがおすすめだ。ポートを開けず、キーを配らず、IAMで権限を管理できる構成は、後からセキュリティ要件が厳しくなっても作り直さずに済む。

関連記事:ネットワークの選び方 — ALB / NLB / VPC / Direct Connect