Habilitar APIs

Habilite as APIs de serviço que o passo a passo usa:

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

As APIs que você precisa dependem do caminho de implantação:

• compute e servicenetworking: necessárias para o caminho Cloud SQL com IP privado
• run: apenas Cloud Run
• container: apenas GKE

Criar a conta de serviço e conceder IAM

O gateway é executado como uma conta de serviço dedicada com permissão para chamar Agent Platform. Ele alcança Cloud SQL sobre o VPC com um usuário de senha, portanto nenhuma função IAM do Cloud SQL é necessária:

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

Em seguida, habilite os modelos Claude para o projeto no Model Garden; os modelos são publicados em regiões específicas, portanto verifique cada cartão de modelo.

Construir e enviar a imagem para Artifact Registry

Construa a imagem de acordo com os requisitos de imagem de contêiner, usando o binário glibc linux-x64, e envie-a:

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

# Cloud Run requires linux/amd64. --provenance=false avoids a buildx OCI
# image index that Cloud Run rejects.
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>"

Provisionar Cloud SQL para PostgreSQL

Crie a instância em um VPC via Private Services Access para que ela não tenha IP público; isso também satisfaz projetos onde constraints/sql.restrictPublicIp é aplicado:

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: one-time per VPC
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"

O runtime Cloud Run ou GKE deve estar neste VPC ou roteado para ele.

Escrever gateway.yaml

O bloco upstreams aponta para Agent Platform com auth: {}, portanto o gateway autentica via Application Default Credentials da conta de serviço do runtime. Consulte a referência de configuração para cada campo.

Dois campos listen dependem do que está na frente do gateway:

• public_url: necessário atrás de Cloud Run ou um GKE Ingress. O gateway constrói o redirect_uri do IdP e seu documento de descoberta apenas a partir deste valor, nunca a partir de cabeçalhos X-Forwarded-*.
• trusted_proxies: os intervalos de origem do front-end. O gateway honra X-Forwarded-For apenas quando o par TCP está nesta lista, depois percorre a cadeia passando hops confiáveis, portanto os limites de taxa de login por IP e eventos de auditoria registram IPs de desenvolvedores em vez do balanceador de carga.

Defina trusted_proxies para corresponder ao seu front-end. Um GKE Ingress externo de classe gce não está listado: ele provisiona um endereço de regra de encaminhamento público, que a verificação rede privada do /login rejeita.

O exemplo abaixo usa os valores do balanceador de carga interno na frente do 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 ignores offline_access; these yield refresh tokens:
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>                        # must match $REGION
project_id: <your-project>
auth: {} # ADC via the runtime service account

Armazenar segredos no Secret Manager

Crie quatro segredos e conceda roles/secretmanager.secretAccessor à conta de serviço claude-gateway:

Como os segredos chegam ao contêiner difere por caminho:

• No GKE eles são montados como arquivos via o driver CSI do Secret Manager, e gateway.yaml referencia ${file:/secrets/...}.
• No Cloud Run, que não pode montar múltiplos segredos em um diretório, gateway.yaml é montado como arquivo e os outros três são injetados como variáveis de ambiente, portanto gateway.yaml referencia ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} e ${GATEWAY_POSTGRES_URL} em vez disso.

Implantar

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 \
--timeout=3600 \
--ingress=internal-and-cloud-load-balancing \
--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"
# On a Standard cluster, existing node pools also need GKE_METADATA;
# Autopilot enables this by default.
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"

Enviar a URL do gateway para máquinas de desenvolvedores

O gateway agora está em execução, mas os desenvolvedores não podem alcançá-lo a partir de /login até que a URL do gateway esteja em suas máquinas. Defina forceLoginMethod e forceLoginGatewayUrl no arquivo de configurações gerenciadas que você implanta em cada dispositivo via MDM. Não há opção de gateway no seletor de login para um desenvolvedor selecionar manualmente.