공유 서비스 모델에서 러너 플릿을 스케일링할 때 이러한 모범 사례와 권장 사항을 적용하세요.

인스턴스 러너 플릿을 호스팅할 때는 다음을 고려한 잘 계획된 인프라가 필요합니다:

• 컴퓨팅 용량
• 스토리지 용량
• 네트워크 대역폭 및 처리량
• 작업 유형(프로그래밍 언어, OS 플랫폼, 종속 라이브러리 포함)

이러한 권장 사항을 사용하여 조직의 요구 사항에 기반한 GitLab Runner 배포 전략을 개발하세요.

워크로드 및 환경 고려#

러너를 배포하기 전에 워크로드 및 환경 요구 사항을 고려하세요.

• GitLab에 온보딩할 계획인 팀 목록을 만드세요.
• 조직에서 사용하는 프로그래밍 언어, 웹 프레임워크, 라이브러리를 카탈로그화하세요. 예를 들어 Go, C++, PHP, Java, Python, JavaScript, React, Node.js.
• 각 팀이 시간당, 일당 실행할 수 있는 CI/CD 작업 수를 추정하세요.
• 컨테이너를 사용하여 해결할 수 없는 빌드 환경 요구 사항이 있는 팀이 있는지 확인하세요.
• 해당 팀에 전용된 러너를 보유하는 것이 가장 적합한 빌드 환경 요구 사항이 있는 팀이 있는지 확인하세요.
• 예상 수요를 지원하는 데 필요할 수 있는 컴퓨팅 용량을 추정하세요.

서로 다른 러너 플릿을 호스팅하기 위해 다른 인프라 스택을 선택할 수 있습니다. 예를 들어 일부 러너를 퍼블릭 클라우드에, 일부는 온프레미스에 배포해야 할 수 있습니다.

러너 플릿의 CI/CD 작업 성능은 플릿 환경과 직접 관련이 있습니다. 많은 수의 리소스 집약적인 CI/CD 작업을 실행하는 경우 공유 컴퓨팅 플랫폼에서 플릿을 호스팅하는 것은 권장되지 않습니다.

러너, 실행기, 자동 스케일링 기능#

gitlab-runner 실행 파일은 CI/CD 작업을 실행합니다. 각 러너는 작업 실행 요청을 받아 사전 정의된 구성에 따라 처리하는 격리된 프로세스입니다. 격리된 프로세스로서 각 러너는 작업을 실행하기 위해 "서브프로세스"(또는 "워커")를 만들 수 있습니다.

동시성 및 제한#

• 동시성(Concurrency): 호스트 시스템에서 구성된 모든 러너를 사용할 때 동시에 실행할 수 있는 작업 수를 설정합니다.
• 제한(Limit): 러너가 동시에 작업을 실행하기 위해 만들 수 있는 서브프로세스 수를 설정합니다.

제한은 자동 스케일링 러너(Docker Machine 및 Kubernetes 등)와 자동 스케일링하지 않는 러너에서 다릅니다.

• 자동 스케일링하지 않는 러너에서 limit은 호스트 시스템에서 러너의 용량을 정의합니다.
• 자동 스케일링 러너에서 limit은 총 실행할 러너 수입니다.

concurrency, limit, request_concurrency가 작업 흐름을 제어하기 위해 상호 작용하는 방법에 대한 자세한 내용은 GitLab Runner 동시성 조정에 관한 KB 문서를 참조하세요.

기본 구성: 하나의 러너 관리자, 하나의 러너#

가장 기본적인 구성의 경우 지원되는 컴퓨팅 아키텍처와 운영 체제에 GitLab Runner 소프트웨어를 설치합니다. 예를 들어 Ubuntu Linux를 실행하는 x86-64 가상 머신(VM)이 있을 수 있습니다.

설치가 완료되면 러너 등록 명령을 한 번만 실행하고 shell 실행기를 선택합니다. 그런 다음 러너 config.toml 파일을 편집하여 동시성을 1로 설정합니다.

concurrent = 1

[[runners]]
  name = "instance-level-runner-001"
  url = ""
  token = ""
  executor = "shell"

