datadog/cluster-agent

Datadog Cluster Agent Docker镜像文档

1. 镜像概述和主要用途

1.1 概述

Datadog Cluster Agent是Datadog推出的容器化组件，专为Kubernetes集群设计，以Docker镜像形式分发。作为集群级监控中枢，其核心职责是聚合集群范围的监控数据、协调节点级Datadog Agent、优化资源占用，并为集群管理提供统一的监控视角。

1.2 主要用途

• 收集并聚合Kubernetes集群级指标（如节点资源使用率、Pod调度状态、命名空间元数据等）；
• 转发集群事件（如部署更新、副本集扩缩容、节点异常等）至Datadog平台；
• 协调节点级Datadog Agent，避免重复监控任务，降低集群资源消耗；
• 提供外部指标（如自定义业务指标）以支持Kubernetes HPA（Horizontal Pod Autoscaler）；
• 输出集群安全与合规相关数据（如RBAC配置、镜像安全扫描结果）。

2. 核心功能和特性

2.1 集群级指标聚合

自动采集并聚合集群范围内的关键指标，包括节点资源（CPU/内存/磁盘）使用率、Pod生命周期状态、命名空间资源配额、PV/PVC绑定状态等，支持按集群、命名空间、工作负载等维度过滤分析。

2.2 事件收集与转发

实时捕获Kubernetes API Server事件（如Pod创建/删除、部署失败、节点NotReady等），并转发至Datadog事件流，支持与监控指标联动分析。

2.3 节点Agent协调

通过集中分发配置（如监控规则、过滤策略），减少节点级Agent的重复计算；动态调整节点Agent的采集范围，避免资源浪费。

2.4 外部指标提供

作为Kubernetes外部指标提供者（External Metrics Provider），支持基于自定义指标（如业务QPS、队列长度）配置HPA，实现按需扩缩容。

2.5 安全与合规监控

检测集群RBAC权限配置、网络策略合规性、镜像拉取策略等安全相关配置，生成合规报告并告警异常项。

2.6 高可用性

支持多副本部署，通过Leader选举机制确保集群故障时监控服务不中断。

3. 使用场景和适用范围

3.1 使用场景

• 多节点Kubernetes集群监控：适用于节点数>5的集群，统一管理分散的节点监控数据；
• 资源优化场景：降低大规模集群中节点Agent的资源占用（减少重复采集任务）；
• 自动扩缩容需求：需基于自定义业务指标或集群指标（如节点平均负载）配置HPA的场景；
• 集群事件审计：需追踪集群操作事件（如手动调整副本数、配置变更）的合规审计场景。

3.2 适用范围

• Kubernetes版本：兼容Kubernetes v1.21+（具体版本支持范围见官方文档）；
• 集群类型：支持自管理Kubernetes集群、云托管集群（EKS/GKE/AKS/ACK等）；
• 环境要求：需具备Kubernetes API Server访问权限，节点级Datadog Agent v7.34+（用于与Cluster Agent通信）。

4. 使用方法和配置说明

4.1 前置要求

• 有效的Datadog API密钥（需具备集群监控权限）；
• Kubernetes集群管理员权限（用于部署RBAC资源、配置ServiceAccount）；
• 节点级Datadog Agent已部署（版本需与Cluster Agent兼容）。

4.2 部署示例

4.2.1 Kubernetes Deployment配置（推荐）

Cluster Agent通常通过Kubernetes Deployment部署，示例配置片段如下：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: datadog-cluster-agent
  namespace: datadog
spec:
  replicas: 1  # 高可用场景可设为2+，配合Leader选举
  selector:
    matchLabels:
      app: datadog-cluster-agent
  template:
    metadata:
      labels:
        app: datadog-cluster-agent
    spec:
      serviceAccountName: datadog-cluster-agent
      containers:
      - name: cluster-agent
        image: gcr.io/datadoghq/cluster-agent:latest  # 或指定版本标签（如7.47.0）
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
          requests:
            cpu: 200m
            memory: 256Mi
        env:
        - name: DD_API_KEY
          valueFrom:
            secretKeyRef:
              name: datadog-secrets
              key: api-key
        - name: DD_SITE
          value: "datadoghq.com"  # 国内用户可设为"datadoghq.cn"
        - name: DD_CLUSTER_AGENT_AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: datadog-cluster-agent-auth
              key: token
        - name: DD_COLLECT_KUBERNETES_EVENTS
          value: "true"
        - name: DD_EXTERNAL_METRICS_PROVIDER_ENABLED
          value: "true"

4.2.2 Docker Run命令（非推荐，仅作示例）

Cluster Agent依赖Kubernetes API和节点Agent协同，通常不直接通过docker run部署。若需测试，需挂载Kubernetes配置并配置必要环境变量：

bash
docker run -d \
  --name datadog-cluster-agent \
  -e DD_API_KEY=<YOUR_API_KEY> \
  -e DD_SITE=datadoghq.com \
  -e DD_CLUSTER_AGENT_AUTH_TOKEN=<AUTH_TOKEN> \
  -e KUBERNETES_SERVICE_HOST=<K8S_API_HOST> \
  -e KUBERNETES_SERVICE_PORT=6443 \
  -v /var/run/secrets/kubernetes.io/serviceaccount:/var/run/secrets/kubernetes.io/serviceaccount \
  gcr.io/datadoghq/cluster-agent:latest

5. 配置参数详解

5.1 核心环境变量

5.2 高级配置

更多配置（如指标采集间隔、自定义标签、代理设置）可通过挂载配置文件实现，详细参数见官方文档。

6. 支持与故障排除

6.1 官方文档

详细配置、兼容性矩阵及最佳实践请参考Datadog Cluster Agent官方文档。

6.2 故障排除

• 日志查看：通过kubectl logs <cluster-agent-pod> -n datadog查看容器日志；
• 指标验证：在Datadog平台导航至Infrastructure > Kubernetes > Clusters检查集群数据是否上报；
• 支持渠道：提交工单至Datadog支持团队（support.datadoghq.com），或在https://github.com/DataDog/datadog-agent%E6%8F%90%E4%BA%A4Issue%E3%80%82