API を有効にする

このチュートリアルで使用するサービス API を有効にします。

gcloud services enable \
aiplatform.googleapis.com \
artifactregistry.googleapis.com \
sqladmin.googleapis.com \
secretmanager.googleapis.com \
iamcredentials.googleapis.com \
iam.googleapis.com \
compute.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
container.googleapis.com

必要な API はデプロイメント パスによって異なります。

• compute と servicenetworking：プライベート IP Cloud SQL パスに必要
• run：Cloud Run のみ
• container：GKE のみ

サービス アカウントを作成して IAM を付与する

ゲートウェイは Google Cloud の Agent Platform を呼び出す権限を持つ専用サービス アカウントとして実行されます。VPC 経由で Cloud SQL に到達するパスワード ユーザーを使用するため、Cloud SQL IAM ロールは不要です。

gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"
SA="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:${SA}" --role="roles/aiplatform.user" --condition=None

次に、Model Garden でプロジェクトの Claude モデルを有効にします。モデルは特定のリージョンに公開されるため、各モデル カードを確認してください。

イメージをビルドして Artifact Registry にプッシュする

コンテナ イメージ要件に従ってイメージをビルドし（linux-x64 glibc バイナリを使用）、プッシュします。

gcloud artifacts repositories create claude-gateway \
--repository-format=docker --location="$REGION"
gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet

# Cloud Run には linux/amd64 が必要です。--provenance=false は buildx OCI
# イメージ インデックスを回避します。これは Cloud Run が拒否します。
docker build --platform=linux/amd64 --provenance=false \
-t "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" .
docker push "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>"

Cloud SQL for PostgreSQL をプロビジョニングする

Private Services Access 経由で VPC 上にインスタンスを作成して、パブリック IP を持たないようにします。これは constraints/sql.restrictPublicIp が適用されているプロジェクトの要件も満たします。

VPC=cc-gateway-vpc
gcloud compute networks create "$VPC" --subnet-mode=custom
gcloud compute networks subnets create cc-gateway-subnet \
--network="$VPC" --region="$REGION" --range=10.0.0.0/24

# Private Services Access：VPC ごとに 1 回限り
gcloud compute addresses create "google-managed-services-${VPC}" \
--global --purpose=VPC_PEERING --prefix-length=16 --network="$VPC"
gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges="google-managed-services-${VPC}" --network="$VPC"

gcloud sql instances create claude-gateway-db \
--database-version=POSTGRES_16 --tier=db-g1-small --region="$REGION" \
--network="projects/${PROJECT_ID}/global/networks/${VPC}" --no-assign-ip
gcloud sql databases create claude_gateway --instance=claude-gateway-db
PGPASS="$(openssl rand -hex 24)"
gcloud sql users create gateway --instance=claude-gateway-db --password="$PGPASS"

PRIVATE_IP="$(gcloud sql instances describe claude-gateway-db \
--format='value(ipAddresses[0].ipAddress)')"
GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${PRIVATE_IP}:5432/claude_gateway?sslmode=require"

Cloud Run または GKE ランタイムは、この VPC 上にあるか、この VPC にルーティングされている必要があります。

gateway.yaml を作成する

upstreams ブロックは Google Cloud の Agent Platform を auth: {} で指定するため、ゲートウェイはランタイム サービス アカウントからのアプリケーション デフォルト認証情報を使用して認証します。すべてのフィールドについては、設定リファレンスを参照してください。

2 つの listen フィールドはゲートウェイの前面を説明します。

• public_url：外部 https:// オリジン。ループバック以外のバインドに必須です。listen リファレンスを参照してください。ゲートウェイは IdP redirect_uri と検出ドキュメントをこの値からのみビルドし、X-Forwarded-* ヘッダーからはビルドしません。
• trusted_proxies：フロント エンドのソース範囲。ゲートウェイは TCP ピアがこのリストにある場合にのみ X-Forwarded-For を受け入れ、信頼できるホップを超えてチェーンをウォークするため、IP ごとのサインイン レート制限と監査イベントはロード バランサーの IP ではなく開発者 IP を記録します。

