• Docker Engine 버전 호환성
• Docker 이미지 설치 및 컨테이너 시작
  • 로컬 시스템 볼륨에서
  • Docker 볼륨에서
• Runner 구성 업데이트
• Runner 버전 업그레이드
• Runner 로그 보기
• 신뢰할 수 있는 SSL 서버 인증서 설치
• 도커 이미지
  • 러너 도커 이미지 생성
• 컨테이너에서 SELinux 사용

컨테이너에서 GitLab Runner 실행

이 페이지에서는 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 명령어 및 옵션...>
• Docker 명령어: docker run <선택한 docker 옵션...> gitlab/gitlab-runner <runner 명령어 및 옵션...>

예를 들어, GitLab Runner에 대한 상위 도움말 정보를 얻으려면 명령어에서 gitlab-runner 부분을 docker run [docker 옵션] gitlab/gitlab-runner으로 변경합니다.

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

이름:
   gitlab-runner - a GitLab Runner

사용법:
   gitlab-runner [global 옵션] 명령어 [명령어 옵션] [인자...]

버전:
   16.5.0 (853330f9)

(...)

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

Docker Engine 버전 호환성

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

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

사전 요구 사항:

• Docker를 설치했어야 합니다.
• GitLab Runner에서 일반적인 문제에 대해 알아보기 위해 FAQ를 읽었어야 합니다.

1. Docker 컨테이너에서 gitlab-runner를 실행할 때, 컨테이너를 다시 시작할 때 구성이 손실되지 않도록 합니다. 구성이 있는 영구 볼륨을 다음 중 하나에 장착합니다:

   • 로컬 시스템 볼륨
   • Docker 볼륨
2. 선택 사항. session_server를 사용하는 경우, docker run 명령어에 -p 8093:8093을 추가하여 포트 8093을 노출합니다.

3. 선택 사항. 오토스케일링을 위해 Docker Machine executor를 사용하는 경우, docker run 명령어에 볼륨을 장착하여 Docker Machine 저장 경로(/root/.docker/machine)를 마운트합니다:

   • 시스템 볼륨 장착의 경우, -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine를 추가합니다.
   • Docker 네임드 볼륨의 경우, -v docker-machine-config:/root/.docker/machine를 추가합니다.
4. 새로운 Runner 등록. GitLab Runner 컨테이너는 작업을 진행하기 위해 등록되어야 합니다.

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

• --env TZ=<TIMEZONE> 플래그를 사용하여 컨테이너의 타임존을 설정합니다. 사용 가능한 타임존 목록을 확인하세요.
• redhat/ubi9-micro를 기반으로 하는 FIPS(연방 정보처리 표준) 호환 GitLab Runner 이미지의 경우, gitlab/gitlab-runner:ubi-fips 태그를 사용합니다.
• 신뢰할 수 있는 SSL 서버 인증서 설치.

로컬 시스템 볼륨에서

로컬 시스템을 구성 볼륨 및 gitlab-runner 컨테이너로 마운트할 경우:

1. 맥OS 시스템의 경우, /srv는 기본적으로 존재하지 않습니다. 설정을 위해 /private/srv 또는 다른 개인 디렉토리를 생성합니다.

2. 필요에 맞게 수정하여 다음 명령어를 실행합니다:

   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 볼륨에서

사용자 정의 데이터 볼륨을 마운트하기 위해 구성 컨테이너를 사용하는 경우:

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

   docker volume create gitlab-runner-config
   

2. 방금 생성한 볼륨을 사용하여 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 구성 업데이트

config.toml에서 Runner 구성을 변경한 후, 변경 사항을 적용하려면 gitlab-runner restart를 실행합니다.

Runner 버전 업그레이드

사전 요구 사항:

• 초기 설정 시와 동일한 방법으로 데이터 볼륨을 장착해야 합니다 (-v /srv/gitlab-runner/config:/etc/gitlab-runner 또는 -v gitlab-runner-config:/etc/gitlab-runner).

1. 최신 버전 또는 특정 태그를 가져옵니다:

   docker pull gitlab/gitlab-runner:latest
   

2. 기존 컨테이너를 중지하고 제거합니다:

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

3. 초기에 수행한 것과 동일하게 컨테이너를 시작합니다:

   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
   

Runner 로그 보기

Runner를 시작하는 방식에 따라 로그 파일 위치가 달라집니다. 다음과 같은 경우에:

• Foregrond 작업인 경우, 로컬로 설치된 이진 파일 또는 Docker 컨테이너에서는 로그가 stdout에 출력됩니다.
• 시스템 서비스인 경우, systemd와 같은 경우, 로그는 Syslog와 같은 시스템 로깅 메커니즘에서 사용 가능합니다.
• Docker 기반 서비스는 주요 프로세스가 컨테이너의 로그에 사용되므로, 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

컨테이너 로그 처리에 대한 자세한 내용은 Docker 문서의 docker container logs 참조하세요.

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

만약 GitLab CI/CD 서버가 자체 서명 SSL 인증서를 사용한다면, 러너 컨테이너가 GitLab CI 서버 인증서를 신뢰하도록 해야 합니다. 이렇게 하면 통신 오류를 방지할 수 있습니다.

사전 조건:

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

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

도커 이미지

GitLab Runner 16.1에서 Alpine을 기반으로 하는 Docker 이미지는 Alpine 3.18을 사용합니다. 이러한 멀티 플랫폼 Docker 이미지들이 있습니다:

• gitlab/gitlab-runner:latest는 Ubuntu를 기반으로 하며, 약 800MB입니다.
• gitlab/gitlab-runner:alpine은 Alpine을 기반으로 하며, 약 460MB입니다.

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

러너 도커 이미지 생성

이미지가 GitLab 리포지토리에서 사용 가능한 업데이트 이전에 이미지의 운영 체제를 업그레이드할 수 있습니다.

사전 조건:

• IBM Z 이미지를 사용하지 않는다면, Linux s390x 또는 Linux ppc64le 플랫폼을 위해 docker-machine 종속성을 포함하지 않습니다. 이 이미지는 유지되지 않습니다. 현재 상태는 이슈 26551를 참조하세요.

최신 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-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
   

3. 업그레이드된 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 (Security-Enhanced Linux)를 사용하여 기본 시스템의 보안을 강화합니다.

이 구성에 주의하세요.

사전 조건:

• 컨테이너에서 빌드를 실행하기 위해 Docker 실행기를 사용하려면, 러너는 /var/run/docker.sock에 액세스해야 합니다.
• 강제 모드의 SELinux를 사용하는 경우, 러너가 /var/run/docker.sock에 액세스할 때 Permission denied 오류를 방지하려면 selinux-dockersock을 설치하세요.

1. 호스트에 지속적인 디렉토리를 만듭니다: mkdir -p /srv/gitlab-runner/config.

2. 볼륨에 대해 :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