# 在 Amazon EKS 上排查 Container Insights
<a name="container-insights-eks-troubleshooting"></a>

本节介绍了在 Amazon EKS 上设置或运行 Container Insights 时可能遇到的常见问题。无论您使用 OTel 方法还是 Classic 方法，均可使用下表和诊断命令来识别和解决问题。

有关特定于方法的设置指南，请参阅[快速入门：Amazon EKS 上的 OTel Container Insights](container-insights-eks-otel-quickstart.md)或[设置指南（AWS CLI）](container-insights-eks-classic-setup.md)。要比较方法，请参阅[比较 Container Insights 方法](container-insights-eks-compare.md)。

## 指标未显示在 CloudWatch 中
<a name="container-insights-eks-troubleshooting-metrics"></a>

如果您在 `ContainerInsights` 命名空间中看不到指标，请使用下表来确定原因。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| ContainerInsights 命名空间中没有指标 | IAM 角色缺少 cloudwatch:PutMetricData 权限 | 将 CloudWatchAgentServerPolicy 托管策略附加到代理 IAM 角色。 | 
| 部分节点会显示指标，但一些节点不会显示 | 由于污点，未在所有节点上调度代理 DaemonSet | 向代理 DaemonSet 添加容忍度以允许在污点节点上进行调度。 | 
| 指标停止显示 | 代理容器组（pod）已被 OOMKilled 或者正在重启 | 在代理容器组（pod）资源规格中增加内存限制。 | 
| 指标过时或为零 | 网络连接受阻 | 检查 VPC 安全组并验证 CloudWatch VPC 端点是否存在。 | 
| 增强指标缺失 | 未为增强的可观测性配置代理 | 在代理配置中设置 enhancedObservability: true。 | 

## 代理容器组（pod）未启动
<a name="container-insights-eks-troubleshooting-agent-pods"></a>

如果代理容器组（pod）无法启动或保持非运行状态，请使用下表来诊断问题。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| ImagePullBackOff | 无法访问 Amazon ECR 或者映像标签不正确 | 验证映像 URI 并确认您的节点可以访问 Amazon ECR。 | 
| Pending | 节点上的 CPU 或内存不足 | 在代理容器组（pod）规范中扩展节点组或减少资源请求。 | 
| CrashLoopBackOff | 配置无效或缺少卷挂载 | 在受影响的容器组（pod）上运行 kubectl logs，查看容器组（pod）日志中是否存在配置错误。 | 
| FailedScheduling | 节点亲和性或污点会阻碍调度 | 查看 DaemonSet 规范中的 nodeSelector 和容忍度。 | 
| 退出代码 1 | 服务账户缺少 IRSA 注释 | 验证服务账户是否有 eks.amazonaws.com/role-arn 注释。 | 

## 附加组件安装失败
<a name="container-insights-eks-troubleshooting-addon"></a>

如果 `amazon-cloudwatch-observability` 附加组件无法安装或报告运行状况不佳，请使用下表来排查问题。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| CREATE\_FAILED | 与先前安装的资源冲突 | 删除有冲突的资源，并在创建附加组件时使用 --resolve-conflicts OVERWRITE。 | 
| 未找到 OIDC 提供者 | 该集群不存在 IAM OIDC 身份提供者 | 通过运行 eksctl utils associate-iam-oidc-provider 创建提供程序。 | 
| 版本冲突 | 附加组件版本与 Kubernetes 版本不兼容 | 通过运行 aws eks describe-addon-versions 列出兼容版本。 | 
| DEGRADED 状态 | 由于缺少权限，运行状况检查失败 | 检查容器组（pod）日志并验证 IRSA 角色是否已附加所需的策略。 | 

## 日志传输问题
<a name="container-insights-eks-troubleshooting-logs"></a>

