longhornio/backing-image-manager

Longhorn Backing Image Manager 镜像文档

1. 镜像概述和主要用途

1.1 镜像概述

Longhorn Backing Image Manager 是 Longhorn 分布式存储系统的核心组件之一，专门用于管理 Longhorn 集群中的备份镜像（Backing Image）。该镜像提供了集中化的备份镜像生命周期管理能力，支持镜像的创建、上传、下载、版本控制及与 Longhorn 卷的集成，是 Longhorn 存储方案中实现卷快速配置、跨节点镜像共享和存储优化的关键组件。

2. 核心功能和特性

2.1 核心功能

• 备份镜像生命周期管理：支持备份镜像的上传（从本地文件或远程 URL）、下载（至本地或远程存储）、删除及元数据管理。
• 版本化控制：支持备份镜像的版本管理，可记录镜像的创建时间、大小、校验和等元数据，支持基于版本的镜像回滚。
• 存储优化：通过集中管理备份镜像，实现跨节点共享基础镜像，减少重复存储占用，提升集群存储利用率。
• 与 Longhorn 卷集成：无缝对接 Longhorn 卷创建流程，支持从备份镜像快速实例化卷，简化卷部署流程。
• 高可用性：支持镜像数据的多副本存储（需配合 Longhorn 集群配置），确保备份镜像的可靠性和故障恢复能力。

2.2 特性亮点

• 轻量级设计：基于 Golang 开发，容器化部署，资源占用低，适合 Kubernetes 环境集成。
• REST API 支持：提供 RESTful API 接口，支持外部系统（如 Longhorn UI、自动化脚本）调用管理功能。
• 灵活的存储适配：支持本地路径、NFS、S3 兼容对象存储等多种存储后端，用于持久化备份镜像数据。
• 完善的日志与监控：支持详细日志输出和 metrics 暴露，便于问题排查和性能监控。

3. 使用场景和适用范围

3.1 适用场景

• Longhorn 存储集群管理：在 Kubernetes 集群中使用 Longhorn 作为分布式存储方案时，需集中管理备份镜像的场景。
• 跨节点镜像共享：多节点 Kubernetes 集群中，需通过共享备份镜像减少重复存储（如多个卷使用相同基础镜像）的场景。
• 镜像版本化管理：需要对备份镜像进行版本控制，支持创建、删除、回滚特定版本镜像的场景（如开发/测试环境镜像迭代）。
• 卷快速部署：需从标准化备份镜像快速创建卷（如数据库初始化卷、应用基础环境卷）的场景。

3.2 适用范围

• 环境要求：Kubernetes 集群（v1.21+），Longhorn 存储系统（v1.3.0+）已部署并正常运行。
• 用户群体：Kubernetes 集群管理员、Longhorn 存储管理员、需要管理 Longhorn 备份镜像的 DevOps 工程师。

4. 详细使用方法和配置说明

4.1 前置条件

• 已部署 Kubernetes 集群（v1.21+），并确保集群网络通畅（节点间、Pod 间通信正常）。
• 已部署 Longhorn 存储系统（v1.3.0+），且 Longhorn Manager 服务正常运行，可通过 API 访问。
• 目标节点已安装 Docker 或容器运行时（如 containerd），并具备持久化存储路径（用于存放备份镜像数据）。

4.2 环境变量配置

4.3 Docker Run 命令示例

通过 docker run 直接运行容器，需挂载本地存储路径并配置 Longhorn API 地址：

bash
docker run -d \
  --name longhorn-backing-image-manager \
  --restart always \
  -p 8080:8080 \  # 暴露管理 API 端口（默认 8080）
  -v /data/longhorn-backing-images:/var/lib/longhorn/backing-images \  # 持久化存储路径
  -e LONGHORN_API_URL="http://longhorn-manager.longhorn-system.svc.cluster.local:9500" \  # Longhorn Manager API 地址
  -e BACKING_IMAGE_STORAGE_PATH="/var/lib/longhorn/backing-images" \  # 容器内存储路径（需与挂载路径一致）
  -e LOG_LEVEL="info" \
  longhornio/backing-image-manager:latest

4.4 Docker Compose 配置示例

创建 docker-compose.yml 文件，定义服务及依赖：

yaml
version: '3.8'

services:
  backing-image-manager:
    image: longhornio/backing-image-manager:latest
    container_name: longhorn-backing-image-manager
    restart: always
    ports:
      - "8080:8080"  # 管理 API 端口
    volumes:
      - /data/longhorn-backing-images:/var/lib/longhorn/backing-images  # 持久化存储
    environment:
      - LONGHORN_API_URL=http://longhorn-manager.longhorn-system.svc.cluster.local:9500  # Longhorn API 地址
      - BACKING_IMAGE_STORAGE_PATH=/var/lib/longhorn/backing-images  # 容器内存储路径
      - LOG_LEVEL=info  # 日志级别
      # 若使用 S3 后端存储，需添加以下配置：
      # - STORAGE_BACKEND_TYPE=s3
      # - S3_ENDPOINT=https://s3.example.com
      # - S3_ACCESS_KEY=AKIAEXAMPLE
      # - S3_SECRET_KEY=secretkeyexample
      # - S3_BUCKET=longhorn-backing-images

启动服务：

bash
docker-compose up -d

4.5 与 Longhorn 集群集成步骤

1. 验证服务状态：
   运行后，通过 curl http://<manager-ip>:8080/health 检查服务健康状态，返回 {"status": "ok"} 表示正常。

2. 注册到 Longhorn：
   在 Longhorn UI 中进入 Settings > General，配置 Backing Image Manager Endpoint 为 http://<manager-ip>:8080，保存后 Longhorn 将自动对接该管理器。

3. 管理备份镜像：

   • 通过 Longhorn UI 的 Backing Images 页面上传、删除镜像，或通过 API 调用（如 POST /v1/backing-images 上传镜像）。
   • 示例：通过 API 上传本地镜像文件：

     bash
     curl -X POST "http://<manager-ip>:8080/v1/backing-images" \
       -H "Content-Type: multipart/form-data" \
       -F "name=base-ubuntu-20.04" \
       -F "file=@/local/path/to/ubuntu-20.04-base.img"
     

4. 从镜像创建卷：
   在 Longhorn UI 中创建卷时，选择 Backing Image 下拉框，即可看到由管理器同步的备份镜像，选择后卷将基于该镜像初始化。

5. 注意事项

• 存储路径权限：确保宿主机挂载路径（如 /data/longhorn-backing-images）有足够权限（建议设置 755），避免容器内读写失败。
• Longhorn 版本兼容性：需使用与 Longhorn 集群版本匹配的 backing-image-manager 镜像（版本号与 Longhorn 一致，如 Longhorn v1.6.0 对应 longhornio/backing-image-manager:v1.6.0）。
• 网络隔离：若集群开启网络策略，需允许管理器 Pod 与 Longhorn Manager、其他节点间的通信（默认端口 9500、8080）。
• 数据备份：若使用本地存储后端，建议定期备份 BACKING_IMAGE_STORAGE_PATH 目录，避免数据丢失。