View a markdown version of this page

设置指南（Amazon CLI） - Amazon CloudWatch
先决条件步骤 1：创建 IAM 角色步骤 2：创建容器组身份关联步骤 3：安装 Amazon CloudWatch 可观测性附加组件步骤 4：确认附加组件状态步骤 5：确认代理容器组（pod）正在运行验证 CloudWatch 中的数据问题排查后续步骤
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

设置指南（Amazon CLI）

本指南将引导您使用 Amazon CLI 在现有 Amazon EKS 集群上安装 Enhanced Container Insights（Classic）。该附加组件会将 CloudWatch 代理部署为 DaemonSet，用于收集基础设施指标、容器日志和性能数据。

维护模式

Enhanced Container Insights（Classic）处于维护模式。有关新部署，建议使用 Enhanced Container Insights（建议）。

先决条件

开始操作之前，请确认已满足以下要求。

  • 运行 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"]
    }]
  }'

  2. 将 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/ 打开 CloudWatch 控制台。

  2. 在导航窗格中，选择 Container Insights。

  3. 确认是否显示了集群的 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"

  2. 确认 IAM 角色是否存在并已附加 CloudWatchAgentServerPolicy。

  3. 确认容器组身份关联是否针对正确的命名空间 (amazon-cloudwatch) 和服务帐户 (cloudwatch-agent)。

  4. 删除失败的附加组件，解决问题后将其重新安装。

    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 端点。

  2. 检查代理日志中是否存在权限错误或连接超时。

    kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"

  3. 确认 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

  2. 确认您的节点是否有足够的 CPU 和内存可供代理容器组（pod）使用。

  3. 确认 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。