coredog

CoreDog 🐶

Kubernetes Core Dump 自动收集系统

简介

CoreDog 在应用崩溃时自动收集 core dump 文件，上传到对象存储，并发送通知。

核心特性：

• 🎯 Webhook 自动注入 volume（opt-in，通过 annotation 开启）
• 🔍 精准识别崩溃的 Pod 和容器
• 📦 自动上传到 S3/COS/OSS
• 🧹 上传后自动清理本地文件
• 🔔 企业微信/Slack 即时通知
• 🔗 [可选] 自动上报到 CoreSight，触发自动分析

快速开始

1. 安装 CoreDog

# 编辑配置
vim charts/values.yaml
# 填写 S3 凭证和通知渠道（见下方配置说明）

# 安装
helm install coredog ./charts -n coredog-system --create-namespace

2. 配置节点

在每个 Kubernetes 节点上执行：

sudo su -

# ⚠️ 重要：路径要与容器内的挂载路径一致
# 如果 coredog.io/path="/corefile"，则配置为：
echo '/corefile/core.%e.%p.%h.%t' > /proc/sys/kernel/core_pattern

# 持久化
echo 'kernel.core_pattern=/corefile/core.%e.%p.%h.%t' >> /etc/sysctl.conf
sysctl -p

# 验证
cat /proc/sys/kernel/core_pattern
# 应该输出: /corefile/core.%e.%p.%h.%t

说明：

• 容器内挂载到 /corefile
• 内核配置也是 /corefile/core.xxx
• 由于 hostPath volume 映射，文件实际写到宿主机的 /data/coredog-system/dumps/<ns>/<pod>/core.xxx

3. 应用接入

在您的应用 Deployment/StatefulSet 中添加 annotations：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      annotations:
        # ⚠️ 必填：开启 CoreDog
        coredog.io/inject: "true"
        # ⚠️ 必填：指定挂载路径
        coredog.io/path: "/corefile"
        # 可选：指定要监控的容器（不填则所有容器）
        coredog.io/container: "app"
    spec:
      containers:
      - name: app
        image: my-app:v1
        command:
          - bash
          - -c
          - |
            ulimit -c unlimited  # ⚠️ 必须设置
            exec /app/server

就这么简单！ 应用崩溃时会自动收集 core dump。

配置说明

存储方案选择

CoreDog 支持三种存储后端：

方案	Protocol	优点	适用场景
S3	s3	标准 S3 API，兼容性强	AWS 用户，通用场景
COS	cos	腾讯云原生，性能优化	腾讯云环境
CFS	cfs	文件存储，支持 POSIX 接口	需要文件系统语义，本地/专线上传

S3 配置示例

StorageConfig:
  protocol: s3
  s3AccesskeyID: "your_ak"
  s3SecretAccessKey: "your_sk"
  s3Region: "us-east-1"
  S3Bucket: "my-bucket"
  S3Endpoint: "s3.amazonaws.com"

COS 配置示例

StorageConfig:
  protocol: cos
  s3AccesskeyID: "your_ak"
  s3SecretAccessKey: "your_sk"
  s3Region: "ap-nanjing"
  S3Bucket: "my-bucket-1234567890"
  S3Endpoint: "cos.ap-nanjing.myqcloud.com"

CFS 配置示例

前置条件：CFS 已挂载到集群节点

StorageConfig:
  protocol: cfs
  CFSMountPath: "/mnt/cfs"      # CFS 挂载路径
  StoreDir: "corefiles"          # CFS 内的存储目录
  DeleteLocalCorefile: true

配置 Watcher Pod 的 volume 挂载（在 Helm values 中）：

corefileVolume:
  type: hostPath
  hostPath:
    path: /mnt/cfs                # 与 CFSMountPath 一致

values.yaml 必填配置

编辑 charts/values.yaml：

config:
  coredog: |-
    StorageConfig:
      # 存储协议选择
      protocol: s3                           # s3: S3/COS, cfs: CFS（默认 s3）
      
      # === 若使用 S3 或 COS 存储 ===
      s3AccesskeyID: "YOUR_ACCESS_KEY"
      s3SecretAccessKey: "YOUR_SECRET_KEY"
      s3Region: "ap-nanjing"
      S3Bucket: "your-bucket"
      S3Endpoint: "cos.ap-nanjing.myqcloud.com"  # COS 填这个，S3 填 S3 endpoint
      
      # === 若使用 CFS 存储 ===
      CFSMountPath: "/mnt/cfs"               # CFS 挂载路径
      
      # 通用配置
      StoreDir: corefiles                    # 存储目录
      DeleteLocalCorefile: true              # 上传后删除本地文件

  S3Bucket: "your-bucket"
  S3Endpoint: "cos.ap-nanjing.myqcloud.com"
  
  # 上传后删除本地文件（强烈推荐）
  DeleteLocalCorefile: true

