히스토리

• GitLab Runner 15.11.0에서 실험적 기능으로 도입.
• GitLab Runner 16.6에서 베타로 변경.
• GitLab Runner 17.1에서 정식 출시.

Docker Autoscaler executor를 사용하기 전에 알려진 이슈 목록은 GitLab Runner 자동 확장에 대한 피드백 이슈를 참조하세요.

Docker Autoscaler executor는 러너 매니저가 처리하는 작업을 수용하기 위해 필요에 따라 인스턴스를 생성하는 자동 확장 지원 Docker executor입니다. Docker executor를 래핑하므로 모든 Docker executor 옵션과 기능이 지원됩니다.

Docker Autoscaler는 자동 확장을 위해 fleeting 플러그인을 사용합니다. Fleeting은 자동 확장 인스턴스 그룹을 위한 추상화로, Google Cloud, AWS, Azure와 같은 클라우드 공급자를 지원하는 플러그인을 사용합니다.

fleeting 플러그인 설치#

대상 플랫폼에 맞는 플러그인을 설치하려면 fleeting 플러그인 설치를 참조하세요. 특정 구성 세부 정보는 해당 플러그인 프로젝트 문서를 참조하세요.

Docker Autoscaler 구성#

Docker Autoscaler executor는 Docker executor를 래핑하므로 모든 Docker executor 옵션과 기능이 지원됩니다.

Docker Autoscaler를 구성하려면 config.toml에서:

• [runners] 섹션에서 executor를 docker-autoscaler로 지정합니다.
• 다음 섹션에서 요구 사항에 따라 Docker Autoscaler를 구성합니다:
  • [runners.docker]
  • [runners.autoscaler]

각 러너 구성에 대한 전용 자동 확장 그룹#

각 Docker Autoscaler 구성에는 전용 자동 확장 리소스가 있어야 합니다:

• AWS의 경우 전용 오토 스케일링 그룹
• GCP의 경우 전용 인스턴스 그룹
• Azure의 경우 전용 확장 집합

다음에 걸쳐 이러한 자동 확장 리소스를 공유하지 마세요:

• 여러 러너 매니저(별도의 GitLab Runner 설치)
• 동일한 러너 매니저의 config.toml 내 여러 [[runners]] 항목

Docker Autoscaler는 클라우드 공급자의 자동 확장 리소스와 동기화해야 하는 인스턴스 상태를 추적합니다. 여러 시스템이 동일한 자동 확장 리소스를 관리하려고 하면 충돌하는 확장 명령을 실행할 수 있으며, 이로 인해 예측할 수 없는 동작, 작업 실패 및 잠재적으로 더 높은 비용이 발생할 수 있습니다.

예시: 인스턴스당 1개 작업을 위한 AWS 자동 확장#

사전 요구 사항:

• Docker Engine이 설치된 AMI. Runner Manager가 AMI의 Docker 소켓에 접근할 수 있도록 하려면 사용자가 docker 그룹에 속해 있어야 합니다.

  [!note] AMI에는 GitLab Runner가 설치될 필요가 없습니다. AMI를 사용하여 시작된 인스턴스는 GitLab에서 러너로 자체 등록해서는 안 됩니다.

• AWS 오토 스케일링 그룹. 러너가 모든 확장 동작을 직접 관리합니다. 확장 정책으로 none을 사용하고 인스턴스 축소 보호를 켜세요. 여러 가용 영역을 구성한 경우 AZRebalance 프로세스를 끄세요.

• 올바른 권한을 가진 IAM 정책.

이 구성은 다음을 지원합니다:

• 인스턴스당 용량 1
• 사용 횟수 1
• 유휴 확장 5
• 유휴 시간 20분
• 최대 인스턴스 수 10

용량과 사용 횟수를 모두 1로 설정하면 각 작업에 다른 작업의 영향을 받지 않는 안전한 임시 인스턴스가 제공됩니다. 작업이 완료되는 즉시 실행된 인스턴스가 즉시 삭제됩니다.

