先决条件常规配置模式日志筛选多账户收集自定义指标维度大型集群的资源调整验证配置更改问题排查

Amazon EKS 上 OTel Container Insights 的高级配置

本主题介绍了 Amazon EKS 上 OTel Container Insights 的高级配置方案。使用这些配置可自定义指标收集、筛选日志、跨账户收集遥测数据、添加自定义维度以及调整大型集群的资源分配。

先决条件

配置高级设置之前，请确认已满足以下要求。

OTel Container Insights 已安装在 Amazon EKS 集群上并处于 ACTIVE 状态
运行 Kubernetes 版本 1.28 或更高版本的 Amazon EKS 集群
AWS 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 之前，使用日志筛选功能将其删除。

配置日志筛选功能

运行以下命令，使用日志筛选器配置更新附加组件。将 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

确认在更新后附加组件状态是否为 ACTIVE。


aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status" \
  --output text

exclude_filters 配置会在代理将与指定日志级别匹配的日志条目发送到 CloudWatch Logs 之前将其移除。这可以减少日志摄取量和相关成本。

多账户收集

通过配置跨账户 IAM 角色假设，可以将遥测数据从工作负载账户发送到中央监控账户。利用这种方法，可以通过单一视图查看不同 AWS 账户中多个 Amazon EKS 集群的指标和日志。

设置多账户收集

在监控账户中创建跨账户角色

在中央监控账户中，创建具有信任策略的 IAM 角色，该策略允许工作负载账户担任该角色。将 workload-account-id 替换为工作负载账户的 AWS 账户 ID。


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::workload-account-id:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

将 CloudWatchAgentServerPolicy 托管策略附加到跨账户角色。

配置用于跨账户传输的附加组件

在工作负载账户中，更新附加组件以担任跨账户角色。将 cluster-name 替换为 Amazon EKS 集群的名称，并将 monitoring-account-id 替换为中央监控账户的 AWS 账户 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

确认在更新后附加组件状态是否为 ACTIVE。


aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status" \
  --output text

自定义指标维度

可以将根据 Kubernetes 标签得出的自定义维度添加到 Container Insights 中。通过自定义维度，可以按更精细的粒度（例如按团队、环境或应用程序层）对指标进行筛选和分组。

从 Kubernetes 标签中添加自定义维度

运行以下命令以配置自定义维度。将 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

确认在更新后附加组件状态是否为 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 配置资源限制

运行以下命令以设置资源请求和限制。将 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

确认附加组件状态是否为 ACTIVE，以及代理容器组（pod）是否以新的资源分配重启。


aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status" \
  --output text

确认代理容器组（pod）是否以新的资源限制运行。


kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent -o jsonpath='{.items[0].spec.containers[0].resources}'

验证配置更改

应用任何高级配置后，请确认附加组件是否运行正常，以及代理容器组（pod）是否成功重启。

验证配置更改

检查附加组件状态是否为 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

确认代理容器组（pod）是否已重启并处于 Running 状态。
```
kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
所有代理容器组（pod）都必须显示包含最近重启时间的 Running 状态。

问题排查

按照以下指南，解决高级配置的常见问题。

附加组件更新因 ConfigurationConflict 而失败

症状：aws eks update-addon 命令返回 ConfigurationConflict 错误。

原因：您提供的 JSON 配置的格式错误或该配置包含无效密钥。

解决方案：要解决这个问题，请完成以下步骤。

使用 JSON linter 或运行以下命令来验证 JSON 配置。
```
echo 'your-json-configuration' | python3 -m json.tool
```
确认 amazon-cloudwatch-observability 附加组件的所有配置密钥是否均有效。
使用更正后的 JSON 重试更新。

跨账户指标未显示在监控账户中

症状：配置多账户收集后，指标未显示在中央监控账户中。

原因：跨账户 IAM 角色信任策略或权限不正确。

解决方案：要解决这个问题，请完成以下步骤。

确认监控账户中的信任策略是否允许工作负载账户担任该角色。
确认跨账户角色是否附加了 CloudWatchAgentServerPolicy 托管策略。

检查代理日志中是否存在 AssumeRole 错误。


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

确认工作负载账户中的代理 IAM 角色是否拥有跨账户角色 ARN 的 sts:AssumeRole 权限。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用 Amazon CloudWatch Observability EKS 附加组件或 Helm 图表安装 CloudWatch 代理

Enhanced Container Insights（Classic）