이 러너가 처리할 수 있는 GitLab CI/CD 작업은 러너를 설치한 호스트 시스템에서 직접 실행됩니다. 터미널에서 CI/CD 작업 명령을 직접 실행하는 것과 같습니다. 이 경우 등록 명령을 한 번만 실행했기 때문에 config.toml 파일에는 [[runners]] 섹션이 하나뿐입니다. 동시성 값을 1로 설정한 경우 이 시스템의 러너 프로세스에 대한 CI/CD 작업을 실행할 수 있는 러너 "워커"는 하나뿐입니다.

중간 구성: 하나의 러너 관리자, 여러 러너#

동일한 머신에 여러 러너를 등록할 수도 있습니다. 이렇게 하면 러너의 config.toml 파일에 여러 [[runners]] 섹션이 있습니다. 모든 추가 러너 워커가 shell 실행기를 사용하고 전역 concurrent 설정 값을 3으로 업데이트하면 호스트는 최대 세 개의 작업을 동시에 실행할 수 있습니다.

concurrent = 3

[[runners]]
  name = "instance_level_shell_001"
  url = ""
  token = ""
  executor = "shell"

[[runners]]
  name = "instance_level_shell_002"
  url = ""
  token = ""
  executor = "shell"

[[runners]]
  name = "instance_level_shell_003"
  url = ""
  token = ""
  executor = "shell"

동일한 머신에 많은 러너 워커를 등록할 수 있으며 각각은 격리된 프로세스입니다. 각 워커의 CI/CD 작업 성능은 호스트 시스템의 컴퓨팅 용량에 따라 달라집니다.

자동 스케일링 구성: 하나 이상의 러너 관리자, 여러 워커#

GitLab Runner가 자동 스케일링을 위해 설정된 경우 러너가 다른 러너의 관리자 역할을 하도록 구성할 수 있습니다. docker-machine 또는 kubernetes 실행기를 사용하여 이를 수행할 수 있습니다. 이러한 유형의 관리자 전용 구성에서 러너 에이전트 자체는 CI/CD 작업을 실행하지 않습니다.

Docker Machine 실행기#

Docker Machine 실행기를 사용하면:

• 러너 관리자가 Docker와 함께 온디맨드 가상 머신 인스턴스를 프로비저닝합니다.
• 이러한 VM에서 GitLab Runner는 .gitlab-ci.yml 파일에 지정한 컨테이너 이미지를 사용하여 CI/CD 작업을 실행합니다.
• 다양한 머신 유형에서 CI/CD 작업의 성능을 테스트해야 합니다.
• 속도 또는 비용을 기반으로 컴퓨팅 호스트를 최적화하는 것을 고려해야 합니다.

Kubernetes 실행기#

Kubernetes 실행기를 사용하면:

• 러너 관리자가 대상 Kubernetes 클러스터에서 Pod를 프로비저닝합니다.
• CI/CD 작업은 여러 컨테이너로 구성된 각 Pod에서 실행됩니다.
• 작업 실행에 사용되는 Pod는 일반적으로 러너 관리자를 호스팅하는 Pod보다 더 많은 컴퓨팅 및 메모리 리소스를 필요로 합니다.

러너 구성 재사용#

동일한 러너 인증 토큰과 연결된 각 러너 관리자에는 system_id 식별자가 할당됩니다. system_id는 러너가 사용되는 머신을 식별합니다. 동일한 인증 토큰으로 등록된 러너는 고유한 system_id에 의해 단일 러너 항목으로 그룹화됩니다.

유사한 러너를 단일 구성 아래에 그룹화하면 러너 플릿 운영이 간소화됩니다.

유사한 러너를 단일 구성 아래에 그룹화할 수 있는 예시 시나리오:

플랫폼 관리자는 태그 docker-builds-2vCPU-8GB를 사용하여 동일한 기본 가상 머신 인스턴스 크기(2 vCPU, 8 GB RAM)를 가진 여러 러너를 제공해야 합니다. 고가용성 또는 스케일링을 위해 최소 두 개의 러너를 원합니다. UI에서 두 개의 별개 러너 항목을 만드는 대신 관리자는 동일한 컴퓨팅 인스턴스 크기를 가진 모든 러너에 대해 하나의 러너 구성을 만들 수 있습니다. 러너 구성에 대한 인증 토큰을 재사용하여 여러 러너를 등록할 수 있습니다. 각 등록된 러너는 docker-builds-2vCPU-8GB 태그를 상속합니다. 단일 러너 구성의 모든 자식 러너에 대해 system_id는 고유 식별자 역할을 합니다.