유휴 확장이 5이면 러너는 향후 수요를 위해 5개의 전체 인스턴스(인스턴스당 용량이 1이므로)를 사용 가능한 상태로 유지하려 합니다. 이 인스턴스들은 최소 20분 동안 유지됩니다.

러너 concurrent 필드는 10(최대 인스턴스 수 * 인스턴스당 용량)으로 설정됩니다.

concurrent = 10

[[runners]]
  name = "docker autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"                                        # Windows AMI의 경우 powershell 또는 pwsh 사용

  # Runner 매니저가 Linux에 호스팅될 때 Windows AMI의 경우 주석 해제
  # environment = ["FF_USE_POWERSHELL_PATH_RESOLVER=1"]

  executor = "docker-autoscaler"

  # Docker Executor 구성
  [runners.docker]
    image = "busybox:latest"

  # Autoscaler 구성
  [runners.autoscaler]
    plugin = "aws" # GitLab 16.11 이상에서는 `gitlab-runner fleeting install`을 실행하여 플러그인을 자동으로 설치하세요

    # GitLab 16.10 이하에서는 플러그인을 수동으로 설치하고 다음을 사용하세요:
    # plugin = "fleeting-plugin-aws"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # 플러그인별 구성 (플러그인 문서 참조)
      name             = "my-docker-asg"               # AWS 오토 스케일링 그룹 이름
      profile          = "default"                     # 선택 사항, 기본값은 'default'
      config_file      = "/home/user/.aws/config"      # 선택 사항, 기본값은 '~/.aws/config'
      credentials_file = "/home/user/.aws/credentials" # 선택 사항, 기본값은 '~/.aws/credentials'

    [runners.autoscaler.connector_config]
      username          = "ec2-user"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

예시: 인스턴스당 1개 작업을 위한 Google Cloud 인스턴스 그룹#

사전 요구 사항:

• COS와 같이 Docker Engine이 설치된 VM 이미지.

  [!note] VM 이미지에는 GitLab Runner가 설치될 필요가 없습니다. VM 이미지를 사용하여 시작된 인스턴스는 GitLab에서 러너로 자체 등록해서는 안 됩니다.

• 단일 영역 Google Cloud 인스턴스 그룹. 자동 확장 모드에서 자동 확장 안 함을 선택하세요. 러너가 자동 확장을 처리하며 Google Cloud 인스턴스 그룹이 아닙니다.

  [!note] 다중 영역 인스턴스 그룹은 현재 지원되지 않습니다. 향후 다중 영역 인스턴스 그룹을 지원하기 위한 이슈가 있습니다.

• 올바른 권한을 가진 IAM 정책. GKE 클러스터에 러너를 배포하는 경우 Kubernetes 서비스 계정과 GCP 서비스 계정 간에 IAM 바인딩을 추가할 수 있습니다. credentials_file로 키 파일을 사용하는 대신 GCP에 인증하기 위해 iam.workloadIdentityUser 권한으로 이 바인딩을 추가할 수 있습니다.

이 구성은 다음을 지원합니다:

• 인스턴스당 용량 1
• 사용 횟수 1
• 유휴 확장 5
• 유휴 시간 20분
• 최대 인스턴스 수 10

용량과 사용 횟수를 모두 1로 설정하면 각 작업에 다른 작업의 영향을 받지 않는 안전한 임시 인스턴스가 제공됩니다. 작업이 완료되는 즉시 실행된 인스턴스가 즉시 삭제됩니다.

유휴 확장이 5이면 러너는 향후 수요를 위해 5개의 전체 인스턴스(인스턴스당 용량이 1이므로)를 사용 가능한 상태로 유지하려 합니다. 이 인스턴스들은 최소 20분 동안 유지됩니다.

러너 concurrent 필드는 10(최대 인스턴스 수 * 인스턴스당 용량)으로 설정됩니다.

concurrent = 10

