gitlab/gitlab-agent-ci-image

gitlab-kas-agent-ci-image

镜像概述和主要用途

gitlab-kas-agent-ci-image 是专为 GitLab KAS (Kubernetes Agent Server) Agent 开发的 CI (持续集成) 专用镜像。其核心用途是在自动化流程中对 GitLab KAS Agent 的代码变更、功能更新进行验证和测试，确保 Agent 与 KAS Server 的兼容性、功能正确性及稳定性。

核心功能和特性

1. 完整测试工具链集成
   预安装 GitLab KAS Agent 测试所需的全套依赖（如 Go 编译器、测试框架、Kubernetes 客户端工具、API 模拟工具等），无需额外配置即可启动测试流程。

2. 多维度测试支持
   支持单元测试（验证 Agent 核心逻辑）、集成测试（验证 Agent 与 KAS Server 交互）、兼容性测试（验证不同 KAS 版本适配性）及 E2E 测试（模拟真实环境下的 Agent 全流程运行）。

3. GitLab CI/CD 原生兼容
   镜像结构和环境变量设计符合 GitLab CI/CD 规范，可直接集成到 GitLab 项目的 .gitlab-ci.yml 配置中，实现提交/合并请求触发的自动化测试。

4. 环境隔离与一致性
   标准化测试环境，避免因本地环境差异导致的测试结果不一致问题，确保团队内测试流程统一。

使用场景和适用范围

• 开发阶段验证：开发人员提交代码或创建合并请求时，自动运行测试，快速反馈代码质量和功能问题。
• 版本发布前测试：在 KAS Agent 版本发布前，通过全量测试（单元+集成+E2E）验证稳定性和兼容性。
• 跨版本兼容性验证：针对 GitLab 不同版本的 KAS Server，验证 Agent 的适配性。
• 故障复现与调试：在 CI 环境中复现特定测试场景，辅助定位 Agent 运行时问题。

使用方法和配置说明

前提条件

• 已配置 GitLab CI/CD Runner（支持 Docker 执行环境）。
• 拥有 GitLab 项目访问权限（需获取 API 令牌用于测试流程）。
• 目标 KAS Server 已部署并可访问（用于集成测试和 E2E 测试）。

1. GitLab CI/CD 配置示例

在项目根目录的 .gitlab-ci.yml 中引用该镜像，配置测试阶段：

yaml
stages:
  - test

variables:
  # 基础环境变量（根据实际情况调整）
  GITLAB_TOKEN: "${CI_JOB_TOKEN}"  # 使用 CI 内置令牌（默认具备项目访问权限）
  KAS_URL: "https://kas.gitlab.example.com"  # 目标 KAS Server 地址
  TEST_TIMEOUT: "30m"  # 测试超时时间

unit-test:
  stage: test
  image: gitlab-kas-agent-ci-image:latest  # 引用 CI 镜像
  script:
    - echo "Running unit tests..."
    - go test ./internal/... -v -timeout ${TEST_TIMEOUT}  # 运行单元测试

integration-test:
  stage: test
  image: gitlab-kas-agent-ci-image:latest
  variables:
    TEST_MODE: "integration"  # 指定测试模式为集成测试
  script:
    - echo "Running integration tests with KAS Server: ${KAS_URL}"
    - go test ./integration/... -v -kas-url ${KAS_URL} -timeout ${TEST_TIMEOUT}

e2e-test:
  stage: test
  image: gitlab-kas-agent-ci-image:latest
  variables:
    TEST_MODE: "e2e"  # 指定测试模式为 E2E 测试
    K8S_CLUSTER_CONFIG: "${KUBE_CONFIG}"  # （可选）E2E 测试需提供 K8s 集群配置
  script:
    - echo "Running E2E tests..."
    - go test ./e2e/... -v -kas-url ${KAS_URL} -kubeconfig <(echo ${K8S_CLUSTER_CONFIG}) -timeout ${TEST_TIMEOUT}

2. 手动运行测试（本地调试用）

若需在本地手动触发测试，通过 docker run 命令启动容器：

bash
docker run -it --rm \
  -e GITLAB_TOKEN="your_personal_access_token" \
  -e KAS_URL="https://kas.gitlab.example.com" \
  -e TEST_MODE="unit" \
  -e TEST_TIMEOUT="10m" \
  -v $(pwd):/app \  # 挂载本地代码目录到容器内
  gitlab-kas-agent-ci-image:latest \
  /bin/bash -c "cd /app && go test ./internal/... -v -timeout \${TEST_TIMEOUT}"

配置参数与环境变量

以下环境变量用于控制测试流程，可在 CI/CD 配置或手动运行时指定：

注意事项

1. 网络权限：CI Runner 需能访问目标 KAS Server 和 GitLab API（若使用自定义 GITLAB_TOKEN）。
2. 资源需求：E2E 测试需较高 CPU/内存资源（建议 Runner 配置 ≥2 CPU 核心、4GB 内存）。
3. 令牌安全：GITLAB_TOKEN 建议通过 GitLab CI/CD 「变量」功能加密存储（勾选「保护变量」和「掩码变量」）。
4. 版本匹配：建议镜像标签与 KAS Agent 目标版本保持一致（如 gitlab-kas-agent-ci-image:v16.0.0），避免兼容性问题。