그룹화된 러너는 여러 러너 관리자가 다른 작업을 실행하기 위해 재사용할 수 있습니다.

GitLab Runner는 시작 시 또는 구성이 저장될 때 system_id를 생성합니다. system_id는 config.toml과 동일한 디렉토리의 .runner_system_id 파일에 저장되며 작업 로그와 러너 관리 페이지에 표시됩니다.

system_id 식별자 생성#

system_id를 생성하기 위해 GitLab Runner는 하드웨어 식별자(예: 일부 Linux 배포판의 /etc/machine-id)에서 고유한 시스템 식별자를 파생시키려고 시도합니다. 성공하지 못하면 GitLab Runner는 system_id를 생성하기 위해 임의 식별자를 사용합니다.

system_id에는 다음 접두사 중 하나가 있습니다:

• r_: GitLab Runner가 임의 식별자를 할당했습니다.
• s_: GitLab Runner가 하드웨어 식별자에서 고유한 시스템 식별자를 할당했습니다.

이를 고려하는 것이 중요합니다. 예를 들어 컨테이너 이미지를 만들 때 system_id가 이미지에 하드코딩되지 않도록 합니다. system_id가 하드코딩된 경우 주어진 작업을 실행하는 호스트를 구별할 수 없습니다.

러너 및 러너 관리자 삭제#

러너 등록 토큰(사용 중단됨)으로 등록된 러너 및 러너 관리자를 삭제하려면 gitlab-runner unregister 명령을 사용하세요.

러너 인증 토큰으로 만들어진 러너 및 러너 관리자를 삭제하려면 UI 또는 API를 사용하세요. 러너 인증 토큰으로 만들어진 러너는 여러 머신에서 재사용할 수 있는 재사용 가능한 구성입니다. gitlab-runner unregister 명령을 사용하면 러너 관리자만 삭제되고 러너는 삭제되지 않습니다.

인스턴스 러너 구성#

자동 스케일링 구성(러너가 "러너 관리자" 역할을 하는)에서 인스턴스 러너를 사용하는 것은 효율적이고 효과적인 시작 방법입니다.

VM 또는 Pod를 호스팅하는 인프라 스택의 컴퓨팅 용량은 다음에 따라 달라집니다:

• 워크로드와 환경을 고려할 때 파악한 요구 사항
• 러너 플릿을 호스팅하는 데 사용하는 기술 스택

CI/CD 워크로드를 실행하고 시간이 지남에 따라 성능을 분석한 후 컴퓨팅 용량을 조정해야 할 수 있습니다.

자동 스케일링 실행기가 있는 인스턴스 러너를 사용하는 구성의 경우 최소 두 개의 러너 관리자로 시작해야 합니다.

시간이 지남에 따라 필요한 총 러너 관리자 수는 다음에 따라 달라집니다:

• 러너 관리자를 호스팅하는 스택의 컴퓨팅 리소스
• 각 러너 관리자에 대해 구성하도록 선택하는 동시성
• 각 관리자가 시간별, 일별, 월별로 실행하는 CI/CD 작업에 의해 생성되는 부하

예를 들어 GitLab.com에서 Docker Machine 실행기와 함께 일곱 개의 러너 관리자를 실행합니다. 각 CI/CD 작업은 Google Cloud Platform(GCP) n1-standard-1 VM에서 실행됩니다. 이 구성으로 월별 수백만 개의 작업을 처리합니다.

러너 모니터링#

러너 플릿을 대규모로 운영하는 데 필수적인 단계는 GitLab과 함께 제공되는 러너 모니터링 기능을 설정하고 사용하는 것입니다.

다음 표에는 GitLab Runner 메트릭 요약이 포함되어 있습니다. 목록에는 Go 특정 프로세스 메트릭이 포함되어 있지 않습니다. 러너에서 해당 메트릭을 보려면 사용 가능한 메트릭에 언급된 대로 명령을 실행하세요.