[[runners]]
  name = "docker autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"                                        # Windows 이미지의 경우 powershell 또는 pwsh 사용

  # Runner 매니저가 Linux에 호스팅될 때 Windows 이미지의 경우 주석 해제
  # environment = ["FF_USE_POWERSHELL_PATH_RESOLVER=1"]

  executor = "docker-autoscaler"

  # Docker Executor 구성
  [runners.docker]
    image = "busybox:latest"

  # Autoscaler 구성
  [runners.autoscaler]
    plugin = "googlecloud" # >= 16.11의 경우 `gitlab-runner fleeting install`을 실행하여 플러그인을 자동으로 설치하세요

    # 17.0 미만 버전의 경우 플러그인을 수동으로 설치하고 다음을 사용하세요:
    # plugin = "fleeting-plugin-googlecompute"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # 플러그인별 구성 (플러그인 문서 참조)
      name             = "my-docker-instance-group" # Google Cloud 인스턴스 그룹 이름
      project          = "my-gcp-project"
      zone             = "europe-west1"
      credentials_file = "/home/user/.config/gcloud/application_default_credentials.json" # 선택 사항, 기본값은 '~/.config/gcloud/application_default_credentials.json'

    [runners.autoscaler.connector_config]
      username          = "runner"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

예시: 인스턴스당 1개 작업을 위한 Azure 확장 집합#

사전 요구 사항:

• Docker Engine이 설치된 Azure VM 이미지.

  [!note] VM 이미지에는 GitLab Runner가 설치될 필요가 없습니다. VM 이미지를 사용하여 시작된 인스턴스는 GitLab에서 러너로 자체 등록해서는 안 됩니다.

• 자동 확장 정책이 manual로 설정된 Azure 확장 집합. 러너가 확장을 처리합니다.

이 구성은 다음을 지원합니다:

• 인스턴스당 용량 1
• 사용 횟수 1
• 유휴 확장 5
• 유휴 시간 20분
• 최대 인스턴스 수 10

용량과 사용 횟수가 모두 1로 설정되면 각 작업에 다른 작업의 영향을 받지 않는 안전한 임시 인스턴스가 제공됩니다. 작업이 완료되면 실행된 인스턴스가 즉시 삭제됩니다.

유휴 확장이 5로 설정되면 러너는 향후 수요를 위해 5개의 인스턴스를 사용 가능한 상태로 유지합니다(인스턴스당 용량이 1이므로). 이 인스턴스들은 최소 20분 동안 유지됩니다.

러너 concurrent 필드는 10(최대 인스턴스 수 * 인스턴스당 용량)으로 설정됩니다.

concurrent = 10

[[runners]]
  name = "docker autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"                                        # Windows AMI의 경우 powershell 또는 pwsh 사용

  # Runner 매니저가 Linux에 호스팅될 때 Windows AMI의 경우 주석 해제
  # environment = ["FF_USE_POWERSHELL_PATH_RESOLVER=1"]

  executor = "docker-autoscaler"

  # Docker Executor 구성
  [runners.docker]
    image = "busybox:latest"

  # Autoscaler 구성
  [runners.autoscaler]
    plugin = "azure" # >= 16.11의 경우 `gitlab-runner fleeting install`을 실행하여 플러그인을 자동으로 설치하세요

    # 17.0 미만 버전의 경우 플러그인을 수동으로 설치하고 다음을 사용하세요:
    # plugin = "fleeting-plugin-azure"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # 플러그인별 구성 (플러그인 문서 참조)
      name = "my-docker-scale-set"
      subscription_id = "9b3c4602-cde2-4089-bed8-889e5a3e7102"
      resource_group_name = "my-resource-group"

    [runners.autoscaler.connector_config]
      username = "azureuser"
      password = "my-scale-set-static-password"
      use_static_credentials = true
      timeout = "10m"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

슬롯 기반 cgroup 지원#

Docker Autoscaler executor는 동시 작업 간의 개선된 리소스 격리를 위해 슬롯 기반 cgroup을 지원합니다. Cgroup 경로는 --cgroup-parent 플래그를 사용하여 Docker 컨테이너에 자동으로 적용됩니다.

