# 快速入门：Amazon EKS 上的 OTel Container Insights 本指南将引导您在现有 Amazon EKS 集群上启用 OTel Container Insights。在此过程结束时，您的集群将在启用增强的可观测性的情况下向 Amazon CloudWatch 发送基础设施指标和容器日志。您可以通过两种方式启用 OTel Container Insights：使用 Amazon Web Services 管理控制台（最快）或使用 Amazon CLI。两种方法都安装相同的 `amazon-cloudwatch-observability` EKS 附加组件和 OTel Container Insights 配置。您不需要手动代理部署、Helm 图表或自定义收集器管道。整个过程不到 5 分钟即可完成。 ## 先决条件从控制台启用 OTel Container Insights 前，请确认已满足以下要求。 + 运行 Kubernetes 1.28 版本或更高版本的现有 Amazon EKS 集群 + 平台版本 `eks.1` 或更高版本 + `amazon-cloudwatch-observability` 附加组件 6.2.0 版本或更高版本 + Amazon CLI 2.15.0 版本或更高版本（用于基于 CLI 的设置） + 已配置 `kubectl` 以与目标集群通信 + IAM 权限：`eks:CreateAddon`、`eks:DescribeAddon` 和 `iam:CreateServiceLinkedRole`。 + 集群上已安装 EKS 容器组身份代理附加组件，或服务账户的 IAM 角色（IRSA）已配置 + 从集群到 CloudWatch 端点的出站互联网访问 ## 启用 OTel Container Insights（控制台） Amazon Web Services 管理控制台提供了启用 OTel Container Insights 的最快途径。 **使用控制台启用 OTel Container Insights** 1. 从以下位置打开 Amazon EKS 控制台：[https://console.aws.amazon.com/eks/](https://console.amazonaws.cn/eks/)。 1. 选择**集群**，然后选择您的集群名称。 1. 选择**可观测性**选项卡。 1. 选择**启用 Container Insights**，然后按照屏幕上的说明进行操作。有关详细的控制台演练过程，请参阅[从控制台启用 OTel Container Insights](container-insights-eks-otel-console.md)。 ## 启用 OTel Container Insights（Amazon CLI）使用以下步骤，利用 Amazon CLI 启用 OTel Container Insights。 ### 步骤 1：创建 IAM 角色创建一个 IAM 角色，让 CloudWatch 可观测性附加组件可以将数据发送到 CloudWatch。 **创建 CloudWatch 可观测性附加组件 IAM 角色** 1. 运行以下命令为 EKS 容器组身份创建具有信任策略的角色。 ``` aws iam create-role \ --role-name EKS-CloudWatch-Observability-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-Observability-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-Observability-Role ``` ### 步骤 3：安装 Amazon CloudWatch 可观测性附加组件在启用 OTel Container Insights 的情况下安装 `amazon-cloudwatch-observability` 附加组件。 **安装附加组件** + 运行如下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。 ``` aws eks create-addon \ --cluster-name {{cluster-name}} \ --addon-name amazon-cloudwatch-observability \ --configuration-values '{"otelContainerInsights":{"enabled":true}}' ``` **重要** `otelContainerInsights.enabled` 配置是必需的。默认情况下，OTel Container Insights 未启用。 ### 步骤 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 中。 ### 检查指标 **在 CloudWatch 中检查指标** 1. 通过 [https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/) 打开 CloudWatch 控制台。 1. 在导航窗格中，选择 **Query Studio**。 1. 使用 PromQL 搜索指标，例如 `container_cpu_usage_seconds_total`。 ### 检查日志要确认集群的日志组是否存在，请运行以下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。 ``` aws logs describe-log-groups \ --log-group-name-prefix "/aws/containerinsights/{{cluster-name}}" \ --query "logGroups[].logGroupName" \ --output table ``` ### 预期数据获取时间下表显示了启用 OTel Container Insights 后每种信号类型的预期延迟。 | 信号 | 预期延迟 | | --- | --- | | 基础设施指标 | 2–3 分钟 | | 容器日志 | 2–3 分钟 | | 性能日志事件 | 3–5 分钟 | ## 问题排查在 Amazon EKS 上启用 OTel Container Insights 时，遵循以下指南，解决常见问题。 ### 附加组件状态显示 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 ``` ### 代理容器组（pod）处于 CrashLoopBackOff 或 Pending 状态 **症状：**运行 `kubectl get pods -n amazon-cloudwatch` 时，一个或多个容器组（pod）显示 `CrashLoopBackOff` 或 `Pending` 状态。 **原因：**由于节点资源不足、权限缺失或网络连接问题，代理容器组（pod）无法启动。 **解决方案：**要解决这个问题，请完成以下步骤。 1. 查看容器组（pod）事件，以获取详细的错误消息。 ``` kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent ``` 1. 检查代理容器日志中是否存在启动错误。 ``` kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50 ``` 1. 确认您的节点是否有足够的 CPU 和内存可供代理容器组（pod）使用。 1. 确认 EKS 容器组身份代理附加组件已安装并正在运行。 ``` kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent ``` ### 5 分钟后指标未显示在 CloudWatch 中 **症状：**代理容器组（pod）显示 `Running` 状态，但在 5 分钟后，CloudWatch 中没有显示任何指标。 **原因：**代理无法向 CloudWatch 发送数据，这通常是因为网络限制或 IAM 权限不正确。 **解决方案：**要解决这个问题，请完成以下步骤。 1. 验证代理容器组（pod）是否可以到达 CloudWatch 端点。检查您的 VPC 安全组和网络 ACL 是否允许传输至 CloudWatch 端点的出站 HTTPS 流量（端口 443）。 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`。 1. 如果您将 VPC 端点用于 CloudWatch，请确认端点策略允许执行所需的操作。