오프라인 환경에 GitLab Duo Agent Platform Self-Hosted 배포
GitLab v19.6Offering: GitLab Self-Managed
요약
오프라인 환경을 구성하려면 구매 전에 클라우드 라이선스 옵트아웃 면제를 받아야 합니다. GitLab 인스턴스와 러너가 공용 인터넷에 접근할 수 없는 오프라인 환경에도 GitLab Duo Agent Platform Self-Hosted를 배포할 수 있습니다.
히스토리
- GitLab 17.9에서 셀프 호스팅 모델 지원이 일반적으로 사용 가능해졌습니다.
- GitLab 18.9에서 오프라인 플로 실행 지원이 도입됐습니다.
오프라인 환경을 구성하려면 구매 전에 클라우드 라이선스 옵트아웃 면제를 받아야 합니다. 자세한 내용은 GitLab 영업 담당자에게 문의합니다.
GitLab 인스턴스와 러너가 공용 인터넷에 접근할 수 없는 오프라인 환경에도 GitLab Duo Agent Platform Self-Hosted를 배포할 수 있습니다. 이 지침은 연결이 제한적이거나 방화벽 정책이 엄격한 환경에도 적용됩니다.
오프라인 환경에서는 AI Gateway 컨테이너 이미지, LLM 모델 가중치, vLLM 추론 서버 이미지, Agent Platform Flows 실행기 이미지를 내부 인프라로 직접 전송해야 합니다.
오프라인 환경에 Agent Platform을 배포하려면 다음 단계를 수행합니다.
- 컨테이너 이미지를 내부 레지스트리로 전송합니다.
- LLM 모델 가중치를 오프라인 파일 시스템으로 전송합니다.
- AI Gateway를 시작합니다.
- vLLM을 시작합니다.
- GitLab Admin에서 AI Gateway를 구성합니다.
- 셀프 호스팅 모델을 추가합니다.
- 오프라인 플로 실행을 구성합니다.
- 배포를 확인합니다.
사전 요구 사항#
- 오프라인 클라우드 라이선스가 적용된 GitLab 18.9 이상.
- 아티팩트를 내려받을 인터넷 연결이 있는 머신.
- 연결된 머신과 오프라인 호스트에 설치된 skopeo와
jq
(Red Hat 계열 시스템에서는
dnf install --assumeyes skopeo jq명령을 사용합니다). - 오프라인 환경으로 파일을 전송할 방법 (물리 매체, 크로스 도메인 솔루션, 배스천 호스트).
- 오프라인 환경의 컨테이너 레지스트리. 예를 들어 GitLab 컨테이너 레지스트리, Harbor, Nexus가 있습니다.
- vLLM의 경우: 추론 호스트에 NVIDIA GPU 드라이버, CUDA 라이브러리, NVIDIA Container Toolkit을 설치합니다. 오프라인 설치 옵션은 NVIDIA CUDA 설치 가이드를 참고합니다.
이 페이지의 모든 명령은 Docker와 Podman에서 모두 동작합니다.
해당하는 경우 docker를 podman으로 바꿉니다.
필수 아티팩트#
LLM 모델 가중치를 제외한 모든 아티팩트는 OCI 컨테이너 이미지입니다.
GitLab 인스턴스 자체가 실행하는 컨테이너 이미지는 별도로 전송합니다. 자세한 내용은 오프라인 GitLab을 참고합니다.
컨테이너 이미지#
| 아티팩트 | 소스 레지스트리 | 태그 형식 | 대략적인 압축 크기 |
|---|---|---|---|
| AI Gateway | registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway |
self-hosted-vX.Y.Z-ee |
0.6 GiB |
| Agent Platform Flows 실행기 | registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image |
vX.Y.Z |
0.5 GiB |
| vLLM 추론 서버 | docker.io/vllm/vllm-openai |
vX.Y.Z (v0.18.1 이상) |
9 GiB |
표에 적힌 크기는 전송하는 압축 크기입니다.
각 이미지는 레지스트리에 로드하거나 호스트로 가져오면 더 커집니다.
전송 전에 크기를 확인하려면
skopeo inspect --raw docker://<image>:<tag>를 실행하고 출력에 나오는 config와
layers 크기를 더합니다.
AI Gateway 태그는 GitLab 버전 번호를 사용합니다.
형식은 self-hosted-v<your-gitlab-version>-ee입니다.
실행기 태그는 사용 중인 GitLab 버전이 플로를 시작할 때 요청하는 태그와
일치해야 합니다.
이 태그는 릴리스마다 고정돼 있습니다. 태그를 확인하려면
ee/app/services/ai/duo_workflows/start_workflow_service.rb 파일에서
해당 버전의 IMAGE_PATH 상수를 확인합니다.
이 태그는 플로가 생성하는 CI/CD job의 이미지로도 표시됩니다.
레지스트리의 최신 태그는 사용 중인 버전이 요청하는 태그보다 앞서 있는
경우가 많으므로, 레지스트리 목록을 보고 태그를 고르지 않습니다.
오프라인 환경에서는 버전 기본값을 따라가지 말고 전송한 이미지로 인스턴스를 고정합니다. 다음 중 하나를 사용합니다.
- 프로젝트의
.gitlab/duo/agent-config.yml파일에 있는image키. 이 키는 해당 프로젝트의 플로에 적용됩니다. duo_workflows_default_image_registry애플리케이션 설정. 이 설정은 태그를 포함한 전체 이미지 참조를 받으며 모든 프로젝트에 적용됩니다.
GitLab Duo Agentic Chat, Code Suggestions, GitLab Duo Code Review,
Agent Platform 플로에는 ClickHouse가 필요하지 않습니다.
GitLab Duo 사용량 분석이 필요하면
ClickHouse
(docker.io/clickhouse/clickhouse-server)도 전송하고 구성해야 합니다.
FIPS 검증 환경에서는 표준 이미지 대신 AI Gateway FIPS 이미지를
사용합니다.
FIPS 이미지는 동일한 self-hosted-vX.Y.Z-ee 태그 형식을 사용합니다.
FIPS 버전 태그는 GitLab 18.10 이상에서 제공됩니다.
자세한 내용은
FIPS 검증 이미지를 참고합니다.
skopeo copy와 docker save 모두 이미지 서명을 전송하지 않습니다.
FIPS 이미지의 진위를 확인하려면 이미지를 전송하기 전에 연결된 머신에서
cosign verify를
실행합니다.
LLM 모델 가중치#
LLM 모델 가중치는 vLLM이 파일 시스템에서 직접 읽는 대용량 파일입니다. 이 파일은 컨테이너 이미지로 배포되지 않습니다.
이 페이지의 예시에서는 Mistral Small 24B(약 48GB)를 사용합니다. 이 모델은 Code Suggestions와 GitLab Duo Chat을 모두 지원합니다. 다른 모델 선택지와 GPU 요구 사항은 지원 모델 및 하드웨어 요구 사항을 참고합니다.
컨테이너 이미지 전송#
연결된 머신에서 필요한 이미지를 아카이브로 저장한 다음, 오프라인 환경의 내부 레지스트리로 로드합니다.
연결된 머신에서 이미지 저장#
이미지를 저장하려면 인터넷에 연결된 머신에서 다음 명령으로 skopeo를 실행합니다.
GITLAB_VERSION="18.10.0"
EXECUTOR_VERSION="v0.0.6"
VLLM_VERSION="v0.18.1"
skopeo copy \
docker://registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v${GITLAB_VERSION}-ee \
docker-archive:aigw.tar
skopeo copy \
docker://registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:${EXECUTOR_VERSION} \
docker-archive:executor.tar
skopeo copy \
docker://docker.io/vllm/vllm-openai:${VLLM_VERSION} \
docker-archive:vllm.tar
연결된 머신이 프록시를 사용하면 skopeo를 실행하기 전에 HTTPS_PROXY를
설정합니다.
export HTTPS_PROXY="http://proxy.example.com:8080"
skopeo를 사용할 수 없으면 docker save를 대신 사용합니다.
GITLAB_VERSION="18.10.0"
docker pull registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v${GITLAB_VERSION}-ee
docker save \
registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v${GITLAB_VERSION}-ee \
--output aigw.tar
내부 레지스트리로 이미지 로드#
아카이브를 오프라인 환경으로 전송한 다음 내부 레지스트리로 로드합니다.
셸 변수는 머신 간에 유지되지 않습니다.
오프라인 호스트에서 INTERNAL_REGISTRY, GITLAB_VERSION, EXECUTOR_VERSION,
VLLM_VERSION을 다시 설정합니다.
내부 레지스트리가 자체 서명 인증서를 사용하면 skopeo가 이를 신뢰하도록 구성합니다.
mkdir --parents /etc/containers/certs.d/<registry-host>
cp ca.crt /etc/containers/certs.d/<registry-host>/ca.crt
그런 다음 이미지를 로드합니다.
INTERNAL_REGISTRY="registry.internal.example.com/duo"
GITLAB_VERSION="18.10.0"
EXECUTOR_VERSION="v0.0.6"
VLLM_VERSION="v0.18.1"
skopeo copy \
docker-archive:aigw.tar \
docker://${INTERNAL_REGISTRY}/ai-gateway:self-hosted-v${GITLAB_VERSION}-ee
skopeo copy \
docker-archive:executor.tar \
docker://${INTERNAL_REGISTRY}/workflow-generic-image:${EXECUTOR_VERSION}
skopeo copy \
docker-archive:vllm.tar \
docker://${INTERNAL_REGISTRY}/vllm-openai:${VLLM_VERSION}
LLM 모델 가중치 전송#
연결된 머신에서 모델 가중치를 내려받으려면 Hugging Face CLI 또는
git lfs를 사용합니다.
Hugging Face CLI를 사용하는 경우는 다음과 같습니다.
pip install huggingface_hub
huggingface-cli download mistralai/Mistral-Small-3.2-24B-Instruct-2506 \
--local-dir ./mistral-small-3.2-24b
사용 중인 huggingface_hub 버전에 huggingface-cli가 없으면
같은 인수로 hf download를 사용합니다.
git lfs를 사용하는 경우는 다음과 같습니다(Python이 필요하지 않습니다).
dnf install --assumeyes git-lfs # On Debian/Ubuntu: apt-get install git-lfs
git lfs install
git clone https://huggingface.co/mistralai/Mistral-Small-3.2-24B-Instruct-2506
내려받은 디렉터리를 오프라인 환경으로 전송한 다음, vLLM 컨테이너가
접근할 수 있는 파일 시스템 경로에 둡니다
(예: /data/models/mistral-small-3.2-24b).
AI Gateway 시작#
내부 레지스트리 이미지로 AI Gateway 컨테이너를 실행하려면 다음을 수행합니다.
-
필요한 JWT 서명 키를 생성합니다.
openssl genrsa -out aigw_signing.key 2048 openssl genrsa -out aigw_validation.key 2048 openssl genrsa -out duo_workflow_jwt.key 2048 openssl genrsa -out duo_workflow_validation.key 2048 -
내부 레지스트리 이미지로 AI Gateway 컨테이너를 실행합니다.
INTERNAL_REGISTRY="registry.internal.example.com/duo" GITLAB_VERSION="18.10.0" GITLAB_DOMAIN="gitlab.internal.example.com" docker run --detach \ --publish 5052:5052 \ --publish 50052:50052 \ --env AIGW_GITLAB_URL=https://${GITLAB_DOMAIN} \ --env AIGW_GITLAB_API_URL=https://${GITLAB_DOMAIN}/api/v4/ \ --env AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \ --env AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)" \ --env DUO_WORKFLOW_AUTH__ENABLED="true" \ --env DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat duo_workflow_jwt.key)" \ --env DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat duo_workflow_validation.key)" \ --env DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL=https://${GITLAB_DOMAIN} \ --env AIGW_CUSTOMER_PORTAL_URL=https://${GITLAB_DOMAIN} \ ${INTERNAL_REGISTRY}/ai-gateway:self-hosted-v${GITLAB_VERSION}-ee
DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL과 AIGW_CUSTOMER_PORTAL_URL을
GitLab 인스턴스 URL로 설정하면 다음이 보장됩니다.
- AI Gateway가 오프라인 환경에서 사용할 수 없는 Customers Portal에 접근을 시도하지 않습니다.
- 요청마다 20초 지연이 발생하지 않습니다.
TLS 종료와 추가 구성 옵션은 자체 호스팅 AI Gateway를 참고합니다.
vLLM 시작#
전송한 모델 가중치를 제공하도록 vLLM을 실행합니다.
INTERNAL_REGISTRY="registry.internal.example.com/duo"
VLLM_VERSION="v0.18.1"
docker run --detach \
--gpus all \
--volume /data/models/mistral-small-3.2-24b:/model \
--publish 8000:8000 \
${INTERNAL_REGISTRY}/vllm-openai:${VLLM_VERSION} \
--model /model \
--served_model_name custom_openai/mistral-small-3.2-24b \
--tensor-parallel-size <number-of-gpus>
<number-of-gpus>를 사용 가능한 GPU 수로 바꿉니다.
GPU가 하나면 --tensor-parallel-size 1을 사용합니다.
Podman에서는 --gpus all을
--device nvidia.com/gpu=all --security-opt label=disable로 바꿉니다.
SELinux를 enforcing 모드로 사용하는 시스템에서 GPU 장치에 접근하려면
--security-opt label=disable 플래그가 필요합니다.
시작한 뒤 모델이 로드됐는지 확인합니다.
curl --silent "http://localhost:8000/v1/models"
- vLLM 구성에 대한 자세한 내용은 지원되는 LLM 서빙 플랫폼을 참고합니다.
- vLLM 배포 방법은 vLLM을 사용한 모델 배포 예시를 참고합니다.
GitLab에서 AI Gateway 구성#
AI Gateway와 vLLM이 실행되면 GitLab이 이를 사용하도록 구성합니다.
- 오른쪽 위에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
- Change configuration을 선택합니다.
- Local AI Gateway URL에
http://<ai-gateway-host>:5052를 입력합니다. - Local URL for the GitLab Duo Agent Platform service에
<ai-gateway-host>:50052를 입력합니다. - GitLab Duo Agent Platform을 켭니다. 켜면 Flow execution 섹션이 펼쳐집니다.
- Image registry에 로드한 실행기 이미지의 전체 참조를 태그와 함께 입력합니다
(예:
registry.internal.example.com/duo/workflow-generic-image:<executor_version>). GitLab은 전체 이미지 참조를 그대로 사용합니다. 레지스트리 호스트 이름만 입력하면, 자체 이미지를 설정하지 않은 플로는 사용 중인 GitLab 버전이 요청하는 태그로<hostname>/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image를 가져옵니다. - Save changes를 선택합니다.
셀프 호스팅 모델 추가#
GitLab 인스턴스에 셀프 호스팅 모델 배포를 추가합니다.
- 오른쪽 위에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
- Configure models for GitLab Duo를 선택합니다.
- Add self-hosted model을 선택합니다.
- 다음 필드를 입력합니다.
- Endpoint에는 vLLM 서버의 URL을 입력합니다.
- Model identifier에는
custom_openai/mistral-small-3.2-24b를 입력합니다.
- 선택 사항. Test connection을 선택해 AI Gateway가 vLLM 엔드포인트에 연결할 수 있는지 확인합니다.
- Add self-hosted model을 선택합니다.
오프라인 플로 실행 구성#
실행기 이미지 v0.0.11 이상에는 /usr/local/bin/duo에 duo-cli가 포함되어 있습니다.
이미지에 duo가 이미 있으면 플로의 CI/CD job은 다운로드를 건너뛰며
duo-cli를 위해 gitlab.com에 연결하지 않습니다.
v0.0.11보다 이전의 실행기 이미지에는 duo-cli가 포함되어 있지 않습니다.
사용 중인 GitLab 버전이 해당 태그를 요청하거나 다른 duo-cli 버전이 필요하다면
사용자 지정 실행기 이미지를 빌드합니다.
-
연결된 머신에서
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현재
duo-cli버전은 GitLab Rails 소스의DUO_CLI_VERSION상수 또는 GitLab 패키지 레지스트리의duo-cli패키지에서 확인합니다. -
바이너리를 포함한 사용자 지정 이미지를 빌드합니다.
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/duov0.1.1을 사용 중인 GitLab 버전이 요청하는 태그로 바꿉니다. -
앞에서 설명한 것과 같은
skopeo copy절차로 이미지를 내부 레지스트리로 전송한 다음, 프로젝트의agent-config.yml에서 해당 이미지를 참조합니다.image: registry.internal.example.com/duo/duo-executor:v0.1.1
이미지가 이 GitLab 인스턴스의 프로젝트 컨테이너 레지스트리에 있다면
플로의 CI/CD job은 프로젝트 간에 이미지를 가져옵니다. job은 외부
계정으로 실행되며 내부 프로젝트는 외부 계정에 비공개로 보이므로
레지스트리가 가져오기를 거부합니다.
호스트 프로젝트가 부여해야 하는 액세스는
GitLab 컨테이너 레지스트리에서 이미지를 가져오도록 플로 구성을 참고합니다.
레지스트리가 자격 증명을 요구하면 러너에 구성합니다.
기본적으로 플로의 job은 프로젝트, 그룹 또는 인스턴스 수준에서 구성한 CI/CD 변수를 받지 않으므로,
거기에 정의한 DOCKER_AUTH_CONFIG 변수는 적용되지 않습니다.
자세한 내용은
이미지 가져오기용 자격 증명 제공을 참고합니다.
배포 확인#
-
AI Gateway가 실행 중인지 확인합니다.
curl --silent "http://<ai-gateway-host>:5052/monitoring/healthz" -
사용하려는 각 GitLab Duo 기능에 셀프 호스팅 모델을 선택합니다. GitLab Duo Agent Platform 기능도 포함합니다.
GitLab Duo Agent Platform 기능에 셀프 호스팅 모델을 할당하기 전에는 상태 점검이 통과하지 않습니다.
-
GitLab Duo 상태 점검을 실행합니다.
- 오른쪽 위에서 Admin을 선택합니다.
- 왼쪽 사이드바에서 GitLab Duo를 선택합니다.
- Run health check를 선택합니다.
상태 점검은 AI Gateway 연결과 라이선스 상태를 검증합니다. GitLab Duo Chat이나 Code Suggestions의 모델 추론은 테스트하지 않습니다.
-
모델 추론을 확인하려면 GitLab UI 또는 IDE에서 GitLab Duo Chat이나 Code Suggestions로 테스트 요청을 보냅니다.
-
Agent Platform Flows를 확인하려면 플로를 트리거한 다음, 실행기 이미지가 내부 레지스트리에서 전달되고
duo-cli가gitlab.com에서 내려받아지지 않는지 확인합니다.
일반적인 문제는 문제 해결을 참고합니다.
아티팩트 업데이트#
GitLab 인스턴스를 업그레이드할 때는 같은 절차로 갱신된 컨테이너 이미지를 전송합니다. 새 GitLab 버전에 맞는 AI Gateway 이미지 태그를 사용합니다.
업그레이드하면 새 버전이 요청하는 실행기 태그도 달라질 수 있습니다. 업그레이드 전에 그 태그를 확인하고, AI Gateway 이미지와 함께 해당 실행기 이미지를 전송합니다.
GitLab을 업그레이드할 때 모델 가중치는 업데이트하지 않아도 됩니다. 다른 모델로 바꿀 때만 업데이트가 필요합니다.
Cloud Connector 키 교체#
GitLab 인스턴스는 AI Gateway로 보내는 토큰에 Cloud Connector 키로 서명합니다. AI Gateway는 인스턴스의 공개 키를 캐시하며, 로드하지 않은 키로 서명된 토큰은 거부합니다.
사전 요구 사항:
- Cloud Connector 키가 하나여야 합니다. 확인하려면
sudo gitlab-rake cloud_connector:keys:list를 실행합니다.
Cloud Connector 키를 교체하려면:
-
GitLab 인스턴스에서 새 키를 생성합니다.
sudo gitlab-rake cloud_connector:keys:createGitLab은 새 키를 게시하고 계속 현재 키로 토큰에 서명합니다.
-
AI Gateway가 새 키를 로드하도록 모든 AI Gateway 컨테이너를 다시 시작합니다.
docker restart <container_name> -
새 키를 서명 키로 지정합니다.
sudo gitlab-rake cloud_connector:keys:rotate -
Puma 또는 Sidekiq을 실행하는 모든 노드에서 새 키로 서명하도록 다시 시작합니다.
sudo gitlab-ctl restart puma sudo gitlab-ctl restart sidekiq -
Puma와 Sidekiq을 다시 시작한 후 최소 1시간 기다립니다. 이전 키로 서명된 토큰은 서명된 후 최대 1시간 동안 유효합니다.
-
이전 키를 제거합니다.
sudo gitlab-rake cloud_connector:keys:trim -
모든 AI Gateway 컨테이너를 다시 시작합니다. 모든 컨테이너가 다시 시작될 때까지 AI Gateway는 이전 키로 서명된 토큰도 계속 수락합니다.
관련 주제#
문제 해결#
오프라인 환경에서 Agent Platform Self-Hosted를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.
오류: 새 Cloud Connector 키를 사용할 때 Forbidden by auth provider#
AI Gateway를 다시 시작하기 전에 cloud_connector:keys:rotate를 실행하면 AI Gateway가
새 키로 서명된 토큰을 Forbidden by auth provider로 거부합니다.
Puma와 Sidekiq 프로세스는 다시 시작한 후 새 키로 서명하며,
이후 해당 프로세스의 GitLab Duo 요청이 실패합니다.
예를 들면 다음과 같습니다.
- 워크플로 토큰 요청이
16:Forbidden by auth provider와 함께400 Bad request를 반환합니다. - 코드 리뷰처럼 GitLab이 직접 시작하는 플로가 시작되지 못합니다.
이 문제를 해결하려면 새 키를 생성한 후 GitLab이 새 키로 서명하기 전에 AI Gateway를 다시 시작합니다.