Kubernetes 통합 테스트는 GitLab Runner의 CI/CD 파이프라인에서 실행됩니다. 이 테스트는 GitLab Runner가 Kubernetes 클러스터와 올바르게 작동하는지 검증합니다. 테스트는 runner-Kubernetes-infra 리포지터리에서 관리하는 전용 Kubernetes 클러스터에서 실행됩니다.

테스트 인프라#

Runner Kubernetes 인프라 리포지터리#

테스트 인프라는 다음에 호스팅됩니다:

• 리포지터리: https://gitlab.com/gitlab-org/ci-cd/runner-tools/runner-kubernetes-infra
• 목적: GitLab Runner 통합 테스트를 위한 전용 Kubernetes 클러스터 관리
• 클러스터: GCP의 runner-k8s (프로젝트 세부 정보와 영역에 대해서는 내부 문서 참고)

인프라는 다운타임 없는 업데이트를 위해 두 개의 별도 클러스터로 구성된 블루-그린 배포 모델을 사용합니다.

클러스터 구성#

노드 풀, 리소스 제한, 오토스케일링 설정을 포함한 자세한 클러스터 구성은 인프라 리포지터리의 클러스터 구성 섹션을 참고하세요.

파이프라인 구조#

테스트 파이프라인 스테이지#

통합 테스트는 다음 GitLab CI/CD 스테이지를 통해 실행됩니다:

1. 통합 Kubernetes 프로비저닝 (provision integration kubernetes):

   • 테스트 전용 RBAC 리소스 프로비저닝
   • 서비스 어카운트 k8s-runner-integration-tests-runner-$CI_PIPELINE_ID 생성
   • mage k8s:provisionIntegrationKubernetes $CI_PIPELINE_ID 실행

2. 통합 테스트 작업 (병렬 실행):

   • integration kubernetes: 표준 통합 테스트
   • integration kubernetes exec legacy: 레거시 실행 전략 테스트
   • integration kubernetes attach: attach 실행 전략 테스트
   • integration kubernetes concrete: Concrete 모드(FF_CONCRETE) 네이티브 스텝 디스패치 테스트

3. 정리 (destroy integration kubernetes):

   • 테스트 전용 리소스 삭제
   • mage k8s:destroyIntegrationKubernetes $CI_PIPELINE_ID 실행

파이프라인 구성#

파이프라인은 .gitlab/ci/test-kubernetes-integration.gitlab-ci.yml에 정의되어 있습니다:

.integration kubernetes:
  extends:
    - .rules:merge_request_pipelines:no_docs:no-community-mr
  tags:
    - $KUBERNETES_RUNNER_INTEGRATION_TAG
  stage: test kubernetes integration
  variables:
    KUBERNETES_SERVICE_ACCOUNT_OVERWRITE: "k8s-runner-integration-tests-runner-$CI_PIPELINE_ID"

테스트 실행#

통합 테스트는 gotestsum을 사용하여 실행됩니다:

gotestsum --format=testname --format-hide-empty-pkg --rerun-fails=3 \
  --hide-summary=output --packages=gitlab.com/gitlab-org/gitlab-runner/executors/kubernetes \
  --junitfile=junit_report.xml --junitfile-hide-empty-pkg -- \
  -timeout=10m -parallel=20 $EXTRA_GO_TEST_FLAGS \
  -tags=integration,kubernetes ./executors/kubernetes/...

주요 파라미터:

• 타임아웃: 테스트당 10분
• 병렬 실행: 최대 20개 테스트 동시 실행
• 재시도 로직: 실패한 테스트는 최대 3번 재시도
• 빌드 태그: integration,kubernetes

테스트 범주#

표준 통합 테스트#

• 작업: integration kubernetes
• 목적: 주요 통합 테스트 스위트
• 기능 플래그: 기본 기능 플래그 구성 사용
• 필터: -skip=TestRunIntegrationTestsWithFeatureFlag로 기능 플래그별 테스트 제외

레거시 실행 전략 테스트#

