# 设置指南（Amazon CLI）
本指南将引导您使用 Amazon CLI 在现有 Amazon EKS 集群上安装 Enhanced Container Insights（Classic）。该附加组件会将 CloudWatch 代理部署为 DaemonSet，用于收集基础设施指标、容器日志和性能数据。
**维护模式**
Enhanced Container Insights（Classic）处于维护模式。有关新部署，建议使用 [Enhanced Container Insights（建议）](container-insights-eks-otel.md)。
## 先决条件
开始操作之前，请确认已满足以下要求。
+ 运行 Kubernetes 1.25 版本或更高版本的现有 Amazon EKS 集群
+ 平台版本 `eks.1` 或更高版本
+ Amazon CLI 版本 2.12.0 或更高版本
+ 已配置 `kubectl` 以与目标集群通信
+ IAM 权限：`eks:CreateAddon`、`eks:DescribeAddon`、`iam:CreateServiceLinkedRole`、`iam:CreateRole` 和 `iam:AttachRolePolicy`
+ 集群上已安装 EKS 容器组身份代理附加组件，或服务账户的 IAM 角色（IRSA）已配置
+ 从集群到 CloudWatch 端点的出站互联网访问
## 步骤 1：创建 IAM 角色
创建一个 IAM 角色，让 CloudWatch 代理可以将数据发送到 CloudWatch。
**创建 CloudWatch 代理 IAM 角色**
1. 运行以下命令为 EKS 容器组身份创建具有信任策略的角色。
```
aws iam create-role \
--role-name EKS-CloudWatch-Agent-Role \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Service": "pods.eks.amazonaws.com" },
"Action": ["sts:AssumeRole", "sts:TagSession"]
}]
}'
```
1. 将 `CloudWatchAgentServerPolicy` 托管式策略附加到角色。
```
aws iam attach-role-policy \
--role-name EKS-CloudWatch-Agent-Role \
--policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
```
## 步骤 2：创建容器组身份关联
将 IAM 角色与集群中的 CloudWatch 代理服务账户相关联。
**创建容器组身份关联**
+ 运行如下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称，并将 {{account-id}} 替换为 Amazon 账户 ID。
```
aws eks create-pod-identity-association \
--cluster-name {{cluster-name}} \
--namespace amazon-cloudwatch \
--service-account cloudwatch-agent \
--role-arn arn:aws:iam::{{account-id}}:role/EKS-CloudWatch-Agent-Role
```
## 步骤 3：安装 Amazon CloudWatch 可观测性附加组件
在集群上安装 `amazon-cloudwatch-observability` 附加组件。
**安装附加组件**
+ 运行如下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。
```
aws eks create-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--addon-version {{v5.x.x-eksbuild.x}}
```
将 {{v5.x.x-eksbuild.x}} 替换为最新可用的 v5.x 版本。不安装 `--addon-version` 会安装最新版本（v6.2.0\+），该版本会激活 OTel 管道而不是 Classic 管道。
## 步骤 4：确认附加组件状态
确认附加组件已成功安装。
**确认附加组件状态**
+ 运行如下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.status" \
--output text
```
预期的输出是 `ACTIVE`。
## 步骤 5：确认代理容器组（pod）正在运行
确认 CloudWatch 代理容器组（pod）是否在 `amazon-cloudwatch` 命名空间中运行。
**确认代理容器组（pod）正在运行**
+ 运行如下命令。
```
kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
所有代理容器组（pod）都必须显示 `Running` 状态。
## 验证 CloudWatch 中的数据
完成设置后，Container Insights 数据将在 3 到 5 分钟内显示在 CloudWatch 中。
**验证 Container Insights 数据**
1. 通过 [https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/) 打开 CloudWatch 控制台。
1. 在导航窗格中，选择 **Container Insights**。
1. 确认是否显示了集群的 `node_cpu_utilization` 和 `pod_memory_utilization` 等指标。
## 问题排查
在 Amazon EKS 上安装 Enhanced Container Insights（Classic）时，使用以下指南来解决常见问题。
### 附加组件状态显示 CREATE\_FAILED 或 DEGRADED
**症状：**运行 `aws eks describe-addon` 时，状态显示 `CREATE_FAILED` 或 `DEGRADED`。
**原因：**由于 IAM 权限不足或容器组身份关联缺失，附加组件安装失败。
**解决方案：**要解决这个问题，请完成以下步骤。
1. 运行以下命令检查详细的错误信息。将 {{cluster-name}} 替换为您集群的名称。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.health"
```
1. 确认 IAM 角色是否存在并已附加 `CloudWatchAgentServerPolicy`。
1. 确认容器组身份关联是否针对正确的命名空间 (`amazon-cloudwatch`) 和服务帐户 (`cloudwatch-agent`)。
1. 删除失败的附加组件，解决问题后将其重新安装。
```
aws eks delete-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability
```
### 5 分钟后指标未显示在 CloudWatch 中
**症状：**代理容器组（pod）显示 `Running` 状态，但在 5 分钟后，CloudWatch 中没有显示任何指标。
**原因：**由于网络限制或 IAM 权限不正确，代理无法将数据发送到 CloudWatch。
**解决方案：**要解决这个问题，请完成以下步骤。
1. 确认您的 VPC 安全组和网络 ACL 是否允许将出站 HTTPS 流量（端口 443）传输到 CloudWatch 端点。
1. 检查代理日志中是否存在权限错误或连接超时。
```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"
```
1. 确认 IAM 角色是否已附加 `CloudWatchAgentServerPolicy` 策略以及信任策略是否允许 `pods.eks.amazonaws.com`。
### 代理容器组（pod）停滞在“待处理”或 CrashLoopBackOff 状态
**症状：**运行 `kubectl get pods -n amazon-cloudwatch` 时，一个或多个容器组（pod）显示 `Pending` 或 `CrashLoopBackOff` 状态。
**原因：**由于节点资源不足、图像拉取失败或权限缺失，代理容器组（pod）无法启动。
**解决方案：**要解决这个问题，请完成以下步骤。
1. 查看容器组（pod）事件，以获取详细的错误消息。
```
kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
1. 确认您的节点是否有足够的 CPU 和内存可供代理容器组（pod）使用。
1. 确认 EKS 容器组身份代理附加组件已安装并正在运行。
```
kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent
```
## 后续步骤
是否准备升级？ 有关从 Enhanced Container Insights（Classic）移至 OTel Container Insights 的分步说明，请参阅[从 Enhanced Container Insights（Classic）迁移到 OTel Container Insights](container-insights-eks-migrate-from-classic.md)。