AWS Systems ManagerのSession ManagerでSSHなしにEC2を管理する方法｜Run Command・Parameter Storeの実践設計

この記事のポイント

・aws ssm start-session でSSHなし・鍵なしでプライベートサブネットのEC2に接続できる
・IAMロール（AmazonSSMManagedInstanceCore）のアタッチが唯一の前提条件
・Run Commandでタグ指定した複数EC2へ同時コマンドを実行できる
・Parameter Storeは無料で設定値管理向け、Secrets Managerはパスワード自動ローテーションが必要な場合に使い分ける

# Step 1: IAMロールを作成（EC2がSSMを呼び出せる信頼ポリシー）
aws iam create-role \
  --role-name EC2-SSMRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# Step 2: AWS管理ポリシー「AmazonSSMManagedInstanceCore」をアタッチ
aws iam attach-role-policy \
  --role-name EC2-SSMRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

# Step 3: EC2インスタンスプロファイルを作成してロールを紐づける
aws iam create-instance-profile \
  --instance-profile-name EC2-SSMProfile
aws iam add-role-to-instance-profile \
  --instance-profile-name EC2-SSMProfile \
  --role-name EC2-SSMRole

# Step 4: 既存EC2にインスタンスプロファイルをアタッチ
aws ec2 associate-iam-instance-profile \
  --instance-id i-0a1b2c3d4e5f67890 \
  --iam-instance-profile Name=EC2-SSMProfile

# SSM Agentの起動状態を確認
sudo systemctl status amazon-ssm-agent

# 出力例（正常動作時）
# amazon-ssm-agent.service - amazon-ssm-agent
#      Loaded: loaded (/lib/systemd/system/amazon-ssm-agent.service; enabled)
#      Active: active (running) since Tue 2026-07-07 10:23:15 UTC; 2h 14min ago
#     Main PID: 1247 (amazon-ssm-agen)

# インストールされていない場合（Amazon Linux 2023）
sudo dnf install -y amazon-ssm-agent
sudo systemctl enable amazon-ssm-agent --now

# SSM用VPCエンドポイントを3つ作成（ap-northeast-1の例）
for svc in ssm ssmmessages ec2messages; do
  aws ec2 create-vpc-endpoint \
    --vpc-id vpc-0abc1234 \
    --service-name com.amazonaws.ap-northeast-1.${svc} \
    --vpc-endpoint-type Interface \
    --subnet-ids subnet-0def5678 subnet-0ghi9012 \
    --security-group-ids sg-0ssm1234 \
    --private-dns-enabled
  echo "Created: ${svc}"
done

# 出力例
# Created: ssm
# Created: ssmmessages
# Created: ec2messages

# Linux（Amazon Linux 2023 / RHEL9 / AlmaLinux 9）
sudo dnf install -y \
  https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm

# macOS（Homebrewを使う場合）
brew install --cask session-manager-plugin

# インストール確認
session-manager-plugin --version
# 1.2.650.0

# 接続先のEC2インスタンスIDをタグ名で確認
aws ec2 describe-instances \
  --filters "Name=tag:Name,Values=web-server-prod" \
  --query 'Reservations[*].Instances[*].{ID:InstanceId,State:State.Name}' \
  --output table

# 出力例
# ------------------------------------------
# |       DescribeInstances                |
# +---------------------+------------------+
# |  ID                 |  State           |
# +---------------------+------------------+
# | i-0a1b2c3d4e5f67890 |  running         |
# +---------------------+------------------+

# Session Managerで接続（SSH不要・鍵不要）
aws ssm start-session --target i-0a1b2c3d4e5f67890

# 接続後のプロンプト（シェルが起動する）
# Starting session with SessionId: tomohiro.miyazaki-0a1b2c3d4e5f67890
# sh-5.2$ whoami
# ssm-user
# sh-5.2$ sudo su -
# [root@ip-10-0-1-42 ~]# hostname
# ip-10-0-1-42.ap-northeast-1.compute.internal

# CloudWatch Logsのロググループを作成
aws logs create-log-group \
  --log-group-name /ssm/session-manager

# セッション設定を更新（ログ出力を有効化）
aws ssm update-document \
  --name SSM-SessionManagerRunShell \
  --document-version "\$LATEST" \
  --content '{
    "schemaVersion": "1.0",
    "sessionType": "Standard_Stream",
    "inputs": {
      "cloudWatchLogGroupName": "/ssm/session-manager",
      "cloudWatchEncryptionEnabled": false,
      "idleSessionTimeout": "20"
    }
  }'

