GitLab Runner을 컨테이너에서 실행하기

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

이 페이지에서는 Docker 컨테이너 내에서 GitLab Runner을 실행하는 방법을 설명합니다.

GitLab Runner Docker 이미지는 Ubuntu 또는 Alpine Linux를 기반으로 합니다.
이것들은 호스트에 GitLab Runner을 직접 설치한 것처럼 표준 gitlab-runner 명령어를 감싸는 역할을 합니다.

이 설정은 각 GitLab Runner 컨테이너에 Docker 데몬에 대한 완전한 제어를 위임합니다.
그 결과, 마이크로서비스가 다른 페이로드도 실행되는 Docker 데몬 내부에서 GitLab Runner을 실행하면
격리가 보장되지 않습니다.

이 설정에서는 실행하는 매개변수의 각 GitLab Runner 명령은 다음과 같은 docker run에 해당합니다:

Runner 명령: gitlab-runner <runner command and options...>
Docker 명령: docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

예를 들어, GitLab Runner에 대한 최상위 도움말 정보를 얻으려면 명령의 gitlab-runner 부분을
docker run [docker options] gitlab/gitlab-runner로 바꾸면 됩니다.

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

NAME:
   gitlab-runner - GitLab Runner

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

VERSION:
   16.5.0 (853330f9)

(...)

명령의 나머지 부분은 등록 문서에 설명된 대로 유지됩니다.
유일한 차이점은 gitlab-runner 명령이 Docker 컨테이너 내에서 실행된다는 것입니다.

Docker 엔진 버전 호환성

Docker 엔진 및 GitLab Runner 컨테이너 이미지의 버전은 일치할 필요가 없습니다.
GitLab Runner 이미지는 이전 및 최신 버전과 호환됩니다.
최신 기능 및 보안 업데이트를 보장하기 위해 항상 최신 안정 Docker 엔진 버전을 사용해야 합니다.

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

전제 조건:

Docker를 설치했습니다.
GitLab Runner에서 흔한 문제를 알기 위해 FAQ를 읽었습니다.

Docker 컨테이너에서 gitlab-runner를 실행할 때, 컨테이너를 재시작할 때 설정이 손실되지 않도록 하세요.
설정이 거주할 영구 볼륨을 마운트합니다. 그 위치는 다음 중 하나일 수 있습니다:
- 로컬 시스템 볼륨
- Docker 볼륨
선택 사항. session_server를 사용하는 경우, docker run 명령에 -p 8093:8093를 추가하여 포트 8093을 노출합니다.
선택 사항. 자동 확장을 위한 Docker 머신 실행기를 사용하려면,
Docker 머신 저장소 경로(/root/.docker/machine)를 마운트하는 볼륨을 추가합니다:
- 시스템 볼륨 마운트의 경우, -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine을 추가합니다.
- Docker 명명된 볼륨의 경우, -v docker-machine-config:/root/.docker/machine을 추가합니다.
새 러너 등록. GitLab Runner 컨테이너는 작업을 수집하기 위해 등록되어야 합니다.

사용 가능한 구성 옵션은 다음과 같습니다:

--env TZ=<TIMEZONE> 플래그로 컨테이너의 시간대를 설정합니다.
사용 가능한 시간대 목록 보기.
redhat/ubi9-micro를 기반으로 하는 FIPS 호환 GitLab Runner 이미지의 경우,
gitlab/gitlab-runner:ubi-fips 태그를 사용합니다.
신뢰할 수 있는 SSL 서버 인증서 설치하기.

로컬 시스템 볼륨에서

gitlab-runner 컨테이너에 마운트된 구성 볼륨 및 기타 리소스에 로컬 시스템을 사용하려면:

선택 사항. MacOS 시스템에서는 기본적으로 /srv가 존재하지 않습니다. 설정을 위해 /private/srv 또는 다른 개인 디렉토리를 만듭니다.

다음 명령을 실행하되 필요에 따라 수정합니다:

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

도커 볼륨에서

구성 컨테이너를 사용하여 사용자 지정 데이터 볼륨을 마운트하려면:

도커 볼륨을 생성합니다:

docker volume create gitlab-runner-config

방금 생성한 볼륨을 사용하여 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

러너 구성 업데이트

config.toml에서 러너 구성을 변경한 후, gitlab-runner restart로 러너를 재시작하여 변경 사항을 적용합니다.

러너 버전 업그레이드

전제 조건:

