Agent Platform Architecture

graph TB
    subgraph Client Space
        Client[Enterprise Users / Applications]
    end

    subgraph Tier 1: Public Front Door (Consumer Project)
        ExtALB[Global External Application Load Balancer<br/>• Single Anycast IP<br/>• Client TLS / SNI Termination<br/>• Edge Cloud Armor / Coarse IAP<br/>• Hostname Routing]
        PSC_NEG1[Regional PSC NEG<br/>global access mode]
        ExtALB --> PSC_NEG1
    end

    subgraph Tier 2: Per-Agent Ingress (Producer / Governance Project)
        SA[PSC Service Attachment]
        IntALB[Regional Internal Application Load Balancer<br/>• Per-Agent IAP & CAA Enforcement<br/>• URL Map Host & Path Rewrite<br/>• Model Armor Service Extensions ext_proc]
        PSC_NEG2[PSC NEG to Google APIs<br/>psc_target_service: REGION-aiplatform.googleapis.com]

        PSC_NEG1 -->|Private Service Connect| SA
        SA --> IntALB
        IntALB --> PSC_NEG2
    end

    subgraph Google Managed Tenant
        RE[Agent Runtime (reasoningEngines / ADK Agent)]
        PSC_NEG2 -->|Private VPC Egress| RE
    end

    Client -->|HTTPS agent-a.example.com| ExtALB

# tier2-urlmap.yaml (use numeric ${AGENT_PROJECT_NUMBER} in pathPrefixRewrite)
name: tier2-re-urlmap
defaultService: projects/${PRODUCER_PROJECT_ID}/regions/${REGION}/backendServices/tier2-re-backend
hostRules:
  - hosts:
      - "agent-a.example.com"
    pathMatcher: agent-matcher
pathMatchers:
  - name: agent-matcher
    defaultService: projects/${PRODUCER_PROJECT_ID}/regions/${REGION}/backendServices/tier2-re-backend
    pathRules:
      - paths:
          - /chat
          - /stream
        service: projects/${PRODUCER_PROJECT_ID}/regions/${REGION}/backendServices/tier2-re-backend
        routeAction:
          urlRewrite:
            hostRewrite: "${REGION}-aiplatform.googleapis.com"
            pathPrefixRewrite: "/v1/projects/${AGENT_PROJECT_NUMBER}/locations/${REGION}/reasoningEngines/${RE_ID}:streamQuery"
      - paths:
          - /query
        service: projects/${PRODUCER_PROJECT_ID}/regions/${REGION}/backendServices/tier2-re-backend
        routeAction:
          urlRewrite:
            hostRewrite: "${REGION}-aiplatform.googleapis.com"
            pathPrefixRewrite: "/v1/projects/${AGENT_PROJECT_NUMBER}/locations/${REGION}/reasoningEngines/${RE_ID}:query"

# Tier 2 Producer Project (${PRODUCER_PROJECT_ID}): Proxy-Only Subnet, Google APIs PSC NEG, Internal ALB & PSC Service Attachment
gcloud compute networks subnets create "tier2-proxy-only-subnet" --project="${PRODUCER_PROJECT_ID}" \
  --network="${PRODUCER_VPC}" --region="${REGION}" --range="10.129.0.0/23" --purpose="REGIONAL_MANAGED_PROXY" --role="ACTIVE"
gcloud compute networks subnets create "tier2-psc-nat-subnet" --project="${PRODUCER_PROJECT_ID}" \
  --network="${PRODUCER_VPC}" --region="${REGION}" --range="10.129.2.0/24" --purpose="PRIVATE_SERVICE_CONNECT"
gcloud compute network-endpoint-groups create "psc-aiplatform-neg" --project="${PRODUCER_PROJECT_ID}" \
  --region="${REGION}" --network-endpoint-type="private-service-connect" --psc-target-service="${REGION}-aiplatform.googleapis.com"
# Note: Add --iap=enabled ONLY if authenticating via Google IAP; omit --iap=enabled when Tier 1 ext_proc injects an STS OAuth access token for Agent Runtime
gcloud compute backend-services create "tier2-re-backend" --project="${PRODUCER_PROJECT_ID}" \
  --region="${REGION}" --load-balancing-scheme="INTERNAL_MANAGED" --protocol="HTTPS"
gcloud compute backend-services add-backend "tier2-re-backend" --project="${PRODUCER_PROJECT_ID}" \
  --region="${REGION}" --network-endpoint-group="psc-aiplatform-neg" --network-endpoint-group-region="${REGION}"
gcloud compute url-maps import "tier2-re-urlmap" --project="${PRODUCER_PROJECT_ID}" --region="${REGION}" --source="tier2-urlmap.yaml" --quiet
gcloud compute target-https-proxies create "tier2-re-https-proxy" --project="${PRODUCER_PROJECT_ID}" \
  --region="${REGION}" --url-map="tier2-re-urlmap" --certificate-manager-certificates="${TIER2_CERT_NAME}"
