AWS SSM Documentで冗長構成を自動化する方法｜複数AZへの統一手順適用

この記事のポイント

・SSM DocumentはEC2への手順をYAMLで定義し再利用できる「実行設計図」
・create-documentコマンドで登録しsend-commandで複数AZに一括適用できる
・ドキュメントのバージョン管理により手順変更を安全にロールバックできる
・タグフィルターにMaxConcurrencyを組み合わせて段階展開リスクを制御できる

# nginx-install.yaml --- カスタムDocument定義
schemaVersion: '2.2'
description: 'Install and enable Nginx on Amazon Linux 2023'
parameters:
  NginxPackage:
    type: String
    default: nginx
    description: Package name to install
    allowedValues:
      - nginx
mainSteps:
  - action: 'aws:runShellScript'
    name: installNginx
    inputs:
      runCommand:
        - 'dnf install -y {{ NginxPackage }}'
        - 'systemctl enable --now nginx'
        - 'systemctl status nginx --no-pager'
      timeoutSeconds: 120

# Documentを登録する
$ aws ssm create-document     --name "MyNginxInstall"     --document-type "Command"     --document-format "YAML"     --content file://nginx-install.yaml     --region ap-northeast-1

{
    "DocumentDescription": {
        "Hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
        "HashType": "Sha256",
        "Name": "MyNginxInstall",
        "Owner": "123456789012",
        "CreatedDate": "2026-10-10T09:00:00.000000+09:00",
        "Status": "Active",
        "DocumentVersion": "1",
        "DefaultVersion": "1",
        "DocumentType": "Command",
        "SchemaVersion": "2.2"
    }
}

# Documentの一覧確認
$ aws ssm list-documents     --filters '[{"Key":"Owner","Values":["Self"]}]'     --query 'DocumentIdentifiers[*].[Name,DocumentVersion,Status]'     --output table

-----------------------------------------------------
|               ListDocuments                       |
+---------------------+--------+------------------+
|  MyNginxInstall     |  1     |  Active          |
+---------------------+--------+------------------+

# Documentを新バージョンで更新する
$ aws ssm update-document     --name "MyNginxInstall"     --document-version "\$LATEST"     --document-format "YAML"     --content file://nginx-install-v2.yaml

# デフォルトバージョンをv2に切り替える
$ aws ssm update-document-default-version     --name "MyNginxInstall"     --document-version "2"

{
    "Description": {
        "Name": "MyNginxInstall",
        "DefaultVersion": "2"
    }
}

# タグ指定で複数AZのEC2に一括実行
$ aws ssm send-command     --document-name "MyNginxInstall"     --document-version "2"     --targets '[{"Key":"tag:Environment","Values":["production"]},{"Key":"tag:Role","Values":["webserver"]}]'     --parameters '{"NginxPackage":["nginx"]}'     --max-concurrency "50%"     --max-errors "1"     --output-s3-bucket-name "my-ssm-output-prod"     --output-s3-key-prefix "ssm-logs/"     --region ap-northeast-1

{
    "Command": {
        "CommandId": "abc12345-1234-1234-1234-abc123456789",
        "DocumentName": "MyNginxInstall",
        "DocumentVersion": "2",
        "Status": "Pending",
        "TargetCount": 6,
        "CompletedCount": 0,
        "MaxConcurrency": "50%",
        "MaxErrors": "1"
    }
}

# インスタンス単位の実行結果を確認する
$ aws ssm list-command-invocations     --command-id "abc12345-1234-1234-1234-abc123456789"     --details     --query 'CommandInvocations[*].[InstanceId,StatusDetails,ResponseCode]'     --output table

-------------------------------------------------------------
|              ListCommandInvocations                       |
+---------------------+-----------+------------------------+
|  i-0abc123def456789 |  Success  |  0                    |
|  i-0def456abc789012 |  Success  |  0                    |
|  i-0ghi789def012345 |  Success  |  0                    |
|  i-0jkl012ghi345678 |  Success  |  0                    |
|  i-0mno345jkl678901 |  Success  |  0                    |
|  i-0pqr678mno901234 |  Success  |  0                    |
+---------------------+-----------+------------------------+

