• Docker Engine 버전 호환성
• 일반적인 GitLab Runner Docker 이미지 사용법
• Docker 이미지 설치 및 컨테이너 시작
  • 옵션 1: 로컬 시스템 볼륨 마운트를 사용하여 Runner 컨테이너 시작
  • 옵션 2: Docker 볼륨을 사용하여 Runner 컨테이너 시작
  • Runner 등록
• 구성 업데이트
• 버전 업그레이드
• GitLab Runner 로그 읽기
• 신뢰할 수 있는 SSL 서버 인증서 설치
• Docker 이미지
  • GitLab Runner Docker 이미지 만들기
• SELinux

Docker 컨테이너에서 GitLab Runner 실행

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를 추가해야 합니다.

옵션 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

옵션 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
   

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

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
   

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