GitLab AIゲートウェイをインストールする

AIゲートウェイは、AIネイティブなGitLab Duo機能へのアクセスを提供する2つのサービスの組み合わせです:

• AIゲートウェイサービス
• GitLab Duo Agent Platformサービス

認証とJSON Web Tokens（JWT）

GitLab Duo機能にアクセスするため、AIゲートウェイはJWTを使用して、GitLabインスタンス上の認証済みユーザーからのリクエストであることを認証します。お使いのGitLabインスタンスがトークンをリクエストすると、サービスはリクエストを認証する短期間有効な署名済みトークンを発行します。

独自のAIゲートウェイをホストする場合、署名キーペアを生成し、キーを環境変数としてサービスに渡す必要があります。

各サービスは独自のキーペアを使用します:

• AIゲートウェイは、GitLab Duoコード提案や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ゲートウェイDockerイメージには、必要なすべてのコードコンテナに格納されています。

前提条件:

• Dockerなどのコンテナエンジンをインストールします。

• ネットワークでアクセス可能な有効なホスト名を使用します。localhostは使用しないでください。

• linux/amd64アーキテクチャ用に約340 MB（圧縮済み）、および最低512 MBのRAMがあることを確認します。

• コンテナがai_gatewayおよびduo-workflow-serviceサービス用に少なくとも2つのCPUにアクセスできることを確認します。

• JWT署名キーを生成します:

  • GitLab Duo Agent Platformの場合:

    shell

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

  • AIゲートウェイの場合（Duo Chatなどの機能に必要）:

    shell

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

  生成されたすべてのキーファイルを安全に保管し、公開しないでください。これらのキーはJWTの署名に使用され、機密性の高い認証情報として扱われる必要があります。

特にヘビーユースの場合、パフォーマンスを向上させるために、最小要件よりも多くのディスク領域、メモリ、およびリソースを割り当てることを検討してください。RAMとディスク容量が増えると、ピーク時のAIゲートウェイの効率性が向上します。

GitLab AIゲートウェイにはGPUは必要ありません。

AIゲートウェイイメージ

標準イメージ

標準AIゲートウェイイメージは、次の場所で入手できます:

• コンテナレジストリ: Stable
• DockerHub: Stable

GitLabバージョンがvX.Y.*-eeの場合、最新のself-hosted-vX.Y.*-eeタグが付いたAIゲートウェイイメージを使用します。例:

• GitLabがv18.2.1-eeで、AIゲートウェイイメージに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ゲートウェイイメージにバージョンself-hosted-v18.2.0-eeのみがある場合は、self-hosted-v18.2.0-eeを使用します。

詳細については、セルフホスト型AIゲートウェイのリリースプロセスを参照してください。

FIPS検証済みイメージ

FIPS 140-3検証済み暗号化を必要とする環境では、FIPS検証済みAIゲートウェイイメージを使用します。このイメージはRed Hat UBI 9上に構築されており、CMVP検証済みのRed Hat OpenSSL FIPSプロバイダーを使用しています。

FIPS検証済みAIゲートウェイイメージは、次の場所で入手できます:

• コンテナレジストリ: Stable
• DockerHub: Stable

標準イメージと同じバージョンタグ形式（self-hosted-vX.Y.Z-ee）を使用します。

FIPS検証済みコンテナを起動するには、Docker実行コマンドのイメージ参照をFIPSイメージに置き換えます:

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

イメージからコンテナを起動する

1. コンテナを起動するには、次のコマンドを実行します:

   shell

   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ゲートウェイの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秒の遅延を解消します。

4. AIゲートウェイ URLとGitLab Duo Agent Platformサービス URLを構成します。

5. オプション。オプション。GitLab Duo Agent PlatformエンドポイントでTLSを使用している場合:

   1. 右上隅で、管理者を選択します。
   2. GitLab Duo > 設定の変更を選択します。
   3. GitLab Duo Agent PlatformサービスでTLSを使用するチェックボックスを選択します。

ネットワークアクセスを制限する

システムを強化するために、次のネットワーク構成を行います:

• AIゲートウェイコンテナの送信ネットワークアクセスを制限します。
• コンテナからの他のすべての送信トラフィックをブロックします。

AIゲートウェイは、次の送信アクセスを必要とします。これらをネットワーク制限の例外として含めることを確認します:

• お使いのGitLabインスタンス（AIGW_GITLAB_URL）。
• 構成済みのAIモデルプロバイダーエンドポイント（例: Anthropic、Gemini Enterprise Agent Platform、またはAzure OpenAI）。
• オフラインライセンスを使用しない限り、ライセンス検証のためのcustomers.gitlab.com。

Linuxホストでの送信アクセスを制限するには、DOCKER-USERチェーンでiptablesルールを使用します。詳細については、Dockerパケットフィルタリングとファイアウォールを参照してください。

DockerとNGINXおよびSSLを設定する

AIゲートウェイインスタンスでSSLを使用するには、以下を使用します:

• Docker
• リバースプロキシとしてのNGINX
• Let’s Encrypt（SSL証明書用）

NGINXは外部クライアントとの安全な接続を管理します。受信HTTPSリクエストを復号化してから、AIゲートウェイに渡します。

前提条件:

• DockerとDocker Composeがインストール済み
• 登録および構成済みのドメイン名

構成ファイルを作成する

作業ディレクトリに次のファイルを作成することから始めます。

1. nginx.conf:

   nginx

   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

   # 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コンテナを起動し、それらが実行中であることを確認します:

   shell

   docker compose up
   docker ps

2. GitLabインスタンスがAIゲートウェイにアクセスするように構成します。

3. GitLabインスタンスがGitLab Duo Agent PlatformサービスのURLにアクセスするように構成します。

4. ヘルスチェックを実行し、AIゲートウェイとAgent Platformの両方にアクセスできることを確認します。

Helmチャートを使用してインストールする

前提条件:

• 以下が必要です:
  • DNSレコードを追加できる、所有しているドメイン。
  • Kubernetesクラスター。
  • kubectlの動作するインストール。
  • Helmバージョンv3.11.0以降の動作するインストール。

詳細については、GKEまたはEKSでGitLabチャートをテストするを参照してください。

AIゲートウェイHelmリポジトリを追加する

AIゲートウェイHelmリポジトリをHelm設定に追加します:

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

AIゲートウェイをインストールする

1. ai-gatewayネームスペースを作成します:

   shell

   kubectl create namespace ai-gateway

2. AIゲートウェイを公開する予定のドメインの証明書を生成します。

3. 以前に作成したネームスペースにTLSシークレットを作成します:

   shell

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

4. チャートのパッケージレジストリで最新のパッケージのバージョン番号を取得します。

5. AIゲートウェイがAPIにアクセスするには、GitLabインスタンスの場所を知っている必要があります。これを行うには、gitlab.urlとgitlab.apiUrlをingress.hostsとingress.tlsの値と共に次のように設定します:

   shell

   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ゲートウェイバージョンのリストは、コンテナレジストリで見つけることができます。

このステップでは、すべてのリソースが割り当てられ、AIゲートウェイが起動するまでに数秒かかる場合があります。

既存のnginx Ingressコントローラーが別のネームスペースでサービスを提供しない場合、AIゲートウェイ用に独自の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ゲートウェイの証明書バンドルに追加する必要があります。

これを行うには、次のいずれかの方法があります:

• ルートCA証明書をAIゲートウェイに渡し、認証が成功するようにします。
• ルートCA証明書をAIゲートウェイコンテナのCAバンドルに追加します。

ルートCA証明書をAIゲートウェイに渡す

ルートCA証明書をAIゲートウェイに渡し、認証が成功するようにするには、REQUESTS_CA_BUNDLE環境変数を設定します。GitLabはベースとなる信頼済みCAリストにCertifiを使用するため、カスタムCAバンドルを次のように構成します:

1. Certifi cacert.pemファイルをダウンロードします:

   shell

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

2. 自己署名ルートCA証明書をファイルに追記します。たとえば、証明書を作成するためにmkcertを使用した場合:

   shell

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

3. REQUESTS_CA_BUNDLEをお使いのcacert.pemファイルへのパスに設定します。たとえば、GDKでは、$GDK_ROOT/env.runitに以下を追加します:

   shell

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

ルートCA証明書をAIゲートウェイコンテナのCAバンドルに追加する

AIゲートウェイがカスタムCAによって署名されたGitLab Self-Managedインスタンスの証明書を信頼できるようにするには、ルートCA証明書をAIゲートウェイコンテナのCAバンドルに追加します。

