플로 실행용 이미지 구성
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
CI/CD로 실행되는 플로는 Docker 이미지 안에서 동작합니다. agent-config.yml에 image를 설정하지 않으면 플로는 기본 이미지를 사용합니다. 기본 이미지는 registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image에 게시됩니다.
CI/CD로 실행되는 플로는 Docker 이미지 안에서 동작합니다. 기본적으로 GitLab은 플로에 필요한 도구와 네트워크 보호 기능이 포함된 이미지를 제공합니다. 프로젝트 의존성을 추가하거나 컴플라이언스 요구 사항을 충족하거나 오프라인 환경에서 플로를 실행하려면, 기본 이미지를 사용자 지정 이미지나 하드닝된 이미지로 교체할 수 있습니다.
플로의 기본 이미지#
agent-config.yml에 image를 설정하지 않으면 플로는 기본 이미지를 사용합니다. 기본 이미지는
Red Hat UBI 9 Minimal을 기반으로 하며 root로 실행됩니다. Anthropic Sandbox Runtime(SRT)과
일반적인 언어 런타임 모음을 포함하므로, 많은 프로젝트에서 사용자 지정 이미지 없이 플로를 실행할 수 있습니다.
기본 이미지는
registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image에 게시됩니다.
이 이미지는 linux/amd64와 linux/arm64용으로 빌드되며 다음 태그 체계를 사용합니다.
- 빌드마다
:<short-sha> - 릴리스마다
:<git-tag>
이미지 구성 요소#
모든 구성 요소와 고정된 버전의 정본 최신 목록은
기본 이미지 런타임 인벤토리를
default-docker-image README에서 참고합니다.
다음 표는 현재 고정된 버전을 보여 줍니다.
| 구성 요소 | 버전 또는 출처 |
|---|---|
| Base image | Red Hat UBI 9 Minimal (ubi9-minimal:9.7-1776833838) |
git |
2.47.x (UBI 9 stock) |
git-lfs |
UBI 9 stock |
| Node.js | 20 (UBI 9 module stream nodejs:20) |
npm |
Bundled with Node.js 20 |
@gitlab/duo-cli |
10.3.0 |
glab (GitLab CLI) |
1.128.0 |
@anthropic-ai/sandbox-runtime (SRT) |
0.0.77 (via npm) |
bwrap (bubblewrap) |
AlmaLinux 9 EPEL (plain binary, root-based sandboxing) |
socat |
AlmaLinux 9 EPEL |
rg (ripgrep) |
AlmaLinux 9 EPEL |
unshare |
UBI 9 (util-linux-core) |
| Python | 3.12 with pip (python3.12, python3.12-pip) |
| Go | 1.22.12 (upstream tarball) |
| Ruby | 3.3 (UBI 9 module stream ruby:3.3) |
| Java | 17 (java-17-openjdk-headless) |
| Runtime user | root |
기본 이미지와 하드닝된 이미지는 하나의 기본 레이어를 공유합니다. 하드닝된 이미지는
그 레이어에 GitLab Duo CLI, glab, SRT를 추가합니다. 기본 이미지는 언어
런타임을 추가한 다음 같은 도구를 추가합니다. 두 이미지는 런타임 사용자와
샌드박스가 권한을 얻는 방식이 다릅니다. 기본 이미지는 root로 실행되며 root 기반
샌드박싱을 사용하고, 하드닝된 이미지는 UID 1001로 실행되며 권한 없는 사용자
네임스페이스에 의존합니다.
기본 Docker 이미지 변경#
CI/CD로 실행되는 모든 플로는 GitLab이 제공하는 Docker 이미지를 사용합니다.
이 Docker 이미지는 Anthropic Sandbox Runtime(srt)을
사용해 네트워크 보호 기능을 자동으로 포함합니다.
특정 의존성이나 도구가 필요한 복잡한 프로젝트라면 Docker 이미지를 변경할 수 있습니다.
기본 Docker 이미지를 변경하려면 agent-config.yml 파일에 다음 구성을 추가합니다.
image: YOUR_DOCKER_IMAGE
예를 들면 다음과 같습니다.
image: python:3.11-slim
image: node:20-alpine
네트워크 보호 추가#
이미지에서 네트워크 보호 기능을 사용하려면 원하는 버전의 srt를
Docker 이미지에 추가합니다.
# Install srt sandboxing with cache clearing and verification
ARG SANDBOX_RUNTIME_VERSION=0.0.77
RUN npm cache clean --force && \
npm install -g @anthropic-ai/sandbox-runtime@${SANDBOX_RUNTIME_VERSION} && \
test -s "$(npm root -g)/@anthropic-ai/sandbox-runtime/package.json" && \
srt --version
SRT와 사용자 지정 이미지에 SRT를 설치하는 방법에 대한 자세한 내용은 원격 실행 환경 샌드박스를 참고합니다.
사용자 지정 이미지 사용#
사용자 지정 Docker 이미지를 사용하는 경우, 에이전트가 올바르게 동작하도록 다음 명령을 사용할 수 있는지 확인합니다.
git2.31 이상. 플로는 환경 변수로 설정되는 자격 증명 헬퍼로 Git 작업을 인증하는데, 이전 버전의 Git은 이를 무시합니다. 이전 버전에서는 푸시처럼 플로의 토큰이 필요한 Git 작업이 실패합니다.curl. 플로 시작 시 GitLab Duo CLI 바이너리를 내려받습니다.
대부분의 베이스 이미지에는 이 명령이 기본으로 포함되어 있습니다. 다만 alpine 계열처럼 최소 구성
이미지에서는 직접 설치해야 할 수 있습니다. 필요하다면
설정 스크립트 구성에서 빠진 명령을 설치할 수 있습니다.
coding_environment: none인 플로는 설정 스크립트를
건너뜁니다. 이러한 플로에서는 이미지 자체에 curl 또는 GitLab Duo CLI가 포함되어 있어야 합니다.
GitLab 18.9 이하에서는 사용자 지정 이미지의 git 버전이 최신인 경우 플로가 실패할 수 있는 알려진 이슈(587996)가 있습니다. 이 이슈는 @gitlab/duo-cli 8.71.0 버전에서 해결되었습니다.
@gitlab/duo-cli 8.71.0 이하를 사용하고 있고 최신 Git 버전에서 플로가 실패하는 것을 피하려면 다음 중 하나를 수행합니다.
- 사용자 지정 이미지에서 Git
2.43.7이하 버전을 사용합니다. @gitlab/duo-cli8.71.0 버전을 사용합니다.
또한 플로 실행 중 에이전트가 호출하는 도구에 따라 다른 공통 유틸리티가 필요할 수 있습니다.
예를 들어 Alpine 기반 이미지를 사용한다면 다음과 같이 구성합니다.
image: python:3.11-alpine
setup_script:
- apk add --update git curl
보안 및 성능#
사용자 지정 Docker 이미지를 사용하는 경우 환경 샌드박스는 사용자 지정 이미지에 Anthropic Sandbox Runtime(SRT)이 포함되어 있을 때만 적용됩니다. SRT가 포함되어 있지 않으면 플로가 러너에서 도달 가능한 모든 도메인과 전체 파일 시스템에 접근할 수 있습니다.
사용자 지정 이미지에서 네트워크 격리가 필요하다면 이미지에 SRT를 설치하고 네트워크 정책을 구성하거나, 러너에 네트워크 수준 제어를 구성합니다(예: 방화벽 규칙이나 네트워크 정책).
job 시작 시간을 약 15~20초 단축하려면 사용자 지정 이미지에
GitLab Duo CLI 바이너리와 glab CLI를 포함합니다.
기본 이미지와 하드닝된 이미지에는 두 도구가 모두 사전 설치되어 있습니다.
오프라인 환경에서 사용자 지정 이미지 사용#
러너가 외부 레지스트리에 접근할 수 없는 오프라인 환경에서는 GitLab Duo CLI가 포함된 사용자 지정 실행기 이미지를 미리 빌드할 수 있습니다. GitLab Duo CLI가 이미 이미지에 있으면 플로를 시작할 때 다운로드 단계를 건너뜁니다.
사전 요건:
- 관리자 액세스 권한.
- GitLab 18.9 이상.
- 이미지를 빌드하고 아티팩트를 내려받을 수 있는 온라인 머신에 대한 접근 권한.
Executor 이미지 v0.0.11 이상은 /usr/local/bin/duo에 GitLab Duo CLI를 포함하므로
플로가 런타임에 이를 내려받지 않습니다. GitLab 버전이 이전 태그를 요청하거나
다른 GitLab Duo CLI 버전이 필요한 경우에만 사용자 지정 이미지를 빌드합니다.
오프라인 환경에 맞게 플로를 구성하려면 다음 단계를 따릅니다.
-
온라인 머신에서 GitLab 패키지 레지스트리에서 GitLab Duo CLI 바이너리를 내려받습니다.
curl --location "https://gitlab.com/api/v4/projects/46519181/packages/generic/duo-cli/10.3.0/duo-linux-x64" \ --output duo-linux-x64 -
해당 바이너리가 포함된 사용자 지정 이미지를 빌드합니다.
FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.1.1 COPY duo-linux-x64 /usr/local/bin/duo RUN chmod +x /usr/local/bin/duo -
이미지를 오프라인 환경으로 전송합니다. 예를 들어 Docker에서는 다음 명령을 실행합니다.
# On an online machine docker save my-duo-executor:latest -o duo-executor.tar # Transfer `duo-executor.tar` to the offline environment # On an offline machine docker load -i duo-executor.tar -
이미지를 내부 컨테이너 레지스트리에 푸시합니다.
-
사용자 지정 이미지 레지스트리를 설정합니다.
- 오른쪽 위 모서리에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
- Change configuration을 선택합니다.
- Image registry 텍스트 상자에 사용자 지정 이미지의 전체 참조를 입력합니다
(예:
registry.internal.example.com/duo-executor:latest). 레지스트리 호스트 이름만 입력하면 자체 이미지를 설정하지 않은 플로는 GitLab 버전이 요청하는 태그로<hostname>/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image를 가져옵니다.
-
상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
-
사용자 지정 이미지를 사용하려면
agent-config.yml파일을 수정합니다.image: registry.internal.example.com/duo-executor:latest
GitLab 컨테이너 레지스트리에서 이미지를 가져오도록 플로 구성#
같은 GitLab 인스턴스에 있는 프로젝트의 컨테이너 레지스트리에 이미지를 푸시하면, 플로의 CI/CD job이 프로젝트 간에 이미지를 가져옵니다. 이 작업은 구성하기 전까지 실패합니다. job은 GitLab이 플로용으로 만드는 서비스 계정으로 실행되고, GitLab은 이 계정을 외부 사용자로 만들기 때문입니다. 내부 프로젝트는 외부 계정에게 비공개로 보이므로 레지스트리가 가져오기를 거부합니다.
가져오기가 성공하려면 두 조건이 모두 충족되어야 합니다. 서비스 계정이 호스트 프로젝트의 컨테이너 레지스트리를 읽을 수 있어야 하고, 플로를 트리거하는 사용자도 읽을 수 있어야 합니다. 복합 ID는 서비스 계정을 해당 사용자의 액세스 범위로 제한하므로, 플로는 트리거한 사용자에게 없는 권한을 가질 수 없습니다. 한 조건만 충족하면 가져오기는 여전히 거부됩니다.
서비스 계정에 액세스 권한을 부여하려면 계정을 외부 사용자가 아니게 하거나 호스트 프로젝트의 멤버로 추가합니다.
계정을 외부 사용자가 아니게 하는 방법은 다음과 같습니다.
- 이미지를 호스팅하는 프로젝트를 내부 공개 범위로 설정합니다. 컨테이너 레지스트리 공개 범위는 Everyone With Access로 설정합니다. Only Project Members를 선택하면 가져오기가 실패합니다. 자세한 내용은 프로젝트 기능 및 권한 구성을 참조합니다.
- 오른쪽 위 모서리에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 Overview > Users를 선택합니다.
- GitLab이 플로용으로 만든 서비스 계정을 찾아 Edit를 선택합니다.
- Access 섹션에서 External 체크박스를 선택 해제합니다.
- Save changes를 선택합니다.
대신 계정을 호스트 프로젝트의 멤버로 추가하는 방법은 다음과 같습니다.
- 서비스 계정을 호스트 프로젝트에 Developer 이상의 권한을 가진 멤버로 추가합니다.
- 플로를 실행하는 프로젝트를 호스트 프로젝트의 job 토큰 허용 목록에 추가합니다.
허용 목록 항목 없이 멤버십만으로는 충분하지 않습니다.
플로를 트리거하는 사용자도 다른 사용자와 같은 규칙으로 호스트 프로젝트에 대한 액세스 권한이 필요합니다. 내부 호스트 프로젝트에서는 외부 사용자가 아니어야 합니다. 비공개 호스트 프로젝트에서는 Reporter 이상의 권한을 가진 멤버여야 합니다. Guest 권한은 충분하지 않습니다. Guest는 프로젝트를 볼 수 있지만 컨테이너 레지스트리에서 가져올 수는 없기 때문입니다.
이미지 가져오기용 자격 증명 제공#
이미지가 있는 레지스트리에 자격 증명이 필요하다면
플로의 job을 실행하는 러너에 자격 증명을 구성합니다. GitLab이 호스팅하는 레지스트리와
호스팅하지 않는 레지스트리 모두에 자격 증명을 구성할 수 있습니다.
기본적으로 플로의 job은 프로젝트, 그룹, 인스턴스 수준에서 구성한 CI/CD 변수를 받지 않으므로,
그곳에 정의한 DOCKER_AUTH_CONFIG 변수는 적용되지 않으며 값을
마스킹할 수도 없습니다.
러너에 자격 증명을 제공하는 방법은 다음과 같습니다.
- 이미지를 호스팅하는 프로젝트에서
read_registry스코프로 배포 토큰을 만듭니다. DOCKER_AUTH_CONFIG를 러너에 추가합니다. 러너의config.toml파일[[runners]]섹션의environment목록 항목으로 추가합니다.
Red Hat Universal Base Image 9 Minimal 사용#
히스토리
- GitLab 19.0에서 도입되었습니다.
GitLab은 Red Hat Universal Base Image(UBI) 9 Minimal을 기반으로 하드닝된 최소 구성 이미지 변형을 제공합니다.
다음이 필요한 환경에서는 하드닝된 이미지를 사용합니다.
- Red Hat UBI 베이스 이미지. 예를 들어 FedRAMP 또는 엔터프라이즈 컴플라이언스 요구 사항이 있는 경우입니다.
- 기본적으로 비루트 컨테이너 실행이 필요한 경우입니다.
- Agent Platform 자체에 필요한 것 외의 언어 런타임이 없는 최소 공격 표면이 필요한 경우입니다.
- 플로 실행 시점에 외부 인터넷 접근이 없어야 하는 경우입니다(모든 Agent Platform 의존성이 미리 설치되어 있습니다).
하드닝된 이미지는 다음 위치에 게시되어 있습니다.
registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened
이 이미지는 linux/amd64와 linux/arm64 모두를 대상으로 빌드되며, 다음 태그 체계를 사용합니다.
- 빌드마다
:<short-sha> - 릴리스마다
:<git-tag>
사전 요건:
- GitLab 18.10 이상
하드닝된 이미지를 사용하려면 agent-config.yml에 다음과 같이 설정합니다.
image: registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened:<tag>
이미지 구성 요소#
모든 구성 요소와 고정된 버전의 정본 최신 목록은
하드닝된 이미지 런타임 인벤토리를
default-docker-image README에서 참고합니다.
다음 표는 현재 고정된 버전을 보여 줍니다.
| 구성 요소 | 버전 또는 출처 |
|---|---|
| Base image | Red Hat UBI 9 Minimal (ubi9-minimal:9.7-1776833838) |
git |
2.47.x (UBI 9 stock) |
git-lfs |
UBI 9 stock |
| Node.js | 20 (UBI 9 module stream nodejs:20) |
npm |
Bundled with Node.js 20 |
@gitlab/duo-cli |
10.3.0 |
glab (GitLab CLI) |
1.128.0 |
@anthropic-ai/sandbox-runtime (SRT) |
0.0.77 (via npm) |
bwrap (bubblewrap) |
AlmaLinux 9 EPEL (plain binary, userns-based sandboxing) |
socat |
AlmaLinux 9 EPEL |
rg (ripgrep) |
AlmaLinux 9 EPEL |
unshare |
UBI 9 (util-linux-core) |
| Runtime user | Non-root, UID 1001 (duo-runner), HOME=/home/duo-runner |
이 이미지에는 GitLab Duo CLI와 glab 이 포함되어 있습니다. 플로 실행 시점에 registry.npmjs.org 나 registry.gitlab.com 으로의
외부 접근은 필요하지 않습니다.
Node.js와 npm은 Anthropic Sandbox Runtime(SRT)을 설치하기 위해서만 이미지에 남아 있습니다.
GitLab Duo CLI 자체는 미리 컴파일된 바이너리이므로 이 둘이 필요하지 않습니다. SRT도
미리 컴파일된 바이너리로 배포되면, 이후 버전의 하드닝된 이미지에서는 Node.js와
npm 이 완전히 제거됩니다.
추가 패키지 추가#
하드닝된 이미지는 UID 1001(duo-runner)로 실행됩니다. agent-config.yml의 setup_script 역시
이 비루트 사용자로 실행되므로 microdnf로 시스템 패키지를 설치할 수 없습니다.
언어 런타임이나 시스템 패키지를 추가하려면 다음 단계를 따릅니다.
-
직접 만든
FROM레이어로 이미지를 확장합니다.FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened:<tag> USER root RUN microdnf install -y python3.12 python3.12-pip && microdnf clean all USER 1001 -
루트 권한이 필요하지 않은 프로젝트 의존성은
setup_script를 사용합니다. 예를 들어pip install --user나npm install입니다.