Grafana 대시보드 구성 팁#

이 공개 리포지터리에서 GitLab.com의 러너 플릿을 운영하는 데 사용하는 Grafana 대시보드의 소스 코드를 찾을 수 있습니다.

GitLab.com에 대한 많은 메트릭을 추적합니다. 클라우드 기반 CI/CD의 대형 공급자로서 이슈를 디버그하기 위해 시스템에 대한 다양한 뷰가 필요합니다. 대부분의 경우 셀프 매니지드 러너 플릿은 GitLab.com에서 추적하는 메트릭 볼륨을 추적할 필요가 없습니다.

대시보드 생성 프로세스#

Grafana는 JSON 형식만 허용하므로 jsonnet 파일을 JSON으로 변환해야 합니다.

runbooks 리포지터리에는 GitLab 인프라 전용 자동화 스크립트가 포함되어 있습니다. 자체 환경에 맞게 이러한 대시보드를 생성하려면:

1. jsonnet 구성 언어(.dashboard.jsonnet 파일)를 사용하여 대시보드를 만듭니다.
2. jsonnet 라이브러리로 jsonnet 파일을 처리하여 JSON 출력을 생성합니다.
3. 결과 JSON 파일을 Grafana에 업로드합니다(API 또는 UI 사용).

사용 가능한 러너 대시보드#

러너 플릿을 모니터링하는 데 사용해야 하는 몇 가지 필수 대시보드:

러너에서 시작된 작업:

• 선택한 시간 간격 동안 러너 플릿에서 실행된 총 작업 개요를 봅니다.
• 사용 추세를 확인합니다. 이 대시보드를 최소한 주 1회 분석해야 합니다.
• 이 데이터를 작업 지속 시간과 같은 메트릭과 연관시켜 CI/CD 작업 성능 SLO를 충족하기 위해 구성 변경 또는 용량 업그레이드가 필요한지 결정합니다.

작업 지속 시간:

• 러너 플릿의 성능 및 스케일링을 분석합니다.
• 성능 병목 현상과 최적화 기회를 식별합니다.

러너 용량:

• limit 또는 concurrent 값으로 나눈 실행 중인 작업 수를 봅니다.
• 추가 작업을 실행할 용량이 있는지 결정합니다.
• 사용률 추세를 기반으로 용량 업그레이드를 계획합니다.

추가 대시보드:

• 메인 대시보드(main.dashboard.jsonnet): 러너 인프라 및 HAProxy 메트릭 개요.
• 비즈니스 메트릭(business-stats.dashboard.jsonnet): 작업 통계, 완료된 작업 시간, 러너 포화도.
• 자동 스케일링 알고리즘(autoscaling-algorithm.dashboard.jsonnet): 자동 스케일링 동작 및 머신 상태 시각화.
• 대기열 개요(queuing-overview.dashboard.jsonnet): 작업 대기열 깊이 및 대기 시간.
• 요청 동시성(request-concurrency.dashboard.jsonnet): 동시 요청 분석.
• 배포(deployment.dashboard.jsonnet): 배포 관련 메트릭.
• 인시던트 대시보드: 자동 스케일링, 데이터베이스, 애플리케이션 및 러너 관리자 이슈 문제 해결을 위한 특수 대시보드.

각 대시보드에는 표시되는 메트릭을 설명하는 소스 jsonnet 파일의 설명과 컨텍스트가 포함되어 있습니다.

템플릿 변수#

대시보드는 Grafana 템플릿 변수를 사용하여 여러 컨텍스트에서 재사용 가능한 대시보드 템플릿을 만듭니다:

• 환경: 예를 들어 production, staging, development.
• 단계: 예를 들어 main, canary.
• 유형: 예를 들어 ci, verify. 사용 사례에 따라 다릅니다.
• 샤드: 선택 사항. 분산 러너 배포의 경우.

이러한 대시보드를 구현하는 조직은 자체 환경 구조에 맞게 이러한 변수를 조정해야 합니다. 가져온 후 Grafana 대시보드 설정에서 이러한 변수를 업데이트합니다.

지원되는 러너#

