longhornio/support-bundle-kit

Longhorn Support Bundle Kit 镜像文档

1. 镜像概述和主要用途

Longhorn Support Bundle Kit 是 Longhorn 分布式存储系统的官方诊断工具镜像，用于快速收集集群中 Longhorn 组件的关键诊断信息（包括日志、配置数据、系统状态等），生成标准化的支持包（Support Bundle）。该工具旨在简化问题排查流程，帮助管理员或技术支持团队高效定位和解决 Longhorn 运行中的故障。

2. 核心功能和特性

2.1 自动信息收集

• 组件日志收集：自动抓取 Longhorn 核心组件（如 manager、engine、instance-manager、replica、ui）的运行日志。
• 配置数据采集：收集 Longhorn 相关的 Kubernetes 资源（CRD、ConfigMap、Secret、Deployment 等）及自定义配置。
• 系统状态记录：获取节点资源使用情况（CPU、内存、磁盘）、卷状态（健康状态、挂载信息）、网络连接性等集群状态数据。

2.2 灵活性与可定制性

• 支持通过参数或环境变量指定收集范围（如排除特定组件日志）。
• 可自定义支持包输出路径和文件名。
• 轻量级设计，无额外依赖，可直接在集群节点或外部环境运行。

2.3 易用性

• 无需手动编写采集脚本，通过简单命令即可生成完整支持包。
• 支持包自动压缩为 tar.gz 格式，便于传输和分析。

3. 使用场景和适用范围

3.1 故障排查

当 Longhorn 集群出现以下问题时，可使用本工具生成支持包：

• 卷挂载失败、数据读写异常或性能下降。
• 组件（如 manager、engine）崩溃或日志报错。
• 节点离线、副本故障导致的高可用失效。

3.2 日常维护

• 定期生成支持包进行健康检查，提前发现潜在风险。
• 版本升级前收集环境信息，确保兼容性。

3.3 技术支持协作

向 Longhorn 官方技术支持团队提交问题时，需附带本工具生成的支持包，以提供完整诊断上下文。

4. 使用方法和配置说明

4.1 前置条件

• 运行环境需安装 Docker（或兼容容器运行时）。
• 若在集群外运行，需挂载 Kubernetes 集群的 kubeconfig 文件（通常位于 ~/.kube/config）。
• 若在集群节点内运行，需确保容器有权限访问 Longhorn 数据目录（如 /var/lib/longhorn）和日志目录（如 /var/log/longhorn）。

4.2 基本使用命令

通过 docker run 命令直接运行镜像，核心是挂载必要的宿主机目录并配置环境变量。

4.3 挂载目录说明

4.4 环境变量配置

5. 部署方案示例

5.1 Docker Run 命令示例

在集群节点上运行（需挂载 Longhorn 数据/日志目录和输出目录）：

bash
docker run --rm \
  -v /var/lib/longhorn:/var/lib/longhorn \  # 挂载 Longhorn 数据目录
  -v /var/log/longhorn:/var/log/longhorn \  # 挂载 Longhorn 日志目录
  -v /tmp/support-bundle:/output \          # 挂载宿主机输出目录（自定义路径）
  -e NAMESPACE=longhorn-system \            # 指定 Longhorn 命名空间
  -e LOG_LEVEL=debug \                      # 开启调试日志（可选）
  -e SKIP_COMPONENTS=ui \                   # 排除 UI 组件日志（可选）
  longhornio/support-bundle-kit:latest      # 镜像名称（需替换为实际版本）

输出说明

执行成功后，支持包将生成在宿主机的 /tmp/support-bundle 目录下，文件名为 longhorn-support-bundle-<timestamp>.tar.gz（如 longhorn-support-bundle-202405201030.tar.gz）。

5.2 集群外运行（需挂载 kubeconfig）

若在集群外机器运行，需通过 kubeconfig 访问集群：

bash
docker run --rm \
  -v ~/.kube/config:/root/.kube/config \    # 挂载本地 kubeconfig
  -v /tmp/support-bundle:/output \          # 输出目录
  -e NAMESPACE=longhorn-system \
  longhornio/support-bundle-kit:latest

6. 注意事项

• 权限要求：容器需以 root 用户运行（默认），以确保有权限读取宿主机的日志和数据目录。
• 敏感信息：支持包可能包含集群配置（如 Secret 部分字段），传输时需注意加密。
• 版本匹配：建议使用与 Longhorn 集群版本一致的 Support Bundle Kit 镜像（如 Longhorn v1.5.1 对应镜像标签 v1.5.1）。
• 空间检查：确保输出目录所在磁盘有足够空间（支持包大小通常为几十 MB 到几百 MB，取决于日志量）。