utils-container 镜像文档

镜像概述和主要用途

utils-container 是一个基于 debian:bookworm-slim 的轻量级 Docker 镜像，集成了多种系统管理和网络诊断工具，旨在为 Kubernetes (K8s) 环境提供便捷的故障排查能力。该镜像可快速部署到 K8s 集群中，帮助用户诊断网络连接、容器运行状态、资源占用等问题。

主要用途：适用于 K8s 集群内的故障排查与调试活动，包括网络连通性测试、容器日志分析、系统资源监控等场景。

核心功能和特性

基础特性

• 轻量级基础：基于 debian:bookworm-slim 构建，镜像体积小，资源占用低，适合在资源受限的 K8s 环境中部署
• 工具集成：包含网络诊断（如 curl、wget、ping、traceroute、tcpdump）、系统监控（如 top、htop、df、du）、DNS 解析（如 nslookup、dig）等多种常用排障工具
• 即开即用：无需额外配置，部署后可直接使用集成工具进行排查操作
• 兼容性好：兼容主流 K8s 版本，支持以 Pod 或 Job 形式在集群内运行

使用场景和适用范围

典型使用场景

• K8s 网络问题排查：诊断 Pod 间网络连通性、Service 访问异常、DNS 解析失败等网络故障
• 容器状态分析：检查容器内进程状态、文件系统挂载、环境变量配置等容器运行信息
• 资源使用监控：分析 CPU、内存、磁盘等资源的实时占用情况，定位资源瓶颈
• 应急故障处理：在集群出现异常时快速部署，进行现场诊断，无需在业务容器中预装工具

适用范围

• K8s 集群管理员和运维人员
• 开发人员在测试/生产环境排查容器化应用问题
• 需要临时分析集群状态的场景

使用方法和配置说明

1. 本地 Docker 环境使用

直接通过 docker run 命令启动容器：

docker run -it --rm nickytd/utils-container:latest

参数说明：

• -it：以交互模式运行并分配终端，支持命令行操作
• --rm：容器退出后自动删除，避免残留资源
• nickytd/utils-container:latest：镜像名称及标签（可替换为具体版本号）

2. Kubernetes 环境使用

2.1 通过 Pod 部署（长期运行）

创建 Pod 配置文件 debug-pod.yaml：

apiVersion: v1
kind: Pod
metadata:
  name: k8s-debug-pod
  namespace: default
spec:
  containers:
  - name: debug-container
    image: nickytd/utils-container:latest
    command: ["sleep", "3600"]  # 保持容器运行1小时（可根据需要调整时长）
  restartPolicy: Never

部署命令：

kubectl apply -f debug-pod.yaml

进入容器执行排查命令：

kubectl exec -it k8s-debug-pod -- /bin/bash

2.2 通过 Job 部署（一次性任务）

创建 Job 配置文件 debug-job.yaml：

apiVersion: batch/v1
kind: Job
metadata:
  name: k8s-debug-job
  namespace: default
spec:
  template:
    spec:
      containers:
      - name: debug-container
        image: nickytd/utils-container:latest
        command: ["/bin/bash", "-c", "tcpdump -i any -c 100; nslookup kubernetes.default.svc.cluster.local"]  # 替换为具体排查命令
      restartPolicy: Never
  backoffLimit: 0  # 任务失败后不重试

部署命令：

kubectl apply -f debug-job.yaml

查看任务执行日志：

kubectl logs job/k8s-debug-job

3. 自定义配置

如需扩展工具集，可基于该镜像构建自定义镜像，示例 Dockerfile：

FROM nickytd/utils-container:latest
RUN apt-get update && apt-get install -y <additional-tools>  # 添加额外工具

构建命令：

docker build -t custom-utils-container:latest .

注意事项

• 在生产环境使用时，建议限制该镜像的权限，避免赋予过多集群访问权限
• 排查完成后及时清理相关 Pod 或 Job 资源，避免资源浪费
• 对于长期运行的排查场景，可适当调整容器运行时长或使用 kubectl debug 命令直接注入目标 Pod 进行调试