GIT

GitLab Group Runner 캐시 문제와 해결 방안

SecuOf 2025. 5. 31. 11:15

GitLab CI/CD를 구성할 때 여러 개의 러너를 그룹으로 묶어 운영하는 경우가 많습니다. 그러나 그룹 러너를 사용할 때 자주 발생하는 문제가 바로 캐시 관리입니다. 이번 글에서는 GitLab 그룹 러너를 사용할 때 node 패키지나 go 패키지를 받아오는 과정에서 캐시 문제로 인해 정상적인 빌드가 되지 않는 현상을 확인하고, 이를 해결할 수 있는 방안을 소개하겠습니다.

🔍 문제 현상

GitLab에서 제공하는 그룹 러너(Group Runner)는 빌드 성능을 높이기 위해 로컬 캐시를 활용합니다. 그러나 여러 서버에서 그룹 러너를 분산 운영하는 경우, 각 서버가 로컬로 독립적인 캐시를 가지고 있으면 다음과 같은 현상이 발생할 수 있습니다.

  • Node 패키지 설치 시 일부 패키지를 찾지 못하거나 오류가 발생함.
  • Go 빌드 시 캐시된 모듈을 제대로 불러오지 못하는 현상이 발생함.

이러한 문제는 동일한 그룹 내 여러 러너 서버 간에 캐시 상태가 다르게 유지되기 때문에 발생합니다. 특히, node_modules나 Go 모듈 캐시 같은 공유가 필요한 의존성에서 자주 나타납니다.

🚩 문제의 원인

기본적으로 GitLab 그룹 러너는 별도의 설정이 없으면 각 러너 서버마다 개별적으로 캐시를 유지합니다. 이러한 이유로 빌드 작업이 서로 다른 러너 서버에서 분산 실행될 때, 이전 작업에서 생성된 캐시를 다른 서버에서 이용할 수 없어 패키지를 매번 다시 다운로드하거나 충돌이 발생할 수 있습니다.

즉, 러너 간 캐시 공유가 안 되는 상황이 문제의 핵심 원인입니다.

✅ 해결 방법

이 문제를 해결하기 위해서는 캐시를 공유할 수 있도록 외부 캐시 저장소를 사용하는 방법이 가장 효과적입니다. 대표적인 외부 캐시 스토리지 옵션은 다음과 같습니다.

  1. AWS S3를 이용한 공유 캐시
  2. MinIO를 이용한 자체 호스팅 캐시 서버

여기서는 가장 손쉽게 접근 가능한 AWS S3를 이용한 방법을 안내하겠습니다.

🛠️ AWS S3 캐시 설정 방법

1. S3 버킷 생성

먼저 AWS 콘솔에서 S3 버킷을 생성합니다.

  • 버킷 이름: 예시로 gitlab-runner-cache-example (원하는 이름 설정)
  • 접근 권한: 러너에서 접근 가능하도록 설정
  • AWS 리전: 러너가 배포된 서버와 가까운 리전 권장

2. IAM 사용자 또는 역할 설정

GitLab 러너가 AWS S3 버킷에 접근할 수 있도록 IAM 사용자를 만들고, 적절한 권한을 부여합니다.

필요 권한 예시:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::gitlab-runner-cache-example/*"
      ]
    }
  ]
}

3. GitLab Runner 설정 변경

GitLab Runner의 설정 파일(config.toml)에 다음과 같이 S3 캐시를 지정합니다.

[[runners]]
  name = "Group Runner"
  url = "https://gitlab.example.com/"
  token = "YOUR_RUNNER_TOKEN"
  executor = "docker"
  [runners.docker]
    image = "docker:latest"
  [runners.cache]
    Type = "s3"
    Path = "runner/cache"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      BucketName = "gitlab-runner-cache-example"
      BucketLocation = "ap-northeast-2" # 예시 리전
      AccessKey = "YOUR_AWS_ACCESS_KEY"
      SecretKey = "YOUR_AWS_SECRET_KEY"

여기서 중요한 옵션은 Shared = true입니다.
이 옵션을 활성화하면 모든 그룹 러너가 동일한 S3 버킷 내 캐시를 공유할 수 있습니다.

⚠️ 주의사항: Shared 옵션이 false인 경우

Shared = false로 설정된 경우, 각 러너는 고유한 캐시를 사용하게 되어 다음과 같은 현상이 발생합니다.

  • 다른 러너 서버 간 캐시 공유가 이루어지지 않음.
  • 동일한 프로젝트 빌드를 서로 다른 러너에서 수행할 때마다 매번 새로운 캐시가 생성되어 저장 공간 낭비 및 빌드 속도 저하의 원인이 될 수 있음.
  • 분산 러너 환경에서는 사실상 로컬 캐시와 비슷한 효과를 가져 비효율적일 수 있음.

그러므로 여러 러너가 분산 환경에서 운영되는 경우에는 반드시 Shared = true로 설정하여 S3 버킷에 통합된 캐시를 관리하는 것이 권장됩니다.

🧪 결과 확인

캐시 설정 이후 GitLab 빌드 작업을 다시 실행하여 node, go 패키지가 정상적으로 캐시되어 공유되는지 확인합니다.
빌드 로그에서 캐시가 성공적으로 저장되고 로드되는 것을 확인할 수 있습니다.

Checking cache for default...
Successfully extracted cache
# ...
Creating cache default...
runtime/node_modules/: found 2685 matching files and directories
Uploading cache.zip to https://s3.amazonaws.com/gitlab-runner-cache-example/runner/cache/...
Created cache

📌 결론

GitLab 그룹 러너를 운영할 때는 반드시 캐시 공유 전략을 고려해야 합니다. AWS S3를 활용한 캐시 공유 설정을 통해 빌드 안정성을 높이고 불필요한 패키지 재설치를 방지하여 빌드 시간을 절약할 수 있습니다.

📚 참고자료

저작자표시 비영리 동일조건 (새창열림)