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

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 명령어 및 옵션...>

다음과 같이 실행될 수 있다는 것입니다:

docker run <선택한 도커 옵션...> gitlab/gitlab-runner <runner 명령어 및 옵션...>

예를 들어, 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 옵션] gitlab/gitlab-runner로 바뀌고, 나머지 명령은 등록 문서에 설명된 대로 그대로 유지됩니다. 유일한 차이점은 gitlab-runner 명령어가 도커 컨테이너 내에서 실행된다는 것입니다.

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

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

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

GitLab Runner와 관련된 일반적인 문제들을 설명하는 자주 묻는 질문(FAQ) 페이지를 읽어보도록 합니다.

• 만약 session_server를 사용하는 경우, docker run 명령에 -p 8093:8093을 추가하여 포트 8093을 노출해야 합니다.

• 오토스케일링 기능을 위해 Docker Machine 실행자를 사용하고자 하는 경우, Docker Machine 저장 경로인 /root/.docker/machine를 마운트해야합니다:

  • 시스템 볼륨 마운트에는 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine를 추가합니다.
  • 도커 명명된 볼륨에는 -v docker-machine-config:/root/.docker/machine를 추가합니다.

참고: 이 설정은 각 GitLab Runner 컨테이너에 대해 Docker 데몬의 완전한 제어를 위임합니다. 결과적으로, Docker 데몬을 실행하는 GitLab Runner 내부에서 다른 페이로드를 실행하면 격리 보장이 깨집니다.

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

참고: macOS에서 /srv는 기본적으로 존재하지 않습니다. /private/srv를 생성하거나 다른 사설 디렉터리를 사용할 수 있습니다.

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

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

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
   

참고: 컨테이너의 시간대를 설정하려면 docker run 명령어에서 --env TZ=<TIMEZONE> 플래그를 사용하세요. 사용 가능한 시간대 목록을 확인하세요.

참고: 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

참고: 볼륨을 마운트하는 데 사용한 동일한 방법을 사용해야 합니다 (-v /srv/gitlab-runner/config:/etc/gitlab-runner 또는 --volumes-from gitlab-runner-config).

GitLab Runner 로그 읽기

GitLab Runner가 포그라운드 작업으로 시작될 때(로컬에 설치된 바이너리인지 또는 도커 컨테이너 안에 있는지 여부에 관계없이), 로그가 표준 출력에 출력됩니다. GitLab Runner가 시스템 서비스로 시작될 때(예: 시스템디와 함께), 로그는 대부분의 경우 Syslog 또는 다른 시스템 로깅 메커니즘을 통해 로깅됩니다.

GitLab Runner가 Docker 기반 서비스로 시작된 경우에는 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 서버가 self-signed SSL 인증서를 사용하는 경우 서로 통신할 수 있도록 GitLab Runner 컨테이너가 GitLab CI 서버 인증서를 신뢰하도록 해야 합니다.

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.
• 알파인을 기반으로 한 gitlab/gitlab-runner:alpine은 압축 해제시 750MB의 우분투 이미지 대비 340MB의 작은 크기를 가지고 있습니다.

Ubuntu 및 Alpine 이미지에 대한 가능한 빌드 지침은 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
   

참고: IBM Z 이미지에는 Linux s390x 또는 Linux ppc64le용으로 아직 유지보수되지 않은 docker-machine 종속성이 포함되어 있지 않습니다. 이슈의 현재 상태를 확인하십시오.

SELinux

일부 배포판(CentOS, Red Hat, Fedora)은 기본적으로 SELinux를 사용하여 기본 시스템 보안을 강화합니다.

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

1. 컨테이너에서 빌드를 실행하기 위해 도커 실행기를 사용하려면 /var/run/docker.sock에 액세스해야 합니다. 그러나 SELinux가 강제 모드인 경우 /var/run/docker.sock에 액세스할 때 허가 거부(Permission denied) 오류가 발생합니다. 이 문제를 해결하려면 selinux-dockersock을 설치하세요.
2. 호스트에 영속적인 디렉토리가 생성되었는지 확인하세요: mkdir -p /srv/gitlab-runner/config.
3. 볼륨에 :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