https://github.com/yafeiaa/coredog
🐶Coredog is an open-source project designed to monitor and manage core dumps in a Kubernetes cluster. It automatically detects core files generated by applications running in the cluster, uploads them to an S3-compatible object storage system, and provides pre-signed S3 download links to all developers through instant messaging software.
https://github.com/yafeiaa/coredog
corefile kubernetes monitor
Last synced: 5 months ago
JSON representation
🐶Coredog is an open-source project designed to monitor and manage core dumps in a Kubernetes cluster. It automatically detects core files generated by applications running in the cluster, uploads them to an S3-compatible object storage system, and provides pre-signed S3 download links to all developers through instant messaging software.
- Host: GitHub
- URL: https://github.com/yafeiaa/coredog
- Owner: yafeiaa
- License: mit
- Created: 2024-03-28T03:50:08.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-21T12:09:11.000Z (almost 2 years ago)
- Last Synced: 2025-04-14T01:32:06.363Z (about 1 year ago)
- Topics: corefile, kubernetes, monitor
- Language: Go
- Homepage: https://hub.docker.com/r/coderflyfyf/coredog
- Size: 313 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CoreDog 🐶
Kubernetes Core Dump 自动收集系统
## 简介
CoreDog 在应用崩溃时自动收集 core dump 文件，上传到对象存储，并发送通知。
**核心特性**：
- 🎯 Webhook 自动注入 volume（opt-in，通过 annotation 开启）
- 🔍 精准识别崩溃的 Pod 和容器
- 📦 自动上传到 S3/COS/OSS
- 🧹 上传后自动清理本地文件
- 🔔 企业微信/Slack 即时通知
- 🔗 [可选] 自动上报到 CoreSight，触发自动分析
## 快速开始
### 1. 安装 CoreDog
```bash
# 编辑配置
vim charts/values.yaml
# 填写 S3 凭证和通知渠道（见下方配置说明）
# 安装
helm install coredog ./charts -n coredog-system --create-namespace
```
### 2. 配置节点
**在每个 Kubernetes 节点上执行**：
```bash
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///core.xxx`
### 3. 应用接入
在您的应用 Deployment/StatefulSet 中添加 annotations：
```yaml
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 配置示例
```yaml
StorageConfig:
protocol: s3
s3AccesskeyID: "your_ak"
s3SecretAccessKey: "your_sk"
s3Region: "us-east-1"
S3Bucket: "my-bucket"
S3Endpoint: "s3.amazonaws.com"
```
#### COS 配置示例
```yaml
StorageConfig:
protocol: cos
s3AccesskeyID: "your_ak"
s3SecretAccessKey: "your_sk"
s3Region: "ap-nanjing"
S3Bucket: "my-bucket-1234567890"
S3Endpoint: "cos.ap-nanjing.myqcloud.com"
```
#### CFS 配置示例
**前置条件**：CFS 已挂载到集群节点
```yaml
StorageConfig:
protocol: cfs
CFSMountPath: "/mnt/cfs" # CFS 挂载路径
StoreDir: "corefiles" # CFS 内的存储目录
DeleteLocalCorefile: true
```
**配置 Watcher Pod 的 volume 挂载**（在 Helm values 中）：
```yaml
corefileVolume:
type: hostPath
hostPath:
path: /mnt/cfs # 与 CFSMountPath 一致
```
### values.yaml 必填配置
编辑 `charts/values.yaml`：
```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: 单容器应用
```yaml
metadata:
annotations:
coredog.io/inject: "true"
coredog.io/path: "/corefile"
spec:
containers:
- name: app
image: my-app:v1
```
### 场景 2: 多容器 Pod - 只监控特定容器
```yaml
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: 自定义路径
```yaml
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: 自定义处理器 - 发送到自定义系统
```yaml
# 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///
mountPath:
↓
应用崩溃 → 生成 core dump → /data/coredog-system/dumps///core.xxx
↓
Watcher 检测到文件
↓
从路径解析: namespace + podname
↓
上传到 S3 → 删除本地文件 → 发送通知
```
## 验证和测试
### 验证注入
```bash
# 创建测试 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
```
### 测试收集
```bash
# 创建会崩溃的测试应用
cat < -c -- 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///core.xxx`
### 本地文件未清理
**检查**：
```bash
# 查看配置
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"
```
## 通知配置
### 企业微信
```yaml
NoticeChannel:
- chan: wechat
webhookurl: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
keyword: "" # 不过滤
```
### Slack
```yaml
NoticeChannel:
- chan: slack
webhookurl: "https://hooks.slack.com/services/xxx"
```
### 多渠道 + 过滤
```yaml
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"
```
### 自定义消息
```yaml
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
```bash
kubectl get pods -A -o json | jq -r '.items[] | select(.metadata.annotations["coredog.io/inject"] == "true") | "\(.metadata.namespace)/\(.metadata.name)"'
```
### 批量开启
```bash
kubectl patch deployment my-app -p '{"spec":{"template":{"metadata":{"annotations":{"coredog.io/inject":"true","coredog.io/path":"/corefile"}}}}}'
```
### 升级
```bash
helm upgrade coredog ./charts -n coredog-system
```
### 卸载
```bash
helm uninstall coredog -n coredog-system
kubectl delete mutatingwebhookconfiguration coredog
```
## 文档
- [故障排查指南](docs/troubleshooting.md)
- [CoreSight 集成指南](CORESIGHT_INTEGRATION.md) - 可选：自动分析 core dump
## 许可证
Apache License 2.0