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비트 개인 키여야 합니다. 이 키가 없으면 서비스는 토큰에 서명할 수 없고 요청은 토큰 생성 오류로 실패합니다.

AI Gateway는 GitLab 인스턴스가 Cloud Connector 키로 서명한 토큰도 검증하며, 인스턴스의 공개 키를 캐시합니다. 인증 실패 없이 Cloud Connector 키를 교체하려면 Cloud Connector 키 교체를 참고합니다.

Docker로 설치#

AI Gateway Docker 이미지는 필요한 모든 코드와 의존성을 단일 컨테이너에 담고 있습니다.

사전 요구 사항:

• Docker 같은 Docker 컨테이너 엔진을 설치합니다.

• 네트워크에서 액세스할 수 있는 유효한 호스트명을 사용합니다. localhost는 사용하지 않습니다.

• linux/amd64 아키텍처 기준으로 약 340MB(압축) 공간과 최소 512MB의 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
    

  [!warning] 생성된 키 파일은 모두 안전하게 보관하고 공개적으로 공유하지 않습니다. 이 키는 JWT 서명에 사용되므로 민감한 자격 증명으로 취급해야 합니다.

특히 사용량이 많은 환경에서 성능을 확보하려면 최소 요구 사항보다 많은 디스크 공간, 메모리, 리소스를 할당하는 것을 고려합니다. RAM과 디스크 용량이 크면 피크 부하 구간에서 AI Gateway의 효율이 올라갑니다.

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 릴리스 프로세스를 참고합니다.

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>

이미지 서명 검증#

히스토리

• GitLab 19.3에서 도입되었습니다.

컨테이너 레지스트리의 self-hosted-fips 태그 이미지는 Cosign으로 서명되며, 서명 방식은 키리스 서명입니다. 서명 ID는 해당 이미지를 만든 CI/CD 설정이므로, GitLab은 서명 키를 공개하지 않습니다.

이미지를 검증하려면 다음 명령을 실행합니다.

cosign verify \
  --certificate-oidc-issuer https://gitlab.com \
  --certificate-identity "https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist//.gitlab-ci.yml@refs/tags/<ai-gateway-tag>" \
  registry.gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/model-gateway/self-hosted-fips:<ai-gateway-tag>

.gitlab-ci.yml 앞의 이중 슬래시는 반드시 필요합니다.

서명은 이미지 옆에 sha256-<digest>.sig 태그로 저장됩니다. 릴리스 태그만 복사하는 미러는 서명을 복사하지 않습니다. 이미지와 서명을 함께 복사하려면 cosign copy를 사용합니다.

이미지로 컨테이너 시작#

1. 다음 명령을 실행하여 컨테이너를 시작합니다.

   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"}가 반환되어야 합니다.

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

3. 오프라인 라이선스를 사용하는 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초 지연을 없앱니다.

   인스턴스에서 GitLab Duo 사용량을 기록하려면 GitLab 인스턴스로 과금 이벤트 전송도 설정합니다.

4. AI Gateway URL과 GitLab Duo Agent Platform 서비스 URL을 구성합니다.

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

   1. 오른쪽 상단에서 Admin을 선택합니다.
   2. GitLab Duo > Change configuration을 선택합니다.
   3. 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. 단, 오프라인 라이선스를 사용하는 경우는 제외합니다.

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

NGINX와 SSL을 사용하는 Docker 설정#

AI Gateway 인스턴스에 SSL을 사용하려면 다음을 사용합니다.

• Docker
• 리버스 프록시로 사용하는 NGINX
• SSL 인증서를 위한 Let's Encrypt

NGINX는 외부 클라이언트와의 보안 연결을 관리합니다. 수신되는 HTTPS 요청을 복호화한 뒤 AI Gateway로 전달합니다.

사전 요구 사항:

• Docker와 Docker Compose 설치
• 등록하고 구성한 도메인 이름

구성 파일 만들기#

먼저 작업 디렉터리에 다음 파일을 만듭니다.

1. 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;
   }
   

2. 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;
       }
   }
   

3. 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

배포와 검증#

솔루션을 배포하고 검증하려면 다음을 수행합니다.

1. nginx와 AIGW 컨테이너를 시작하고 실행 중인지 확인합니다.

   docker compose up
   docker ps
   

2. AI Gateway에 액세스하도록 GitLab 인스턴스를 구성합니다.

3. GitLab Duo Agent Platform 서비스 URL에 액세스하도록 GitLab 인스턴스를 구성합니다.