gcloud compute forwarding-rules create "tier2-re-fwd-rule" --project="${PRODUCER_PROJECT_ID}" \
  --region="${REGION}" --load-balancing-scheme="INTERNAL_MANAGED" --network="${PRODUCER_VPC}" \
  --subnet="${PRODUCER_SUBNET}" --target-https-proxy="tier2-re-https-proxy" --target-https-proxy-region="${REGION}" --ports=443
gcloud compute service-attachments create "tier2-re-service-attachment" --project="${PRODUCER_PROJECT_ID}" \
  --region="${REGION}" --producer-forwarding-rule="tier2-re-fwd-rule" --connection-preference="ACCEPT_AUTOMATIC" --nat-subnets="tier2-psc-nat-subnet"

# Tier 1 Consumer Front-Door Project (${FRONTDOOR_PROJECT_ID}): Global External ALB (with Edge Cloud Armor & IAP) -> PSC NEG -> Tier 2 Service Attachment
gcloud compute network-endpoint-groups create "tier1-to-tier2-psc-neg" --project="${FRONTDOOR_PROJECT_ID}" \
  --region="${REGION}" --network-endpoint-type="private-service-connect" \
  --psc-target-service="projects/${PRODUCER_PROJECT_ID}/regions/${REGION}/serviceAttachments/tier2-re-service-attachment" \
  --network="${FRONTDOOR_VPC}" --subnet="${FRONTDOOR_SUBNET}"
gcloud compute backend-services create "tier1-ext-backend" --project="${FRONTDOOR_PROJECT_ID}" \
  --global --load-balancing-scheme="EXTERNAL_MANAGED" --protocol="HTTPS" \
  --security-policy="${CLOUD_ARMOR_POLICY}" \
  --iap=enabled,oauth2-client-id="${IAP_CLIENT_ID}",oauth2-client-secret="${IAP_CLIENT_SECRET}"
gcloud compute backend-services add-backend "tier1-ext-backend" --project="${FRONTDOOR_PROJECT_ID}" \
  --global --network-endpoint-group="tier1-to-tier2-psc-neg" --network-endpoint-group-region="${REGION}"
gcloud compute url-maps create "tier1-ext-urlmap" --project="${FRONTDOOR_PROJECT_ID}" --default-service="tier1-ext-backend"
gcloud compute target-https-proxies create "tier1-ext-https-proxy" --project="${FRONTDOOR_PROJECT_ID}" \
  --url-map="tier1-ext-urlmap" --ssl-certificates="${TIER1_SSL_CERT}"
gcloud compute forwarding-rules create "tier1-ext-fwd-rule" --project="${FRONTDOOR_PROJECT_ID}" \
  --global --load-balancing-scheme="EXTERNAL_MANAGED" --target-https-proxy="tier1-ext-https-proxy" --ports=443