# セッション終了後にログを確認
aws logs get-log-events \
  --log-group-name /ssm/session-manager \
  --log-stream-name i-0a1b2c3d4e5f67890 \
  --query 'events[].message' \
  --output text | head -30

# ポートフォワード（自分のPCの13306番→EC2経由でRDS 3306番）
# EC2はトンネルの中継役になる（EC2自体にはSSHしない）
aws ssm start-session \
  --target i-0a1b2c3d4e5f67890 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{
    "host":["mydb.xxxxxxxxxxxx.ap-northeast-1.rds.amazonaws.com"],
    "portNumber":["3306"],
    "localPortNumber":["13306"]
  }'

# 上記コマンド実行中に別ターミナルからRDSへ接続
mysql -h 127.0.0.1 -P 13306 -u admin -p

# Redis（ElastiCache）へのポートフォワード例
aws ssm start-session \
  --target i-0a1b2c3d4e5f67890 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{
    "host":["my-redis.xxxxxx.0001.apne1.cache.amazonaws.com"],
    "portNumber":["6379"],
    "localPortNumber":["16379"]
  }'

# AWS-RunShellScriptドキュメントを使って単一EC2でコマンド実行
aws ssm send-command \
  --instance-ids i-0a1b2c3d4e5f67890 \
  --document-name "AWS-RunShellScript" \
  --parameters '{"commands":["df -h","systemctl status nginx | head -10"]}' \
  --comment "ディスク確認とnginxステータス"

# 出力例（コマンドIDが返る）
# {
#   "Command": {
#     "CommandId": "ab12cd34-ef56-7890-gh12-ij3456klmnop",
#     "DocumentName": "AWS-RunShellScript",
#     "Status": "Pending"
#   }
# }

# 実行結果を取得
aws ssm get-command-invocation \
  --command-id "ab12cd34-ef56-7890-gh12-ij3456klmnop" \
  --instance-id i-0a1b2c3d4e5f67890 \
  --query '{Status:Status,Output:StandardOutputContent}'

# tag:Environment=production の全EC2にセキュリティアップデートを一括適用
aws ssm send-command \
  --targets 'Key=tag:Environment,Values=production' \
  --document-name "AWS-RunShellScript" \
  --parameters '{"commands":["sudo dnf update -y --security"]}' \
  --comment "セキュリティアップデート一括適用" \
  --timeout-seconds 600

# 全対象インスタンスの実行状況を一覧表示
aws ssm list-command-invocations \
  --command-id "ab12cd34-ef56-7890-gh12-ij3456klmnop" \
  --details \
  --query 'CommandInvocations[*].{ID:InstanceId,Status:Status}' \
  --output table

# 出力例（3台のEC2に実行した場合）
# -------------------------------------------
# |       ListCommandInvocations            |
# +---------------------+-------------------+
# |  ID                 |  Status           |
# +---------------------+-------------------+
# | i-0a1b2c3d4e5f67890 |  Success          |
# | i-0b2c3d4e5f678901  |  Success          |
# | i-0c3d4e5f6789012   |  Success          |
# +---------------------+-------------------+

# 実行ログをS3に保存（長時間のパッチ適用ログ管理に便利）
aws ssm send-command \
  --targets 'Key=tag:Environment,Values=production' \
  --document-name "AWS-RunShellScript" \
  --parameters '{"commands":["sudo dnf update -y"]}' \
  --output-s3-bucket-name "my-ssm-logs-bucket" \
  --output-s3-key-prefix "run-command/$(date +%Y%m%d)" \
  --comment "本番環境フルアップデート"

# S3に保存されたログを確認
aws s3 ls s3://my-ssm-logs-bucket/run-command/ --recursive

# 推奨の命名規則（/{環境}/{アプリ名}/{パラメータ名}）
/prod/api-server/db-password
/prod/api-server/db-endpoint
/prod/api-server/stripe-secret-key
/staging/api-server/db-password

# パスに階層をつけることで、アプリ単位・環境単位でまとめて取得できる

# SecureString型でパラメータを登録（KMSで自動暗号化される）
aws ssm put-parameter \
  --name "/prod/api-server/db-password" \
  --value "P@ssw0rd!Secure2026" \
  --type SecureString \
  --description "本番DBの接続パスワード"

# パスワードを復号して取得（--with-decryptionが必要）
aws ssm get-parameter \
  --name "/prod/api-server/db-password" \
  --with-decryption \
  --query 'Parameter.Value' \
  --output text

# 出力例
# P@ssw0rd!Secure2026