4. 헬스 체크를 수행하여 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 설치#

1. ai-gateway 네임스페이스를 생성합니다.

   kubectl create namespace ai-gateway
   

2. AI Gateway와 GitLab Duo Agent Platform 서비스를 노출할 도메인의 인증서를 생성합니다.

3. 앞에서 생성한 네임스페이스에 TLS 시크릿을 생성합니다.

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

4. 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
   
   kubectl -n ai-gateway create secret generic ai-gateway-jwt \
     --from-file=aigw_signing.key \
     --from-file=aigw_validation.key \
     --from-file=duo_workflow_jwt.key \
     --from-file=duo_workflow_validation.key
   

5. 차트의 패키지 레지스트리에서 최신 패키지의 버전 번호를 확인합니다.

6. AI Gateway가 API에 접근하려면 GitLab 인스턴스의 위치를 알아야 합니다. gitlab.url과 gitlab.apiUrl을 Ingress, gRPC Ingress, JWT 키 값과 함께 다음과 같이 설정합니다.

   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 "ingress.gitlabIngressEnabled=false" \
     --set "grpcIngress.hosts[0].host=<your_gateway_grpc_domain>" \
     --set "grpcIngress.hosts[0].paths[0].path=/" \
     --set "grpcIngress.hosts[0].paths[0].pathType=Prefix" \
     --set "grpcIngress.tls[0].secretName=ai-gateway-tls" \
     --set "grpcIngress.tls[0].hosts[0]=<your_gateway_grpc_domain>" \
     --set "grpc-tls-proxy.enabled=true" \
     --set "grpc-tls-proxy.tlsSecretName=ai-gateway-tls" \
     --set "grpc-tls-proxy.upstream.host=ai-gateway" \
     --set "aigwSigningKey.secret=ai-gateway-jwt" \
     --set "aigwSigningKey.key=aigw_signing.key" \
     --set "aigwValidationKey.secret=ai-gateway-jwt" \
     --set "aigwValidationKey.key=aigw_validation.key" \
     --set "duoWorkflowSigningKey.secret=ai-gateway-jwt" \
     --set "duoWorkflowSigningKey.key=duo_workflow_jwt.key" \
     --set "duoWorkflowValidationKey.secret=ai-gateway-jwt" \
     --set "duoWorkflowValidationKey.key=duo_workflow_validation.key" \
     --timeout=300s --wait --wait-for-jobs
   

   차트는 ingress.gitlabIngressEnabled가 false일 때만 Ingress를 렌더링합니다. gRPC Ingress는 차트의 TLS 프록시를 통해 GitLab Duo Agent Platform 서비스를 제공합니다. grpc-tls-proxy.upstream.host는 AI Gateway 서비스의 이름이어야 하며, 이 명령의 릴리스 이름에서는 ai-gateway입니다.

   오프라인 라이선스를 사용하고 인터넷에 접근할 수 없는 오프라인 환경에서는 --timeout=300s 앞에 다음 값도 명령에 추가합니다.

     --set "extraEnvironmentVariables[0].name=AIGW_CUSTOMER_PORTAL_URL" \
     --set "extraEnvironmentVariables[0].value=https://<your_gitlab_domain>" \
     --set "extraEnvironmentVariables[1].name=LITELLM_LOCAL_MODEL_COST_MAP" \
     --set-string "extraEnvironmentVariables[1].value=True" \
     --set "grpc-tls-proxy.image.repository=<your_internal_registry>/nginx" \
   

   차트는 이미 DUO_WORKFLOW_AUTH__OIDC_CUSTOMER_PORTAL_URL을 gitlab.url로 설정합니다. 인터넷에 접근할 수 없으면 LITELLM_LOCAL_MODEL_COST_MAP이 True여야 합니다. 그렇지 않으면 LiteLLM이 시작할 때 raw.githubusercontent.com에서 다운로드를 다시 시도하고, AI Gateway가 연결을 받기 전에 활성 상태 프로브가 Pod를 다시 시작합니다.

   명령을 실행하기 전에 TLS 프록시의 nginx:alpine 이미지를 <your_internal_registry>/nginx로 미러링합니다.

   인스턴스에서 GitLab Duo 사용량을 기록하려면 GitLab 인스턴스로 과금 이벤트 전송도 설정합니다.

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

모든 리소스가 할당되고 AI Gateway가 시작되기까지 이 단계에는 몇 초가 걸릴 수 있습니다.

