- Docker executor를 사용하는 러너 등록
- 이미지란 무엇인가
- 이미지 요구사항
.gitlab-ci.yml
파일에서image
정의하기- 비공개 컨테이너 레지스트리에서 이미지에 액세스
- 사용자 지정 GitLab Runner Docker 이미지 생성
Docker 컨테이너에서 CI/CD 작업 실행하기
별도이고 격리된 Docker 컨테이너에서 CI/CD 작업을 실행할 수 있습니다.
로컬 머신에서 Docker를 실행하는 경우 컨테이너에서 테스트를 실행할 수 있습니다. 전용 CI/CD 서버에서 테스트하는 대신 컨테이너에서 테스트할 수 있습니다.
Docker 컨테이너에서 CI/CD 작업을 실행하려면 다음을 해야 합니다:
- 모든 작업이 Docker 컨테이너에서 실행되도록 러너를 등록합니다. 이를 위해 등록 중에 Docker executor를 선택합니다.
- 작업을 실행할 컨테이너를 지정합니다.
.gitlab-ci.yml
파일에서 이미지를 지정하여이를 수행합니다. - 선택 사항. MySQL과 같은 다른 서비스를 컨테이너에 실행합니다. 이를 위해
.gitlab-ci.yml
파일에서 services를 지정합니다.
Docker executor를 사용하는 러너 등록
GitLab Runner와 Docker를 함께 사용하려면 Docker executor를 사용하는 러너를 등록해야합니다.
다음 예제는 서비스를 제공하도록 임시 템플릿을 설정하는 방법을 보여줍니다.
cat > /tmp/test-config.template.toml << EOF
[[runners]]
[runners.docker]
[[runners.docker.services]]
name = "postgres:latest"
[[runners.docker.services]]
name = "mysql:latest"
EOF
그런 다음이 템플릿을 사용하여 러너를 등록하십시오.
sudo gitlab-runner register \
--url "https://gitlab.example.com/" \
--registration-token "PROJECT_REGISTRATION_TOKEN" \
--description "docker-ruby:2.6" \
--executor "docker" \
--template-config /tmp/test-config.template.toml \
--docker-image ruby:2.6
등록된 러너는 ruby:2.6
Docker 이미지를 사용하고 빌드 프로세스 중에 액세스 할 수있는 postgres:latest
및 mysql:latest
두 가지 서비스를 실행합니다.
이미지란 무엇인가
image
키워드는 Docker executor가 CI/CD 작업을 실행하는 데 사용하는 Docker 이미지의 이름입니다.
기본적으로 executor는 Docker Hub에서 이미지를 가져옵니다.
그러나gitlab-runner/config.toml
파일에서 레지스트리 위치를 구성 할 수 있습니다.
예를 들어, Docker pull policy를 사용하여 로컬 이미지를 설정 할 수 있습니다.
이미지 및 Docker Hub에 대한 자세한 정보는 Docker 개요를 참조하십시오.
이미지 요구사항
CI/CD 작업을 실행하는 데 사용되는 모든 이미지는 다음의 애플리케이션이 설치되어 있어야합니다.
-
sh
또는bash
grep
.gitlab-ci.yml
파일에서 image
정의하기
모든 작업에 사용되는 이미지를 정의하고 실행 중에 사용하고자하는 서비스 디렉터리을 정의 할 수 있습니다.
default:
image: ruby:2.6
services:
- postgres:11.7
before_script:
- bundle install
test:
script:
- bundle exec rake spec
이미지 이름은 다음 형식 중 하나 여야합니다.
-
image: <image-name>
(latest
태그와 함께<image-name>
사용하는 것과 동일) image: <image-name>:<tag>
image: <image-name>@<digest>
비공개 컨테이너 레지스트리에서 이미지에 액세스
비공개 컨테이너 레지스트리에 액세스하려면 GitLab Runner 프로세스가 다음을 사용할 수 있습니다:
- 정적으로 정의된 자격 증명. 특정 레지스트리의 사용자 이름 및 암호입니다.
- 자격 증명 리포지터리. 자세한 내용은 관련 Docker 문서를 참조하십시오.
- 자격 증명 도우미. 자세한 내용은 관련 Docker 문서를 참조하십시오.
사용할 옵션을 정의하려면 러너 프로세스가 다음 순서대로 구성을 읽습니다:
-
DOCKER_AUTH_CONFIG
CI/CD 변수. - 러너의
config.toml
파일에서 설정된DOCKER_AUTH_CONFIG
환경 변수. - 프로세스를 실행하는 사용자의
$HOME/.docker
디렉터리의config.json
파일입니다. 자식 프로세스를 특권 없는 사용자로 실행하도록--user
플래그가 제공된 경우 메인 러너 프로세스 사용자의 홈 디렉터리가 사용됩니다.
요구 사항 및 제한 사항
- GitLab Runner 13.1 및 이후의 Kubernetes executor에서 사용할 수 있습니다.
-
자격 증명 리포지터리와 자격 증명 도우미를 사용하려면 이진 파일을 GitLab Runner
$PATH
에 추가하고 액세스 권한이 필요합니다. 따라서 이러한 기능은 인스턴스 러너나 러너가 설치된 환경에 액세스 권한이 없는 경우에는 사용할 수 없습니다.
정적으로 정의된 자격 증명 사용
비공개 레지스트리에 액세스하려면 두 가지 접근 방식이 있습니다.
두 경우 모두 적절한 인증 정보로 CI/CD 변수인 DOCKER_AUTH_CONFIG
를 설정해야 합니다.
- 작업별: 하나의 작업을 비공개 레지스트리에 액세스하도록 구성하려면
CI/CD 변수로
DOCKER_AUTH_CONFIG
를 추가하십시오. - 러너별: 모든 작업이 비공개 레지스트리에 액세스할 수 있도록 러너를 구성하려면
러너의 구성에서 환경 변수로
DOCKER_AUTH_CONFIG
를 추가하십시오.
아래 예제를 참조하세요.
DOCKER_AUTH_CONFIG
데이터 결정
예를 들어, registry.example.com:5000/private/image:latest
이미지에 액세스하려고 한다고 가정해 봅시다. 이 이미지는 비공개이며 비공개 컨테이너 레지스트리에 로그인해야 합니다.
다음은 로그인 자격 증명으로 가정한 내용입니다:
키 | 값 |
---|---|
레지스트리 | registry.example.com:5000
|
사용자 이름 | my_username
|
암호 | my_password
|
DOCKER_AUTH_CONFIG
의 값 결정을 위한 다음 방법 중 하나를 사용하십시오:
-
로컬 컴퓨터에서
docker login
을 수행:docker login registry.example.com:5000 --username my_username --password my_password
그런 다음
~/.docker/config.json
의 내용을 복사하십시오.컴퓨터에서 레지스트리에 액세스할 필요가 없으면
docker logout
을 실행하십시오:docker logout registry.example.com:5000
또는 일부 설정에서는 Docker 클라이언트가 사용 가능한 시스템 키 리포지터리를 사용하여
docker login
의 결과를 저장할 수 있습니다. 이 경우~/.docker/config.json
을 읽는 것이 불가능하므로${username}:${password}
의 필요한 base64로 인코딩된 버전을 준비하고 Docker 구성 JSON을 매뉴얼으로 작성해야 합니다. 터미널을 열고 다음 명령을 실행하십시오:# printf 사용 (echo 대신)은 암호에 새 줄을 인코딩하는 것을 방지합니다. printf "my_username:my_password" | openssl base64 -A # 복사할 예시 출력 bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
다음과 같이 Docker JSON 구성 내용을 작성하십시오:
{ "auths": { "registry.example.com:5000": { "auth": "(위의 Base64 콘텐츠)" } } }
작업 구성
registry.example.com:5000
에 액세스하는 단일 작업을 구성하려면 다음 단계를 따릅니다:
-
CI/CD 변수인
DOCKER_AUTH_CONFIG
를 Docker 구성 파일의 내용으로 추가하십시오:{ "auths": { "registry.example.com:5000": { "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" } } }
-
이제
.gitlab-ci.yml
파일의image
또는services
에 정의된registry.example.com:5000
에서 어떤 비공개 이미지든 사용할 수 있습니다:image: registry.example.com:5000/namespace/image:tag
위 예제에서 GitLab Runner는 이미지
namespace/image:tag
를 찾기 위해registry.example.com:5000
을 살펴봅니다.
원하는 레지스트리를 원하는 만큼 추가하여 "auths"
해시에 레지스트리를 추가할 수 있습니다.
러너가 DOCKER_AUTH_CONFIG
와 일치하도록하기 위해 모든 곳에 전체 hostname:port
조합이 필요합니다. 예를 들어 .gitlab-ci.yml
파일에 registry.example.com:5000/namespace/image:tag
가 지정된 경우 DOCKER_AUTH_CONFIG
에도 registry.example.com:5000
을 지정해야 합니다. registry.example.com
만 지정하는 것은 작동하지 않습니다.
러너 구성
동일한 레지스트리에 액세스하는 많은 파이프라인이 있다면 러너 수준에서 레지스트리 액세스를 설정해야 합니다. 이렇게 하면 파이프라인 작성자가 해당 러너에서 작업을 실행하기만 하면 비공개 레지스트리에 액세스할 수 있으며, 레지스트리 변경 및 자격 증명 로테이션을 간소화할 수 있습니다.
이것은 해당 러너의 모든 작업이 동일한 권한으로 레지스트리에 액세스할 수 있음을 의미합니다. 레지스트리 액세스를 제어해야 하는 경우 러너 액세스도 제어해야 합니다.
러너에 DOCKER_AUTH_CONFIG
를 추가하려면:
-
러너의
config.toml
파일을 다음과 같이 수정하십시오:[[runners]] environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"]
-
DOCKER_AUTH_CONFIG
의 데이터에 포함된 큰따옴표는 반드시 역슬래시로 이스케이프해야 합니다. 이렇게 하면 TOML로 해석되지 않게 됩니다. -
environment
옵션은 디렉터리입니다. 러너에 기존 항목이 있을 수 있으므로 디렉터리에 추가해야 합니다.
-
-
러너 서비스를 다시 시작하십시오.
자격 증명 리포지터리 사용
자격 증명 리포지터리를 구성하려면 다음을 수행해야 합니다:
-
자격 증명 리포지터리를 사용하려면 특정 키체인이나 외부 리포지터리와 상호 작용하는 외부 도우미 프로그램이 필요합니다. 해당 도우미 프로그램이 GitLab Runner
$PATH
에 있는지 확인하십시오. -
GitLab Runner가 사용하도록 하십시오. 두 가지 방법 중 하나로 할 수 있습니다:
-
CI/CD 변수에
DOCKER_AUTH_CONFIG
를 추가하십시오. Docker 구성 파일의 내용을 값으로 지정하면 됩니다.{ "credsStore": "osxkeychain" }
-
또는, Self-Managed형 러너의 경우 이전 JSON을
${GITLAB_RUNNER_HOME}/.docker/config.json
에 추가하십시오. GitLab Runner는 이 구성 파일을 읽어 이 리포지터리에 대해 필요한 도우미를 사용합니다.
-
credsStore
는 모든 레지스트리에 접근하는 데 사용됩니다.
만약 비공개 레지스트리에서 이미지와 Docker Hub의 공개 이미지를 모두 사용한다면 Docker Hub에서 가져오기가 실패합니다. Docker 데몬은 모든 레지스트리에 동일한 자격 증명을 사용하려고 시도합니다.
자격 증명 도우미 사용
- GitLab Runner 12.0에서 소개되었습니다.
예를 들어, <aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest
이미지를 사용하려고 한다고 가정해 봅시다. 이 이미지는 비공개이며 프라이빗 컨테이너 레지스트리에 로그인해야 합니다.
<aws_account_id>.dkr.ecr.<region>.amazonaws.com
에 대한 액세스를 구성하려면 다음 단계를 수행하세요.
- GitLab Runner의
$PATH
에docker-credential-ecr-login
이 있는지 확인합니다. - 다음 중 하나의 AWS 자격 증명을 설정합니다. GitLab Runner가 자격 증명에 액세스할 수 있도록 확인합니다.
-
GitLab Runner가 그것을 사용하도록 만듭니다. 이 작업을 수행하는 두 가지 방법이 있습니다. 아래 중 하나를 선택하세요.
-
다음 값으로
DOCKER_AUTH_CONFIG
환경 변수를 만듭니다. Docker 구성 파일의 내용을 값으로 사용합니다.{ "credHelpers": { "<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login" } }
이렇게 하면 Docker가 특정 레지스트리에 대해 자격 증명 도우미를 사용하도록 설정됩니다.
대신, Docker가 Amazon Elastic Container Registry (ECR) 레지스트리를 모두 위해 자격 증명 도우미를 사용하도록 구성할 수도 있습니다.
{ "credsStore": "ecr-login" }
-
또는, Self-Managed Runner를 실행 중이라면, 이전의 JSON을
${GITLAB_RUNNER_HOME}/.docker/config.json
에 추가합니다. GitLab Runner는 이 구성 파일을 읽고 해당 리포지터리에 필요한 도우미를 사용합니다.
-
-
이제
.gitlab-ci.yml
파일의image
나services
에서 정의된<aws_account_id>.dkr.ecr.<region>.amazonaws.com
에서 비공개 이미지를 사용할 수 있습니다.image: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest
위의 예에서 GitLab Runner는 이미지
private/image:latest
를 위해<aws_account_id>.dkr.ecr.<region>.amazonaws.com
를 살펴봅니다.
필요한 만큼 많은 레지스트리를 위한 구성을 추가할 수 있습니다.
이미지의 무결성을 보장하기 위해 체크섬 사용
이미지의 무결성을 확인하기 위해 .gitlab-ci.yml
파일에서 작업 정의에 이미지 체크섬을 사용하는 것을 권장합니다. 실패한 이미지 무결성 확인은 수정된 컨테이너 사용을 방지합니다.
이미지 체크섬을 사용하려면 다음과 같이 끝에 체크섬을 추가해야 합니다.
image: ruby:2.6.8@sha256:d1dbaf9665fe8b2175198e49438092fdbcf4d8934200942b94425301b17853c7
이미지 체크섬을 가져오려면, 이미지 TAG
탭에서 DIGEST
열을 확인하세요.
예를 들어 Ruby 이미지를 확인합니다.
체크섬은 6155f0235e95
와 같은 임의의 문자열입니다.
또한 docker images --digests
명령어로 시스템의 모든 이미지의 체크섬을 확인할 수 있습니다.
❯ docker images --digests
REPOSITORY TAG DIGEST (...)
gitlab/gitlab-ee latest sha256:723aa6edd8f122d50cae490b1743a616d54d4a910db892314d68470cc39dfb24 (...)
gitlab/gitlab-runner latest sha256:4a18a80f5be5df44cb7575f6b89d1fdda343297c6fd666c015c0e778b276e726 (...)
사용자 지정 GitLab Runner Docker 이미지 생성
AWS CLI 및 Amazon ECR Credential Helper를 패키지화하기 위해 사용자 지정 GitLab Runner Docker 이미지를 생성할 수 있습니다. 이 설정을 통해 컨테이너화된 애플리케이션에 대한 AWS 서비스와의 상호 작용을 안전하고 효율적으로 처리할 수 있습니다. 예를 들어, AWS에서 마이크로서비스를 배포하는 팀은 이 설정을 사용하여 매뉴얼 자격 증명 관리 없이 Amazon ECR에서 Docker 이미지를 관리, 배포 및 업데이트할 수 있습니다.
- AWS와 GitLab의 인증.
-
다음 내용으로
Dockerfile
을 만듭니다.# 패키지 버전 관리 ARG GITLAB_RUNNER_VERSION=v16.4.0 ARG AWS_CLI_VERSION=2.2.30 # AWS CLI 및 Amazon ECR Credential Helper FROM amazonlinux as aws-tools RUN set -e \ && yum update -y \ && yum install -y --allowerasing git make gcc curl unzip \ && curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip" \ && unzip awscliv2.zip && ./aws/install -i /usr/local/bin \ && yum clean all # ECR Credential Helper 다운로드 및 설치 RUN curl --location --output /usr/local/bin/docker-credential-ecr-login "https://github.com/awslabs/amazon-ecr-credential-helper/releases/latest/download/docker-credential-ecr-login-linux-amd64" RUN chmod +x /usr/local/bin/docker-credential-ecr-login # ECR 자격 증명 도우미 구성 RUN mkdir -p /root/.docker RUN echo '{ "credsStore": "ecr-login" }' > /root/.docker/config.json # GitLab Runner를 기반으로 하는 최종 이미지 FROM gitlab/gitlab-runner:${GITLAB_RUNNER_VERSION} # 필요한 패키지 설치 RUN apt-get update \ && apt-get install -y --no-install-recommends jq procps curl unzip groff libgcrypt20 tar gzip less openssh-client \ && apt-get clean && rm -rf /var/lib/apt/lists/* # AWS CLI 및 Amazon ECR Credential Helper 이진 파일 복사 COPY --from=aws-tools /usr/local/bin/ /usr/local/bin/ # ECR Credential Helper 구성 복사 COPY --from=aws-tools /root/.docker/config.json /root/.docker/config.json
-
.gitlab-ci.yml
내에서 사용자 정의 GitLab Runner Docker 이미지를 빌드하려면 아래 예제를 포함하세요.variables: DOCKER_DRIVER: overlay2 IMAGE_NAME: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME GITLAB_RUNNER_VERSION: v16.4.0 AWS_CLI_VERSION: 2.13.21 stages: - build build-image: stage: build script: - echo "GitLab 컨테이너 레지스트리에 로그인 중..." - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - echo "Docker 이미지 빌드 중..." - docker build --build-arg GITLAB_RUNNER_VERSION=${GITLAB_RUNNER_VERSION} --build-arg AWS_CLI_VERSION=${AWS_CLI_VERSION} -t ${IMAGE_NAME} . - echo "Docker 이미지를 GitLab 컨테이너 레지스트리에 푸시 중..." - docker push ${IMAGE_NAME} rules: - changes: - Dockerfile
- Runner 등록.