puzzle/k8s-debugbox

k8s-debugbox

镜像概述

k8s-debugbox是一款基于最小镜像的Kubernetes Pod调试工具，通过向目标Pod复制静态链接的调试工具（包括shell）实现调试功能，适用于排查基于最小镜像的Pod问题。

核心功能

• 向指定Pod或控制器（如Deployment、StatefulSet等）添加/移除调试工具
• 针对Pod的特定容器打开调试shell
• 兼容kubectl（Kubernetes客户端）和oc（OpenShift客户端）
• 对控制器操作时自动触发重新部署（OpenShift DeploymentConfig可禁用）

使用场景

• 调试Kubernetes集群中无内置调试工具的最小镜像Pod
• 临时向Pod添加调试工具进行问题排查
• 对控制器管理的批量Pod安装/移除调试工具

配置说明

环境要求

• Kubernetes集群：无特殊要求
• 客户端：Bash 3及以上版本、kubectl或oc客户端（Windows需安装Cmdr或WSL）

安装步骤

1. 从https://github.com/puzzle/k8s-debugbox/releases%E4%B8%8B%E8%BD%BD%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC
2. 解压下载的文件
3. 进入解压后的目录
4. 运行install.sh（Windows系统运行install.bat）

使用示例

sh
# 为指定Pod的第一个容器打开调试shell（自动安装工具）
k8s-debugbox pod hello-42-dmj88

# 为指定Pod的proxy容器打开调试shell
k8s-debugbox pod hello-42-dmj88 -c proxy

# 向指定Pod安装调试工具
k8s-debugbox pod hello-42-dmj88 --add

# 从指定Deployment移除调试工具（需重新部署）
k8s-debugbox deployment hello --remove

Docker部署示例（作为Init Container）

yaml
apiVersion: v1
kind: Pod
metadata:
  name: debug-demo-pod
spec:
  initContainers:
  - name: debugbox-init
    image: puzzle/k8s-debugbox
    command: ["sh", "-c", "cp /tools/* /debug-tools/"]
    volumeMounts:
    - name: debug-vol
      mountPath: /debug-tools
  containers:
  - name: app-container
    image: alpine:3.18
    command: ["sleep", "infinity"]
    volumeMounts:
    - name: debug-vol
      mountPath: /usr/local/bin
  volumes:
  - name: debug-vol
    emptyDir: {}

开发说明

若需开发k8s-debugbox，需克隆https://github.com/puzzle/k8s-debugbox%EF%BC%8C%E8%BF%9B%E5%85%A5%E7%9B%AE%E5%BD%95%E5%B9%B6%E8%BF%90%E8%A1%8C%60bootstrap.sh%60%E8%84%9A%E6%9C%AC%EF%BC%8C%E8%AF%A5%E8%84%9A%E6%9C%AC%E4%BC%9A%E9%80%9A%E8%BF%87curl%E4%B8%8B%E8%BD%BD%E9%9D%99%E6%80%81%E7%BC%96%E8%AF%91%E7%9A%84%E8%B0%83%E8%AF%95%E5%B7%A5%E5%85%B7%E3%80%82