기존 nginx Ingress 컨트롤러가 다른 네임스페이스의 서비스를 제공하지 않는다면 AI Gateway 용 Ingress 컨트롤러를 직접 구성해야 할 수 있습니다. 여러 네임스페이스에 걸친 배포에 맞게 Ingress가 올바르게 구성되었는지 확인합니다.

ai-gateway Helm 차트의 버전은 helm search repo ai-gateway --versions로 조회해 적절한 차트 버전을 찾습니다.

Pod가 모두 실행될 때까지 기다립니다.

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

Pod가 모두 실행되면 IP 인그레스와 DNS 레코드를 설정할 수 있습니다.

오프라인 GitLab 인스턴스로 과금 이벤트 전송#

히스토리

• GitLab 19.5에서 local_billing_persistence라는 기능 플래그와 함께 도입되었습니다. 기본적으로 사용 설정되어 있습니다.

오프라인 환경에서는 AI Gateway가 인터넷의 GitLab 과금 수집기에 접근할 수 없습니다. 대신 AI Gateway가 GitLab Duo 과금 이벤트를 GitLab 인스턴스로 보내도록 구성하면, 인스턴스가 사용량을 로컬에 기록합니다.

AI Gateway는 서비스 계정에 속한 개인 액세스 토큰으로 GitLab 인스턴스에 인증합니다. 일반 사용자에게 속한 토큰은 거부됩니다.

사전 요구 사항:

• 관리자 액세스 권한.
• 오프라인 라이선스를 사용하는 GitLab 인스턴스.

GitLab 인스턴스로 과금 이벤트를 전송하려면:

1. 인스턴스 서비스 계정을 생성합니다.

2. ai_features 스코프로 서비스 계정의 개인 액세스 토큰을 생성합니다.

3. AI Gateway에서 다음 환경 변수를 설정합니다.

   • AIGW_BILLING_EVENT__ENABLED: true.
   • AIGW_BILLING_EVENT__ENDPOINT: https://<your_gitlab_domain>/api/v4/ai/billable_usage/events.
   • AIGW_BILLING_EVENT__API_KEY: 서비스 계정의 개인 액세스 토큰.

   Docker 배포에서는 -e로 변수를 전달합니다.

   -e AIGW_BILLING_EVENT__ENABLED=true \
   -e AIGW_BILLING_EVENT__ENDPOINT=https://<your_gitlab_domain>/api/v4/ai/billable_usage/events \
   -e AIGW_BILLING_EVENT__API_KEY=<service_account_token> \
   

   GitLab Helm 차트 배포에서는 extraEnvironmentVariables에 변수를 추가합니다. 토큰은 values.yaml 파일에 일반 텍스트로 넣지 말고 Kubernetes 시크릿에 저장합니다.

4. AI Gateway를 다시 시작합니다.

자체 서명 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 번들은 다음과 같이 구성합니다.

1. Certifi cacert.pem 파일을 내려받습니다.

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

2. 자체 서명 루트 CA 인증서를 이 파일 뒤에 덧붙입니다. 예를 들어 mkcert로 인증서를 생성한 경우는 다음과 같습니다.

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

3. REQUESTS_CA_BUNDLE을 cacert.pem 파일의 경로로 설정합니다. 예를 들어 GDK에서는 $GDK_ROOT/env.runit에 다음을 추가합니다.

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

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

사용자 지정 CA로 서명된 GitLab Self-Managed 인스턴스의 인증서를 AI Gateway가 신뢰하도록 하려면, 루트 CA 인증서를 AI Gateway 컨테이너의 CA 번들에 추가합니다.

이 방법에서는 이후 차트 버전에서 루트 CA 번들에 적용된 변경 사항이 반영되지 않습니다.

AI Gateway를 Helm 차트로 배포한 경우 다음과 같이 진행합니다.

1. 사용자 지정 루트 CA 인증서를 로컬 파일 뒤에 덧붙입니다.

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

2. 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.
   

3. 로컬 파일로 새 시크릿을 생성합니다.

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

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

   volumes:
     - name: cacerts
       secret:
         secretName: ca-certificates
         optional: false
   
   volumeMounts:
     - name: cacerts
       mountPath: "/tmp"
       readOnly: true
   

5. 마운트된 파일을 가리키도록 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
   

6. 차트를 다시 배포합니다.

Helm 차트에서 이 기능을 자체적으로 지원하기 위한 이슈 3이 있습니다.

Docker 배포의 경우#