• 작업: integration kubernetes exec legacy
• 기능 플래그: FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=true
• 필터: TestRunIntegrationTestsWithFeatureFlag만 실행
• 목적: 이전 버전과의 호환성 검증

Attach 전략 테스트#

• 작업: integration kubernetes attach
• 기능 플래그: FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY=false
• 필터: TestRunIntegrationTestsWithFeatureFlag만 실행
• 목적: 새로운 attach 기반 실행 전략 테스트

Concrete 모드 테스트#

• 작업: integration kubernetes concrete
• 기능 플래그: FF_CONCRETE=true
• 필터: TestRunIntegrationTestsWithFeatureFlag만 실행
• 목적: steps.Connector를 통해 라우팅되는 네이티브 스텝 디스패치 검증 (이 플래그에서 Build.UseNativeSteps()가 true를 반환합니다).

RBAC 및 권한#

동적 권한 프로비저닝#

프로비저닝 시스템(mage k8s:provisionIntegrationKubernetes)은 코드베이스를 분석하여 필요한 최소 RBAC 권한을 생성합니다:

1. 코드 분석: Kubernetes API 호출을 위해 /executors/kubernetes/를 스캔
2. 권한 생성: 필요한 권한만 포함된 role YAML 생성
3. 리소스 생성: 생성된 RBAC를 k8s-runner-integration-tests 네임스페이스에 적용

이 시스템은 테스트가 테스트 대상 코드와 동일한 권한을 사용하도록 보장합니다.

테스트별 서비스 어카운트#

각 파이프라인은 고유한 리소스를 생성합니다:

• 서비스 어카운트: k8s-runner-integration-tests-runner-$CI_PIPELINE_ID
• Role: 코드 분석을 기반으로 생성
• Role binding: 서비스 어카운트를 생성된 role에 연결

관리자 권한#

통합 테스트는 테스트 관리를 위한 관리자 RBAC도 사용합니다:

• 서비스 어카운트: integration-tests-admin
• 목적: 테스트 리소스 생성/삭제, 클러스터 상태 관찰
• 범위: 일반 러너 작업을 넘어선 추가 권한

테스트 구현#

테스트 환경#

테스트는 다음 환경 변수와 함께 실행됩니다:

• KUBERNETES_SERVICE_ACCOUNT_OVERWRITE: 파이프라인별 서비스 어카운트
• 기능 플래그 변수 (기능 플래그 테스트용)
• 클러스터 연결 세부 정보 (인프라에서 관리)

리소스 관리#

자동 정리#

인프라에는 자동 정리 메커니즘이 포함되어 있습니다. CronJob, 스케줄링 및 구성에 대한 자세한 내용은 인프라 리포지터리의 운영 자동화 섹션을 참고하세요.

리소스 격리#

테스트는 충돌을 방지하기 위해 리소스 그룹을 사용합니다:

• "$CI_COMMIT_REF_SLUG-k8s-integration"
• "$CI_COMMIT_REF_SLUG-k8s-integration-exec-legacy"
• "$CI_COMMIT_REF_SLUG-k8s-integration-attach"
• "$CI_COMMIT_REF_SLUG-k8s-integration-concrete"

모니터링 및 관측 가능성#

메트릭 및 로깅#

테스트 인프라에는 포괄적인 모니터링 및 로깅이 포함되어 있습니다. Grafana 액세스, Prometheus 대시보드, Loki를 이용한 로그 집계, 사용 가능한 make 명령에 대한 자세한 내용은 인프라 리포지터리의 메트릭 및 로그 수집 섹션을 참고하세요.

트러블슈팅#

일반적인 문제#

• 테스트 타임아웃:
  • 클러스터 리소스 가용성을 확인하세요.
  • 워커 풀 스케일링을 확인하세요 (0~6개 노드).
  • 테스트 병렬 처리 설정을 검토하세요.
• RBAC 권한:
  • 프로비저닝 작업이 성공했는지 확인하세요.
  • 서비스 어카운트 생성을 확인하세요.
  • 생성된 Role이 코드 요구 사항과 일치하는지 확인하세요.