# 1台の詳細ログを確認する
$ aws ssm get-command-invocation     --command-id "abc12345-1234-1234-1234-abc123456789"     --instance-id "i-0abc123def456789"

{
    "Status": "Success",
    "StatusDetails": "Success",
    "StandardOutputContent": "Last metadata expiration check...
Nginx 1.24.0 installed
* nginx.service: active (running)"
}

# deploy-nginx-conf.yaml --- nginx.conf配信Document
schemaVersion: '2.2'
description: 'Deploy nginx.conf from S3 and reload Nginx'
parameters:
  S3Bucket:
    type: String
    description: 'S3 bucket where nginx.conf is stored'
  S3Key:
    type: String
    description: 'S3 key for nginx.conf'
    default: 'configs/nginx.conf'
mainSteps:
  - action: 'aws:runShellScript'
    name: backupCurrentConf
    inputs:
      runCommand:
        - 'cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%Y%m%d%H%M%S)'
  - action: 'aws:runShellScript'
    name: downloadNewConf
    inputs:
      runCommand:
        - 'aws s3 cp s3://{{ S3Bucket }}/{{ S3Key }} /etc/nginx/nginx.conf'
        - 'nginx -t && systemctl reload nginx'
        - 'echo "Deploy completed: $(hostname)"'
      timeoutSeconds: 60

# AZを問わず3AZ全時に配信実行
$ aws ssm send-command     --document-name "DeployNginxConf"     --document-version "\$DEFAULT"     --targets '[{"Key":"tag:Role","Values":["nginx-prod"]}]'     --parameters '{"S3Bucket":["my-config-bucket"],"S3Key":["configs/nginx-20261010.conf"]}'     --max-concurrency "4"     --max-errors "1"     --region ap-northeast-1

# 全台完了確認
$ aws ssm list-command-invocations     --command-id "xyz99999-9999-9999-9999-xyz999999999"     --query 'CommandInvocations[*].[InstanceId,StatusDetails]'     --output table     --region ap-northeast-1

# EC2インスタンス上で実行(まずSSHで確認)
$ sudo systemctl status amazon-ssm-agent
$ sudo systemctl restart amazon-ssm-agent

# SSMのオンラインインスタンス一覧でOnline状態確認
$ aws ssm describe-instance-information     --filters '[{"Key":"PingStatus","Values":["Online"]}]'     --query 'InstanceInformationList[*].[InstanceId,PlatformType,PingStatus,IPAddress]'     --output table

-----------------------------------------------------------
|          DescribeInstanceInformation                    |
+---------------------+-------+--------+----------------+
|  i-0abc123def456789 | Linux | Online | 10.0.1.45      |
|  i-0def456abc789012 | Linux | Online | 10.0.2.78      |
|  i-0ghi789def012345 | Linux | Online | 10.0.3.12      |
+---------------------+-------+--------+----------------+

# EC2上でSSMエンドポイントへの死活監視
$ curl -s -o /dev/null -w "%{http_code}"     https://ssm.ap-northeast-1.amazonaws.com/ping

200

# SSコマンドでアウトバウンド接続を確認
$ ss -tn | grep ':443'

ESTAB      0      0      10.0.1.45:54321      3.112.xxx.xxx:443

# 3つのSSMエンドポイントを作成する(各AZのサブネットへ)
for svc in ssm ssmmessages ec2messages; do
  aws ec2 create-vpc-endpoint     --vpc-id vpc-0abc123     --service-name com.amazonaws.ap-northeast-1.${svc}     --vpc-endpoint-type Interface     --subnet-ids subnet-0az1a subnet-0az1b subnet-0az1c     --security-group-ids sg-0ssm123     --private-dns-enabled     --region ap-northeast-1
done