# Grant Edge & Backend IAM (Workforce Pool / Service Account roles/aiplatform.user; add roles/iap.httpsResourceAccessor if using IAP)
gcloud projects add-iam-policy-binding "${PRODUCER_PROJECT_ID}" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/${WORKFORCE_POOL_ID}/*" --role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding "${PRODUCER_PROJECT_ID}" --member="${EXT_PROC_IDENTITY}" --role="roles/aiplatform.user"

export PROJECT_ID="gov-hub-proj" MCP_PROJECT_ID="mcp-spoke-proj" REGION="us-central1"
export TRUST_CONFIG_ID="enterprise-private-ca-trust" MCP_SERVICE_NAME="mcp-server-prod"
export MCP_VPC="mcp-spoke-vpc" MCP_SUBNET="mcp-ilb-subnet" MCP_ILB_IP="10.20.10.10"
export MCP_INTERNAL_FQDN="mcp.internal.example.com" MCP_INTERNAL_CERT="mcp-internal-private-cert"

# 1. Import Certificate Manager TrustConfig in ${REGION} (reference in ACT tlsConfig with additionalRoots: PUBLICLY_TRUSTED_ROOTS so WebPKI roots for aiplatform.googleapis.com are preserved)
cat <<EOF > trust-config.yaml
trustStores:
  - trustAnchors:
      - pemCertificate: |
          -----BEGIN CERTIFICATE-----
          ...Enterprise Private Root CA PEM...
          -----END CERTIFICATE-----
EOF
gcloud certificate-manager trust-configs import "${TRUST_CONFIG_ID}" \
  --project="${PROJECT_ID}" --location="${REGION}" --source="trust-config.yaml"

# 2. Because native Cloud Run (*.run.app) uses Google-managed certificates, front Cloud Run with a Serverless NEG and Regional INTERNAL_MANAGED ALB (with IAP enabled; --protocol="HTTP" is required by GCE for Serverless NEGs)
gcloud compute network-endpoint-groups create "mcp-serverless-neg" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" \
  --network-endpoint-type="serverless" --cloud-run-service="${MCP_SERVICE_NAME}"
gcloud compute backend-services create "mcp-internal-backend" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" \
  --load-balancing-scheme="INTERNAL_MANAGED" --protocol="HTTP" \
  --iap=enabled,oauth2-client-id="${IAP_CLIENT_ID}",oauth2-client-secret="${IAP_CLIENT_SECRET}"
gcloud compute backend-services add-backend "mcp-internal-backend" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" \
  --network-endpoint-group="mcp-serverless-neg" --network-endpoint-group-region="${REGION}"
# Configure defaultService + wildcard "*" hostRule alongside ${MCP_INTERNAL_FQDN} (requires IAP and/or ServerTlsPolicy mTLS)
gcloud compute url-maps create "mcp-internal-urlmap" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" --default-service="mcp-internal-backend"
gcloud compute url-maps add-path-matcher "mcp-internal-urlmap" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" --path-matcher-name="mcp-matcher" \
  --default-service="mcp-internal-backend" --new-hosts="${MCP_INTERNAL_FQDN},*"
gcloud compute target-https-proxies create "mcp-internal-https-proxy" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" --url-map="mcp-internal-urlmap" \
  --certificate-manager-certificates="${MCP_INTERNAL_CERT}"
gcloud compute forwarding-rules create "mcp-internal-fwd-rule" \
  --project="${MCP_PROJECT_ID}" --region="${REGION}" --load-balancing-scheme="INTERNAL_MANAGED" \
  --network="${MCP_VPC}" --subnet="${MCP_SUBNET}" --address="${MCP_ILB_IP}" \
  --target-https-proxy="mcp-internal-https-proxy" --target-https-proxy-region="${REGION}" --ports=443

# lb-traffic-extension.yaml (Global External ALB: --location=global; use regions/${REGION}/... for Regional Internal ALB)
name: ext-proc-token-exchange
loadBalancingScheme: EXTERNAL_MANAGED
forwardingRules:
  - https://www.googleapis.com/compute/v1/projects/${PROJECT_ID}/global/forwardingRules/${FORWARDING_RULE_NAME}
extensionChains:
  - name: token-exchange-chain
    matchCondition:
      celExpression: 'true'
    extensions:
      - name: ext-proc-auth-swap
        authority: ext-proc.internal.example.com
        service: https://www.googleapis.com/compute/v1/projects/${PROJECT_ID}/global/backendServices/${EXT_PROC_BACKEND_SERVICE}
        supportedEvents:
          - REQUEST_HEADERS
        timeout: 1.0s
        failOpen: false

gcloud compute backend-services create "${EXT_PROC_BACKEND_SERVICE}" --project="${PROJECT_ID}" \
  --global --load-balancing-scheme="EXTERNAL_MANAGED" --protocol="HTTP2" --health-checks="${EXT_PROC_HC}"
gcloud service-extensions lb-traffic-extensions import ext-proc-token-exchange \
  --location="global" \
  --source="lb-traffic-extension.yaml" \
  --project="${PROJECT_ID}"

import hashlib, json, threading, time, urllib.parse, httpx
from envoy.config.core.v3 import base_pb2
from envoy.service.ext_proc.v3 import external_processor_pb2 as ep_pb2

_STS_CLIENT = httpx.Client(timeout=0.4)
_STS_LOCK = threading.Lock()
_STS_CACHE: dict[str, tuple[str, float]] = {}

def exchange_workforce_token_via_sts(idp_jwt: str, workforce_pool_provider: str, user_project: str = "") -> str:
  digest = hashlib.sha256(f"{workforce_pool_provider}:{idp_jwt}".encode("utf-8")).hexdigest()
  now = time.time()
  if (cached := _STS_CACHE.get(digest)) and now < cached[1] - 60:
    return cached[0]
  provider_path = workforce_pool_provider.strip().removeprefix("//iam.googleapis.com/").lstrip("/")
  payload = {
      "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
      "audience": f"//iam.googleapis.com/{provider_path}",
      "scope": "https://www.googleapis.com/auth/cloud-platform",
      "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
      "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
      "subject_token": idp_jwt,
  }
  if user_project:
    payload["options"] = json.dumps({"userProject": user_project})
  resp = _STS_CLIENT.post("https://sts.googleapis.com/v1/token", content=urllib.parse.urlencode(payload), headers={"Content-Type": "application/x-www-form-urlencoded"})
  resp.raise_for_status()
  body = resp.json()
  with _STS_LOCK:
    _STS_CACHE[digest] = (str(body["access_token"]), now + float(body.get("expires_in", 3600)))
  return str(body["access_token"])

def build_ext_proc_header_mutation(original_auth: str, gcp_token: str) -> ep_pb2.HeaderMutation:
  return ep_pb2.HeaderMutation(
      set_headers=[
          base_pb2.HeaderValueOption(
              header=base_pb2.HeaderValue(key="X-Forwarded-User-Authorization", raw_value=original_auth.encode("utf-8")),
              append_action=base_pb2.HeaderValueOption.OVERWRITE_IF_EXISTS_OR_ADD,
          ),
          base_pb2.HeaderValueOption(
              header=base_pb2.HeaderValue(key="Authorization", raw_value=f"Bearer {gcp_token}".encode("utf-8")),
              append_action=base_pb2.HeaderValueOption.OVERWRITE_IF_EXISTS_OR_ADD,
          ),
      ]
  )