원래와 동일한 방법으로 데이터 볼륨을 마운트해야 합니다 (-v /srv/gitlab-runner/config:/etc/gitlab-runner 또는 -v gitlab-runner-config:/etc/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

러너 로그 보기

로그 파일 위치는 러너를 시작하는 방법에 따라 다릅니다. 다음과 같이 시작할 때:

포그라운드 작업으로, 로컬에 설치된 바이너리로 하거나 도커 컨테이너에서, 로그가 stdout에 출력됩니다.
시스템 서비스로, systemd와 같이, 시스템 로그 메커니즘(Syslog 등)에서 로그를 확인할 수 있습니다.
도커 기반 서비스로, docker logs 명령을 사용합니다. gitlab-runner ... 명령은 컨테이너의 주요 프로세스입니다.

예를 들어, 다음 명령으로 컨테이너를 시작하면 이름이 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를 당신의 컨테이너 이름으로 교체합니다:

docker logs gitlab-runner

컨테이너 로그 처리에 대한 더 많은 정보는 Docker 문서의 docker container logs를 참조하십시오.

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

GitLab CI/CD 서버가 자체 서명된 SSL 인증서를 사용하는 경우, 러너 컨테이너가 GitLab CI 서버 인증서를 신뢰하도록 설정해야 합니다. 이는 통신 실패를 방지합니다.

전제 조건:

ca.crt 파일에는 GitLab Runner가 신뢰할 수 있도록 하고자 하는 모든 서버의 루트 인증서가 포함되어야 합니다.

선택 사항. gitlab/gitlab-runner 이미지는 /etc/gitlab-runner/certs/ca.crt에서 신뢰할 수 있는 SSL 인증서를 찾습니다. 이 동작을 변경하려면 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 구성 옵션을 사용하세요.
ca.crt 파일을 데이터 볼륨(또는 컨테이너)의 certs 디렉토리에 복사합니다.
선택 사항. 컨테이너가 이미 실행 중인 경우, 시작 시 ca.crt 파일을 가져오도록 재시작합니다.

도커 이미지

GitLab Runner 16.1에서 Alpine 기반의 도커 이미지는 Alpine 3.18을 사용합니다. 이러한 다중 플랫폼 도커 이미지는 다음과 같습니다:

gitlab/gitlab-runner:latest는 Ubuntu 기반으로 약 800 MB입니다.
gitlab/gitlab-runner:alpine는 Alpine 기반으로 약 460 MB입니다.

두 Ubuntu 및 Alpine 이미지에 대한 가능한 빌드 지침은 GitLab Runner 소스를 참조하세요.

러너 도커 이미지 만들기

GitLab 저장소에서 업데이트가 가능해지기 전에 이미지의 운영 체제를 업그레이드할 수 있습니다.

필수 조건:

IBM Z 이미지를 사용하지 않아야 하며, 이 이미지는 docker-machine 의존성이 포함되어 있지 않습니다. 이 이미지는 Linux s390x 또는 Linux ppc64le 플랫폼에 대해 유지 관리되지 않습니다. 현재 상태에 대한 자세한 내용은 issue 26551를 참조하세요.

최신 Alpine 버전의 gitlab-runner 도커 이미지를 빌드하려면:

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

업그레이드된 gitlab-runner 이미지를 만듭니다.

GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner \
GITLAB_RUNNER_IMAGE_TAG=alpine-v17.5.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

업그레이드된 gitlab-runner-helper 이미지를 만듭니다.

GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper \
GITLAB_RUNNER_IMAGE_TAG=x86_64-v17.5.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 사용

CentOS, Red Hat 및 Fedora와 같은 일부 배포판은 기본적으로 보안을 강화하기 위해 SELinux(보안 강화 리눅스)를 사용합니다.

이 구성에 주의하세요.

필수 조건:

Docker executor를 사용하여 컨테이너에서 빌드를 실행하려면 러너가 /var/run/docker.sock에 접근할 수 있어야 합니다.
강제 모드에서 SELinux를 사용하는 경우, 러너가 /var/run/docker.sock에 접근할 때 Permission denied 오류를 방지하려면 selinux-dockersock를 설치하세요.

호스트에 영구 디렉토리를 만듭니다: mkdir -p /srv/gitlab-runner/config.

볼륨에 :Z를 사용하여 Docker를 실행합니다:

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

On this page

GitLab Runner을 컨테이너에서 실행하기

Docker 엔진 버전 호환성

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

로컬 시스템 볼륨에서

도커 볼륨에서

러너 구성 업데이트

러너 버전 업그레이드

러너 로그 보기

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

도커 이미지

러너 도커 이미지 만들기

컨테이너에서 SELinux 사용

도움말

기능 사용 가능성과 제품 평가판

도움받기

On this page