olm-csv-test 镜像文档

一、镜像概述和主要用途

概述

olm-csv-test 是一个用于 OLM（Operator Lifecycle Manager）环境中 CSV（ClusterServiceVersion）文件测试的制品镜像。它旨在提供轻量级工具集，支持 CSV 文件的语法验证、元数据合规性检查及与 OLM 兼容性测试，帮助开发者和运维团队在 Operator 部署前确保 CSV 文件的正确性。

主要用途

• 验证 CSV 文件的 YAML 语法规范性
• 检查 CSV 元数据（如版本、依赖、权限声明等）是否符合 OLM 规范
• 模拟 OLM 环境对 CSV 文件的解析过程，提前发现兼容性问题

二、核心功能和特性

核心功能

1. 语法验证：基于 JSON Schema 校验 CSV 文件的 YAML 结构合法性
2. 元数据检查：验证必填字段（如 metadata.name、spec.version、spec.provider 等）的存在性和格式
3. 兼容性测试：模拟不同 OLM 版本（v0.18+）对 CSV 文件的解析逻辑，输出兼容性报告
4. 依赖分析：检测 CSV 中声明的 Operator 依赖（如 spec.relatedImages、spec.required）是否完整

特性

• 轻量级：基于 Alpine 基础镜像，镜像体积 < 50MB
• 无状态：无需持久化存储，通过挂载文件或环境变量传入配置
• 可扩展：支持自定义校验规则（通过挂载额外 Schema 文件）

三、使用场景和适用范围

使用场景

1. Operator 开发阶段：开发者本地验证 CSV 文件修改后的正确性
2. CI/CD 流水线集成：作为构建步骤嵌入流水线，在 Operator 镜像构建前自动校验 CSV
3. OLM 部署前检查：在将 Operator 提交至 CatalogSource 前，验证 CSV 与目标集群 OLM 版本的兼容性

适用范围

• 目标用户：Kubernetes Operator 开发者、DevOps 工程师、OLM 运维团队
• 环境要求：支持 Docker 或容器运行时的 Linux/macOS 环境，Kubernetes 集群（可选，用于模拟部署）

四、使用方法和配置说明

基础使用流程

1. 准备待测试的 CSV 文件（本地路径，如 ./my-operator.csv.yaml）
2. 通过 docker run 命令挂载文件并执行测试
3. 查看输出日志，获取测试结果（通过/失败及具体错误信息）

Docker Run 命令示例

docker run -it --rm \
  -v $(pwd)/my-operator.csv.yaml:/test/csv.yaml \  # 挂载本地 CSV 文件到容器内/test目录
  -e CSV_PATH=/test/csv.yaml \                     # 指定容器内 CSV 文件路径
  -e OLM_VERSION=v0.24.0 \                         # 目标 OLM 版本（可选，默认 latest）
  olm-csv-test:latest                              # 镜像名称及标签

环境变量说明

配置参数

支持通过命令行参数覆盖环境变量配置，格式为 docker run ... olm-csv-test:latest [参数]。常用参数：

• --csv-path：同 CSV_PATH 环境变量
• --olm-version：同 OLM_VERSION 环境变量
• --version：输出镜像内置工具版本

示例（命令行参数优先）：

docker run -it --rm \
  -v $(pwd)/my-operator.csv.yaml:/test/csv.yaml \
  olm-csv-test:latest \
  --csv-path /test/csv.yaml \
  --olm-version v0.23.0 \
  --output-format json

五、部署方案示例

Docker Compose 配置

适用于本地多文件测试或集成到开发环境，示例 docker-compose.yml：

version: '3.8'
services:
  csv-test:
    image: olm-csv-test:latest
    volumes:
      - ./csv-files:/test/csv-files  # 挂载本地目录（含多个 CSV 文件）
    environment:
      - OLM_VERSION=v0.24.0
      - VALIDATION_MODE=strict
      - OUTPUT_FORMAT=json
    command: ["--csv-path", "/test/csv-files/operator-v1.2.0.csv.yaml"]  # 指定测试文件

启动命令：

docker-compose up

六、输出说明

测试完成后，容器将输出以下信息（以 text 格式为例）：

[INFO] Starting CSV test for /test/csv.yaml (OLM version: v0.24.0)
[PASS] YAML syntax validation
[PASS] Required fields check (metadata.name, spec.version, spec.provider)
[WARN] Optional field 'spec.maintainers' is missing (lenient mode: allowed)
[PASS] OLM v0.24.0 compatibility check
[INFO] Test completed: 3 passed, 1 warning

若为 json 格式，输出将包含结构化的 results 数组（含每个检查项的 status、message 和 severity）。