Docker 컨테이너에서 GitLab Runner 실행

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed

GitLab Runner을 Docker 컨테이너 내부에서 실행하는 방법입니다.

Docker Engine 버전 호환성

일반적으로 Docker Engine의 버전과 GitLab Runner 컨테이너 이미지의 버전은 일치할 필요가 없습니다. GitLab Runner 이미지는 역방향 및 순방향 호환되어야 합니다. 그러나 최신 기능 및 보안 업데이트를 보장하기 위해 항상 최신의 안정적인 Docker Engine 버전을 사용해야 합니다.

일반적인 GitLab Runner Docker 이미지 사용법

GitLab Runner Docker 이미지(Ubuntu 또는 Alpine Linux 기반)는 표준 gitlab-runner 명령어 주변으로 설계되었으며 마치 GitLab Runner가 호스트에 직접 설치된 것처럼 작동합니다.

일반적인 규칙은 다음과 같습니다. 일반적으로 수행되는 GitLab Runner 명령어는 다음과 같이 실행됩니다:

gitlab-runner <runner command and options...>

다음과 같이 실행할 수 있습니다:

docker run <선택한 docker 옵션...> gitlab/gitlab-runner <runner command and options...>

예를 들어, GitLab Runner 명령어에 대한 최상위 도움말 정보를 얻으려면 다음처럼 실행할 수 있습니다:

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   16.5.0 (853330f9)

(...)

요약하면, 명령어의 gitlab-runner 부분은 docker run [docker options] gitlab/gitlab-runner으로 대체되며 나머지 명령어는 등록 문서에 설명된대로 유지됩니다. 유일한 차이점은 gitlab-runner 명령어가 Docker 컨테이너 내에서 실행된다는 것입니다.

Docker 이미지 설치 및 컨테이너 시작

시작하기 전에, Docker가 설치되어 있는지 확인하세요.

Docker 컨테이너 내에서 gitlab-runner를 실행하려면 컨테이너가 다시 시작될 때 구성이 손실되지 않도록해야 합니다. 이를 위해 아래에 설명된 두 가지 옵션이 있습니다.

가장 흔한 GitLab Runner의 문제를 설명하는 FAQ 섹션을 읽으십시오.

  • 만약 session_server를 사용 중이라면 docker run 명령어에 -p 8093:8093를 추가하여 포트 8093을 공개해야 합니다.
  • Docker Machine executor를 사용하여 오토스케일링 기능을 사용하려면 Docker Machine 저장 경로를 마운트해야 합니다:
    • 시스템 볼륨 마운트에는 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine
    • Docker의 명명된 볼륨에는 -v docker-machine-config:/root/.docker/machine를 추가해야 합니다.
note
이 설정은 각 GitLab Runner 컨테이너에 대해 Docker 데몬의 완전한 제어를 위임합니다. 이로 인해 GitLab Runner을 Docker 데몬 내에서 실행하면 격리 보장이 깨집니다.

옵션 1: 로컬 시스템 볼륨 마운트를 사용하여 Runner 컨테이너 시작

다음 예제는 gitlab-runner 컨테이너로 마운트되는 구성 볼륨을 위해 로컬 시스템을 사용합니다. 이 볼륨은 구성 및 기타 리소스에 사용됩니다.

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest
note
macOS에서 /srv 디렉터리가 기본적으로 존재하지 않습니다. /private/srv를 만들거나 다른 개인 디렉터리를 사용할 수 있습니다.

옵션 2: Docker 볼륨을 사용하여 Runner 컨테이너 시작

이 예제에서는 사용자 정의 데이터 볼륨을 마운트하는 구성 컨테이너를 사용할 수 있습니다.

  1. Docker 볼륨을 생성합니다:

    docker volume create gitlab-runner-config
    
  2. 방금 생성한 Docker 볼륨을 사용하여 GitLab Runner 컨테이너를 시작합니다:

    docker run -d --name gitlab-runner --restart always \
        -v /var/run/docker.sock:/var/run/docker.sock \
        -v gitlab-runner-config:/etc/gitlab-runner \
        gitlab/gitlab-runner:latest
    
note
컨테이너의 시간대를 설정하려면 docker run 명령어에서 --env TZ=<TIMEZONE> 플래그를 사용하세요. 사용 가능한 시간대 디렉터리 보기.
note
redhat/ubi8-minimal을 기반으로 하는 FIPS 호환 GitLab Runner 이미지의 경우 gitlab/gitlab-runner:ubi-fips 태그를 사용하세요.

Runner 등록

마지막 단계는 새 Runner를 등록하는 것입니다. GitLab Runner 컨테이너는 등록될 때까지 어떠한 작업도 수행하지 않습니다.

구성 업데이트

config.toml에서 구성을 변경하면 변경 사항을 적용하기 위해 Runner를 다시 시작해야 할 수 있습니다. config.toml은 Runner를 구성하는 데 사용하는 구성 파일이며, Runner를 등록하면 생성됩니다.

변경을 적용하기 위해 gitlab-runner restart 대신 컨테이너 전체를 다시 시작해야 합니다:

docker restart gitlab-runner

버전 업그레이드

최신 버전 (또는 특정 태그)을 가져오려면 다음을 실행하세요:

docker pull gitlab/gitlab-runner:latest

기존 컨테이너를 중지하고 제거하세요:

docker stop gitlab-runner && docker rm gitlab-runner

