ユーザーデータ と Systems Manager を利用して CloudWatch エージェントを自動セットアップしてみた
こんにちは。テクニカルサポートチームのShiinaです。
はじめに
EC2 のユーザーデータを使用するとインスタンス起動時に特定のスクリプトを実行したり、設定を適用したりすることができます。
スクリプトを書いてパッケージのインストールも行うことができますが、Systems Manager の Systems Manager ドキュメントを実行することもできます。
今回はユーザーデータを使用して、Systems Manager の Run Command を実行し、CloudWatch エージェントのインストールと設定までを自動で実施してみました。
本記事では必要な設定と Linux、Windows インスタンス用のユーザーデータサンプルをご紹介します。
前提
・Systems Manager エージェント (SSM Agent) がインストールされている AMI を使用していること
・Linux の場合は AWS CLI がインストールされている AMI を使用していること
・Windows の場合は AWS Tools for Windows PowerShell がインストールされている AMI を使用していること
・Systems Manager エージェント (SSM Agent) が必要なサービスに通信できること
使用する Systems Manager ドキュメント
Systems Manager ドキュメントを使用して CloudWatch エージェントのインストールと設定の自動化を行います。
使用する Systems Manager ドキュメントは次の通りです。
- AWS-ConfigureAWSPackage
最新の CloudWatch エージェントのインストールを行います。 - AmazonCloudWatch-ManageAgent
パラメータストアに登録された CloudWatch 設定ファイルを使用して CloudWatch の設定を行います。
設定手順
1.パラメータストア登録
要件に沿ったメトリクスやログの収集を行う CloudWatch 設定パラメータをあらかじめ用意しておきます。
用意した CloudWatch 設定ファイルは Systems Manager パラメータストアのパラメータとして登録します。
今回使用したパラメータは次の通りです。
- パラメータ名:AmazonCloudWatch-linux
{
"agent": {
"metrics_collection_interval": 60,
"run_as_user": "cwagent"
},
"metrics": {
"aggregation_dimensions": [
[
"InstanceId"
]
],
"append_dimensions": {
"AutoScalingGroupName": "${aws:AutoScalingGroupName}",
"ImageId": "${aws:ImageId}",
"InstanceId": "${aws:InstanceId}",
"InstanceType": "${aws:InstanceType}"
},
"metrics_collected": {
"disk": {
"measurement": [
"used_percent"
],
"metrics_collection_interval": 60,
"resources": [
"*"
]
},
"mem": {
"measurement": [
"mem_used_percent"
],
"metrics_collection_interval": 60
}
}
}
}
- パラメータ名:AmazonCloudWatch-windows
{
"metrics": {
"aggregation_dimensions": [
[
"InstanceId"
]
],
"append_dimensions": {
"AutoScalingGroupName": "${aws:AutoScalingGroupName}",
"ImageId": "${aws:ImageId}",
"InstanceId": "${aws:InstanceId}",
"InstanceType": "${aws:InstanceType}"
},
"metrics_collected": {
"LogicalDisk": {
"measurement": [
"% Free Space"
],
"metrics_collection_interval": 60,
"resources": [
"*"
]
},
"Memory": {
"measurement": [
"% Committed Bytes In Use"
],
"metrics_collection_interval": 60
}
}
}
}
2.IAM ロールポリシー設定
EC2 のインスタンスロールに Systems Manager と CloudWatch に必要なアクションを許可するマネージドポリシーを設定します。
・AmazonSSMManagedInstanceCore
・CloudWatchAgentServerPolicy
Run Command の実行に必要なアクションと実行状況を取得するために必要なアクションを許可するポリシーをインラインポリシーで設定します。
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:ListCommandInvocations",
"ssm:GetCommandInvocation"
],
"Resource": "*"
}
]
}
ユーザーデータ
Linux インスタンス用
-
処理の概要
・インスタンスメタデータからインスタンス ID を取得します。
・AWS CLI の send-command コマンドを利用して AWS-ConfigureAWSPackage ドキュメントを呼び出し、CloudWatch エージェントのインストールを行います。
・上記の処理が完了するまで待機します。
・AWS CLI の send-command コマンドを利用して AmazonCloudWatch-ManageAgent ドキュメントを呼び出し、CloudWatch エージェントの設定を行います。 -
サンプルコード
#!/bin/bash
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
INSTANCE_ID=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id)
INSTALL_COMMAND_ID=$(aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--targets "[{\"Key\":\"InstanceIds\",\"Values\":[\"$INSTANCE_ID\"]}]" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["AmazonCloudWatchAgent"],"version":["latest"],"additionalArguments":["{}"]}' \
--region ap-northeast-1 \
--query "Command.CommandId" \
--output text)
while true; do
STATUS=$(aws ssm list-command-invocations \
--command-id "$INSTALL_COMMAND_ID" \
--details \
--query "CommandInvocations[0].Status" \
--output text \
--region ap-northeast-1)
if [[ "$STATUS" == "Success" ]]; then
break
elif [[ "$STATUS" == "Failed" || "$STATUS" == "Cancelled" ]]; then
exit 1
else
sleep 10
fi
done
aws ssm send-command \
--document-name "AmazonCloudWatch-ManageAgent" \
--targets "[{\"Key\":\"InstanceIds\",\"Values\":[\"$INSTANCE_ID\"]}]" \
--parameters '{"action":["configure"],"mode":["ec2"],"optionalConfigurationSource":["ssm"],"optionalConfigurationLocation":["AmazonCloudWatch-linux"],"optionalRestart":["yes"]}' \
--region ap-northeast-1
Windows インスタンス用
-
処理の概要
・Systems Manager エージェント (SSM Agent) サービスの有効化と起動を行います。
・上記の処理が完了するまで待機します。
・インスタンスメタデータからインスタンス ID を取得します。
・AWS Tools for Windows PowerShell の Send-SSMCommand コマンドを利用して 「AWS-ConfigureAWSPackage」 ドキュメントを呼び出し、CloudWatch エージェントのインストールを行います。
・上記の処理が完了するまで待機します。
・AWS Tools for Windows PowerShell の Send-SSMCommand コマンドを利用して 「AmazonCloudWatch-ManageAgent」 ドキュメントを呼び出し、CloudWatch エージェントの設定を行います。 -
サンプルコード
<powershell>
Set-Service -Name AmazonSSMAgent -StartupType Automatic
Start-Service AmazonSSMAgent
while ((Get-Service -Name AmazonSSMAgent).Status -ne 'Running') {
Start-Sleep -Seconds 5
}
$token = Invoke-RestMethod -Method PUT -Uri "http://169.254.169.254/latest/api/token" -Headers @{"X-aws-ec2-metadata-token-ttl-seconds"="21600"}
$instanceId = Invoke-RestMethod -Method GET -Uri "http://169.254.169.254/latest/meta-data/instance-id" -Headers @{"X-aws-ec2-metadata-token"=$token}
$installCommand = Send-SSMCommand `
-DocumentName "AWS-ConfigureAWSPackage" `
-Targets @(@{Key="InstanceIds"; Values=@($instanceId)}) `
-Parameters @{
action=@("Install");
installationType=@("Uninstall and reinstall");
version=@("latest");
additionalArguments=@("{}");
name=@("AmazonCloudWatchAgent")
} `
-Region "ap-northeast-1"
$installCommandId = $installCommand.CommandId
while ($true) {
Start-Sleep -Seconds 10
$status = (Get-SSMCommandInvocation -CommandId $installCommandId -InstanceId $instanceId -Region "ap-northeast-1").Status
if ($status -eq "Success") {
break
} elseif ($status -eq "Failed" -or $status -eq "Cancelled") {
exit 1
}
}
Send-SSMCommand `
-DocumentName "AmazonCloudWatch-ManageAgent" `
-Targets @(@{Key="InstanceIds"; Values=@($instanceId)}) `
-Parameters @{
action=@("configure");
mode=@("ec2");
optionalConfigurationSource=@("ssm");
optionalConfigurationLocation=@("AmazonCloudWatch-windows");
optionalRestart=@("yes")
} `
-Region "ap-northeast-1"
</powershell>
やってみた
1.インスタンスの起動
Amazon Linux 2023、Windows Server 2025 の AMI を利用してユーザーデータを指定してインスタンスの起動を行ってみます。
-
Amazon Linux 2023
-
Windows Server 2025
2.RunCommand 実行結果の確認
ユーザーデータにより Run Command が実行されたことを確認します。
Systems Manager コンソールのナビゲーションペインより [Run Command] を選択します。
[コマンド履歴]タブを選択します。
インスタンス起動時に実行されたドキュメント 「AWS-ConfigureAWSPackage」 と 「AmazonCloudWatch-ManageAgent」 が成功していることが確認できました。
3.サービスの確認
インスタンスに接続して、インストールを行なった CloudWatch エージェントが動作しているか確認を行います。
- Linux
amazon-cloudwatch-agent サービスのステータスを確認します。
systemctl status amazon-cloudwatch-agent.service
● amazon-cloudwatch-agent.service - Amazon CloudWatch Agent
Loaded: loaded (/etc/systemd/system/amazon-cloudwatch-agent.service; enabled; preset: disabled)
Active: active (running) since Sun 2025-02-02 06:27:33 UTC; 57s ago
Main PID: 2440 (amazon-cloudwat)
Tasks: 6 (limit: 1111)
Memory: 22.5M
CPU: 275ms
CGroup: /system.slice/amazon-cloudwatch-agent.service
└─2440 /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent -config /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.toml -envconfig /opt/aws/amazon-cloudw>
active (running) 状態となっていることが確認できました。
- Windows
AmazonCloudWatchAgent サービスのステータスを確認します。
PS C:\Windows\system32> Get-Service -Name AmazonCloudWatchAgent
Status Name DisplayName
------ ---- -----------
Running AmazonCloudWatc... Amazon CloudWatch Agent
Running 状態となっていることが確認できました。
4.メトリクスの確認
CloudWatch 設定パラメータが反映され、必要なメトリクスの収集が行われていることを確認します。
EC2 コンソールのナビゲーションペインより [インスタンス] を選択します。
インスタンス一覧より該当のインスタンス ID を選択します。
メトリクスタブを選択します。
-
Linux
disk_used_percent、mem_used_percent のメトリクスが記録されていることが確認できました。
-
Windows
LogicalDisk、Memory のメトリクスが記録されていることが確認できました。
まとめ
EC2 のユーザーデータを活用して Systems Manager の RunCommand を用いた CloudWatch エージェントのインストールと設定を自動化する方法を紹介しました。
RunCommand 以外にもパッケージのインストールや設定の処理をまとめた SSM オートメーションランブックの自動実行などにも応用可能です。
AWS 提供の Systems Manager ドキュメントを利用できるため、信頼性が高く、標準化された実行環境で一貫した運用管理が可能になるメリットもあります。
呼び出す処理を記述すれば良いため、独自でスクリプト作成やデバッグを行う手間が省けます。
本記事が誰かのお役に立てれば幸いです。
参考