本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 部署 CloudWatch 代理程式以收集 Amazon ECS 上的 EC2 執行個體層級指標
若要部署 CloudWatch 代理程式以從 EC2 執行個體託管之 Amazon ECS 叢集中收集執行個體層級指標，請使用具有預設組態的 Quick Start 設定，或手動安裝代理以便能自訂代理。
這兩種方法都需要您至少有一個已部署了 EC2 啟動類型的 Amazon ECS 叢集，並要求 CloudWatch 代理程式容器可以存取 Amazon EC2 執行個體中繼資料服務 (IMDS)。如需有關 IMDS 的詳細資訊，請參閱[執行個體中繼資料與使用者資料](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)。
這些方法也假設您 AWS CLI 已安裝 。此外，若要執行下列程序中的命令，您必須登入具有 **IAMFullAccess** 和 **AmazonECS\$1FullAccess** 政策的帳戶或角色。
**重要**
在任務定義中定義 CloudWatch Agent 容器時，請設定 `essential: false`。這可防止整個 Amazon ECS 服務在 CloudWatch Agent 容器發生故障時停止。即使代理程式暫時無法使用，其他重要的應用程式容器仍會繼續執行。
**Topics**
+ [使用 快速設定 CloudFormation](#deploy-container-insights-ECS-instancelevel-quickstart)
+ [手動和自訂設定](#deploy-container-insights-ECS-instancelevel-manual)
## 使用 快速設定 CloudFormation
若要使用快速設定，請輸入下列命令以使用 CloudFormation 來安裝代理程式。將 *cluster-name* 和 *cluster-region* 替換成您 Amazon ECS 叢集的名稱和區域。
此命令會建立 IAM 角色 **CWAgentECSTaskRole** 和 **CWAgentECSExecutionRole**。如果您的帳戶中已存在這些角色，請在輸入命令時改用 `ParameterKey=CreateIAMRoles,ParameterValue=False`，而不是使用 `ParameterKey=CreateIAMRoles,ParameterValue=True`。否則命令會失敗。
```
ClusterName=cluster-name
Region=cluster-region
curl -O https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cloudformation-quickstart/cwagent-ecs-instance-metric-cfn.json
aws cloudformation create-stack --stack-name CWAgentECS-${ClusterName}-${Region} \
--template-body file://cwagent-ecs-instance-metric-cfn.json \
--parameters ParameterKey=ClusterName,ParameterValue=${ClusterName} \
ParameterKey=CreateIAMRoles,ParameterValue=True \
--capabilities CAPABILITY_NAMED_IAM \
--region ${Region}
```
**(替代) 使用您自己的 IAM 角色**
如果您想要使用自己自訂的 ECS 任務角色和 ECS 任務執行角色，不使用 **CWAgentECSTaskRole** 和 **CWAgentECSExecutionRole** 角色，請先確定要作為 ECS 任務角色使用的角色連接了 **CloudWatchAgentServerPolicy**。此外，亦請確定要作為 ECS 任務執行角色使用的角色同時連接了 **CloudWatchAgentServerPolicy** 和 **AmazonECSTaskExecutionRolePolicy** 政策。然後輸入下列命令。在命令中，以您自訂 ECS 任務角色的 ARN 取代 *task-role-arn*，以您自訂 ECS 任務執行角色的 ARN 取代 *execution-role-arn*。
```
ClusterName=cluster-name
Region=cluster-region
TaskRoleArn=task-role-arn
ExecutionRoleArn=execution-role-arn
curl -O https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cloudformation-quickstart/cwagent-ecs-instance-metric-cfn.json
aws cloudformation create-stack --stack-name CWAgentECS-${ClusterName}-${Region} \
--template-body file://cwagent-ecs-instance-metric-cfn.json \
--parameters ParameterKey=ClusterName,ParameterValue=${ClusterName} \
ParameterKey=TaskRoleArn,ParameterValue=${TaskRoleArn} \
ParameterKey=ExecutionRoleArn,ParameterValue=${ExecutionRoleArn} \
--capabilities CAPABILITY_NAMED_IAM \
--region ${Region}
```
**故障診斷快速設定**
若要檢查 CloudFormation 堆疊的狀態，請輸入下列命令。
```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation describe-stacks --stack-name CWAgentECS-$ClusterName-$Region --region $Region
```
如果您看到的 `StackStatus` 不是 `CREATE_COMPLETE` 或 `CREATE_IN_PROGRESS`，請檢查堆疊事件以找出錯誤。輸入以下命令。
```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation describe-stack-events --stack-name CWAgentECS-$ClusterName-$Region --region $Region
```
若要檢查 `cwagent` 常駐程式服務的狀態，請輸入以下命令。在輸出中，您應該會看到 `runningCount` 等於 `deployment` 區段的 `desiredCount`。如果不相等，請檢查輸出的 `failures` 區段。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs describe-services --services cwagent-daemon-service --cluster $ClusterName --region $Region
```
您也可以使用 CloudWatch Logs 主控台檢查代理程式日誌。尋找 **/ecs/ecs-cwagent-daemon-service** 日誌群組。
**刪除 CloudWatch 代理程式的 CloudFormation 堆疊**
如果您需要刪除 CloudFormation 堆疊，請輸入下列命令。
```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation delete-stack --stack-name CWAgentECS-${ClusterName}-${Region} --region ${Region}
```
## 手動和自訂設定
依本節的步驟手動部署 CloudWatch 代理，以從 EC2 執行個體託管的 Amazon ECS 叢集中收集執行個體層級指標。
### 必要的 IAM 角色和政策
需要兩個 IAM 角色。如果角色不存在，即必須建立角色。如需這些角色的詳細資訊，請參閱 [IAM 任務角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)和 [Amazon ECS 任務執行角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html)。
+ *ECS 任務角色*，CloudWatch 代理程式用來發布指標的角色。如果此角色已經存在，您必須確定它連接了 `CloudWatchAgentServerPolicy` 政策。
+ *ECS 任務執行角色*，CloudWatch 代理用來啟動 Amazon ECS 代理程式的角色。如果此角色已經存在，您必須確定它連接了 `AmazonECSTaskExecutionRolePolicy` 和 `CloudWatchAgentServerPolicy` 政策。
如果您尚未擁有這些角色，您可以使用下列命令建立它們並連接必要的政策。第一個命令會建立 ECS 任務角色。
```
aws iam create-role --role-name CWAgentECSTaskRole \
--assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Sid\": \"\",\"Effect\": \"Allow\",\"Principal\": {\"Service\": \"ecs-tasks.amazonaws.com\"},\"Action\": \"sts:AssumeRole\"}]}"
```
輸入上一個命令後，請記下命令輸出中作為 "TaskRoleArn" 的 `Arn` 值。稍後建立任務定義時需要使用此值。然後輸入下列命令以連接必要的政策。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
--role-name CWAgentECSTaskRole
```
下一個命令會建立 ECS 任務執行角色。
```
aws iam create-role --role-name CWAgentECSExecutionRole \
--assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Sid\": \"\",\"Effect\": \"Allow\",\"Principal\": {\"Service\": \"ecs-tasks.amazonaws.com\"},\"Action\": \"sts:AssumeRole\"}]}"
```
輸入上一個命令後，請記下命令輸出中作為 "ExecutionRoleArn" 的 `Arn` 值。稍後建立任務定義時需要使用此值。然後輸入下列命令以連接必要的政策。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
--role-name CWAgentECSExecutionRole
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy \
--role-name CWAgentECSExecutionRole
```
### 建立任務定義並啟動常駐程式服務
建立任務定義並用它啟動 CloudWatch 代理程式作為常駐程式服務。若要建立任務定義，請輸入下列命令。在前幾行中，將預留位置更換為您部署的實際值。*logs-region* 是 CloudWatch Logs 所在的區域，*cluster-region* 則是您叢集所在的區域。*task-role-arn* 是您所用之 ECS 任務角色的 Arn，*execution-role-arn* 則是 ECS 任務執行角色的 Arn。
```
TaskRoleArn=task-role-arn
ExecutionRoleArn=execution-role-arn
AWSLogsRegion=logs-region
Region=cluster-region
curl https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cwagent-ecs-instance-metric.json \
| sed "s|{{task-role-arn}}|${TaskRoleArn}|;s|{{execution-role-arn}}|${ExecutionRoleArn}|;s|{{awslogs-region}}|${AWSLogsRegion}|" \
| xargs -0 aws ecs register-task-definition --region ${Region} --cli-input-json
```
然後執行下列命令以啟動協助程式服務。將 *cluster-name* 和 *cluster-region* 替換成您 Amazon ECS 叢集的名稱和區域。
**重要**
在執行此命令之前，請先移除所有容量提供者策略。否則，該命令將無法運作。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs create-service \
--cluster ${ClusterName} \
--service-name cwagent-daemon-service \
--task-definition ecs-cwagent-daemon-service \
--scheduling-strategy DAEMON \
--region ${Region}
```
如果看到此錯誤訊息 `An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent`，即表示您已經建立名為 `cwagent-daemon-service` 的協助程式服務。您必須使用下列命令作為範例，先刪除該服務。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs delete-service \
--cluster ${ClusterName} \
--service cwagent-daemon-service \
--region ${Region} \
--force
```
### (選用) 進階組態
或者，您可以選擇使用 SSM 為 EC2 執行個體託管之 Amazon ECS 叢集中的 CloudWatch 代理程式，指定其他組態選項。選項如下：
+ `metrics_collection_interval` – CloudWatch 代理程式收集指標的頻率 (秒)。預設為 60。範圍介於 1–172,000 之間。
+ `endpoint_override` – (選用) 指定不同端點以傳送日誌。如果從 VPC 中的叢集發布，且想要在 VPC 端點記錄資料，建議您這麼做。
`endpoint_override` 的值必須是 URL 字串。
+ `force_flush_interval` – 指定日誌在傳送到伺服器之前停留在記憶體緩衝區內的最長時間 (以秒為單位)。不論此欄位的設定如何，如果緩衝區中的日誌大小達到 1 MB，系統會立即將日誌傳送到伺服器。預設值為 5 秒。
+ `region` – 根據預設，代理會將指標發布至 Amazon ECS 容器執行個體所在的同一區域。若要覆寫此項目，您可在此指定不同的區域。例如 `"region" : "us-east-1"`
以下是自訂組態的範例：
```
{
"agent": {
"region": "us-east-1"
},
"logs": {
"metrics_collected": {
"ecs": {
"metrics_collection_interval": 30
}
},
"force_flush_interval": 5
}
}
```
**若要在 Amazon ECS 容器中自訂 CloudWatch 代理程式組態**
1. 確定 **AmazonSSMReadOnlyAccess** 政策已連接至您的 Amazon ECS 任務執行角色。您可以輸入以下命令來執行此操作。此範例假設您的 Amazon ECS 任務執行角色是 CWAgentECSExecutionRole。如果使用不同的角色，請更換下列命令中的角色名稱。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
--role-name CWAgentECSExecutionRole
```
1. 建立類似上述範例的自訂組態檔案。將此檔案命名為 `/tmp/ecs-cwagent-daemon-config.json`。
1. 執行下列命令，將此組態放入參數存放區。將 *cluster-region* 替換成您 Amazon ECS 叢集的區域。若要執行此命令，您必須登入具有 **AmazonSSMFullAccess** 政策的使用者或角色。
```
Region=cluster-region
aws ssm put-parameter \
--name "ecs-cwagent-daemon-service" \
--type "String" \
--value "`cat /tmp/ecs-cwagent-daemon-config.json`" \
--region $Region
```
1. 將任務定義檔案下載至本機檔案，例如 `/tmp/cwagent-ecs-instance-metric.json`
```
curl https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cwagent-ecs-instance-metric.json -o /tmp/cwagent-ecs-instance-metric.json
```
1. 修改任務定義檔案。移除以下區段：
```
"environment": [
{
"name": "USE_DEFAULT_CONFIG",
"value": "True"
}
],
```
以下列內容取代該區段：
```
"secrets": [
{
"name": "CW_CONFIG_CONTENT",
"valueFrom": "ecs-cwagent-daemon-service"
}
],
```
1. 依照下列步驟重新啟動代理作為協助程式服務：
1. 執行下列命令。
```
TaskRoleArn=task-role-arn
ExecutionRoleArn=execution-role-arn
AWSLogsRegion=logs-region
Region=cluster-region
cat /tmp/cwagent-ecs-instance-metric.json \
| sed "s|{{task-role-arn}}|${TaskRoleArn}|;s|{{execution-role-arn}}|${ExecutionRoleArn}|;s|{{awslogs-region}}|${AWSLogsRegion}|" \
| xargs -0 aws ecs register-task-definition --region ${Region} --cli-input-json
```
1. 執行下列命令以啟動協助程式服務。將 *cluster-name* 和 *cluster-region* 替換成您 Amazon ECS 叢集的名稱和區域。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs create-service \
--cluster ${ClusterName} \
--service-name cwagent-daemon-service \
--task-definition ecs-cwagent-daemon-service \
--scheduling-strategy DAEMON \
--region ${Region}
```
如果看到此錯誤訊息 `An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent`，即表示您已經建立名為 `cwagent-daemon-service` 的協助程式服務。您必須使用下列命令作為範例，先刪除該服務。
```
ClusterName=cluster-name
Region=Region
aws ecs delete-service \
--cluster ${ClusterName} \
--service cwagent-daemon-service \
--region ${Region} \
--force
```