공유 러너 플리트의 계획 및 운영

이 안내서에는 공유 서비스 모델에서 러너 플리트를 확장하는 데 관한 모범 사례가 포함되어 있습니다.

공유 러너 플리트를 호스팅할 때는 다음 사항을 고려한 잘 계획된 인프라가 필요합니다.

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

회사의 요구 사항에 기반을 둔 GitLab 러너 배포 전략을 개발하기 위해 이 가이드를 사용하세요.

이 가이드는 사용해야 하는 인프라 유형에 대해 구체적인 권장 사항을 제공하지는 않지만, 매월 수백만 개의 CI/CD 작업을 처리하는 GitLab.com에서 러너 플리트를 운영하는 경험을 바탕으로 통찰을 제공합니다.

작업 부하 및 환경 고려

러너를 배포하기 전에 작업 부하 및 환경 요구 사항을 고려해야 합니다.

  • GitLab에 추가할 팀 디렉터리을 작성합니다.
  • 회사에서 사용 중인 프로그래밍 언어, 웹 프레임워크 및 라이브러리를 디렉터리화합니다. 예: Go, C++, PHP, Java, Python, JavaScript, React, Node.js.
  • 각 팀이 시간당 또는 하루에 실행할 수 있는 CI/CD 작업 수를 추정합니다.
  • 컨테이너 사용으로 해결할 수 없는 팀 빌드 환경 요구 사항을 확인합니다.
  • 해당 팀에 러너를 전용으로 할당하는 것이 가장 적합한 빌드 환경 요구 사항을 확인합니다.
  • 예상 수요를 지원하기 위해 필요한 컴퓨팅 용량을 추정합니다.

여러분은 서로 다른 인프라 스택을 선택하여 다른 러너 플리트를 호스팅할 수 있습니다. 예를 들어, 공용 클라우드와 온프레미스에 각각 일부 러너를 배포해야 할 수도 있습니다.

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

워커, 실행자 및 자동확장 기능

gitlab-runner 실행 파일은 여러분의 CI/CD 작업을 실행합니다. 각 러너는 사전 정의된 구성에 따라 작업 실행 요청을 수신하고 처리하는 격리된 프로세스입니다. 격리된 프로세스로서 각 러너는 작업을 실행하기 위해 “서브 프로세스”(또는 “워커”로 불림)를 생성할 수 있습니다.

병행성 및 제한

  • 병행성: 호스트 시스템의 모든 구성된 러너를 사용할 때 병행으로 실행할 수 있는 작업 수를 설정합니다.
  • 제한: 러너가 동시에 실행할 수 있는 서브 프로세스 수를 설정합니다.

제한은 Docker Machine 및 Kubernetes와 같은 자동확장 러너의 경우에는 일반적인 러너와 다릅니다.

  • 자동확장을 사용하지 않는 러너에서 제한은 호스트 시스템의 러너 용량을 정의합니다.
  • 자동확장 러너에서 제한은 총 러너 수를 의미합니다.

기본 구성: 하나의 러너, 하나의 워커

가장 기본적인 구성에서는 지원되는 컴퓨팅 아키텍처 및 운영 체제에 GitLab 러너 소프트웨어를 설치합니다. 예를 들어, 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 실행자를 사용하도록 등록되었고, 전역 구성 옵션인 병행성 값을 3으로 업데이트하면 이 호스트에서 동시에 실행할 수 있는 작업 상한선은 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 러너가 자동확장을 위해 설정되면 러너를 다른 러너의 관리자로 구성할 수 있습니다. 이 작업은 docker-machine 또는 kubernetes 실행자로 수행할 수 있습니다. 이러한 유형의 관리자 전용 구성에서 러너 에이전트는 CI/CD 작업을 실행하지 않습니다.

Docker Machine 실행자

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

Kubernetes 실행자

  • 러너 관리자는 대상 Kubernetes 클러스터에서 파드를 프로비저닝합니다.
  • CI/CD 작업은 여러 컨테이너로 이루어진 각 파드에서 실행됩니다.
  • 작업 실행을 위한 파드는 일반적으로 러너 관리자를 호스트하는 파드보다 더 많은 컴퓨팅 및 메모리 리소스가 필요합니다.

러너 구성 재사용

러너 인증 토큰과 관련된 각 러너 관리자에는 system_id 식별자가 할당됩니다. system_id는 러너가 사용되는 기계를 식별합니다. 동일한 인증 토큰으로 등록된 다른 system_id 값을 가진 러너는 하나의 러너로 그룹화됩니다. 그룹화된 러너는 여러 러너 관리자에 의해 다른 작업을 실행하는 데 재사용될 수 있습니다.

GitLab 러너는 시작 시 또는 구성이 저장될 때 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 명령어를 사용하면, 러너 매니저만 삭제되고 러너는 삭제되지 않습니다.

인스턴스 수준 공유 러너 구성

러너가 “러너 매니저”로 작동하는 자동 확장 구성(autoscaling configuration)에서 인스턴스 수준 공유 러너를 사용하는 것은 효율적이고 효과적인 방법입니다.

VM 또는 파드를 호스팅하는 인프라 스택의 컴퓨팅 용량은 다음에 의존합니다:

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

CI/CD 워크로드를 실행하고 성능을 분석한 후 컴퓨팅 용량을 조정해야 할 것입니다.

자동 확장 실행기를 사용하는 구성에서는, 최소한 두 개의 러너 매니저로 시작하는 것이 좋습니다.