如果 Amazon CloudWatch Logs 中未显示容器日志，请使用下表确定原因。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| 日志组不存在 | 缺少 logs:CreateLogGroup 权限 | 向代理 IAM 角色添加 Amazon CloudWatch Logs 权限。 | 
| 日志组存在但为空 | 未为日志配置代理，或区域不匹配 | 验证代理配置是否包括日志收集，以及该区域是否与您的集群区域相匹配。 | 
| 日志延迟超过 5 分钟 | 刷新间隔过高或节点负载过重 | 减少代理配置中的 force\_flush\_interval 值。 | 
| 性能日志缺失 | 代理仅针对应用程序日志进行配置 | 验证代理配置中是否存在“Container Insights”性能日志部分。 | 

## 迁移特定问题
<a name="container-insights-eks-troubleshooting-migration"></a>

如果您在 Container Insights 方法之间迁移时遇到问题，请使用下表。有关完整的迁移工作流程，请参阅[迁移指南](container-insights-eks-migration-hub.md)。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| 并行运行期间重复的指标 | 这两种方法均同时发布指标 | 此行为在并行运行过程中是符合预期的。验证新方法后，请禁用旧方法。 | 
| 方法之间的指标值不同 | 不同的计算方法 | 预计会有微小的差异（小于 5%）。差异较大表示方法之间的配置不匹配。 | 
| 回滚失败 | 未重新应用自定义配置 | 回滚时重新应用完整的配置值。 | 
| 迁移过程中触发警报 | 切换周期的指标缺失 | 在受影响的警报上，暂时将缺失的数据处理设置为 notBreaching。 | 

## OTel Container Insights 问题
<a name="container-insights-eks-troubleshooting-otel"></a>

以下问题是特定于 OTel Container Insights 方法的问题。有关一般指导，请参阅[快速入门：Amazon EKS 上的 OTel Container Insights](container-insights-eks-otel-quickstart.md)。


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| 403 禁止导出错误 | IAM 角色缺少 CloudWatch 权限 | 验证 CloudWatchAgentServerPolicy 是否已附加到代理角色。 | 
| 指标端点的连接被拒绝 | 收集器无法到达 kubelet | 验证hostNetwork: true 是否在容器组（pod）规范中进行了设置，或者确认服务账户是否具有所需的权限。 | 
| 高内存使用量 | 批处理器队列太长 | 减少收集器配置中的 batch/timeout 和 batch/send\_batch\_size 值。 | 
| 自定义指标未显示 | 未为应用程序端点配置接收器 | 在收集器配置中添加一个以您的应用指标端口为目标的 Prometheus 接收器。 | 

## 常规诊断命令
<a name="container-insights-eks-troubleshooting-commands"></a>

使用以下命令来收集有关 Container Insights 部署的信息。

要检查代理容器组（pod）状态，请运行以下命令。

```
kubectl get pods -n amazon-cloudwatch
```

要查看代理容器组（pod）日志，请运行以下命令。

```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50
```

要检查代理的 DaemonSet 状态，请运行以下命令。

```
kubectl get daemonset -n amazon-cloudwatch
```

要在服务账户上创建 IAM 角色，请运行以下命令。

```
kubectl get serviceaccount -n amazon-cloudwatch -o yaml
```

要检查集群附加组件的状态，请运行以下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。

```
aws eks describe-addon --cluster-name {{cluster-name}} --addon-name amazon-cloudwatch-observability
```

要列出 Container Insights 日志组，请运行以下命令。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。

```
aws logs describe-log-groups --log-group-name-prefix "/aws/containerinsights/{{cluster-name}}"
```

## 相关资源
<a name="container-insights-eks-troubleshooting-related"></a>

有关在 Amazon EKS 上设置和运行 Container Insights 的更多信息，请参阅以下主题。
+ [快速入门：Amazon EKS 上的 OTel Container Insights](container-insights-eks-otel-quickstart.md)：设置 OTel Container Insights
+ [设置指南（AWS CLI）](container-insights-eks-classic-setup.md)：设置 Classic Container Insights
+ [迁移指南](container-insights-eks-migration-hub.md)：在方法之间迁移
+ [比较 Container Insights 方法](container-insights-eks-compare.md)：比较 Container Insights 方法