DotNet Core Agent for Kubernetes 技术文档

1. 镜像概述和主要用途

DotNet Core Agent for Kubernetes 是一款专为 Kubernetes 环境设计的 .NET Core 应用代理程序，旨在增强容器化 .NET Core 应用的可观测性、可靠性与管理能力。该代理通过与 Kubernetes 生态工具集成，提供健康检查、指标收集、分布式追踪、日志转发等核心功能，帮助开发者和运维人员实现对 .NET Core 应用的全生命周期管理。

2. 核心功能和特性

2.1 可观测性增强

• 健康检查：支持 HTTP 就绪探针（Readiness Probe）和存活探针（Liveness Probe），自定义检查路径与阈值。
• 指标收集：内置 Prometheus 指标暴露，支持 .NET Core 应用性能指标（如请求延迟、错误率、GC 状态）及系统指标（CPU/内存使用率）。
• 分布式追踪：集成 OpenTelemetry，支持 Jaeger、Zipkin 等追踪后端，自动注入追踪上下文（Trace ID/Span ID）。
• 日志转发：支持将应用日志转发至 ELK Stack、Loki、Fluentd 等日志系统，支持结构化日志（JSON 格式）。

2.2 应用管理能力

• 配置注入：支持从 Kubernetes ConfigMap/Secret 动态注入应用配置，无需重启容器。
• 服务发现：自动发现 Kubernetes 集群内的服务端点，简化微服务间通信配置。
• 资源监控：实时监控容器资源使用情况，支持自定义资源告警阈值。

3. 使用场景和适用范围

3.1 典型使用场景

• 微服务架构：为 Kubernetes 集群中的 .NET Core 微服务提供统一的可观测性入口，简化跨服务追踪与问题定位。
• 生产环境监控：满足 SLO/SLA 要求的关键业务应用，需实时监控性能指标与异常告警。
  -. 多集群管理：在混合云或多集群部署场景中，统一收集 .NET Core 应用的指标与日志。
• 开发测试诊断：快速定位开发/测试环境中 .NET Core 应用的运行时问题（如内存泄漏、死锁）。

3.2 适用范围

• 运行在 Kubernetes 集群（v1.18+）中的 .NET Core 应用（.NET Core 3.1+ / .NET 5+）。
• 支持单机 Docker 环境（用于本地调试）及 Kubernetes 集群（开发/测试/生产环境）。
• 兼容 x86_64/arm64 架构，支持中小型（10-100 节点）及大型（100+ 节点）Kubernetes 集群。

4. 使用方法和配置说明

4.1 镜像拉取

bash
# 从默认仓库拉取最新版本（实际使用时需替换为具体镜像仓库地址）
docker pull [镜像仓库地址]/dotnet-core-agent:latest

4.2 基本使用（Docker 环境）

4.2.1 最简运行示例

bash
docker run -d \
  --name dotnet-agent \
  -p 9090:9090  # 暴露指标端口 \
  -e AGENT_LOG_LEVEL=info \
  -e METRICS_ENABLED=true \
  [镜像仓库地址]/dotnet-core-agent:latest

4.2.2 完整配置示例（含追踪与日志转发）

bash
docker run -d \
  --name dotnet-agent \
  -p 9090:9090 \  # 指标端口
  -p 9411:9411 \  # Zipkin 追踪端口（若启用）
  -e AGENT_LOG_LEVEL=debug \  # 调试模式日志
  -e METRICS_ENABLED=true \  # 启用指标收集
  -e METRICS_PORT=9090 \  # 指标暴露端口
  -e TRACING_ENABLED=true \  # 启用分布式追踪
  -e TRACING_EXPORTER=zipkin \  # 追踪导出器（jaeger/zipkin）
  -e TRACING_ZIPKIN_ENDPOINT=[***] \  # Zipkin 服务地址
  -e LOG_FORWARDING_ENABLED=true \  # 启用日志转发
  -e LOG_FORWARDING_DESTINATION=loki \  # 日志目标（loki/elk/fluentd）
  -e LOG_FORWARDING_LOKI_ENDPOINT=[***] \  # Loki 服务地址
  -v /path/to/agent-config:/etc/dotnet-agent/config.yaml \  # 挂载自定义配置文件
  [镜像仓库地址]/dotnet-core-agent:latest

