AI Gateway는 AI 네이티브 GitLab Duo 기능에 대한 액세스를 제공하는 두 가지 서비스의 조합입니다:

• AI Gateway 서비스

• GitLab Duo Agent Platform 서비스

인증 및 JSON 웹 토큰(JWT)#

GitLab Duo 기능에 액세스하기 위해 AI Gateway는 JWT를 사용하여 요청이 GitLab 인스턴스의 인증된 사용자로부터 오는지 확인합니다. GitLab 인스턴스가 토큰을 요청하면 서비스는 요청을 승인하는 단기 서명 토큰을 발급합니다.

자체 AI Gateway를 호스팅하는 경우 서명 키 쌍을 생성하고 이 키를 환경 변수로 서비스에 전달해야 합니다.

각 서비스는 자체 키 쌍을 사용합니다:

• AI Gateway는 GitLab Duo Code Suggestions 및 GitLab Duo Chat과 같은 기능에 AIGW_SELF_SIGNED_JWT__SIGNING_KEY와 AIGW_SELF_SIGNED_JWT__VALIDATION_KEY를 사용합니다.

• GitLab Duo Agent Platform 서비스는 DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY와 DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY를 사용합니다.

각 쌍은 다음과 같은 역할을 제공합니다:

• 서명 키는 서비스가 발급하는 토큰에 서명합니다.

• 유효성 검사 키는 키 교체 중 토큰을 검증하여, 이전 키로 서명된 토큰이 만료될 때까지 계속 유효하도록 합니다.

쌍의 두 키 모두 PEM 형식의 RSA 2048비트 개인 키여야 합니다. 이 키가 없으면 서비스가 토큰에 서명할 수 없어 요청이 토큰 생성 오류와 함께 실패합니다.

Docker를 사용하여 설치#

GitLab AI Gateway Docker 이미지는 단일 컨테이너에 필요한 모든 코드와 의존성을 포함합니다.

사전 요구 사항:

Docker와 같은 Docker 컨테이너 엔진을 설치하세요.

네트워크에서 접근 가능한 유효한 호스트명을 사용하세요. localhost는 사용하지 마세요.

linux/amd64 아키텍처에서 약 340 MB(압축 기준)의 공간과 최소 512 MB의 RAM이 필요합니다.

ai_gateway 및 duo-workflow-service 서비스를 위해 컨테이너가 최소 2개의 CPU에 접근할 수 있어야 합니다.

JWT 서명 키를 생성하세요:

GitLab Duo Agent Platform의 경우:

openssl genrsa -out duo_workflow_jwt.key 2048
openssl genrsa -out duo_workflow_validation.key 2048

AI Gateway의 경우 (Duo Chat 등의 기능에 필요):

openssl genrsa -out aigw_signing.key 2048
openssl genrsa -out aigw_validation.key 2048

생성된 모든 키 파일을 안전하게 보관하고 공개적으로 공유하지 마세요. 이 키들은 JWT 서명에 사용되며 민감한 자격 증명으로 취급해야 합니다.

특히 사용량이 많은 경우 더 나은 성능을 위해 최소 요구 사항보다 더 많은 디스크 공간, 메모리 및 리소스를 할당하는 것을 고려하세요. 더 높은 RAM과 디스크 용량은 최고 부하 시 AI Gateway의 효율을 높일 수 있습니다.

GitLab AI Gateway에는 GPU가 필요하지 않습니다.

AI Gateway 이미지#

표준 이미지#

표준 AI Gateway 이미지는 다음 위치에서 제공됩니다:

• 컨테이너 레지스트리: Stable

• DockerHub: Stable

GitLab 버전이 vX.Y.*-ee인 경우, 가장 최신의 self-hosted-vX.Y.*-ee 태그가 있는 AI Gateway 이미지를 사용하세요. 예를 들어:

• GitLab 버전이 v18.2.1-ee이고 AI Gateway 이미지에 self-hosted-v18.2.0-ee, self-hosted-v18.2.1-ee, self-hosted-v18.2.2-ee 버전이 있으면 self-hosted-v18.2.2-ee를 사용하세요.

• GitLab 버전이 v18.2.1-ee이고 AI Gateway 이미지에 self-hosted-v18.2.0-ee 버전만 있으면 self-hosted-v18.2.0-ee를 사용하세요.

자세한 내용은 셀프 호스팅 AI Gateway의 릴리스 프로세스를 참조하세요.

Nightly 빌드는 하위 호환성이 보장되지 않습니다. 항상 명시적인 버전 태그로 안정 릴리스를 사용하세요.

FIPS 검증 이미지#

FIPS 140-3 검증된 암호화가 필요한 환경에는 FIPS 검증 AI Gateway 이미지를 사용하세요. 이 이미지는 Red Hat UBI 9 기반으로 빌드되며 CMVP 검증된 Red Hat OpenSSL FIPS 프로바이더를 사용합니다.

FIPS 검증 AI Gateway 이미지는 다음 위치에서 제공됩니다:

• 컨테이너 레지스트리: Stable

• DockerHub: Stable

표준 이미지와 동일한 버전 태그 형식(self-hosted-vX.Y.Z-ee)을 사용하세요.

FIPS 검증 컨테이너를 시작하려면 Docker run 명령의 이미지 참조를 FIPS 이미지로 교체하세요:

registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway/self-hosted-fips:<ai-gateway-tag>