• 리소스 충돌:
  • 리소스 그룹 격리를 확인하세요.
  • 정리 작업 실행을 확인하세요.
  • 파이프라인별 이름 지정을 검토하세요.

디버깅 단계#

1. 인프라 상태를 확인합니다. make 명령과 인프라 관리에 대한 자세한 내용은 블루-그린 배포를 참고하세요.

2. 테스트 로그를 검토합니다:

   • 특정 실패에 대한 파이프라인 작업 로그를 확인하세요.
   • 집계된 로그를 위해 Grafana 대시보드를 사용하세요. 자세한 내용은 로그 수집을 참고하세요.
   • 테스트별 이슈를 위해 gotestsum 출력을 검토하세요.

3. RBAC 검증:

   kubectl get sa,role,rolebinding -n k8s-runner-integration-tests
   kubectl describe role k8s-runner-integration-tests-runner-$CI_PIPELINE_ID -n k8s-runner-integration-tests
   

로컬에서 테스트 실행#

통합 테스트는 도달 가능한 모든 Kubernetes 클러스터를 대상으로 실행할 수 있습니다 (kubectl cluster-info가 성공해야 합니다). 클러스터에 도달할 수 없으면 테스트는 조용히 건너뛰므로, 클러스터가 없어도 하드 오류가 아니라 아무 동작도 하지 않습니다.

대부분의 로컬 개발에서는 유닛 테스트나 적절한 RBAC 설정을 갖춘 로컬 클러스터 (kind, minikube, Rancher Desktop)를 사용하세요. 전용 CI/CD 클러스터와 완전히 동등한 환경을 구성하려면 GKE 클러스터에 대한 액세스, 일치하는 RBAC 권한, CI/CD 환경 변수가 필요합니다.

매트릭스 모드 선택#

TestRunIntegrationTestsWithFeatureFlag는 매트릭스 CI/CD 작업마다 한 번씩 실행되는 동일한 테스트 스위트이며, 두 개의 환경 변수로 파라미터화됩니다. 특정 모드를 로컬에서 재현하려면:

CI_RUNNER_TEST_FEATURE_FLAG=FF_CONCRETE \
CI_RUNNER_TEST_FEATURE_FLAG_VALUE=true \
go test -tags=integration,kubernetes -timeout=30m -v \
  -run TestRunIntegrationTestsWithFeatureFlag \
  ./executors/kubernetes/...

integration kubernetes exec legacy 또는 integration kubernetes attach 작업을 각각 재현하려면 FF_USE_LEGACY_KUBERNETES_EXECUTION_STRATEGY(true 또는 false)로 대체하세요.

헬퍼 이미지 재정의#

기본적으로 픽스처는 헬퍼 이미지를(getTestBuild의 withDevHelperImage를 통해) 현재 파이프라인의 (development|bleeding|stable) docker images 작업에서 빌드된 이미지로 고정합니다. 로컬에서 CI_PROJECT_DIR이 설정되지 않은 경우, 픽스처는 러너에 컴파일된 기본 헬퍼 이미지로 폴백합니다.

특정 헬퍼 이미지(게시된 bleeding 태그, 로컬에서 빌드한 이미지 또는 디버깅 변형)를 대상으로 실행하려면 다음을 설정하세요:

CI_RUNNER_TEST_HELPER_IMAGE=registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:bleeding

이 재정의는 아티팩트 조회와 컴파일된 기본값 모두보다 우선합니다. 이를 통해 헬퍼 측 변경에 대한 반복 루프가 가능해집니다. 즉, 헬퍼 이미지를 로컬에서 빌드하고 테스트 클러스터가 가져올 수 있는 레지스트리에 푸시한 다음, CI_RUNNER_TEST_HELPER_IMAGE가 푸시된 태그를 가리키도록 하면 됩니다. CI/CD 파이프라인은 필요하지 않습니다.

기본 헬퍼 이미지에 steps 하위 명령이 없는 경우 FF_CONCRETE 실행에 필요합니다.

관련 항목#

• GitLab Runner Kubernetes executor
• Runner Kubernetes 인프라 리포지터리
• GitLab Runner Infrastructure Toolkit (GRIT)