この方法では、チャートの以降のバージョンでルートCAバンドルに加えられた変更は許可されません。

AIゲートウェイのHelmチャートデプロイでこれを行うには:

1. カスタムルートCA証明書をローカルファイルに追記します:

   shell

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

2. /etc/ssl/certs/ca-certificates.crtバンドルファイルをAIゲートウェイコンテナからローカルファイルにコピーします:

   shell

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

3. ローカルファイルから新しいシークレットを作成します:

   shell

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

4. チャットvalues.ymlのシークレットを使用して、volumeおよびvolumeMountを定義します。これにより、コンテナに/tmp/ca-certificates.crtファイルが作成されます:

   shell

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

5. マウントされたファイルを指すようにREQUESTS_CA_BUNDLEとSSL_CERT_FILE環境変数を設定します:

   shell

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

6. チャートを再デプロイします。

イシュー 3は、Helmチャートでこれをネイティブにサポートするために存在します。

Dockerデプロイの場合

Dockerデプロイの場合も、同じ方法を使用します。唯一の違いは、ローカルファイルをコンテナにマウントするには、--volume /root/ca-certificates.crt:/tmp/ca-certificates.crtを使用することです。

相互TLS（mTLS）を必要とするモデルエンドポイントに接続する

モデルエンドポイントまたはその前にあるプロキシが、呼び出し元にクライアント証明書での認証を要求する場合、AIゲートウェイが証明書を提示するように構成します。このアプローチは、curl --certオプションと同等です。

mTLSを必要とするモデルエンドポイントに接続するには、AIゲートウェイで次の環境変数を設定します:

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ゲートウェイは、アップストリームサーバーがTLSハンドシェイク中に証明書をリクエストした場合にのみ、クライアント証明書を提示します。この設定は、クライアント証明書を必要としないモデルエンドポイントには影響しません。

AIゲートウェイDockerイメージをアップグレードする

AIゲートウェイをアップグレードするには、最新のDockerイメージタグをダウンロードします。

1. 実行中のコンテナを停止します。

   shell

   sudo docker stop gitlab-aigw

2. 既存のコンテナを削除します。

   shell

   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を常に設定します:

  shell

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

• pullPolicyをvalues.yamlに追加します:

  yaml

  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ゲートウェイをインストールする代替方法については、イシュー 463773を参照してください。

ヘルスチェックとデバッグ

GitLab Duo Self-Hostedインストールのデバッグを行うには、次のコマンドを実行します:

sudo gitlab-rake gitlab:duo:verify_self_hosted_setup

以下を確認してください:

• AIゲートウェイのURLは正しく構成されています（Ai::Setting.instance.ai_gateway_url経由）。
• GitLab Duoアクセスは、/admin/code_suggestions経由でルートユーザーに対して明示的に有効にされています。

アクセスイシューが解決しない場合は、認証が正しく構成されており、ヘルスチェックが通過していることを確認します。

永続的なイシューがある場合、エラーメッセージはAIGW_AUTH__BYPASS_EXTERNAL=trueで認証をバイパスすることを提案する可能性がありますが、これはトラブルシューティングの場合のみ行ってください。

管理者 > GitLab Duoに移動して、ヘルスチェックを実行することもできます。

これらのテストはオフライン環境で実行されます:

AIゲートウェイを監視する

Prometheusを使用して、AIゲートウェイの使用状況とパフォーマンスに関するメトリクスを収集します。

AIゲートウェイのPrometheusメトリクスを設定する

Prometheusメトリクスを設定するには:

1. 必要な環境変数を設定し、ポート8082を開きます:

   shell

   -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を開きます:

   shell

   -e PROMETHEUS_METRICS__ADDR=0.0.0.0
   -e PROMETHEUS_METRICS__PORT=8083

2. gitlab-ai-gatewayコンテナからホストにメトリクスポートを公開します:

   • Docker CLIの場合:

     shell

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

   • Docker Composeの場合、gitlab-ai-gatewayサービスに追加します:

     shell

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

   これにより、AIゲートウェイメトリクスエンドポイントがポート8082に、GitLab Duo Workflow Serviceメトリクスエンドポイントがポート8083に公開されます。

3. AIゲートウェイコンテナを再起動します。

Prometheusをメトリクスのスクレイプに構成する