초기 설정대로 컨테이너를 시작하세요:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest
note
원래 사용했던 것과 동일한 방법으로 데이터 볼륨을 마운트해야 합니다 (-v /srv/gitlab-runner/config:/etc/gitlab-runner 또는 --volumes-from gitlab-runner-config).

GitLab Runner 로그 읽기

GitLab Runner가 foreground 작업으로 시작된 경우 (로컬로 설치된 이진 파일이거나 Docker 컨테이너 내부에 있는 경우) 로그는 표준 출력에 인쇄됩니다. 시스템 서비스(예: Systemd와 함께)로 시작된 경우, 대부분의 경우 로그는 Syslog 또는 기타 시스템 로깅 메커니즘을 통해 기록됩니다.

Docker 기반 서비스로 시작된 GitLab Runner의 경우 gitlab-runner ... 명령이 컨테이너의 주요 프로세스이므로 로그는 docker logs 명령을 사용하여 읽을 수 있습니다.

예를 들어, GitLab Runner가 다음 명령어로 시작된 경우:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

다음과 같이 로그를 볼 수 있습니다:

docker logs gitlab-runner

여기서 gitlab-runner는 첫 번째 명령어에서 --name gitlab-runner로 설정된 컨테이너의 이름입니다.

컨테이너 로그 처리에 대한 자세한 정보는 Docker 문서 페이지에서 확인할 수 있습니다.

신뢰할 수 있는 SSL 서버 인증서 설치

GitLab CI 서버가 자체 서명된 SSL 인증서를 사용하는 경우 GitLab CI 서버 인증서가 GitLab Runner 컨테이너에서 신뢰되도록해야 합니다.

gitlab/gitlab-runner 이미지는 신뢰할 수 있는 SSL 인증서를 /etc/gitlab-runner/certs/ca.crt에서 찾도록 구성되어 있지만 이를 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 구성 옵션을 사용하여 변경할 수 있습니다.

ca.crt 파일을 데이터 볼륨 (또는 컨테이너)의 certs 디렉터리로 복사하세요. ca.crt 파일은 GitLab Runner가 신뢰해야 하는 모든 서버의 루트 인증서를 포함해야 합니다. GitLab Runner 컨테이너가 시작하면 ca.crt 파일을 가져오기 때문에 컨테이너가 이미 실행 중인 경우 변경 사항이 적용되도록 컨테이너를 다시 시작해야 할 수 있습니다.

Docker 이미지

다음과 같은 멀티 플랫폼 Docker 이미지를 사용할 수 있습니다:

  • gitlab/gitlab-runner:latest는 Ubuntu를 기반으로 합니다.
  • gitlab/gitlab-runner:alpine은 훨씬 작은 용량을 가진 Alpine을 기반으로 합니다 (750MB Ubuntu 대비 340MB 알파인 압축 해제).

가능한 빌드 지침에 대한 GitLab Runner 소스를 참조하세요.

GitLab Runner Docker 이미지 만들기

GitLab Runner 16.1 버전부터 Alpine을 기반으로 한 GitLab Runner Docker 이미지는 Alpine 3.18을 사용합니다. 그러나 GitLab 리포지터리에서 사용 가능하기 전에 이미지의 OS를 업그레이드할 수 있습니다.

최신 Alpine 버전을 기반으로 gitlab-runner Docker 이미지를 빌드하려면 다음을 수행하세요:

  1. alpine-upgrade/Dockerfile을 만듭니다.

    ARG GITLAB_RUNNER_IMAGE_TYPE
    ARG GITLAB_RUNNER_IMAGE_TAG
    FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}
       
    RUN apk update
    RUN apk upgrade
    
  2. 업그레이드된 gitlab-runner 이미지를 만듭니다.

    GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner GITLAB_RUNNER_IMAGE_TAG=alpine-v16.1.0 docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG -f alpine-upgrade/Dockerfile alpine-upgrade
       
    
  3. 업그레이드된 gitlab-runner-helper 이미지를 만듭니다.

    GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper GITLAB_RUNNER_IMAGE_TAG=x86_64-v16.1.0 docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG -f alpine-upgrade/Dockerfile alpine-upgrade
    
note
Linux s390x 또는 Linux ppc64le 플랫폼에 대해 아직 Linux s390x 또는 Linux ppc64le 용으로 유지보수되지 않기 때문에 IBM Z 이미지에는 docker-machine 의존성이 포함되어 있지 않습니다. 현재 상태에 대한 자세한 내용은 이슈를 참조하세요.

SELinux

일부 배포(센토스, 레드햇, 페도라)는 기본적으로 SELinux를 사용하여 기본 시스템의 보안을 강화합니다.

이러한 구성을 처리할 때 특별한 주의가 필요합니다.

  1. 컨테이너에서 빌드를 실행하기 위해 도커 executor를 사용하려면 /var/run/docker.sock에 액세스해야 합니다. 그러나 SELinux가 강제 모드인 경우 /var/run/docker.sock에 액세스시 Permission denied 오류가 발생합니다. 이 문제를 해결하려면 selinux-dockersock를 설치하세요.
  2. 호스트에 영구 디렉터리가 만들어졌는지 확인하세요: mkdir -p /srv/gitlab-runner/config.
  3. 볼륨에서 :Z와 함께 도커를 실행하세요:

     docker run -d --name gitlab-runner --restart always \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
       gitlab/gitlab-runner:latest