이미지에서 컨테이너 시작#

다음 명령어를 실행하여 컨테이너를 시작하세요:

docker run -d -p 5052:5052 -p 50052:50052 \
 -e AIGW_GITLAB_URL=<your_gitlab_instance> \
 -e AIGW_GITLAB_API_URL=<your_gitlab_instance>/api/v4/ \
 -e AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \
 -e AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)" \
 -e DUO_WORKFLOW_AUTH__ENABLED="true" \
 -e DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat duo_workflow_jwt.key)" \
 -e DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat duo_workflow_validation.key)" \
 registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:<ai-gateway-tag>

다음 플레이스홀더를 교체하세요:

<your_gitlab_instance>: GitLab 인스턴스 URL (예: https://gitlab.example.com).

• <ai-gateway-tag>: GitLab 인스턴스에 맞는 버전. GitLab 버전이 vX.Y.0이면 self-hosted-vX.Y.0-ee를 사용하세요.

컨테이너 호스트에서 http://localhost:5052에 접근하면 {"error":"No authorization header presented"}가 반환되어야 합니다.

포트 5052와 50052가 호스트에서 컨테이너로 포워딩되어 있는지 확인하세요. 포트 5052는 AI Gateway의 HTTP 통신을 처리합니다. 포트 50052는 GitLab Duo Agent Platform 서비스의 gRPC 통신을 처리합니다.

오프라인 라이선스를 사용하는 GitLab 인스턴스의 경우, AIGW 컨테이너에서 -e DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL=<your_gitlab_instance>와 -e AIGW_CUSTOMER_PORTAL_URL=<your_gitlab_instance>를 설정하세요. 이 구성은:

GitLab Duo Workflow Service가 로컬 GitLab 인스턴스에 대해서만 인증하도록 강제합니다.

• 연결할 수 없는 CustomersDot 호출로 인한 20초 지연을 제거합니다.

AI gateway URL과 GitLab Duo Agent Platform 서비스 URL을 구성하세요.

선택 사항. 로컬 GitLab Duo Agent Platform 엔드포인트가 TLS를 사용하는 경우:

오른쪽 상단에서 Admin을 선택하세요.

• GitLab Duo > Change configuration을 선택하세요.

• Use TLS for the GitLab Duo Agent Platform service 체크박스를 선택하세요.

네트워크 액세스 제한#

시스템을 강화하려면 다음 네트워크 구성을 수행하세요:

• AI Gateway 컨테이너의 아웃바운드 네트워크 액세스를 제한합니다.

• 컨테이너에서 다른 모든 아웃바운드 트래픽을 차단합니다.

AI Gateway는 다음에 대한 아웃바운드 액세스가 필요합니다. 이를 네트워크 제한의 예외로 포함하세요:

• GitLab 인스턴스(AIGW_GITLAB_URL).

• 구성된 AI 모델 제공자 엔드포인트(예: Anthropic, Gemini Enterprise Agent Platform, 또는 Azure OpenAI).

• 오프라인 라이선스를 사용하지 않는 경우 라이선스 검증을 위한 customers.gitlab.com.

방화벽 규칙을 프로덕션 환경에 적용하기 전에 비프로덕션 환경에서 테스트하세요. 지나치게 제한적인 규칙은 AI Gateway 기능을 중단시킬 수 있습니다.

Linux 호스트에서 아웃바운드 액세스를 제한하려면 DOCKER-USER 체인에서 iptables 규칙을 사용하세요. 자세한 내용은 Docker 패킷 필터링 및 방화벽을 참조하세요.

NGINX 및 SSL로 Docker 설정#

NGINX 또는 Caddy를 리버스 프록시로 배포하는 이 방법은 [이슈 455854](https://gitlab.com/gitlab-org/gitlab/-/issues/455854)가

구현될 때까지 SSL을 지원하기 위한 임시 해결 방법입니다.

AI Gateway 인스턴스에 SSL을 사용하려면 다음을 사용하세요:

• Docker

• 리버스 프록시로서 NGINX

• SSL 인증서를 위한 Let’s Encrypt

NGINX는 외부 클라이언트와의 보안 연결을 관리합니다. AI Gateway에 전달하기 전에 들어오는 HTTPS 요청을 복호화합니다.

사전 요구 사항:

• Docker 및 Docker Compose 설치

• 등록 및 구성된 도메인 이름

구성 파일 생성#

작업 디렉터리에 다음 파일들을 생성하는 것으로 시작하세요.

nginx.conf:

user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
events {
    worker_connections  1024;
}
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    sendfile        on;
    keepalive_timeout  65;
    include /etc/nginx/conf.d/*.conf;
}

default.conf:

# nginx/conf.d/default.conf
server {
    listen 80;
    server_name _;

    # Forward all requests to the AI Gateway
    location / {
        proxy_pass http://gitlab-ai-gateway:5052;
        # proxy_read_timeout is the longest allowed idle gap between response chunks,
        # not the total response time. Reasoning models can pause for minutes before responding.
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
        proxy_buffering off;
    }
}

server {
    listen 443 ssl;
    server_name _;

    # SSL configuration
    ssl_certificate /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    # Configuration for self-signed certificates
    ssl_verify_client off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # Proxy headers
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket support (if needed)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # Forward all requests to the AI Gateway
    location / {
        proxy_pass http://gitlab-ai-gateway:5052;
        # proxy_read_timeout is the longest allowed idle gap between response chunks,
        # not the total response time. Reasoning models can pause for minutes before responding.
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
        proxy_buffering off;
    }
}

grpc-nginx.conf:

# Configuration for Duo Agent Platform with TLS
events {
    worker_connections 1024;
}

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;
    error_log /var/log/nginx/error.log debug;

    upstream grpcservers {
        server gitlab-ai-gateway:50052;
    }

    server {
        listen 8443 ssl;
        http2 on;

        ssl_certificate /etc/nginx/ssl/server.crt;
        ssl_certificate_key /etc/nginx/ssl/server.key;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;

        location / {
            grpc_pass grpc://grpcservers;
            grpc_set_header Host $host;
        }
    }
}

Let’s Encrypt를 사용하여 SSL 인증서 설정#

SSL 인증서를 설정하려면:

• Docker 기반 NGINX 서버의 경우 Certbot이 Let’s Encrypt 인증서를 구현하는 자동화된 방법을 제공합니다.

• 또는 Certbot 수동 설치를 사용할 수 있습니다.

환경 파일 생성#

JWT 서명 및 유효성 검사 키를 저장하는 .env 파일을 생성하세요:

echo "AIGW_SELF_SIGNED_JWT__SIGNING_KEY=\"$(cat aigw_signing.key)\"" > .env
echo "AIGW_SELF_SIGNED_JWT__VALIDATION_KEY=\"$(cat aigw_validation.key)\"" >> .env
echo "DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY=\"$(cat duo_workflow_jwt.key)\"" >> .env
echo "DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY=\"$(cat duo_workflow_validation.key)\"" >> .env

Docker Compose 파일 생성#

이제 docker-compose.yaml 파일을 생성하세요.

services:
  nginx-proxy:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /path/to/nginx.conf:/etc/nginx/nginx.conf:ro
      - /path/to/default.conf:/etc/nginx/conf.d/default.conf:ro
      - /path/to/fullchain.pem:/etc/nginx/ssl/server.crt:ro
      - /path/to/privkey.pem:/etc/nginx/ssl/server.key:ro
    networks:
      - proxy-network
    depends_on:
      - gitlab-ai-gateway

grpc-proxy:
    image: nginx:alpine
    ports:
      - "8443:8443"
    volumes:
      - /path/to/grpc-nginx.conf:/etc/nginx/nginx.conf:ro
      - /path/to/fullchain.pem:/etc/nginx/ssl/server.crt:ro
      - /path/to/privkey.pem:/etc/nginx/ssl/server.key:ro
    networks:
      - proxy-network
    depends_on:
      - gitlab-ai-gateway
    restart: always

  gitlab-ai-gateway:
    image: registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:<ai-gateway-tag>
    ports:
      - "50052:50052" # Agent Platform gRPC exposed to the host
    expose:
      - "5052" # Only exposed internally to the proxy network
    environment:
      - AIGW_GITLAB_URL=<your_gitlab_instance>
      - AIGW_GITLAB_API_URL=https://<your_gitlab_domain>/api/v4/
    env_file:
      - .env
    networks:
      - proxy-network
    restart: always

networks:
  proxy-network:
    driver: bridge

배포 및 검증#

솔루션을 배포하고 검증하려면:

nginx 및 AIGW 컨테이너를 시작하고 실행 중인지 확인하세요:

docker compose up
docker ps

GitLab 인스턴스를 AI Gateway에 접근하도록 구성하세요.

GitLab Duo Agent Platform 서비스 URL에 접근하도록 GitLab 인스턴스를 구성하세요.

헬스 체크를 수행하고 AI Gateway와 Agent Platform 모두 접근 가능한지 확인하세요.

Helm 차트를 사용하여 설치#

사전 요구 사항:

• 다음이 필요합니다:

DNS 레코드를 추가할 수 있는 소유 도메인.

• Kubernetes 클러스터.

• kubectl의 정상 작동 설치.

• Helm 버전 v3.11.0 이상의 정상 작동 설치.

자세한 내용은 GKE 또는 EKS에서 GitLab 차트 테스트를 참조하세요.

AI Gateway Helm 리포지터리 추가#

Helm 구성에 AI Gateway Helm 리포지터리를 추가하세요:

helm repo add ai-gateway \
https://gitlab.com/api/v4/projects/gitlab-org%2fcharts%2fai-gateway-helm-chart/packages/helm/devel

AI Gateway 설치#

ai-gateway 네임스페이스를 생성하세요:

kubectl create namespace ai-gateway

AI Gateway를 노출할 도메인에 대한 인증서를 생성하세요.

이전에 생성한 네임스페이스에 TLS 시크릿을 생성하세요:

kubectl -n ai-gateway create secret tls ai-gateway-tls --cert="<path_to_cert>" --key="<path_to_cert_key>"

차트의 Package Registry에서 최신 패키지의 버전 번호를 확인하세요.

AI Gateway가 API에 접근하려면 GitLab 인스턴스의 위치를 알아야 합니다. 이를 위해 gitlab.url과 gitlab.apiUrl을 ingress.hosts 및 ingress.tls 값과 함께 다음과 같이 설정하세요:

helm repo add ai-gateway \
  https://gitlab.com/api/v4/projects/gitlab-org%2fcharts%2fai-gateway-helm-chart/packages/helm/devel
helm repo update

helm upgrade --install ai-gateway \
  ai-gateway/ai-gateway \
  --version <latest-package-in-registery> \
  --namespace=ai-gateway \
  --set="image.tag=<ai-gateway-image-version>" \
  --set="gitlab.url=https://<your_gitlab_domain>" \
  --set="gitlab.apiUrl=https://<your_gitlab_domain>/api/v4/" \
  --set "ingress.enabled=true" \
  --set "ingress.hosts[0].host=<your_gateway_domain>" \
  --set "ingress.hosts[0].paths[0].path=/" \
  --set "ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
  --set "ingress.tls[0].secretName=ai-gateway-tls" \
  --set "ingress.tls[0].hosts[0]=<your_gateway_domain>" \
  --set="ingress.className=nginx" \
  --set "extraEnvironmentVariables[0].name=AIGW_SELF_SIGNED_JWT__SIGNING_KEY" \
  --set "extraEnvironmentVariables[0].value=$(cat aigw_signing.key)" \
  --set "extraEnvironmentVariables[1].name=AIGW_SELF_SIGNED_JWT__VALIDATION_KEY" \
  --set "extraEnvironmentVariables[1].value=$(cat aigw_validation.key)" \
  --set "extraEnvironmentVariables[2].name=DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY" \
  --set "extraEnvironmentVariables[2].value=$(cat duo_workflow_jwt.key)" \
  --set "extraEnvironmentVariables[3].name=DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY" \
  --set "extraEnvironmentVariables[3].value=$(cat duo_workflow_validation.key)" \
  --set "extraEnvironmentVariables[4].name=DUO_WORKFLOW_AUTH__ENABLED" \
  --set "extraEnvironmentVariables[4].value={{ true | quote }}" \
  --timeout=300s --wait --wait-for-jobs

image.tag로 사용 가능한 AI Gateway 버전 목록은 컨테이너 레지스트리에서 확인할 수 있습니다.

모든 리소스를 할당하고 AI Gateway를 시작하는 데 몇 초가 걸릴 수 있습니다.

기존 nginx Ingress 컨트롤러가 다른 네임스페이스의 서비스를 처리하지 않는 경우 AI Gateway에 대한 Ingress Controller를 별도로 설정해야 할 수 있습니다. 멀티 네임스페이스 배포의 경우 Ingress가 올바르게 설정되어 있는지 확인하세요.

ai-gateway Helm 차트 버전은 helm search repo ai-gateway --versions를 사용하여 적절한 차트 버전을 찾으세요.

파드가 실행될 때까지 기다리세요:

kubectl wait pod \
  --all \
  --for=condition=Ready \
  --namespace=ai-gateway \
  --timeout=300s

파드가 실행되면 IP ingress와 DNS 레코드를 설정할 수 있습니다.

자체 서명 SSL 인증서로 GitLab 인스턴스 또는 모델 엔드포인트에 연결#

GitLab 인스턴스 또는 모델 엔드포인트가 자체 서명 인증서로 구성된 경우, 루트 인증 기관(CA) 인증서를 AI Gateway의 인증서 번들에 추가해야 합니다.

이를 위해 다음 중 하나를 수행할 수 있습니다:

• 루트 CA 인증서를 AI Gateway에 전달하여 인증이 성공하도록 합니다.

• 루트 CA 인증서를 AI Gateway 컨테이너의 CA 번들에 추가합니다.

루트 CA 인증서를 AI Gateway에 전달#

루트 CA 인증서를 AI Gateway에 전달하여 인증이 성공하는지 확인하려면 REQUESTS_CA_BUNDLE 환경 변수를 설정하세요. GitLab이 기본 신뢰할 수 있는 CA 목록으로 Certifi를 사용하므로 사용자 정의 CA 번들을 다음과 같이 구성합니다:

Certifi cacert.pem 파일을 다운로드하세요:

curl "https://raw.githubusercontent.com/certifi/python-certifi/2024.07.04/certifi/cacert.pem" --output cacert.pem

자체 서명 루트 CA 인증서를 파일에 추가하세요. 예를 들어 mkcert를 사용하여 인증서를 생성한 경우:

cat "$(mkcert -CAROOT)/rootCA.pem" >> path/to/your/cacert.pem

REQUESTS_CA_BUNDLE을 cacert.pem 파일 경로로 설정하세요. 예를 들어 GDK에서 $GDK_ROOT/env.runit에 다음을 추가하세요:

export REQUESTS_CA_BUNDLE=/path/to/your/cacert.pem

AI Gateway 컨테이너의 CA 번들에 루트 CA 인증서 추가#

사용자 정의 CA가 서명한 GitLab Self-Managed 인스턴스의 인증서를 AI Gateway가 신뢰하도록 허용하려면 루트 CA 인증서를 AI Gateway 컨테이너의 CA 번들에 추가하세요.

이 방법은 이후 차트 버전에서 루트 CA 번들에 대한 변경 사항을 허용하지 않습니다.

AI Gateway의 Helm 차트 배포에 대해 이를 수행하려면:

사용자 정의 루트 CA 인증서를 로컬 파일에 추가하세요:

cat customCA-root.crt >> ca-certificates.crt

AI Gateway 컨테이너에서 로컬 파일로 /etc/ssl/certs/ca-certificates.crt 번들 파일을 복사하세요:

kubectl cp -n gitlab ai-gateway-55d697ff9d-j9pc6:/etc/ssl/certs/ca-certificates.crt ca-certificates.crt.

로컬 파일에서 새 시크릿을 생성하세요:

kubectl create secret generic ca-certificates -n gitlab --from-file=cacertificates.crt=ca-certificates.crt

values.yml에서 시크릿을 사용하여 volume과 volumeMount를 정의하세요. 이렇게 하면 컨테이너에 /tmp/ca-certificates.crt 파일이 생성됩니다:

volumes:
  - name: cacerts
    secret:
      secretName: ca-certificates
      optional: false

volumeMounts:
  - name: cacerts
    mountPath: "/tmp"
    readOnly: true

REQUESTS_CA_BUNDLE 및 SSL_CERT_FILE 환경 변수를 마운트된 파일을 가리키도록 설정하세요:

extraEnvironmentVariables:
  - name: REQUESTS_CA_BUNDLE
    value: /tmp/ca-certificates.crt
  - name: SSL_CERT_FILE
    value: /tmp/ca-certificates.crt

차트를 재배포하세요.

Helm 차트에서 이를 기본으로 지원하기 위한 이슈 3이 있습니다.

Docker 배포의 경우#

Docker 배포의 경우 동일한 방법을 사용하세요. 유일한 차이점은 컨테이너에 로컬 파일을 마운트하려면 --volume /root/ca-certificates.crt:/tmp/ca-certificates.crt를 사용한다는 것입니다.

상호 TLS(mTLS)가 필요한 모델 엔드포인트에 연결#

History

• GitLab 19.3에서 소개됨.

모델 엔드포인트 또는 그 앞의 프록시가 호출자에게 클라이언트 인증서로 인증할 것을 요구하는 경우, AI Gateway가 인증서를 제시하도록 구성하세요. 이 방법은 curl --cert 옵션과 동일합니다.

mTLS가 필요한 모델 엔드포인트에 연결하려면 AI Gateway에서 다음 환경 변수를 설정하세요:

GitLab Helm 차트 배포의 경우 클라이언트 인증서를 마운트하고 변수를 설정하세요:

volumes:
  - name: mtls-client-cert
    secret:
      secretName: aigw-mtls-client-cert
      optional: false

volumeMounts:
  - name: mtls-client-cert
    mountPath: /certs
    readOnly: true

extraEnvironmentVariables:
  - name: AIGW_MTLS__ENABLED
    value: "true"
  - name: AIGW_MTLS__CERT_FILE
    value: /certs/client.pem

Docker 배포의 경우 동일한 환경 변수를 사용하고 --volume /path/to/client.pem:/certs/client.pem으로 인증서를 마운트하세요.

AI Gateway는 업스트림 서버가 TLS 핸드셰이크 중에 인증서를 요청할 때만 클라이언트 인증서를 제시합니다. 이 구성은 클라이언트 인증서가 필요하지 않은 모델 엔드포인트에는 영향을 주지 않습니다.

AI Gateway Docker 이미지 업그레이드#

AI Gateway를 업그레이드하려면 최신 Docker 이미지 태그를 다운로드하세요.

실행 중인 컨테이너를 중지하세요:

sudo docker stop gitlab-aigw

기존 컨테이너를 제거하세요:

sudo docker rm gitlab-aigw

새 이미지를 가져와서 실행하세요.

모든 환경 변수가 올바르게 설정되어 있는지 확인하세요.

보안 업데이트 및 이미지 검증#

최신 보안 패치를 실행하고 있는지 확인하려면 배포 방법에 따라 다음 지침을 따르세요.

Kubernetes 또는 Helm 배포의 경우#

0.7.0 이전의 차트 버전과 Kubernetes는 기본적으로 imagePullPolicy: IfNotPresent를 사용하므로 태그가 변경되지 않으면 업데이트된 이미지를 가져오지 않습니다. 이는 동일한 버전 태그로 릴리스된 보안 패치를 놓칠 수 있음을 의미합니다.

이미지 다이제스트를 사용하는 다음 방법을 사용하세요:

# Find the image digest from the container registry
# Use this digest in your Helm install/upgrade command

helm upgrade --install ai-gateway \
  ai-gateway/ai-gateway \
  --set="image.tag=self-hosted-v18.2.1-ee@sha256:abc123..." \
  # ... other flags

또는 다음 방법 중 하나를 사용하여 imagePullPolicy를 설정할 수 있습니다:

imagePullPolicy를 항상(always)으로 설정하세요:

helm upgrade --install ai-gateway \
  ai-gateway/ai-gateway \
  --set="image.pullPolicy=Always" \
  # ... other flags

values.yaml에 pullPolicy를 추가하세요:

image:
  pullPolicy: Always

업데이트를 강제로 가져오려면:

kubectl rollout restart deployment/ai-gateway -n ai-gateway

Docker 배포의 경우#

업그레이드할 때 최신 이미지를 가져오고 있는지 확인하세요:

# Check current image digest
docker images --digests | grep ai-assist

# Pull latest version explicitly
docker pull registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:<ai-gateway-tag>

# Verify digest changed
docker images --digests | grep ai-assist

변경 불가 배포를 위해 이미지 다이제스트를 사용하려면:

docker run -d -p 5052:5052 -p 50052:50052 \
 -e AIGW_GITLAB_URL=<your_gitlab_instance> \
 -e AIGW_GITLAB_API_URL=https://<your_gitlab_domain>/api/v4/ \
 -e DUO_WORKFLOW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat duo_workflow_jwt.key)" \
 -e DUO_WORKFLOW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat duo_workflow_validation.key)" \
 -e AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \
 -e AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)" \
 registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway:self-hosted-v18.2.1-ee@sha256:abc123...

대안적인 설치 방법#

AI Gateway를 설치하는 대안적인 방법에 대한 정보는 이슈 463773을 참조하세요.

헬스 체크 및 디버깅#

GitLab Duo Self-Hosted 설치의 문제를 디버그하려면 다음 명령어를 실행하세요:

sudo gitlab-rake gitlab:duo:verify_self_hosted_setup

다음 사항을 확인하세요:

• AI Gateway URL이 (Ai::Setting.instance.ai_gateway_url을 통해) 올바르게 구성되어 있는지 확인하세요.

• /admin/code_suggestions를 통해 루트 사용자에 대한 GitLab Duo 접근이 명시적으로 활성화되어 있는지 확인하세요.

접근 문제가 지속되면 인증이 올바르게 구성되어 있고 헬스 체크가 통과하는지 확인하세요.

문제가 지속될 경우 오류 메시지에서 AIGW_AUTH__BYPASS_EXTERNAL=true로 인증을 우회하도록 제안할 수 있지만 문제 해결 목적으로만 사용하세요.

Admin > GitLab Duo로 이동하여 헬스 체크를 실행할 수도 있습니다.

오프라인 환경에서는 다음 테스트가 수행됩니다:

AI Gateway 모니터링#

Prometheus를 사용하여 AI Gateway 사용량 및 성능에 대한 메트릭을 수집하세요.

AI Gateway에 대한 Prometheus 메트릭 설정#

Prometheus 메트릭을 설정하려면:

필수 환경 변수를 설정하고 포트 8082를 여세요:

-e AIGW_FASTAPI__METRICS_HOST=0.0.0.0
-e AIGW_FASTAPI__METRICS_PORT=8082

GitLab Duo Workflow 서비스에 대한 Prometheus 설정#

GitLab Duo Workflow 서비스에서 Prometheus 메트릭을 설정하려면:

필수 환경 변수를 설정하고 포트 8083을 여세요:

-e PROMETHEUS_METRICS__ADDR=0.0.0.0
-e PROMETHEUS_METRICS__PORT=8083

gitlab-ai-gateway 컨테이너에서 호스트로 메트릭 포트를 노출하세요:

Docker CLI의 경우:

-p 8082:8082 \
-p 8083:8083 \

Docker Compose의 경우 gitlab-ai-gateway 서비스에 다음을 추가하세요:

ports:
  - "8082:8082"
  - "8083:8083"

이렇게 하면 포트 8082에 AI Gateway 메트릭 엔드포인트가 노출되고 포트 8083에 GitLab Duo Workflow Service 메트릭 엔드포인트가 노출됩니다.

AI Gateway 컨테이너를 재시작하세요

메트릭 스크래핑을 위한 Prometheus 구성#

AI Gateway와 GitLab Duo Workflow 서비스에서 메트릭을 수집하려면 Prometheus 인스턴스에 다음 prometheus.yml 구성을 추가하세요. 이 구성에서 Prometheus는 15초마다 두 서비스에서 메트릭을 스크래핑합니다.

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'ai-gateway'
    static_configs:
      - targets: ['<your_AIGW_domain>:8082']
    scheme: 'http'
    metrics_path: '/metrics'

  - job_name: 'duo-agent-platform-service'
    static_configs:
      - targets: ['<your_duo_agent_platform_service_domain>:8083']
    scheme: 'http'
    metrics_path: '/metrics'

메트릭 수집 확인#

AI Gateway와 GitLab Duo Workflow 서비스의 대상이 수집되고 있는지 확인하려면:

Prometheus UI에서 Status > Targets로 이동하세요.

Alerts 또는 Graph 탭으로 이동하여 메트릭을 쿼리하세요. AI Gateway와 GitLab Duo Workflow 서비스는 다음 엔드포인트에서 메트릭을 노출합니다:

AI Gateway: http://<your_AIGW_domain>:8082/metrics

• GitLab Duo Workflow service: http://<your_duo_agent_platform_service_domain>:8083/metrics

AI Gateway에 자동 스케일링이 필요한가요?#

자동 스케일링은 필수가 아니지만 가변 워크로드, 높은 동시성 요구 사항 또는 예측할 수 없는 사용 패턴이 있는 환경에 권장됩니다. GitLab 프로덕션 환경에서:

• 기준 설정: 2개의 CPU 코어와 8 GB RAM을 가진 단일 AI Gateway 인스턴스는 약 40개의 동시 요청을 처리할 수 있습니다.

• 스케일링 지침: AWS t3.2xlarge 인스턴스(8 vCPU, 32 GB RAM)와 같은 더 큰 설정의 경우, 게이트웨이는 기준 설정의 4배에 해당하는 최대 160개의 동시 요청을 처리할 수 있습니다.

• 요청 처리량: GitLab.com의 관찰된 사용량에 따르면 1,000명의 활성 사용자당 7 RPS(초당 요청 수)가 계획을 위한 합리적인 메트릭입니다.

• 자동 스케일링 옵션: Kubernetes HPA(Horizontal Pod Autoscaler) 또는 유사한 메커니즘을 사용하여 CPU, 메모리 사용률 또는 요청 지연 시간 임계값과 같은 메트릭을 기반으로 인스턴스 수를 동적으로 조정하세요.

배포 크기별 구성 예시#

• 소규모 배포:

2 vCPU 및 8 GB RAM을 가진 단일 인스턴스.

• 최대 40개의 동시 요청 처리.

• 최대 50명의 사용자와 예측 가능한 워크로드를 가진 팀 또는 조직.

• 고정 인스턴스로 충분할 수 있으며, 비용 효율성을 위해 자동 스케일링을 비활성화할 수 있습니다.

• 중규모 배포:

8 vCPU 및 32 GB RAM을 가진 단일 AWS t3.2xlarge 인스턴스.

• 최대 160개의 동시 요청 처리.

• 50~200명의 사용자와 중간 수준의 동시성 요구 사항을 가진 조직.

• 50% CPU 사용률 또는 500ms 이상의 요청 지연 시간 임계값으로 Kubernetes HPA를 구현하세요.

• 대규모 배포:

여러 AWS t3.2xlarge 인스턴스 또는 동급의 클러스터.

• 각 인스턴스는 160개의 동시 요청을 처리하며 여러 인스턴스로 수천 명의 사용자까지 확장됩니다.

• 200명 이상의 사용자와 가변적이고 높은 동시성 워크로드를 가진 기업.

• 실시간 수요를 기반으로 파드를 스케일링하기 위해 HPA를 사용하고, 클러스터 전체 리소스 조정을 위해 노드 자동 스케일링을 결합하세요.

AI Gateway 컨테이너 사양 및 리소스 할당#

AI Gateway는 다음 리소스 할당 하에서 효과적으로 작동합니다:

• 컨테이너당 2개의 CPU 코어와 8 GB RAM.

• 컨테이너는 GitLab 프로덕션 환경에서 일반적으로 약 7.39%의 CPU와 비례하는 메모리를 사용하며, 성장 또는 버스트 활동 처리를 위한 여유를 남깁니다.

리소스 경합 완화 전략#

Kubernetes 리소스 요청 및 제한을 사용하여 AI Gateway 컨테이너가 보장된 CPU 및 메모리 할당을 받도록 하세요. 예를 들어:

resources:
  requests:
    memory: "16Gi"
    cpu: "4"
  limits:
    memory: "32Gi"
    cpu: "8"

Prometheus 및 Grafana와 같은 도구를 구현하여 리소스 사용률(CPU, 메모리, 지연 시간)을 추적하고 병목 현상을 조기에 감지하세요.

다른 서비스와의 리소스 경쟁을 방지하기 위해 노드 또는 인스턴스를 AI Gateway 전용으로 할당하세요.

스케일링 전략#

• Kubernetes HPA를 사용하여 다음과 같은 실시간 메트릭을 기반으로 파드를 스케일링하세요:

평균 CPU 사용률이 50%를 초과하는 경우.

• 요청 지연 시간이 지속적으로 500ms 이상인 경우.

• 파드가 증가함에 따라 인프라 리소스를 동적으로 스케일링하기 위해 노드 자동 스케일링을 활성화하세요.

스케일링 권장 사항#

여러 GitLab 인스턴스 지원#

단일 AI Gateway를 배포하여 여러 GitLab 인스턴스를 지원하거나, 인스턴스 또는 지리적 지역별로 별도의 AI Gateway를 배포할 수 있습니다. 어떤 방법이 적합한지 결정하는 데 도움이 되도록 다음을 고려하세요:

• 1,000명의 유료 사용자당 초당 약 7개 요청의 예상 트래픽.

• 모든 인스턴스에서 총 동시 요청을 기반으로 한 리소스 요구 사항.

• 각 GitLab 인스턴스에 대한 모범 사례 인증 구성.

AI Gateway와 인스턴스 동일 위치 배치#

AI Gateway는 다음을 통해 위치에 관계없이 사용자에게 최적의 성능을 보장하기 위해 전 세계 여러 지역에서 제공됩니다:

• GitLab Duo 기능에 대한 응답 시간 개선.

• 지리적으로 분산된 사용자의 지연 시간 감소.

• 데이터 주권 요구 사항 준수.

특히 Code Suggestions와 같은 지연 시간에 민감한 기능을 위해 원활한 개발자 경험을 제공하는 데 도움이 되도록 GitLab 인스턴스와 동일한 지리적 지역에 AI Gateway를 배치해야 합니다.

문제 해결#

AI Gateway 작업 시 다음과 같은 문제가 발생할 수 있습니다.

OpenShift 권한 문제#

OpenShift에 AI Gateway를 배포할 때 OpenShift 보안 모델로 인해 권한 오류가 발생할 수 있습니다.

/tmp에서 읽기 전용 파일 시스템#

AI Gateway는 /tmp에 쓸 수 있어야 합니다. 그러나 보안이 제한된 OpenShift 환경에 따라 /tmp가 읽기 전용일 수 있습니다.

이 문제를 해결하려면 새 EmptyDir 볼륨을 생성하고 /tmp에 마운트하세요. 다음 방법 중 하나로 이를 수행할 수 있습니다:

명령줄에서:

oc set volume <object_type>/<name> --add --name=tmpVol --type=emptyDir --mountPoint=/tmp

values.yaml에 추가하세요:

volumes:
- name: tmp-volume
  emptyDir: {}

volumeMounts:
- name: tmp-volume
  mountPath: "/tmp"

HuggingFace 모델#

기본적으로 AI Gateway는 HuggingFace 모델 캐싱에 /home/aigateway/.hf를 사용하는데, OpenShift의 보안이 제한된 환경에서는 쓸 수 없을 수 있습니다. 이로 인해 다음과 같은 권한 오류가 발생할 수 있습니다:

[Errno 13] Permission denied: '/home/aigateway/.hf/...'

이를 해결하려면 HF_HOME 환경 변수를 쓰기 가능한 위치로 설정하세요. /var/tmp/huggingface 또는 컨테이너가 쓸 수 있는 다른 디렉터리를 사용할 수 있습니다.

다음 방법 중 하나로 이를 구성할 수 있습니다:

values.yaml에 추가하세요:

extraEnvironmentVariables:
  - name: HF_HOME
    value: /var/tmp/huggingface  # Use any writable directory

또는 Helm 업그레이드 명령어에 포함하세요:

--set "extraEnvironmentVariables[0].name=HF_HOME" \
--set "extraEnvironmentVariables[0].value=/var/tmp/huggingface"  # Use any writable directory

이 구성은 AI Gateway가 OpenShift 보안 제약을 준수하면서 HuggingFace 모델을 적절히 캐시할 수 있도록 합니다. 선택하는 정확한 디렉터리는 특정 OpenShift 구성 및 보안 정책에 따라 다를 수 있습니다.

볼륨 마운트로 가려진 토크나이저 캐시#

다음과 같은 경우 AI Gateway 이미지에 미리 캐시된 토크나이저 파일이 볼륨 마운트로 가려질 수 있습니다:

• 코드 완성 요청이 500 오류를 반환하는 경우.

• AI Gateway 로그가 huggingface.co에서 Salesforce/codegen2-16B를 다운로드하려는 transformers/utils/hub.py의 OSError를 표시하는 경우.

self-hosted AI Gateway 이미지(self-hosted-vX.Y.Z-ee)는 HF_HUB_OFFLINE=true를 설정하고 빌드 시 토크나이저를 미리 캐시하므로, 런타임에 huggingface.co에 대한 네트워크 액세스가 발생해서는 안 됩니다. 네트워크 액세스가 발생하면, Helm 값의 빈 디렉터리가 /home/aigateway/.hf에 마운트되어 캐시된 파일을 덮어쓸 수 있습니다.

huggingface.co에 대한 이그레스 액세스를 허용하여 이 문제를 해결하려고 하지 마세요. 대신 문제를 진단하려면 AI Gateway Pod에서 다음을 실행하세요:

ls -la /home/aigateway/.hf/hub/ 2>/dev/null || echo "NO_CACHE_DIR"
env | grep -E '^(HF_|TRANSFORMERS_)'

캐시 디렉터리가 없거나 비어 있는 경우 다음을 수행하세요:

• values.yaml에서 /home/aigateway/.hf 또는 HF_HOME으로 설정된 경로를 타깃으로 하는 volumeMounts가 있는지 확인하세요.

• 이미지의 내장 캐시와 겹치지 않는 디렉터리로 마운트를 제거하거나 재매핑하세요.

자체 서명 인증서 오류#

AI Gateway가 사용자 정의 인증 기관(CA)이 서명한 인증서 또는 자체 서명 인증서를 사용하여 GitLab 인스턴스 또는 모델 엔드포인트에 연결하려고 할 때 AI Gateway에서 [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain 오류가 기록됩니다.

이를 해결하려면 자체 서명 SSL 인증서로 GitLab 인스턴스 또는 모델 엔드포인트에 연결을 참조하세요.

토큰 생성 실패#

Duo Chat과 같은 기능을 사용할 때 Token creation failed 오류가 발생하면 AI Gateway에 AIGW_SELF_SIGNED_JWT__SIGNING_KEY 및 AIGW_SELF_SIGNED_JWT__VALIDATION_KEY 환경 변수가 설정되어 있지 않을 수 있습니다.

이 키들은 AI Gateway가 단기 사용자 JWT를 발급하는 데 필요합니다. 이 키가 없으면 AI Gateway가 토큰에 서명할 수 없어 JWK 역직렬화 실패가 발생합니다.

이 문제를 해결하려면:

필수 키를 생성하세요:

openssl genrsa -out aigw_signing.key 2048
openssl genrsa -out aigw_validation.key 2048

키를 환경 변수로 전달하여 AI Gateway 컨테이너에 추가하세요:

-e AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \
-e AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)"

AI Gateway 컨테이너를 재시작하세요.

PEM 파일 로드 시 SSL 인증서 오류#

Docker 컨테이너에 PEM 파일을 로드하는 동안 JWKError가 발생하면 SSL 인증서 오류를 해결해야 할 수 있습니다.

이 문제를 해결하려면 다음 환경 변수를 사용하여 Docker 컨테이너의 적절한 인증서 번들 경로를 설정하세요:

• SSL_CERT_FILE=/path/to/ca-bundle.pem

• REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

/path/to/ca-bundle.pem을 인증서 번들 경로로 교체하세요.