切り分けの順番
つながらないときは、ローカル側から順に確認すると早い。エラーメッセージがどの段階で出ているかで、原因の範囲を絞り込める。
エラー別の対処法
| エラー・症状 | 主な原因 | 対処 |
|---|---|---|
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 RemotePort | EICE で 22 / 3389 以外のポートを指定した | SSH -L と組み合わせるか、SSM に切り替える(PART 03) |
bind [127.0.0.1]:15432: Address already in use など | ローカルのポートが他のプロセスに使われている | 別のローカルポートを使うか、使用中のプロセスを止める(次の節) |
ローカルポートの競合を調べる
ローカルにDBを入れている、前回のトンネルが残っている、といった理由でポートが使用中のことは多い。どのプロセスが使っているかは次のように調べる。
Get-NetTCPConnection -LocalPort 15432 -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess
Get-Process -Id <上で表示された OwningProcess>
# コマンドプロンプトの場合
netstat -ano | findstr :15432lsof -nP -iTCP:15432 -sTCP:LISTEN残っているのが session-manager-plugin や ssh のプロセスなら、前回のトンネルの消し忘れだ。
接続が途中で切れる
| 方式 | 切れる原因 | 対処 |
|---|---|---|
| SSM | Session 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 イベントとして残る。
aws cloudtrail lookup-events \
--lookup-attributes AttributeKey=EventName,AttributeValue=StartSession \
--max-results 20 \
--query "Events[].[EventTime,Username]" --output tableSQLの操作履歴まで残したい場合は、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 Endpoint | PART 03 |
| scp・Remote-SSH・複数ポート転送も使いたい | SSH over SSM | PART 04 |
| 既存の踏み台を当面使い続ける | SSH踏み台(22番は送信元IPを限定) | PART 04 |
迷ったら、まずSSMで組んでみるのがおすすめだ。ポートを開けず、キーを配らず、IAMで権限を管理できる構成は、後からセキュリティ要件が厳しくなっても作り直さずに済む。