# 階層パス配下のパラメータを一覧表示
aws ssm get-parameters-by-path \
  --path "/prod/api-server/" \
  --recursive \
  --query 'Parameters[*].{Name:Name,Type:Type}' \
  --output table

# 出力例
# ----------------------------------------------------------
# |              GetParametersByPath                       |
# +-------------------------------------+-----------------+
# |  Name                               |  Type           |
# +-------------------------------------+-----------------+
# | /prod/api-server/db-endpoint        |  String         |
# | /prod/api-server/db-password        |  SecureString   |
# | /prod/api-server/stripe-secret-key  |  SecureString   |
# +-------------------------------------+-----------------+

# EC2インスタンス用IAMポリシー（パスで権限を絞る例）
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:GetParametersByPath"
      ],
      "Resource": "arn:aws:ssm:ap-northeast-1:123456789012:parameter/prod/api-server/*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:ap-northeast-1:123456789012:key/your-kms-key-id"
    }
  ]
}

#!/bin/bash
# アプリ起動スクリプト（Parameter Storeから秘密情報を取得する例）

DB_PASS=$(aws ssm get-parameter \
  --name "/prod/api-server/db-password" \
  --with-decryption \
  --query 'Parameter.Value' \
  --output text \
  --region ap-northeast-1)

DB_HOST=$(aws ssm get-parameter \
  --name "/prod/api-server/db-endpoint" \
  --query 'Parameter.Value' \
  --output text \
  --region ap-northeast-1)

# 取得した値を環境変数にセットしてアプリを起動
export DATABASE_PASSWORD="${DB_PASS}"
export DATABASE_HOST="${DB_HOST}"
./myapp --config /etc/myapp/config.yaml

# EC2に紐付いているIAMロールを確認
aws ec2 describe-instances \
  --instance-ids i-0a1b2c3d4e5f67890 \
  --query 'Reservations[0].Instances[0].IamInstanceProfile.Arn'

# 出力例（設定済みの場合）
# "arn:aws:iam::123456789012:instance-profile/EC2-SSMProfile"

# IAMロールに必要なポリシーが付いているか確認
aws iam list-attached-role-policies \
  --role-name EC2-SSMRole \
  --query 'AttachedPolicies[*].PolicyName' \
  --output text

# 出力例（正常）
# AmazonSSMManagedInstanceCore

# EC2にSSH接続できる場合はAgentのログを確認
sudo journalctl -u amazon-ssm-agent -n 30 --no-pager

# 典型的なエラーと原因
# "Failed to load instance info from metadata"
# → EC2のIAMロールが設定されていない
# "No credential providers found"
# → IMDSv2のみ有効な環境でIAMロール未設定

# Agentを再起動して状態確認
sudo systemctl restart amazon-ssm-agent
sudo systemctl status amazon-ssm-agent

# マネジメントコンソール側でのインスタンス登録状態確認
aws ssm describe-instance-information \
  --query 'InstanceInformationList[*].{ID:InstanceId,Status:PingStatus,Agent:AgentVersion}' \
  --output table

# 出力例（正常登録済み）
# ---------------------------------------------------------
# |      DescribeInstanceInformation                      |
# +---------------------+---------+---------------------+
# |  ID                 | Agent   | Status              |
# +---------------------+---------+---------------------+
# | i-0a1b2c3d4e5f67890 | 3.3.xxx | Online              |
# +---------------------+---------+---------------------+

# "Online"でなく一覧に表示されない場合はIAMロールかSSM Agentを確認する

# エンドポイントの作成状況を確認（3つ必要）
aws ec2 describe-vpc-endpoints \
  --filters "Name=vpc-id,Values=vpc-0abc1234" \
  --query 'VpcEndpoints[*].{Service:ServiceName,State:State,DNS:PrivateDnsEnabled}' \
  --output table

# 正常な出力例
# -----------------------------------------------------------------------
# |                      DescribeVpcEndpoints                           |
# +--------------------------------------------------+----------+------+
# |  Service                                         |  State   | DNS  |
# +--------------------------------------------------+----------+------+
# | com.amazonaws.ap-northeast-1.ssm                 | available| True |
# | com.amazonaws.ap-northeast-1.ssmmessages         | available| True |
# | com.amazonaws.ap-northeast-1.ec2messages         | available| True |
# +--------------------------------------------------+----------+------+

# EC2内からSSMエンドポイントの名前解決を確認（プライベートIPが返れば正常）
dig ssm.ap-northeast-1.amazonaws.com +short

# 正常な出力例（プライベートIPアドレスが返る）
# 10.0.1.45
# 10.0.2.67