# Amazon EKS 上 OTel Container Insights 的高级配置
本主题介绍了 Amazon EKS 上 OTel Container Insights 的高级配置方案。使用这些配置可自定义指标收集、筛选日志、跨账户收集遥测数据、添加自定义维度以及调整大型集群的资源分配。
## 先决条件
配置高级设置之前，请确认已满足以下要求。
+ OTel Container Insights 已安装在 Amazon EKS 集群上并处于 `ACTIVE` 状态
+ 运行 Kubernetes 版本 1.28 或更高版本的 Amazon EKS 集群
+ Amazon CLI 版本 2.15.0 或更高版本
+ 已配置 `kubectl` 以与目标集群通信
+ IAM 权限：`eks:UpdateAddon`、`eks:DescribeAddon` 和 `iam:AttachRolePolicy`（跨账户配置需要）
## 常规配置模式
所有高级配置都遵循相同的模式。可以使用 `aws eks update-addon` 命令将 JSON 配置传递给 `amazon-cloudwatch-observability` 附加组件。
```
aws eks update-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--configuration-values '{{JSON-configuration}}' \
--resolve-conflicts OVERWRITE
```
**重要**
`--resolve-conflicts OVERWRITE` 标志可替换任何现有的附加组件配置。要保留现有设置，请在运行命令之前将其与新配置合并。
## 日志筛选
可以通过排除符合特定条件的日志来降低 CloudWatch Logs 成本。在代理将调试级日志或详细日志发送到 CloudWatch 之前，使用日志筛选功能将其删除。
**配置日志筛选功能**
1. 运行以下命令，使用日志筛选器配置更新附加组件。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。
```
aws eks update-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--configuration-values '{
"otelContainerInsights": {
"enabled": true
},
"agent": {
"config": {
"logs": {
"metrics_collected": {
"kubernetes": {
"enhanced_container_insights": true
}
},
"exclude_filters": [
{
"type": "log_level_filter",
"log_level": "DEBUG"
}
]
}
}
}
}' \
--resolve-conflicts OVERWRITE
```
1. 确认在更新后附加组件状态是否为 `ACTIVE`。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.status" \
--output text
```
`exclude_filters` 配置会在代理将与指定日志级别匹配的日志条目发送到 CloudWatch Logs 之前将其移除。这可以减少日志摄取量和相关成本。
## 多账户收集
通过配置跨账户 IAM 角色假设，可以将遥测数据从工作负载账户发送到中央监控账户。利用这种方法，可以通过单一视图查看不同 Amazon 账户中多个 Amazon EKS 集群的指标和日志。
### 设置多账户收集
**在监控账户中创建跨账户角色**
1. 在中央监控账户中，创建具有信任策略的 IAM 角色，该策略允许工作负载账户担任该角色。将 {{workload-account-id}} 替换为工作负载账户的 Amazon 账户 ID。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{{workload-account-id}}:root"
},
"Action": "sts:AssumeRole"
}
]
}
```
1. 将 `CloudWatchAgentServerPolicy` 托管策略附加到跨账户角色。
**配置用于跨账户传输的附加组件**
1. 在工作负载账户中，更新附加组件以担任跨账户角色。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称，并将 {{monitoring-account-id}} 替换为中央监控账户的 Amazon 账户 ID。
```
aws eks update-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--configuration-values '{
"otelContainerInsights": {
"enabled": true
},
"agent": {
"config": {
"credentials": {
"role_arn": "arn:aws:iam::{{monitoring-account-id}}:role/CrossAccountCWObservabilityRole"
}
}
}
}' \
--resolve-conflicts OVERWRITE
```
1. 确认在更新后附加组件状态是否为 `ACTIVE`。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.status" \
--output text
```
## 自定义指标维度
可以将根据 Kubernetes 标签得出的自定义维度添加到 Container Insights 中。通过自定义维度，可以按更精细的粒度（例如按团队、环境或应用程序层）对指标进行筛选和分组。
**从 Kubernetes 标签中添加自定义维度**
1. 运行以下命令以配置自定义维度。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称，并将 {{label-key}} 替换为 Kubernetes 标签以用作维度。
```
aws eks update-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--configuration-values '{
"otelContainerInsights": {
"enabled": true
},
"agent": {
"config": {
"logs": {
"metrics_collected": {
"kubernetes": {
"enhanced_container_insights": true,
"metric_dimensions": {
"custom_dimensions": ["{{label-key}}"]
}
}
}
}
}
}
}' \
--resolve-conflicts OVERWRITE
```
1. 确认在更新后附加组件状态是否为 `ACTIVE`。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.status" \
--output text
```
配置生效后，指定的 Kubernetes 标签将作为维度显示在 CloudWatch 中的Container Insights 指标上。
## 大型集群的资源调整
对于大型集群，可能需要提高 CloudWatch 代理 DaemonSet 的 CPU 和内存限制。默认资源分配适用于小集群，但是较大的集群会生成更多的遥测数据，并且需要额外的代理资源。
下表根据集群大小提供了大小调整指南。
| 集群大小 | CPU 请求 | CPU 限制 | 内存请求 | 内存限制 |
| --- | --- | --- | --- | --- |
| 小型（20 个节点或更少） | 100 m | 200 m | 128 Mi | 256 Mi |
| 中型（21–100 个节点） | 200 m | 400 m | 256 Mi | 512 Mi |
| 大型（超过 100 个节点） | 300 m | 500 m | 384 Mi | 768 Mi |
| 超大型（500 多个节点） | 500 m | 1000 m | 512 Mi | 1 Gi |
**为代理 DaemonSet 配置资源限制**
1. 运行以下命令以设置资源请求和限制。将 {{cluster-name}} 替换为您的 Amazon EKS 集群的名称，并将资源值替换为上表中的值。
```
aws eks update-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--configuration-values '{
"otelContainerInsights": {
"enabled": true
},
"agent": {
"resources": {
"requests": {
"cpu": "{{cpu-request}}",
"memory": "{{memory-request}}"
},
"limits": {
"cpu": "{{cpu-limit}}",
"memory": "{{memory-limit}}"
}
}
}
}' \
--resolve-conflicts OVERWRITE
```
1. 确认附加组件状态是否为 `ACTIVE`，以及代理容器组（pod）是否以新的资源分配重启。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.status" \
--output text
```
1. 确认代理容器组（pod）是否以新的资源限制运行。
```
kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent -o jsonpath='{.items[0].spec.containers[0].resources}'
```
## 验证配置更改
应用任何高级配置后，请确认附加组件是否运行正常，以及代理容器组（pod）是否成功重启。
**验证配置更改**
1. 检查附加组件状态是否为 `ACTIVE`。将 {{cluster-name}} 替换为 Amazon EKS 集群的名称。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.{Status:status,ConfigValues:configurationValues}" \
--output table
```
1. 确认代理容器组（pod）是否已重启并处于 `Running` 状态。
```
kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
所有代理容器组（pod）都必须显示包含最近重启时间的 `Running` 状态。
## 问题排查
按照以下指南，解决高级配置的常见问题。
### 附加组件更新因 ConfigurationConflict 而失败
**症状：**`aws eks update-addon` 命令返回 `ConfigurationConflict` 错误。
**原因：**您提供的 JSON 配置的格式错误或该配置包含无效密钥。
**解决方案：**要解决这个问题，请完成以下步骤。
1. 使用 JSON linter 或运行以下命令来验证 JSON 配置。
```
echo '{{your-json-configuration}}' | python3 -m json.tool
```
1. 确认 `amazon-cloudwatch-observability` 附加组件的所有配置密钥是否均有效。
1. 使用更正后的 JSON 重试更新。
### 跨账户指标未显示在监控账户中
**症状：**配置多账户收集后，指标未显示在中央监控账户中。
**原因：**跨账户 IAM 角色信任策略或权限不正确。
**解决方案：**要解决这个问题，请完成以下步骤。
1. 确认监控账户中的信任策略是否允许工作负载账户担任该角色。
1. 确认跨账户角色是否附加了 `CloudWatchAgentServerPolicy` 托管策略。
1. 检查代理日志中是否存在 `AssumeRole` 错误。
```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "AssumeRole\|AccessDenied"
```
1. 确认工作负载账户中的代理 IAM 角色是否拥有跨账户角色 ARN 的 `sts:AssumeRole` 权限。