trusted_proxies をフロント エンドに合わせて設定します。クラス gce の外部 GKE Ingress はリストされていません。これはパブリック転送ルール アドレスをプロビジョニングし、/login プライベート ネットワーク チェックがこれを拒否します。

以下の例は、内部ロード バランサー イン フロント オブ Cloud Run の値を使用します。

listen:
host: 0.0.0.0
port: 8080
public_url: https://claude-gateway.internal.example.com
trusted_proxies: [169.254.0.0/16, <your-proxy-only-subnet-cidr>]

oidc:
issuer: https://accounts.google.com
client_id: <your-oauth-client-id>
client_secret: ${OIDC_CLIENT_SECRET}           # GKE: ${file:/secrets/oidc-client-secret}
allowed_email_domains: [example.com]
# Google は offline_access を無視します。これらはリフレッシュ トークンを生成します。
scopes: [openid, profile, email]
extra_auth_params: { access_type: offline, prompt: consent }

session:
jwt_secret: ${GATEWAY_JWT_SECRET}              # GKE: ${file:/secrets/jwt-secret}

store:
postgres_url: ${GATEWAY_POSTGRES_URL}          # GKE: ${file:/secrets/postgres-url}

upstreams:
- provider: vertex
region: <your-region>                        # $REGION と一致する必要があります
project_id: <your-project>
auth: {} # ランタイム サービス アカウント経由の ADC

Secret Manager にシークレットを保存する

4 つのシークレットを作成し、roles/secretmanager.secretAccessor を claude-gateway サービス アカウントに付与します。

シークレットがコンテナに到達する方法はトラックによって異なります。

• GKE では Secret Manager CSI ドライバー経由でファイルとしてマウントされ、gateway.yaml は ${file:/secrets/...} を参照します。
• Cloud Run では複数のシークレットを 1 つのディレクトリにマウントできないため、gateway.yaml はファイルとしてマウントされ、他の 3 つは環境変数として注入されるため、gateway.yaml は代わりに ${GATEWAY_JWT_SECRET}、${OIDC_CLIENT_SECRET}、${GATEWAY_POSTGRES_URL} を参照します。

デプロイ

gcloud run deploy claude-gateway \
--image="${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" \
--region="$REGION" \
--service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \
--min-instances=1 \
--max-instances=8 \
--timeout=3600 \
--ingress=internal \
--network="$VPC" --subnet=cc-gateway-subnet --vpc-egress=private-ranges-only \
--set-secrets=/etc/claude/gateway.yaml=gateway-config:latest,GATEWAY_JWT_SECRET=gateway-jwt-secret:latest,OIDC_CLIENT_SECRET=gateway-oidc-client-secret:latest,GATEWAY_POSTGRES_URL=gateway-postgres-url:latest \
--no-invoker-iam-check

gcloud container clusters update <cluster> --region="$REGION" \
--workload-pool="${PROJECT_ID}.svc.id.goog"
# Standard クラスターでは、既存のノード プールも GKE_METADATA が必要です。
# Autopilot はデフォルトでこれを有効にします。
gcloud container node-pools update <pool> --cluster=<cluster> \
--region="$REGION" --workload-metadata=GKE_METADATA

kubectl create namespace claude-gateway
kubectl create serviceaccount gateway -n claude-gateway

gcloud iam service-accounts add-iam-policy-binding \
"claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \
--role roles/iam.workloadIdentityUser \
--member "serviceAccount:${PROJECT_ID}.svc.id.goog[claude-gateway/gateway]"

kubectl annotate serviceaccount gateway -n claude-gateway \
iam.gke.io/gcp-service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

ゲートウェイ URL を開発者マシンにプッシュする

ゲートウェイは実行されていますが、ゲートウェイ URL がマシンに配置されるまで、開発者は /login からそれに到達できません。完全なマネージド設定スニペットを forceLoginMethod、forceLoginGatewayUrl、および parentSettingsBehavior: "merge" オプトインと共に、MDM 経由で各デバイスにデプロイします。開発者が手動で選択できるログイン ピッカーのゲートウェイ オプションはありません。