이러한 대시보드는 모든 GitLab Runner 실행기 유형과 함께 작동합니다:

• Kubernetes
• Shell
• VM (Docker Machine)
• Windows

메트릭 수집은 실행기에 독립적이며 모든 러너 플릿 유형에서 사용 가능합니다.

대시보드 사용자 정의#

환경에 맞게 대시보드를 수정하려면:

1. dashboards/ci-runners/ 디렉토리의 .dashboard.jsonnet 파일을 편집합니다.

2. Grafonnet 라이브러리 구문(jsonnet 기반)을 사용합니다.

3. 플레이그라운드를 사용하여 변경 사항을 테스트합니다:

   ./test-dashboard.sh dashboards/ci-runners/your-dashboard.dashboard.jsonnet
   

4. ./generate-dashboards.sh를 사용하여 재생성하고 배포합니다.

자세한 내용은 대시보드 확장에 관한 비디오 가이드를 참조하세요.

Kubernetes에서 러너 모니터링 시 고려 사항#

OpenShift, EKS, GKE와 같은 Kubernetes 플랫폼에서 호스팅되는 러너 플릿의 경우 Grafana 대시보드를 설정하는 데 다른 접근 방식을 사용합니다.

Kubernetes에서는 러너 CI/CD 작업 실행 Pod가 자주 만들어지고 삭제될 수 있습니다. 이러한 경우 러너 관리자 Pod를 모니터링하고 다음을 구현하는 것을 계획해야 합니다:

• 게이지: 다양한 소스의 동일한 메트릭의 집계를 표시합니다.
• 카운터: rate 또는 increase 함수를 적용할 때 카운터를 재설정합니다.

높은 카디널리티 메트릭#

일부 메트릭은 높은 카디널리티로 인해 수집하고 저장하는 데 리소스가 많이 필요할 수 있습니다. 높은 카디널리티는 메트릭에 많은 가능한 값을 가진 레이블이 포함될 때 발생하여 많은 수의 고유한 시계열 데이터 포인트를 초래합니다.

성능을 최적화하기 위해 이러한 메트릭은 기본적으로 활성화되어 있지 않으며 FF_EXPORT_HIGH_CARDINALITY_METRICS 기능 플래그를 사용하여 토글할 수 있습니다.

높은 카디널리티 메트릭 목록#

• gitlab_runner_job_stage_duration_seconds: 초 단위로 개별 작업 단계의 지속 시간을 측정합니다. 이 메트릭에는 다음과 같은 사전 정의된 값을 가질 수 있는 stage 레이블이 포함됩니다:

  • resolve_secrets
  • prepare_executor
  • prepare_script
  • get_sources
  • clear_worktree
  • restore_cache
  • download_artifacts
  • after_script
  • step_script
  • archive_cache
  • archive_cache_on_failure
  • upload_artifacts_on_success
  • upload_artifacts_on_failure
  • cleanup_file_variables

  또한 이 목록에는 step_run과 같은 사용자 정의 단계가 포함될 수 있습니다.

높은 카디널리티 메트릭 관리#

Prometheus 레이블 재지정 구성을 사용하여 불필요한 레이블 값이나 전체 메트릭을 제거함으로써 카디널리티를 제어하고 줄일 수 있습니다.

특정 단계를 제거하는 구성 예시#

다음 구성은 stage 레이블에서 prepare_executor 값이 있는 모든 메트릭을 제거합니다:

scrape_configs:
  - job_name: 'gitlab_runner_metrics'
    static_configs:
      - targets: ['localhost:9252']
    metric_relabel_configs:
      - source_labels: [__name__, "stage"]
        regex: "gitlab_runner_job_stage_duration_seconds;prepare_executor"
        action: drop

관련 단계만 유지하는 예시#

다음 구성은 step_script 단계의 메트릭만 유지하고 다른 메트릭은 완전히 삭제합니다:

scrape_configs:
  - job_name: 'gitlab_runner_metrics'
    static_configs:
      - targets: ['localhost:9252']
    metric_relabel_configs:
      - source_labels: [__name__, "stage"]
        regex: "gitlab_runner_job_stage_duration_seconds;step_script"
        action: keep