시간이 지남에 따라 필요한 러너 매니저의 총 수는 다음에 의존합니다:

  • 러너 매니저를 호스팅하는 스택의 컴퓨팅 리소스.
  • 각 러너 매니저에 대해 구성할 동시성.
  • 시간당, 일별 및 월별로 각 매니저가 실행하는 CI/CD 작업에서 생성되는 부하.

예를 들어, GitLab.com에서는 현재 Docker Machine 실행기를 사용하는 일곱 개의 러너 매니저가 실행됩니다. 각 CI/CD 작업은 Google Cloud Platform (GCP) n1-standard-1 VM에서 실행됩니다. 이러한 구성으로 우리는 매월 수백만 개의 작업을 처리합니다.

러너 모니터링

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

다음 표에는 GitLab Runner 메트릭의 요약이 포함되어 있습니다. Go 특정 프로세스 메트릭은 포함되어 있지 않습니다. 러너에서 이러한 메트릭을 보려면 여기에 나와 있는 대로 명령을 실행하세요.

메트릭 이름 설명
gitlab_runner_api_request_statuses_total 러너, 엔드포인트 및 상태별로 분할된 API 요청의 총 수.
gitlab_runner_autoscaling_machine_creation_duration_seconds 머신 생성 시간의 히스토그램.
gitlab_runner_autoscaling_machine_states 이 제공자(provider)에서 상태별 머신 수.
gitlab_runner_concurrent 동시성 설정 값.
gitlab_runner_errors_total 잡행 로그 라인을 추적하는 카운터인 총 오류 수. 이 메트릭에는 level 라벨이 포함됩니다. 가능한 값은 warning 및 error입니다. 만약 이 메트릭을 포함하기로 결정한다면, 관측할 때 rate() 또는 increase()를 사용하세요. 다시 말해, 경고 또는 오류의 비율이 증가하는 것을 알 경우, 추가 조사가 필요한 문제가 있을 수 있습니다.
gitlab_runner_jobs 현재 실행 중인 작업 수(라벨의 다른 범위로).
gitlab_runner_job_duration_seconds 작업 지속 시간의 히스토그램.
gitlab_runner_jobs_total 실행된 총 작업 표시.
gitlab_runner_limit 현재 제한 설정 값.
gitlab_runner_request_concurrency 새로운 작업에 대한 현재 동시 요청 수.
gitlab_runner_request_concurrency_exceeded_total 구성된 request_concurrency 제한을 초과하는 초과 요청 수.
gitlab_runner_version_info 다양한 빌드 통계 필드별로 레이블이 지정된 상수 1 값을 가진 메트릭.
process_cpu_seconds_total 사용자 및 시스템 CPU 시간의 총량(초).
process_max_fds 최대 열린 파일 기술자 수.
process_open_fds 열린 파일 기술자 수.
process_resident_memory_bytes 사용 중인 메모리 크기(바이트).
process_start_time_seconds 프로세스의 시작 시간(유닉스 시대 이후 초).
process_virtual_memory_bytes 가상 메모리 크기(바이트).
process_virtual_memory_max_bytes 사용 가능한 가상 메모리의 최대량(바이트).

Grafana 대시보드 구성 팁

이 공개 리포지터리에서는 GitLab.com의 러너 플릿을 운영하는 데 사용하는 Grafana 대시보드의 소스 코드를 찾을 수 있습니다. GitLab.com에서는 많은 메트릭을 추적합니다. 대규모 클라우드 기반 CI/CD 제공업체로서, 시스템에 대해 다양한 보기를 필요로 하므로 문제를 디버깅할 수 있습니다. 대부분의 경우, 온프레미스(runner fleets) 러너 플릿은 GitLab.com에서 추적하는 메트릭의 양이 필요하지 않습니다.

러너 플릿을 모니터링하는 데 사용할 수 있는 몇 가지 필수 대시보드를 여기에 소개합니다.

러너에서 시작된 작업:

  • 선택한 시간 간겨에 러너 플릿에서 실행된 총 작업 개요를 볼 수 있습니다.
  • 사용량의 트렌드를 확인하세요. 최소한 주별로 이 대시보드를 분석해야 합니다.

이 데이터를 작업 지속 시간과 같은 다른 메트릭과 연관하여, 내부 CI/CD 작업 성능에 대한 SLO를 제공하기 위해 구성 변경이나 용량 업그레이드가 필요한지를 결정할 수 있습니다.

작업 지속 시간:

  • 러너 플릿의 성능과 확장을 분석하세요.

러너 용량:

  • 실행 중인 작업 수가 제한 또는 동시성의 값으로 나눠서 표시됩니다.
  • 추가 작업을 실행할 여유가 있는지 확인하세요.

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

Kubernetes 플랫폼을 사용하여 러너 플리트를 호스팅하는 경우(예: OpenShift, EKS, 또는 GKE), Grafana 대시보드를 설정하는 데 다른 방식이 필요합니다.

Kubernetes에서는 러너 CI/CD 작업 실행 pod이 자주 생성되고 삭제될 수 있습니다. 이러한 경우에는 러너 관리자 pod을 모니터링하고 아래와 같이 구현할 계획을 세워야 할 것입니다:

  • 게이지(Gauges): 다양한 소스에서 동일한 메트릭의 집계를 표시합니다.
  • 카운터(Counters): rate 또는 increase 기능을 적용할 때 카운터를 재설정합니다.