datadog/cws-instrumentation

Datadog CWS 工具化边车镜像

1. 镜像概述

Datadog CWS 工具化边车镜像是一个轻量级容器，设计为边车（sidecar）模式部署，专为 Datadog Cloud Workload Security (CWS) 产品提供工具化能力。其核心用途是辅助容器化应用与 Datadog CWS 集成，实现工作负载的安全监控、数据采集及工具化管理，支持 CWS 产品的安全事件检测、行为分析等核心功能落地。

2. 核心功能与特性

• 轻量级设计：镜像体积小（通常<50MB），资源占用低（默认内存消耗<30MB，CPU占用<5%），适合与主应用协同部署，无显著性能影响。
• CWS 原生集成：深度适配 Datadog CWS 产品，支持安全事件采集、工作负载行为监控、威胁检测规则同步等核心能力。
• 自动化工具化：内置工具化逻辑，可自动完成与 CWS 相关的数据预处理、格式转换及上报准备，减少人工配置成本。
• 跨环境兼容：支持 Docker、Kubernetes 等主流容器编排平台，兼容 Linux x86_64/arm64 架构。

3. 使用场景与适用范围

3.1 使用场景

• 容器化应用安全监控：在 Docker 或 Kubernetes 环境中，作为边车容器与主应用协同部署，为 Datad CWS 提供工具化支撑，实现主应用的安全监控与事件上报。
• CWS 规则落地：辅助 Datadog CWS 安全规则在容器环境中生效，包括进程行为监控、文件系统访问审计、网络连接跟踪等。
• 轻量化数据采集：针对资源受限场景（如边缘计算、嵌入式容器），提供低开销的 CWS 数据采集能力。

3.2 适用范围

• 所有需与 Datadog CWS 集成的容器化应用（支持 Docker 镜像、OCI 镜像规范）。
• Kubernetes 集群中 Deployment、StatefulSet、DaemonSet 等资源的边车注入场景。
• 兼容 Datadog Agent v7.40+ 及 CWS 产品最新版本，支持主流 Linux 发行版（Ubuntu 20.04+、CentOS 8+、Debian 11+）。

4. 使用方法与配置说明

4.1 前置条件

• 已获取 Datadog API 密钥（DD_API_KEY），可从 Datadog 控制台 获取。
• 已部署 Datadog Agent（推荐 v7.40+），且 Agent 可正常与 Datadog 后端通信（需配置 DD_API_KEY 及 DD_SITE）。
• 容器运行环境：Docker Engine 20.10+ 或 Kubernetes 1.21+。

4.2 Docker 运行示例

通过 docker run 命令直接部署边车容器，需与主应用共享网络命名空间以监控其进程：

bash
docker run -d \
  --name datadog-cws-sidecar \
  --network=container:<主应用容器ID> \  # 共享主应用网络，确保进程级监控
  -e DD_API_KEY=<your-datadog-api-key> \  # 必选：Datadog API密钥
  -e DD_SITE="datadoghq.com" \  # 可选：Datadog站点，默认datadoghq.com
  -e DD_CWS_INSTRUMENTATION_ENABLED="true" \  # 必选：启用CWS工具化
  -e DD_LOG_LEVEL="info" \  # 可选：日志级别（debug/info/warn/error）
  -v /var/run/docker.sock:/var/run/docker.sock:ro \  # 采集容器元数据（可选）
  -v /proc:/host/proc:ro \  # 采集主机proc信息（可选）
  -v /sys/fs/cgroup:/host/sys/fs/cgroup:ro \  # 采集cgroup信息（可选）
  gcr.io/datadoghq/cws-sidecar:latest  # 镜像地址（以Datadog官方为准）

4.3 Docker Compose 配置示例

在 docker-compose.yml 中定义主应用与边车容器的协同部署：

yaml
version: '3.8'
services:
  main-app:
    image: your-main-app:latest  # 主应用镜像
    ports:
      - "8080:8080"
    # 主应用其他配置（环境变量、挂载等）

  cws-sidecar:
    image: gcr.io/datadoghq/cws-sidecar:latest
    depends_on:
      - main-app
    network_mode: "service:main-app"  # 共享主应用网络命名空间
    environment:
      - DD_API_KEY=<your-datadog-api-key>  # 替换为实际API密钥
      - DD_SITE=datadoghq.com
      - DD_CWS_INSTRUMENTATION_ENABLED=true
      - DD_LOG_LEVEL=info
      - DD_AGENT_HOST=host.docker.internal  # 本地Docker环境下指向主机Agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - /sys/fs/cgroup:/host/sys/fs/cgroup:ro
    restart: always  # 确保边车容器随主应用重启

4. 使用方法与配置说明（续）

4.4 核心配置参数（环境变量）

4.5 挂载配置

建议根据监控需求挂载以下目录（只读权限）：

• /var/run/docker.sock:ro：获取容器元数据（如主应用容器ID、镜像信息）。
• /proc:/host/proc:ro：访问主机proc文件系统，采集进程、CPU、内存等指标。
• /sys/fs/cgroup:/host/sys/fs/cgroup:ro：获取cgroup信息，用于资源使用监控。
• /var/log:/host/var/log:ro：采集主应用日志（如主应用日志路径为/var/log/app）。

5. 注意事项

• 权限要求：边车容器需以非root用户运行（默认已配置），但挂载目录需确保只读权限（ro），避免权限泄露。
• 版本兼容性：需与 Datadog Agent 版本匹配，推荐使用最新版边车镜像以确保功能同步。
• 资源限制：建议为边车容器设置资源限制（如 Kubernetes 中 resources.limits）：内存限制 128Mi，CPU限制 100m。
• 安全最佳实践：敏感信息（如DD_API_KEY）应通过密钥管理工具（如 Kubernetes Secrets）注入，避免明文配置。