4.3 Kubernetes 部署

4.3.1 Deployment 示例

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dotnet-agent
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dotnet-agent
  template:
    metadata:
      labels:
        app: dotnet-agent
    spec:
      containers:
      - name: dotnet-agent
        image: [镜像仓库地址]/dotnet-core-agent:latest
        ports:
        - containerPort: 9090  # 指标端口
        - containerPort: 9411  # 追踪端口（若启用）
        env:
        - name: AGENT_LOG_LEVEL
          value: "info"
        - name: METRICS_ENABLED
          value: "true"
        - name: METRICS_PORT
          value: "9090"
        - name: TRACING_ENABLED
          value: "true"
        - name: TRACING_EXPORTER
          value: "jaeger"
        - name: TRACING_JAEGER_ENDPOINT
          value: "[***]"  # Jaeger 收集器地址
        - name: LOG_FORWARDING_ENABLED
          value: "true"
        - name: LOG_FORWARDING_DESTINATION
          value: "loki"
        - name: LOG_FORWARDING_LOKI_ENDPOINT
          value: "[***]"
        resources:
          limits:
            cpu: "500m"
            memory: "512Mi"
          requests:
            cpu: "200m"
            memory: "256Mi"
        volumeMounts:
        - name: agent-config
          mountPath: /etc/dotnet-agent/config.yaml
          subPath: config.yaml
      volumes:
      - name: agent-config
        configMap:
          name: dotnet-agent-config  # 关联 ConfigMap（见下方）

4.3.2 ConfigMap 配置示例（自定义配置文件）

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: dotnet-agent-config
  namespace: default
data:
  config.yaml: |
    metrics:
      scrape_interval: 10s  # 指标采集间隔
      include_process_metrics: true  # 包含进程级指标
    tracing:
      sampler_type: parentbased_always_on  # 追踪采样策略
      sampler_param: 1.0  # 采样率（0.0-1.0）
    logs:
      max_batch_size: 100  # 日志批处理大小
      flush_interval: 5s  # 日志刷新间隔

4.4 配置参数说明

4.4.1 环境变量配置

4.4.2 配置文件说明

支持通过挂载 config.yaml 自定义高级配置（优先级高于环境变量），配置项结构示例：

yaml
# /etc/dotnet-agent/config.yaml
metrics:
  scrape_interval: 10s          # 指标采集间隔
  include_process_metrics: true  # 包含进程 CPU/内存指标
  include_aspnetcore_metrics: true  # 包含 ASP.NET Core 特有指标（如请求数、延迟）
tracing:
  sampler_type: parentbased_always_on  # 追踪采样策略
  sampler_param: 1.0                   # 采样率（0.0-1.0）
  baggage_propagation: true            # 是否启用 Baggage 传播
logs:
  max_batch_size: 100        # 日志批处理最大条数
  flush_interval: 5s         # 日志刷新间隔
  include_callstack: false   # 是否包含错误调用栈（仅 error 级别日志）

5. 注意事项

• 版本兼容性：需与 .NET Core 3.1+ 应用兼容，Kubernetes 集群版本需 ≥ 1.18。
• 网络策略：确保代理容器可访问目标服务（如 Prometheus、Jaeger、Loki），需配置 Kubernetes NetworkPolicy 允许相关端口通信。
• 资源限制：生产环境建议配置 CPU 限制 ≥ 200m、内存 ≥ 256Mi，避免资源竞争影响代理稳定性。
• 安全配置：敏感信息（如服务地址、认证令牌）建议通过 Kubernetes Secret 注入，避免明文环境变量。