Docker 배포에서도 같은 방법을 사용합니다. 다만 로컬 파일을 컨테이너에 마운트할 때 --volume /root/ca-certificates.crt:/tmp/ca-certificates.crt를 사용한다는 점만 다릅니다.

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

히스토리

• GitLab 19.2에서 도입되었습니다.

모델 엔드포인트 또는 그 앞단의 프록시가 호출자에게 클라이언트 인증서로 인증할 것을 요구한다면, 인증서를 제시하도록 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 이미지 태그를 내려받습니다.

1. 실행 중인 컨테이너를 중지합니다.

   sudo docker stop gitlab-aigw
   

2. 기존 컨테이너를 제거합니다.

   sudo docker rm gitlab-aigw
   

3. 새 이미지를 풀하고 실행합니다.

4. 환경 변수가 모두 올바르게 설정되었는지 확인합니다.

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

최신 보안 패치가 적용된 상태로 운영하려면 배포 방식에 따라 다음 지침을 따릅니다.

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 이 ApplicationSetting.current.ai_gateway_url을 통해 올바르게 구성되어 있습니다.
• /admin/code_suggestions에서 root 사용자에 대해 GitLab Duo 액세스가 명시적으로 활성화되어 있습니다.

액세스 문제가 계속되면 인증이 올바르게 구성되었는지, 상태 점검이 통과하는지 확인합니다.

문제가 지속되면 오류 메시지가 AIGW_AUTH__BYPASS_EXTERNAL=true로 인증을 우회하도록 안내할 수 있지만, 이는 문제 해결 목적으로만 사용합니다.

Admin > GitLab Duo로 이동해 상태 점검을 실행할 수도 있습니다.

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

AI Gateway 모니터링#

Prometheus를 사용해 AI Gateway의 사용량과 성능에 대한 메트릭을 수집합니다.

AI Gateway 용 Prometheus 메트릭 설정#

Prometheus 메트릭을 설정하려면 다음과 같이 진행합니다.

1. 필요한 환경 변수를 설정하고 8082 포트를 엽니다.

   -e AIGW_FASTAPI__METRICS_HOST=0.0.0.0
   -e AIGW_FASTAPI__METRICS_PORT=8082
   

GitLab Duo Workflow 서비스용 Prometheus 설정#

GitLab Duo Workflow 서비스에 Prometheus 메트릭을 설정하려면 다음과 같이 진행합니다.

1. 필요한 환경 변수를 설정하고 8083 포트를 엽니다.

   -e PROMETHEUS_METRICS__ADDR=0.0.0.0
   -e PROMETHEUS_METRICS__PORT=8083
   

2. gitlab-ai-gateway 컨테이너의 메트릭 포트를 호스트에 노출합니다.

   • Docker CLI의 경우

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

   • Docker Compose의 경우 gitlab-ai-gateway 서비스에 다음을 추가합니다.

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

   이렇게 하면 AI Gateway 메트릭 엔드포인트가 8082 포트에, GitLab Duo Workflow 서비스 메트릭 엔드포인트가 8083 포트에 노출됩니다.

3. 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 서비스의 타깃이 수집되고 있는지 확인하려면 다음과 같이 진행합니다.

1. Prometheus UI에서 Status > Targets로 이동합니다.

2. Alerts 또는 Graph 탭으로 이동해 메트릭을 조회합니다. AI Gateway와 GitLab Duo Workflow 서비스는 다음 엔드포인트에 메트릭을 노출합니다.

   • AI Gateway: http://<your_AIGW_domain>:8082/metrics
   • GitLab Duo Workflow 서비스: http://<your_duo_agent_platform_service_domain>:8083/metrics

AI Gateway의 오토스케일링 필요 여부#

오토스케일링이 필수는 아니지만, 워크로드 변동이 크거나 높은 동시성이 필요하거나 사용 패턴을 예측하기 어려운 환경에서는 권장합니다. GitLab 프로덕션 환경 기준은 다음과 같습니다.

• 기준 구성: CPU 코어 2개와 RAM 8GB를 갖춘 AI Gateway 인스턴스 1대는 약 40건의 동시 요청을 처리합니다.
• 확장 지침: AWS t3.2xlarge 인스턴스(vCPU 8개, RAM 32GB) 같은 더 큰 구성에서는 기준 구성의 4배에 해당하는 최대 160건의 동시 요청을 처리합니다.
• 요청 처리량: GitLab.com에서 관측된 사용량을 보면 활성 사용자 1,000명당 초당 7건(RPS)이 계획 수립에 적절한 지표입니다.
• 오토스케일링 옵션: Kubernetes Horizontal Pod Autoscaler(HPA) 나 유사한 메커니즘을 사용해 CPU, 메모리 사용률, 요청 지연 시간 임계값 같은 메트릭을 기준으로 인스턴스 수를 동적으로 조정합니다.