AIゲートウェイとGitLab Duo Workflowサービスからメトリクスを収集するには、次のprometheus.yml設定をPrometheusインスタンスに追加します。この設定では、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ゲートウェイとGitLab Duo Workflowサービスのターゲットが収集されていることを検証するには:

1. Prometheus UIで、ステータス > Targetsに移動します。

2. アラートまたはグラフタブに移動してメトリクスをクエリします。AIゲートウェイとGitLab Duo Workflowサービスは、次のエンドポイントでメトリクスを公開します:

   • AIゲートウェイ: http://<your_AIGW_domain>:8082/metrics
   • GitLab Duo Workflowサービス: http://<your_duo_agent_platform_service_domain>:8083/metrics

AIゲートウェイはオートスケールする必要がありますか？

オートスケールは必須ではありませんが、変動するワークロード、高い並行処理要件、または予測不能な使用パターンを持つ環境には推奨されます。GitLab本番環境では:

• ベースライン設定: 2 CPUコアと8 GB RAMを備えた単一のAIゲートウェイインスタンスは、約40の並行処理リクエストを処理できます。
• スケーリングガイドライン: AWS t3.2xlargeインスタンス（8 vCPU、32 GB RAM）のような大規模な設定では、ゲートウェイはベースライン設定の4倍に相当する最大160の並行処理リクエストを処理できます。
• リクエストスループット: GitLab.comの観測された使用状況から、1000アクティブユーザーあたり7 RPS（1秒あたりのリクエスト数）が計画にとって合理的なメトリクスであることが示唆されています。
• オートスケールオプション: Kubernetes Horizontal Pod Autoscalers（HPA）または類似のメカニズムを使用して、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ゲートウェイコンテナの仕様とリソース割り当て

AIゲートウェイは、次のリソース割り当てで効果的に動作します:

• コンテナあたり2 CPUコアと8 GBのRAM。
• コンテナは、通常、GitLab本番環境で約7.39%のCPUとそれに比例したメモリを利用し、成長やバーストアクティビティに対応する余地を残しています。

リソース競合の軽減戦略

• Kubernetesのリクエストと制限を使用して、AIゲートウェイコンテナが保証されたCPUとメモリ割り当てを受け取ることを確認します。例:

  yaml

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

• PrometheusやGrafanaのようなツールを実装して、リソース使用率（CPU、メモリ、レイテンシー）を追跡し、ボトルネックを早期に検出します。

• ノードまたはインスタンスをAIゲートウェイに排他的に割り当てて、他のサービスとのリソース競合を防ぎます。

スケーリング戦略

• Kubernetes HPAを使用して、次のようなリアルタイムのメトリクスに基づいてポッドをスケールします:
  • 平均CPU使用率が50%を超える。
  • 要求レイテンシーが常に500msを超える。
  • ノードオートスケールを有効にして、ポッドの増加に合わせてインフラストラクチャリソースを動的にスケールします。

スケーリングの推奨事項

複数のGitLabインスタンスをサポートする

単一のAIゲートウェイをデプロイして複数のGitLabインスタンスをサポートするか、インスタンスまたは地理的リージョンごとに個別のAIゲートウェイをデプロイできます。どちらが適切かを判断するために、以下を考慮してください:

• 1,000請求対象ユーザーあたり毎秒約7リクエストの予想トラフィック。
• すべてのインスタンスにおける合計並行処理リクエスト数に基づくリソース要件。
• 各GitLabインスタンスのベストプラクティス認証設定。

AIゲートウェイとインスタンスを併置する

AIゲートウェイは、場所に関係なくユーザーに最適なパフォーマンスを保証するために、世界中の複数のリージョンで利用可能です:

• GitLab Duo機能の応答時間の改善。
• 地理的に分散したユーザーのレイテンシーを削減。
• データ主権要件へのコンプライアンス。

AIゲートウェイは、GitLabインスタンスと同じ地理的リージョンに配置し、特にレイテンシーに敏感なコード提案のような機能のために、スムーズなデベロッパーエクスペリエンスを提供する必要があります。

トラブルシューティング

AIゲートウェイを使用する際に、次のイシューに遭遇する可能性があります。

OpenShiftのパーミッションイシュー

OpenShiftにAIゲートウェイをデプロイする際、OpenShiftのセキュリティモデルによりパーミッションエラーが発生する可能性があります。

