📚 课程目录第4章 operator-sdk scorecard基础

4. operator-sdk scorecard 基础：工作原理、配置文件与基本测试用例

scorecard 是 operator-sdk 内置的 Operator 发布包质量检查工具。它通过执行一组可配置的测试用例，验证 Operator 的元数据、部署行为、权限模型和集群兼容性，是 Operator 发布前必须通过的“准入关卡”。

4.1 scorecard 工作原理

scorecard 采用“测试镜像 + 临时命名空间”的沙箱执行模型，确保每次检查的隔离性和可重复性。

  核心执行流程：
  加载配置：读取 config.yaml，解析测试阶段（stage）和测试用例列表。
构建测试镜像：将 Operator 的 bundle 内容打包为临时测试镜像，注入测试入口。
创建临时命名空间：在目标集群中创建随机命名的命名空间，用于部署和测试。
执行测试阶段：按配置顺序运行每个 stage 下的测试用例，每个用例在独立 Pod 中执行。
收集结果：汇总每个测试用例的通过/失败/错误状态，生成 JSON 或人类可读报告。
清理资源：删除临时命名空间和测试镜像，释放集群资源。

4.2 配置文件（config.yaml）结构

scorecard 的配置文件通常位于 bundle/tests/scorecard/config.yaml，采用 YAML 格式定义测试阶段和测试用例。一个典型的配置文件包含以下顶层字段：

字段	类型	说明	是否必填
`kind`	string	固定为 `Configuration`	是
`apiversion`	string	固定为 `scorecard.operatorframework.io/v1alpha3`	是
`metadata`	object	包含 `name` 和 `labels`，用于标识配置	是
`stages`	array	测试阶段列表，每个阶段包含一组测试用例	是

每个 stage 对象的结构如下：

字段	类型	说明
`name`	string	阶段名称，如 `basic`、`olm`
`description`	string	阶段描述，用于报告输出
`labels`	object	标签选择器，用于过滤测试用例
`tests`	array	测试用例列表，每个用例包含 `name`、`description`、`labels`、`entrypoint`、`kubeconfig` 等字段

最佳实践：建议将测试分为 basic（基础检查）和 olm（OLM 集成检查）两个阶段。basic 阶段验证 Operator 能否正常启动和响应，olm 阶段验证 Operator 在 OLM 框架下的安装、升级和依赖解析。

4.3 基本测试用例编写

每个测试用例的核心是 entrypoint 字段，它定义了测试执行的命令和参数。以下是一个完整的 config.yaml 示例：

kind: Configuration
apiversion: scorecard.operatorframework.io/v1alpha3
metadata:
  name: scorecard-config
  labels:
    app.kubernetes.io/part-of: my-operator

stages:
- name: basic
  description: 基础部署与功能检查
  labels:
    stage: basic
  tests:
  - name: operator-deployment-check
    description: 验证 Operator 部署是否成功
    labels:
      test-type: deployment
    entrypoint:
    - scorecard-test
    - basic-check
    kubeconfig: /kubeconfig
    cleanup:
      enabled: true
      timeout: 30

  - name: crd-existence-check
    description: 验证 CRD 是否已注册到集群
    labels:
      test-type: crd
    entrypoint:
    - scorecard-test
    - crd-check
    kubeconfig: /kubeconfig

- name: olm
  description: OLM 集成检查
  labels:
    stage: olm
  tests:
  - name: olm-integration-check
    description: 验证 OLM 安装与依赖解析
    labels:
      test-type: olm
    entrypoint:
    - scorecard-test
    - olm-check
    kubeconfig: /kubeconfig
    storage:
      spec:
        mountPath: /tmp/storage
        emptyDir: {}

4.4 测试用例关键字段详解

字段	说明	示例值
`entrypoint`	测试入口命令和参数，数组形式	`["scorecard-test", "basic-check"]`
`kubeconfig`	测试 Pod 内 kubeconfig 的挂载路径	`/kubeconfig`
`cleanup`	测试结束后是否清理资源及超时时间	`enabled: true; timeout: 30`
`storage`	测试 Pod 的临时存储挂载配置	`spec: { mountPath: "/tmp/storage", emptyDir: {} }`
`labels`	用于过滤和分组的自定义标签	`test-type: deployment`

注意：entrypoint 中的命令必须在测试镜像内可执行。operator-sdk 提供了内置的 scorecard-test 二进制，支持 basic-check、crd-check、olm-check 等子命令。如果使用自定义测试镜像，需要确保入口脚本或二进制存在。

4.5 运行 scorecard 与查看结果

在 Operator 项目根目录执行以下命令运行 scorecard：

# 运行所有测试阶段
operator-sdk scorecard --config bundle/tests/scorecard/config.yaml \
  --kubeconfig ~/.kube/config \
  --namespace test-ns

# 仅运行 basic 阶段
operator-sdk scorecard --config bundle/tests/scorecard/config.yaml \
  --selector stage=basic

# 输出 JSON 格式结果
operator-sdk scorecard --config bundle/tests/scorecard/config.yaml \
  --output json > scorecard-result.json

scorecard 的输出包含每个测试用例的详细状态：

状态	含义	后续操作
pass	测试通过	无需处理
fail	测试未通过，Operator 存在缺陷	查看日志，修复问题后重新测试
error	测试执行过程中出现异常	检查配置、集群状态或测试镜像
skip	测试被跳过（标签不匹配或条件不满足）	确认标签选择器是否正确

4.6 常见问题与避坑指南

kubeconfig 权限不足：scorecard 测试 Pod 默认使用 /kubeconfig 路径，确保该文件具有创建、删除资源的权限。
测试镜像拉取失败：如果使用私有镜像仓库，需要在 config.yaml 中配置 imagePullSecrets。
测试超时：Operator 启动较慢时，适当增加 cleanup.timeout 或测试用例的 timeout 字段。
标签选择器不匹配：使用 --selector 过滤时，确保标签键值对与 config.yaml 中的 labels 完全一致。
自定义测试镜像：如果使用非默认的测试镜像，需要在 config.yaml 的 tests 中指定 image 字段。

  核心要点回顾：
  scorecard 通过“测试镜像 + 临时命名空间”实现隔离执行。
config.yaml 是 scorecard 的“剧本”，定义阶段和测试用例。
每个测试用例的核心是 entrypoint，它决定了测试逻辑。
测试结果分为 pass、fail、error、skip 四种状态。
建议将测试分为 basic 和 olm 两个阶段，分别覆盖基础功能和 OLM 集成。