이점, 사전 요구 사항 및 설정 지침을 포함한 슬롯 기반 cgroup에 대한 자세한 정보는 슬롯 기반 cgroup 지원을 참조하세요.

Docker 특정 구성#

표준 슬롯 cgroup 구성 외에도 서비스 컨테이너에 대한 별도의 cgroup 템플릿을 지정할 수 있습니다:

[[runners]]
  executor = "docker+autoscaler"
  use_slot_cgroups = true
  slot_cgroup_template = "gitlab-runner/slot-${slot}"

  [runners.docker]
    service_slot_cgroup_template = "gitlab-runner/service-slot-${slot}"

사용 가능한 모든 옵션은 슬롯 기반 cgroup 구성 문서를 참조하세요.

문제 해결#

ERROR: error during connect: ssh tunnel: EOF ()#

외부 소스(예: 오토 스케일링 그룹 또는 자동화된 스크립트)에 의해 인스턴스가 제거되면 다음 오류와 함께 작업이 실패합니다:

ERROR: Job failed (system failure): error during connect: Post "http://internal.tunnel.invalid/v1.43/containers/xyz/wait?condition=not-running": ssh tunnel: EOF ()

그리고 GitLab Runner 로그는 작업에 할당된 인스턴스 ID에 대해 instance unexpectedly removed 오류를 표시합니다:

ERROR: instance unexpectedly removed    instance=<instance_id> max-use-count=9999 runner=XYZ slots=map[] subsystem=taskscaler used=45

이 오류를 해결하려면 클라우드 공급자 플랫폼에서 인스턴스와 관련된 이벤트를 확인하세요. 예를 들어 AWS에서는 이벤트 소스 ec2.amazonaws.com에 대한 CloudTrail 이벤트 히스토리를 확인하세요.

ERROR: Preparation failed: unable to acquire instance: context deadline exceeded#

AWS fleeting 플러그인을 사용할 때 다음 오류와 함께 작업이 간헐적으로 실패할 수 있습니다:

ERROR: Preparation failed: unable to acquire instance: context deadline exceeded

이 오류는 reserved 인스턴스 수가 오르락내리락하기 때문에 AWS CloudWatch 로그에 자주 표시됩니다:

"2024-07-23T18:10:24Z","instance_count:1,max_instance_count:1000,acquired:0,unavailable_capacity:0,pending:0,reserved:0,idle_count:0,scale_factor:0,scale_factor_limit:0,capacity_per_instance:1","required scaling change",
"2024-07-23T18:10:25Z","instance_count:1,max_instance_count:1000,acquired:0,unavailable_capacity:0,pending:0,reserved:1,idle_count:0,scale_factor:0,scale_factor_limit:0,capacity_per_instance:1","required scaling change",
"2024-07-23T18:11:15Z","instance_count:1,max_instance_count:1000,acquired:0,unavailable_capacity:0,pending:0,reserved:0,idle_count:0,scale_factor:0,scale_factor_limit:0,capacity_per_instance:1","required scaling change",
"2024-07-23T18:11:16Z","instance_count:1,max_instance_count:1000,acquired:0,unavailable_capacity:0,pending:0,reserved:1,idle_count:0,scale_factor:0,scale_factor_limit:0,capacity_per_instance:1","required scaling change",

이 오류를 해결하려면 AWS의 오토 스케일링 그룹에서 AZRebalance 프로세스가 비활성화되어 있는지 확인하세요.

Job failures when scaling from zero instances on Azure VMSS#

Microsoft Azure Virtual Machine Scale Sets에는 오버프로비저닝 기능이 있으며, 이로 인해 작업 실패가 발생할 수 있습니다. Azure가 확장할 때 용량을 보장하기 위해 추가 VM을 생성하고 요청된 용량을 충족한 후에 종료합니다. 이 동작은 GitLab Runner의 인스턴스 추적과 충돌하여 Azure가 종료하려는 인스턴스에 오토스케일러가 작업을 할당하는 원인이 됩니다.

VMSS 구성에서 overprovision을 false로 설정하여 오버프로비저닝을 비활성화하세요.