Rook Toolbox 镜像文档

镜像概述和主要用途

Rook Toolbox 是 Rook 云原生存储编排器的配套工具镜像，集成了管理、诊断和维护 Rook/Ceph 存储集群所需的全套工具集。其核心用途是简化 Rook 集群的部署验证、日常运维操作、故障排查及性能调优，为管理员提供一站式的集群管理环境。

核心功能和特性

1. Ceph 原生工具集成

• 集群管理工具：ceph（集群状态管理）、rados（对象存储操作）、rbd（块存储管理）、cephfs（文件系统管理）、ceph-objectstore-tool（对象网关管理）等，支持 Ceph 集群全生命周期操作。
• 诊断工具：ceph-disk（磁盘管理）、ceph-volume（OSD 部署）、ceph-log（日志分析），支持集群健康检查与故障定位。

2. Rook 专用工具

• rookctl：Rook 集群管理命令行工具，支持集群配置、资源查询、运维操作（如创建存储池、扩容 OSD 等）。
• Rook 插件：集成与 Rook Operator 交互的接口，可直接获取集群部署状态、资源配置等元数据。

3. 系统与运维工具

• 系统工具：df（磁盘空间）、mount（挂载管理）、lsblk（块设备列表）、nc/telnet（网络测试），用于排查存储挂载与网络连通性。
• Kubernetes 集成：可选集成 kubectl 及 kubectl-rook-ceph 插件，支持直接在 Toolbox 中管理 K8s 集群内的 Rook 资源（需配置 K8s 集群访问权限）。

使用场景和适用范围

1. 集群部署验证

• 检查 Rook/Ceph 集群初始化状态（如 Mon/Mgr/OSD 守护进程健康性）。
• 验证存储资源可用性（如存储池创建、客户端密钥生成、挂载测试）。

2. 日常运维

• 集群状态监控：执行 ceph -s 查看集群健康状态、PG 分布、OSD 状态。
• 资源管理：创建/删除存储池（rados mkpool）、调整副本数（ceph osd pool set <pool> size <n>）。
• 性能监控：通过 ceph perf 采集性能指标（如 IOPS、延迟）。

3. 故障排查

• 日志分析：ceph log last 100 查看最近日志，定位 OSD 故障、PG 不一致等问题。
• 数据恢复：执行 ceph osd repair <osd-id> 修复损坏数据，或通过 rbd repair 恢复块设备。
• 网络诊断：测试 Mon/OSD 节点间网络连通性（如 telnet <mon-ip> 6789）。

4. 开发与测试

• 快速搭建本地 Rook/Ceph 管理环境，验证新配置（如自定义存储池策略、性能参数调优）。

详细使用方法和配置说明

环境准备

• 依赖：需访问 Rook/Ceph 集群的网络（如 Mon 节点 IP:Port）、集群配置文件（ceph.conf）及管理员密钥（client.admin.keyring）。
• 镜像版本：需与 Rook 集群版本匹配（如 Rook v1.12.x 对应 Toolbox 镜像 rook/ceph:v1.12.0）。

在 Docker 环境中使用（本地/非 K8s 场景）

适用于本地开发或独立部署的 Rook 集群，通过 Docker 直接运行 Toolbox 容器。

基础命令（交互式终端）

docker run -it --rm \
  --name rook-toolbox \
  --net=host  # 共享主机网络，确保能访问 Rook/Ceph 集群节点 \
  -v /path/to/ceph-config:/etc/ceph \  # 挂载 Ceph 配置目录（含 ceph.conf 和密钥） \
  -v /path/to/rook-data:/var/lib/rook \  # 挂载 Rook 数据目录（可选，用于持久化元数据） \
  -e ROOK_CLUSTER_NAMESPACE=my-rook-cluster \  # 指定 Rook 集群命名空间（若集群非默认命名空间） \
  rook/ceph:v1.12.0 toolbox  # 镜像版本需与 Rook 集群匹配

执行单次诊断命令

# 示例：检查集群状态
docker run --rm \
  -v /path/to/ceph-config:/etc/ceph \
  rook/ceph:v1.12.0 toolbox ceph -s

在 Kubernetes 环境中使用（推荐）

Rook 集群通常部署在 Kubernetes 中，Toolbox 需以 Pod 形式运行，通过 K8s 网络访问集群资源。

部署 Toolbox（Deployment 方式）

创建长期运行的 Toolbox Pod，用于日常运维：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rook-ceph-toolbox
  namespace: rook-ceph  # Rook 集群命名空间
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rook-ceph-toolbox
  template:
    metadata:
      labels:
        app: rook-ceph-toolbox
    spec:
      containers:
      - name: rook-ceph-toolbox
        image: rook/ceph:v1.12.0  # 镜像版本需与 Rook 集群匹配
        command: ["sleep", "365d"]  # 保持 Pod 长期运行
        volumeMounts:
        - name: ceph-config  # 挂载 Ceph 配置（含密钥和 mon 地址）
          mountPath: /etc/ceph
        - name: rook-data  # 挂载 Rook 数据目录（集群元数据）
          mountPath: /var/lib/rook
      volumes:
      - name: ceph-config
        secret:  # 从 K8s Secret 获取 Ceph 配置（Rook 自动创建）
          secretName: rook-ceph-mon
      - name: rook-data
        hostPath:  # 挂载主机 Rook 数据目录（需确保节点路径一致）
          path: /var/lib/rook
          type: DirectoryOrCreate

执行运维命令

通过 kubectl exec 进入 Toolbox Pod 执行操作：

# 进入 Toolbox 终端
kubectl -n rook-ceph exec -it deploy/rook-ceph-toolbox -- bash

# 检查集群状态
ceph -s

# 查看存储池列表
rados lspools

# 查看 OSD 状态
ceph osd tree

# 查看 PG 分布
ceph pg stat

一次性诊断任务（Job 方式）

对集群执行临时诊断（如日志采集、健康检查），可通过 K8s Job 运行：

apiVersion: batch/v1
kind: Job
metadata:
  name: rook-ceph-diagnose
  namespace: rook-ceph
spec:
  template:
    spec:
      containers:
      - name: diagnose
        image: rook/ceph:v1.12.0
        command: ["/bin/bash", "-c"]
        args:
          - ceph -s;  # 集群状态
            rados df;  # 存储池容量
            ceph health detail;  # 健康详情
        volumeMounts:
        - name: ceph-config
          mountPath: /etc/ceph
      volumes:
      - name: ceph-config
        secret:
          secretName: rook-ceph-mon
      restartPolicy: Never
  backoffLimit: 0  # 失败后不重试

查看诊断结果：

kubectl -n rook-ceph logs job/rook-ceph-diagnose

配置参数与环境变量

环境变量

挂载卷说明

部署示例

Docker 本地连接外部 Rook 集群

docker run -it --rm \
  --name rook-toolbox \
  -e ROOK_CLUSTER_NAMESPACE=my-rook-cluster \  # 自定义集群命名空间
  -v /local/path/to/ceph:/etc/ceph \  # 挂载本地 Ceph 配置（含密钥）
  -v /local/path/to/rook:/var/lib/rook \  # 挂载本地 Rook 数据目录
  --net=host \  # 共享主机网络，确保能访问 Rook 集群节点（Mon/OSD IP）
  rook/ceph:v1.12.0 toolbox

Kubernetes 长期运维 Deployment

见上文“部署 Toolbox（Deployment 方式）”配置示例，部署后可通过 kubectl exec 持续执行运维操作。

Kubernetes 一次性诊断 Job

见上文“一次性诊断任务（Job 方式）”配置示例，适用于临时健康检查或日志采集场景。