kubeshop/testkube-api-server

Testkube Kubernetes API Server 镜像文档

一、镜像概述与主要用途

Testkube Kubernetes API Server 是 Testkube 测试平台的核心组件，作为系统的中枢神经系统，负责处理所有 API 请求，协调测试工作流的定义、触发、执行与结果收集。该组件连接 Testkube CLI、UI、CI/CD 工具与 Kubernetes 集群中的测试执行资源，实现测试编排与基础设施的解耦，支持在分布式环境中大规模运行各类测试任务。

二、核心功能与特性

2.1 核心功能

• API 请求处理：提供 RESTful API 接口，支持测试工作流定义、执行触发、结果查询等操作
• 测试执行协调：与 Kubernetes 资源（Pod、Job、CRD）交互，管理测试作业生命周期（创建、调度、终止）
• 测试工具集成：原生支持 K6、Playwright、JMeter、Cypress 等主流测试工具，兼容自定义测试脚本
• 结果收集与存储：聚合测试执行日志、生成 artifacts（视频、报告等），并持久化存储至指定后端
• 工作流编排：支持复杂测试套件定义，实现多步骤测试任务的串行/并行执行

2.2 关键特性

• Kubernetes 原生：基于 Kubernetes API 设计，利用原生调度、扩缩容能力
• 高可扩展性：支持水平扩展以应对大规模测试请求，通过自定义 Executor 扩展测试工具支持范围
• 安全集成：与 Kubernetes RBAC 集成，支持 API 认证（Token、OAuth2）与授权控制
• 多源触发：支持 CLI、API、CI/CD 工具、Kubernetes Event、定时任务等多种触发方式
• 轻量化设计：无状态架构，支持滚动更新与故障自动恢复

三、使用场景与适用范围

3.1 典型使用场景

• CI/CD 流水线集成：作为测试步骤嵌入 GitLab CI、GitHub Actions、Jenkins 等流水线，触发环境验证测试
• 多团队共享测试平台：提供集中式 API 入口，支持多项目/团队隔离的测试资源管理
• 复杂测试套件编排：构建系统测试、集成测试套件，协调多工具组合执行（如 JMeter 性能测试 + Cypress UI 测试）
• 大规模测试执行：利用 Kubernetes 节点分布式运行测试任务，支持数千并发测试用例
• 测试结果集中分析：统一收集测试日志与报告，对接 Grafana、Prometheus 实现可视化监控

3.2 适用范围

• 基于 Kubernetes 的应用开发/测试团队
• 需要标准化测试流程的中大型研发组织
• 依赖多测试工具的复杂应用系统（微服务、分布式架构）
• 对测试执行效率、可观测性有高要求的场景

四、使用方法与配置说明

4.1 前置要求

• Kubernetes 集群（v1.21+），具备集群管理员权限（生产环境）
• Docker 19.03+ 或容器运行时（开发/单机测试）
• 网络访问：允许 8080 端口（默认 API 端口）的入站流量

4.2 部署方式

4.2.1 Docker 单机运行（开发/测试）

bash
docker run -d \
  --name testkube-api-server \
  -p 8080:8080 \
  -v $HOME/.kube/config:/root/.kube/config \  # 挂载 K8s 配置（外部集群访问）
  -e KUBERNETES_CONFIG=/root/.kube/config \   # 指定 K8s 配置路径
  -e LOG_LEVEL=info \                         # 日志级别（debug/info/warn/error）
  -e API_PORT=8080 \                          # API 服务端口
  kubeshop/testkube-api-server:latest

4.2.2 Docker Compose 部署（含依赖组件）

yaml
version: "3.8"
services:
  api-server:
    image: kubeshop/testkube-api-server:latest
    ports:
      - "8080:8080"
    volumes:
      - $HOME/.kube/config:/root/.kube/config
    environment:
      - KUBERNETES_CONFIG=/root/.kube/config
      - LOG_LEVEL=info
      - API_PORT=8080
      - MONGODB_URI=mongodb://mongodb:27017/testkube  # 结果存储（可选外部 MongoDB）
    depends_on:
      - mongodb

  mongodb:  # 可选：本地 MongoDB 用于存储测试结果
    image: mongo:5.0
    ports:
      - "27017:27017"
    volumes:
      - mongodb-data:/data/db

volumes:
  mongodb-data:

4.2.3 Kubernetes Helm 部署（生产环境）

Testkube 官方推荐通过 Helm Chart 部署完整平台（含 API Server）：

bash
# 添加 Helm 仓库
helm repo add testkube https://kubeshop.github.io/helm-charts
helm repo update

# 安装 Testkube（含 API Server）
helm install testkube testkube/testkube \
  --namespace testkube \
  --create-namespace \
  --set apiServer.logLevel=info \
  --set apiServer.service.type=NodePort  # 或 LoadBalancer（根据集群网络配置）

4.3 配置参数详解

4.3.1 环境变量

4.3.2 命令行参数

可通过 docker run kubeshop/testkube-api-server --help 查看完整参数，常用参数：

bash
--api-port 8080              # 同环境变量 API_PORT
--log-level debug            # 同环境变量 LOG_LEVEL
--namespace testkube         # 同环境变量 NAMESPACE
--kubeconfig /root/.kube/config  # 同环境变量 KUBERNETES_CONFIG

4.4 验证部署

部署后可通过以下方式验证 API Server 可用性：

bash
# 检查服务状态
curl http://localhost:8080/health

# 预期响应（健康状态）
{"status":"ok","version":"v1.10.0"}  # 版本号随镜像更新变化

五、集成示例

5.1 与 Testkube CLI 集成

bash
# 配置 CLI 连接 API Server
testkube config set-context --api-uri http://localhost:8080

# 触发示例测试（需提前定义测试资源）
testkube run test my-test

5.2 CI/CD 流水线集成（GitHub Actions）

yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Testkube Test
        run: |
          curl -X POST "http://testkube-api-server:8080/v1/tests/my-test/execution" \
            -H "Content-Type: application/json" \
            -d '{"trigger": "github-actions", "params": {"ENV": "staging"}}'

六、故障排除

6.1 常见问题

• 问题：API Server 无法连接 Kubernetes 集群
  排查：检查 KUBERNETES_CONFIG 路径是否正确，或确认容器是否以 in-cluster 模式运行（需挂载 serviceaccount 令牌）。

• 问题：测试执行后无结果返回
  排查：检查 MONGODB_URI 配置，确保 MongoDB 服务可访问；查看 API Server 日志（docker logs testkube-api-server）定位存储错误。

• 问题：API 认证失败
  排查：确认 AUTH_ENABLED 与 JWT_SECRET 配置，检查请求头是否包含有效的 Authorization: Bearer <token>。

七、参考链接

• 官方文档：docs.testkube.io
• 测试定义指南：Defining Tests
• Helm Chart 配置：https://github.com/kubeshop/helm-charts/tree/main/charts/testkube