/tmpにある読み取り専用ファイルシステム

AIゲートウェイは/tmpへの書き込みが必要です。ただし、セキュリティが制限されたOpenShift環境では、/tmpが読み取り専用である可能性があります。

このイシューを解決するには、新しいEmptyDirボリュームを作成し、/tmpにマウントします。これを行うには、次のいずれかの方法があります:

• コマンドラインから:

  shell

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

• お使いのvalues.yamlに追加:

  yaml

  volumes:
  - name: tmp-volume
    emptyDir: {}
  
  volumeMounts:
  - name: tmp-volume
    mountPath: "/tmp"

HuggingFaceモデル

デフォルトでは、AIゲートウェイはHuggingFaceモデルのキャッシュに/home/aigateway/.hfを使用しますが、OpenShiftのセキュリティ制限された環境では書き込み可能でない場合があります。これにより、次のようなパーミッションエラーが発生する可能性があります:

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

これを解決するには、HF_HOME環境変数を書き込み可能な場所に設定します。/var/tmp/huggingfaceまたはコンテナによって書き込み可能な任意のディレクトリを使用できます。

これは次のいずれかの方法で構成できます:

• お使いのvalues.yamlに追加:

  yaml

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

• または、Helmアップグレードコマンドに含めます:

  shell

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

この設定により、AIゲートウェイはOpenShiftのセキュリティ制約を尊重しながらHuggingFaceモデルを適切にキャッシュできます。選択する正確なディレクトリは、特定のOpenShift設定とセキュリティポリシーによって異なる場合があります。

ボリュームマウントによってシャドウされたトークナイザーキャッシュ

AIゲートウェイイメージ内のプリキャッシュされたトークナイザーファイルは、次の場合にボリュームマウントによってシャドウされる可能性があります:

• コード補完リクエストが500エラーを返す。
• AIゲートウェイログに、transformers/utils/hub.pyからのOSErrorがhuggingface.coからSalesforce/codegen2-16Bをダウンロードしようとしていることが表示される。

セルフホスト型AIゲートウェイイメージ（self-hosted-vX.Y.Z-ee）はHF_HUB_OFFLINE=trueを設定し、ビルド時にトークナイザーをプリキャッシュするため、ランタイム時にhuggingface.coへのネットワークアクセスは発生しないはずです。ネットワークアクセスが発生した場合、Helm値の空のディレクトリが/home/aigateway/.hfにマウントされ、キャッシュされたファイルを上書きする可能性があります。

huggingface.coへのエグレスアクセスを許可することで、このイシューを解決しようとしないでください。代わりに、イシューを診断するには、AIゲートウェイポッドで次を実行します:

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

キャッシュディレクトリが見つからないか空の場合は、次を実行します:

1. values.yamlで、/home/aigateway/.hfまたはHF_HOMEによって設定されたパスをターゲットとするvolumeMountsがあるかどうかを確認します。
2. マウントを、イメージの組み込みキャッシュと重ならないディレクトリに削除または再マッピングします。

自己署名証明書エラー

AIゲートウェイがカスタム認証局（CA）によって署名された証明書または自己署名証明書を使用してGitLabインスタンスまたはモデルエンドポイントに接続しようとすると、AIゲートウェイによって[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chainエラーがログに記録されます。

これを解決するには、自己署名SSL証明書を使用してGitLabインスタンスまたはモデルエンドポイントに接続するを参照してください。

トークン作成失敗

Duo Chatなどの機能を使用しているときにToken creation failedエラーが発生した場合、AIGW_SELF_SIGNED_JWT__SIGNING_KEYとAIGW_SELF_SIGNED_JWT__VALIDATION_KEY環境変数がAIゲートウェイに設定されていない可能性があります。

これらのキーは、AIゲートウェイが短期間有効なユーザーJWTを発行するために必要です。これらのキーがないと、AIゲートウェイはトークンに署名できず、JWKの逆シリアル化失敗を引き起こします。

この問題を解決するには、次の手順に従います:

1. 必要なキーを生成します:

   shell

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

2. キーを環境変数として渡すことにより、お使いのAIゲートウェイコンテナにキーを追加します:

   shell

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

3. AIゲートウェイコンテナを再起動します。

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をお使いの証明書バンドルへのパスに置き換えます。