# ⚠️ 通知渠道（至少配置一个）
NoticeChannel:
  - chan: wechat
    webhookurl: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"

# [可选] CoreSight 集成 - 自动分析 core dump
# CoreSight:
#   enabled: true
#   apiUrl: "http://coresight-api:8000"
#   token: "your-agent-token"

### 自定义处理器配置

CoreDog 支持在检测到 coredump 后执行自定义 shell 脚本，可选择性地替代默认的通知和 CoreSight 上报行为。

```yaml
CustomHandler:
  enabled: true                    # 启用自定义处理器
  timeout: 300                     # 脚本超时时间（秒）
  skipDefaultNotify: true          # 跳过默认通知（企业微信/Slack）
  skipCoreSight: true              # 跳过 CoreSight 上报
  script: |
    #!/bin/bash
    # 发送到自定义 webhook
    curl -X POST "https://your-api.com/coredump" \
      -H "Content-Type: application/json" \
      -d "{\"url\": \"$COREDUMP_URL\", \"pod\": \"$POD_NAMESPACE/$POD_NAME\"}"

可用环境变量：

变量	说明	示例
COREDUMP_FILE	本地文件路径	/corefile/core.bash.123
COREDUMP_URL	上传后的 URL	https://s3.xxx/corefiles/xxx
COREDUMP_FILENAME	文件名	core.bash.123
COREDUMP_MD5	文件 MD5	abc123...
COREDUMP_SIZE	文件大小（字节）	1234567
COREDUMP_EXECUTABLE	可执行文件路径	/usr/bin/bash
POD_NAME	Pod 名称	my-app-xxx
POD_NAMESPACE	命名空间	default
POD_UID	Pod UID	abc-123-xxx
POD_NODE_IP	节点 IP	10.0.0.1
POD_IMAGE	容器镜像	my-app:v1
POD_CONTAINER	容器名称	app
HOST_IP	宿主机 IP	10.0.0.1

注意：部分 Pod 信息（如 POD_IMAGE、POD_NODE_IP 等）在某些情况下可能为空。 脚本中建议使用 [ -z "$POD_IMAGE" ] 检查变量是否为空，或使用 ${POD_NAME:-unknown} 提供默认值。

Annotations 配置

Annotation	必填	说明	示例
coredog.io/inject	✅	是否开启注入	"true"
coredog.io/path	✅	Core dump 挂载路径	"/corefile"
coredog.io/container	❌	指定容器（逗号分隔），不填=所有容器	"app,worker"

路径安全限制

以下路径不允许使用（安全考虑）：

• /, /etc, /usr, /bin, /sbin, /var, /root, /home, /boot

推荐使用：

• /corefile ✅
• /data/dumps ✅
• /app/coredumps ✅

使用场景

场景 1: 单容器应用

metadata:
  annotations:
    coredog.io/inject: "true"
    coredog.io/path: "/corefile"
spec:
  containers:
  - name: app
    image: my-app:v1

场景 2: 多容器 Pod - 只监控特定容器

metadata:
  annotations:
    coredog.io/inject: "true"
    coredog.io/path: "/corefile"
    coredog.io/container: "gamesvr,dbproxy"  # 只监控业务容器
spec:
  containers:
  - name: gamesvr      # ✅ 会被注入
  - name: dbproxy      # ✅ 会被注入
  - name: nginx        # ❌ 不会被注入
  - name: metrics      # ❌ 不会被注入

场景 3: 自定义路径

metadata:
  annotations:
    coredog.io/inject: "true"
    coredog.io/path: "/data/dumps"  # 自定义路径
spec:
  containers:
  - name: app
    command:
      - bash
      - -c
      - |
        ulimit -c unlimited
        cd /data/dumps  # 确保路径一致
        exec /app/server

场景 4: 自定义处理器 - 发送到自定义系统

# values.yaml
config:
  coredog: |-
    # ... 存储配置 ...
    
    # 启用自定义处理器，替代默认通知
    CustomHandler:
      enabled: true
      skipDefaultNotify: true    # 不发送企业微信/Slack
      skipCoreSight: false       # 仍然上报 CoreSight
      timeout: 60
      script: |
        #!/bin/bash
        # 发送到内部告警系统
        curl -X POST "https://alert.internal.com/api/coredump" \
          -H "Authorization: Bearer $ALERT_TOKEN" \
          -H "Content-Type: application/json" \
          -d "{
            \"severity\": \"critical\",
            \"source\": \"coredog\",
            \"pod\": \"$POD_NAMESPACE/$POD_NAME\",
            \"node\": \"$POD_NODE_IP\",
            \"file_url\": \"$COREDUMP_URL\",
            \"executable\": \"$COREDUMP_EXECUTABLE\"
          }"

架构说明

Pod 创建 → Webhook 拦截 → 检查 annotations
                            ↓
                    inject=true 且 path 已设置？
                            ↓
                    注入 volume 和 volumeMount
                            ↓
                    hostPath: /data/coredog-system/dumps/<ns>/<pod>/
                    mountPath: <path annotation>
                            ↓
应用崩溃 → 生成 core dump → /data/coredog-system/dumps/<ns>/<pod>/core.xxx
                            ↓
                    Watcher 检测到文件
                            ↓
                    从路径解析: namespace + podname
                            ↓
                    上传到 S3 → 删除本地文件 → 发送通知

验证和测试

验证注入

# 创建测试 Pod
kubectl run test --image=ubuntu \
  --annotations="coredog.io/inject=true,coredog.io/path=/corefile" \
  -- sleep 3600

# 检查是否注入成功
kubectl get pod test -o yaml | grep -A 5 coredog-corefile

# 应该看到：
# - name: coredog-corefile
#   hostPath:
#     path: /data/coredog-system/dumps/default/test

测试收集

# 创建会崩溃的测试应用
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: crash-test
  annotations:
    coredog.io/inject: "true"
    coredog.io/path: "/corefile"
spec:
  containers:
  - name: app
    image: ubuntu:22.04
    command:
      - bash
      - -c
      - |
        ulimit -c unlimited
        sleep 5
        kill -11 \$\$  # 触发段错误
EOF

# 查看收集日志
kubectl logs -n coredog-system -l app.kubernetes.io/component=watcher -f

期望看到：

level=info msg="capture a file:/corefile/core.bash.xxx"
level=info msg="resolved pod from webhook path: default/crash-test"
level=info msg="deleted local corefile: /corefile/core.bash.xxx"

故障排查

Pod 未被注入

检查：

# 1. 查看 webhook 日志
kubectl logs -n coredog-system -l app.kubernetes.io/component=webhook

# 应该看到类似：
# Skip injection for pod default/my-pod - Reason: annotation coredog.io/path is required but not set

常见原因：

• ❌ 忘记添加 coredog.io/inject: "true"
• ❌ 忘记添加 coredog.io/path
• ❌ path 使用了危险路径（如 /etc）

Core Dump 未被检测

检查：

# 1. 验证节点配置
cat /proc/sys/kernel/core_pattern
# 应该是: /data/coredog-system/dumps/%E/%E.%p.%h.%t

# 2. 验证 ulimit
kubectl exec <pod> -c <container> -- bash -c "ulimit -c"
# 应该是: unlimited

# 3. 查看 watcher 日志
kubectl logs -n coredog-system -l app.kubernetes.io/component=watcher -f

Pod 信息识别失败

现象：通知显示 [/] core: xxx 而不是 [namespace/podname]

原因：路径格式不符合预期

解决：

• 确认 Pod 有正确的 annotations
• 确认 Webhook 正常工作
• 检查文件实际路径是否为 /data/coredog-system/dumps/<ns>/<pod>/core.xxx

本地文件未清理

检查：

# 查看配置
kubectl get cm -n coredog-system coredog -o yaml | grep DeleteLocalCorefile
# 应该是: true

# 查看日志中是否有删除记录
kubectl logs -n coredog-system -l app.kubernetes.io/component=watcher | grep "deleted local corefile"

通知配置

企业微信

NoticeChannel:
  - chan: wechat
    webhookurl: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
    keyword: ""  # 不过滤

Slack

NoticeChannel:
  - chan: slack
    webhookurl: "https://hooks.slack.com/services/xxx"

多渠道 + 过滤

NoticeChannel:
  # 所有环境
  - chan: wechat
    webhookurl: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=ALL"
    keyword: ""
  
  # 只通知生产环境
  - chan: wechat
    webhookurl: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=PROD"
    keyword: "production"

自定义消息

messageTemplate: |
  🚨 应用崩溃
  Pod: {pod.namespace}/{pod.name}
  节点: {pod.node}
  文件: {corefile.filename}
  下载: {corefile.url}

可用变量：

• {pod.namespace}, {pod.name}, {pod.uid}, {pod.node}
• {host.ip}
• {corefile.path}, {corefile.filename}, {corefile.url}

运维管理

查看已开启 CoreDog 的 Pod

kubectl get pods -A -o json | jq -r '.items[] | select(.metadata.annotations["coredog.io/inject"] == "true") | "\(.metadata.namespace)/\(.metadata.name)"'

批量开启

kubectl patch deployment my-app -p '{"spec":{"template":{"metadata":{"annotations":{"coredog.io/inject":"true","coredog.io/path":"/corefile"}}}}}'

升级

helm upgrade coredog ./charts -n coredog-system

卸载

helm uninstall coredog -n coredog-system
kubectl delete mutatingwebhookconfiguration coredog

文档

• 故障排查指南
• CoreSight 集成指南 - 可选：自动分析 core dump

许可证

Apache License 2.0