배포 규모별 구성 예시#

• 소형 배포
  • vCPU 2개와 RAM 8GB를 갖춘 단일 인스턴스입니다.
  • 최대 40건의 동시 요청을 처리합니다.
  • 사용자 50명 이하이며 워크로드가 예측 가능한 팀 또는 조직에 적합합니다.
  • 고정 인스턴스로 충분할 수 있으며, 비용 효율을 위해 오토스케일링을 비활성화할 수 있습니다.
• 중형 배포
  • vCPU 8개와 RAM 32GB를 갖춘 AWS t3.2xlarge 단일 인스턴스입니다.
  • 최대 160건의 동시 요청을 처리합니다.
  • 사용자 50~200명이며 동시성 요구가 중간 수준인 조직에 적합합니다.
  • CPU 사용률 50% 또는 요청 지연 시간 500ms 초과를 임계값으로 Kubernetes HPA를 적용합니다.
• 대형 배포
  • AWS t3.2xlarge 또는 동급 인스턴스 여러 대로 구성한 클러스터입니다.
  • 인스턴스마다 동시 요청 160건을 처리하며, 인스턴스를 늘려 수천 명의 사용자까지 확장합니다.
  • 사용자 200명을 넘고 변동이 크며 동시성이 높은 워크로드를 다루는 기업에 적합합니다.
  • HPA로 실시간 수요에 맞춰 Pod를 확장하고, 노드 오토스케일링을 함께 사용해 클러스터 전체의 리소스를 조정합니다.

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

AI Gateway는 다음 리소스 할당에서 안정적으로 동작합니다.

• 컨테이너당 CPU 코어 2개와 RAM 8GB.
• GitLab 프로덕션 환경에서 컨테이너는 보통 CPU를 약 7.39% 사용하고 그에 비례하는 메모리를 사용하므로, 증설이나 급증 트래픽 처리에 여유가 있습니다.

리소스 경합 완화 전략#

• Kubernetes 리소스 요청과 제한을 사용해 AI Gateway 컨테이너가 CPU와 메모리를 보장받도록 합니다. 예를 들면 다음과 같습니다.

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

• Prometheus, Grafana 같은 도구를 도입해 리소스 사용률(CPU, 메모리, 지연 시간)을 추적하고 병목을 조기에 감지합니다.

• AI Gateway 전용 노드나 인스턴스를 할당해 다른 서비스와의 리소스 경쟁을 방지합니다.

확장 전략#

• Kubernetes HPA를 사용해 다음과 같은 실시간 메트릭을 기준으로 Pod를 확장합니다.
  • 평균 CPU 사용률 50% 초과.
  • 요청 지연 시간이 지속적으로 500ms 초과.
  • Pod가 늘어날 때 인프라 리소스가 동적으로 확장되도록 노드 오토스케일링을 활성화합니다.

확장 권장 사항#

여러 GitLab 인스턴스 지원#

AI Gateway 1대를 배포해 여러 GitLab 인스턴스를 지원할 수도 있고, 인스턴스별 또는 지리적 리전별로 AI Gateway를 분리해 배포할 수도 있습니다. 어느 쪽이 적합한지 판단할 때는 다음을 고려합니다.

• 과금 대상 사용자 1,000명당 초당 약 7건으로 예상되는 트래픽.
• 모든 인스턴스의 총 동시 요청 수에 기반한 리소스 요구 사항.
• 각 GitLab 인스턴스에 권장되는 인증 구성.

AI Gateway와 인스턴스를 같은 위치에 배치#

AI Gateway는 전 세계 여러 리전에서 제공되며, 다음을 통해 위치와 관계없이 사용자에게 필요한 성능을 제공합니다:

• GitLab Duo 기능의 응답 시간 개선.
• 지리적으로 분산된 사용자의 지연 시간 감소.
• 데이터 주권 요건 준수.

AI Gateway는 GitLab 인스턴스와 같은 지리적 리전에 배치해야 하며, 그래야 Code Suggestions처럼 지연 시간에 민감한 기능을 포함해 개발자가 매끄러운 경험을 얻습니다.