GCP API Gateway Feature-Implementierungen

Detaillierte Implementierung aller Features für GCP API Gateway Provider in GAL

Navigation: - ← Zurück zur GCP API Gateway Übersicht - → Deployment & Migration

Inhaltsverzeichnis

1. Provider-Spezifische Features
2. Beispiele

---

Provider-Spezifische Features

1. OpenAPI 2.0 (Swagger) Only

Wichtig: GCP API Gateway unterstützt nur OpenAPI 2.0 (Swagger), nicht OpenAPI 3.0.

GAL generiert automatisch OpenAPI 2.0 für GCP:

swagger: "2.0"
info:
  title: "User API"
  version: "1.0.0"
schemes:
  - https
x-google-backend:
  address: "https://backend.example.com"
  deadline: 30.0

2. x-google-backend Extension

Die x-google-backend Extension definiert Backend-Konfiguration:

x-google-backend:
  address: "https://service-abc123-uc.a.run.app"
  path_translation: "APPEND_PATH_TO_ADDRESS"
  deadline: 60.0
  disable_auth: false
  jwt_audience: "https://service-abc123-uc.a.run.app"

Per-Operation Backend:

paths:
  /api/users:
    get:
      x-google-backend:
        address: "https://read-service.run.app"
        deadline: 10.0
    post:
      x-google-backend:
        address: "https://write-service.run.app"
        deadline: 30.0

3. JWT Authentication (x-google-issuer)

GCP API Gateway validiert JWT Tokens automatisch:

securityDefinitions:
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    x-google-audiences: "https://my-project.example.com"

security:
  - google_jwt: []

JWT Token Format:

# Google Sign-In Token
curl "https://GATEWAY_URL/api/users" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

4. Service Account Backend Auth

Für Cloud Run / Cloud Functions Backends:

x-google-backend:
  address: "https://my-service-abc123-uc.a.run.app"
  jwt_audience: "https://my-service-abc123-uc.a.run.app"

API Gateway fügt automatisch Service Account JWT Token hinzu.

4. Traffic Splitting & Canary Deployments

Feature: Gewichtsbasierte Traffic-Verteilung für A/B Testing, Canary Deployments und Blue/Green Deployments.

Status: ⚠️ Eingeschränkt unterstützt (GCP API Gateway native Limitierungen)

GCP API Gateway unterstützt Traffic Splitting nicht nativ in der OpenAPI Spec. Workarounds:

Workaround 1: Cloud Load Balancer mit Traffic Splitting

GCP Cloud Load Balancer unterstützt gewichtsbasiertes Traffic Splitting vor API Gateway:

Architektur:

Client
  ↓
Cloud Load Balancer (Traffic Split)
  ├─ 90% → API Gateway 1 (Stable) → Cloud Run Revision 1
  └─ 10% → API Gateway 2 (Canary) → Cloud Run Revision 2

Terraform Config:

resource "google_compute_url_map" "api_urlmap" {
  name = "api-urlmap"

  default_url_redirect {
    path_redirect = "/api"
  }

  # Weighted Backend Services
  path_matcher {
    name            = "api-path-matcher"
    default_service = google_compute_backend_service.api_backends.id

    route_rules {
      priority = 1
      route_action {
        weighted_backend_services {
          backend_service = google_compute_backend_service.stable_backend.id
          weight          = 90  # 90% Stable
        }
        weighted_backend_services {
          backend_service = google_compute_backend_service.canary_backend.id
          weight          = 10  # 10% Canary
        }
      }
    }
  }
}

Deployment:

# 1. Create Load Balancer
gcloud compute url-maps create api-lb \
  --default-service=stable-backend

# 2. Add Canary Backend mit 10% Traffic
gcloud compute url-maps add-path-matcher api-lb \
  --path-matcher-name=api-matcher \
  --default-service=stable-backend \
  --backend-service-path-rules="/api/*=stable-backend:90,canary-backend:10"

Workaround 2: Cloud Run Traffic Splitting (Backend)

Nutze Cloud Run als Backend mit nativem Traffic Splitting:

Strategie: 1. Deploy neue Version als Cloud Run Revision 2. Konfiguriere Traffic Split zwischen Revisions 3. API Gateway routet zu Cloud Run (unverändert)

Cloud Run Traffic Split:

# 1. Deploy neue Revision (Canary)
gcloud run deploy api-service \
  --image gcr.io/project/api:canary \
  --no-traffic  # Kein Traffic initial

# 2. Traffic Split: 90% stable, 10% canary
gcloud run services update-traffic api-service \
  --to-revisions api-service-001=90,api-service-002=10

GAL Config (Backend Traffic Split):

services:
  - name: api_service
    type: rest
    upstream:
      host: api-service-abc123-uc.a.run.app  # Cloud Run URL
      port: 443
      # Traffic Split erfolgt auf Cloud Run Ebene

Workaround 3: Multiple API Gateway Configs

Deploye 2 API Gateway Configs mit unterschiedlichen Backends:

Architektur:

Client
  ↓
DNS Weighted Routing (90/10)
  ├─ 90% → api-gateway-stable.endpoints.project.cloud.goog
  └─ 10% → api-gateway-canary.endpoints.project.cloud.goog

Deployment:

# 1. Stable API Gateway
gcloud api-gateway apis create stable-api --project=PROJECT_ID

gcloud api-gateway api-configs create stable-config \
  --api=stable-api \
  --openapi-spec=stable-openapi.yaml \
  --backend-auth-service-account=sa@project.iam.gserviceaccount.com

gcloud api-gateway gateways create stable-gateway \
  --api=stable-api \
  --api-config=stable-config \
  --location=us-central1

# 2. Canary API Gateway
gcloud api-gateway apis create canary-api --project=PROJECT_ID

gcloud api-gateway api-configs create canary-config \
  --api=canary-api \
  --openapi-spec=canary-openapi.yaml \
  --backend-auth-service-account=sa@project.iam.gserviceaccount.com

gcloud api-gateway gateways create canary-gateway \
  --api=canary-api \
  --api-config=canary-config \
  --location=us-central1

# 3. Cloud DNS Weighted Routing
gcloud dns record-sets create api.example.com --type=A --ttl=300 \
  --rrdatas="STABLE_IP:90,CANARY_IP:10"

GCP API Gateway Traffic Splitting Features

Feature	GCP API Gateway	Workaround
Weight-based Splitting	❌ Native	✅ Cloud Load Balancer
Cloud Run Revisions	✅ Backend	Cloud Run Traffic Split (native)
Multiple Gateways	⚠️ Complex	DNS Weighted Routing
Header-based Routing	⚠️ Limited	OpenAPI x-google-backend per path
A/B Testing	❌ Native	Cloud Load Balancer + Cloud Run
Blue/Green	✅ Gateway Swap	Switch API Config (instant)

Best Practices für GCP API Gateway:

Empfohlene Strategie:

1. Cloud Run als Backend:
2. ✅ Nutze Cloud Run Traffic Splitting (native, einfach)
3. ✅ API Gateway bleibt unverändert
4. ✅ Gradual Rollout: 5% → 25% → 50% → 100%

5. ✅ Instant Rollback via gcloud run services update-traffic

6. Cloud Load Balancer (Enterprise):

7. ✅ Für komplexe Traffic Routing Szenarien
8. ✅ Gewichtsbasiertes Splitting auf Gateway-Ebene

9. ❌ Höhere Kosten (zusätzlicher Load Balancer)

10. Blue/Green via API Config:

11. ✅ Deploye neue API Config (Blue/Green)
12. ✅ Instant Switch via gcloud api-gateway gateways update
13. ✅ Rollback durch vorherige Config

Cloud Run Gradual Rollout Beispiel:

# Phase 1: 5% Canary
gcloud run services update-traffic api-service \
  --to-revisions stable=95,canary=5

# Phase 2: 25% Canary (nach Monitoring)
gcloud run services update-traffic api-service \
  --to-revisions stable=75,canary=25

# Phase 3: 50% Canary
gcloud run services update-traffic api-service \
  --to-revisions stable=50,canary=50

# Phase 4: 100% Canary (Full Migration)
gcloud run services update-traffic api-service \
  --to-revisions canary=100

# Rollback (instant)
gcloud run services update-traffic api-service \
  --to-revisions stable=100

GAL Limitation: ⚠️ GAL kann GCP API Gateway Traffic Splitting nicht automatisch generieren, da: - GCP API Gateway hat kein natives Traffic Splitting in OpenAPI 2.0 - Traffic Split muss über Cloud Run oder Cloud Load Balancer erfolgen - Multi-Gateway Setup ist komplex und kostspielig

Alternative: Für native Traffic Splitting Support nutze: - ✅ Envoy (weighted_clusters) - ✅ Nginx (split_clients) - ✅ Kong (upstream targets with weights) - ✅ HAProxy (server weights) - ✅ Traefik (weighted services) - ✅ APISIX (traffic-split plugin)

Siehe auch: - Traffic Splitting Guide - Vollständige Dokumentation - Cloud Run Traffic Splitting - Cloud Load Balancing

---

Beispiele

Vollständige Beispiele finden Sie in:

• examples/gcp-apigateway-example.yaml - 5 komplette Szenarien
• tests/test_gcp_apigateway.py - 9 Export-Tests
• tests/test_import_gcp_apigateway.py - 17 Import-Tests

Schnell-Referenz

Basis-Setup:

version: "1.0"
provider: gcp_apigateway
global_config:
  gcp_apigateway:
    project_id: "my-project"
    api_id: "my-api"
    backend_address: "https://backend.example.com"
services:
  - name: api
    type: rest
    protocol: http
    upstream:
      targets:
        - host: backend.example.com
          port: 443
    routes:
      - path_prefix: /api
        methods: [GET, POST]

Mit JWT:

global_config:
  gcp_apigateway:
    jwt_issuer: "https://accounts.google.com"
    jwt_jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    jwt_audiences: ["https://my-project.example.com"]

Mit CORS:

global_config:
  gcp_apigateway:
    cors_enabled: true
    cors_allow_origins: ["https://app.example.com"]

---

Request Mirroring

⚠️ Workaround: Cloud Functions

GCP API Gateway unterstützt Request Mirroring nicht nativ. GAL konfiguriert einen Cloud Functions Workaround.

GAL Config:

services:
  - name: user_api
    protocol: http
    upstream:
      targets:
        - host: backend.example.com
          port: 443
    routes:
      - path_prefix: /api/users
        mirroring:
          enabled: true
          mirroring_cloud_function_url: "https://us-central1-my-project.cloudfunctions.net/mirror-function"
          targets:
            - name: shadow-backend
              upstream:
                host: shadow.example.com
                port: 443
              sample_percentage: 50
              timeout: 5
              headers:
                X-Mirror: "true"
                X-Shadow-Version: "v2"

Cloud Functions Implementation (mirror-function):

// Cloud Functions HTTP Trigger
const https = require('https');

exports.mirrorRequest = (req, res) => {
  // Sample percentage check (50%)
  const sampleRate = parseInt(process.env.SAMPLE_PERCENTAGE || '50');

  if (Math.random() * 100 < sampleRate) {
    // Fire-and-forget mirror request
    const mirrorOptions = {
      hostname: process.env.SHADOW_HOST,
      port: 443,
      path: req.path,
      method: req.method,
      headers: {
        ...req.headers,
        'x-mirror': 'true',
        'x-shadow-version': 'v2'
      }
    };

    const mirrorReq = https.request(mirrorOptions, (mirrorRes) => {
      // Ignore response
      mirrorRes.on('data', () => {});
      mirrorRes.on('end', () => {});
    });

    mirrorReq.on('error', (error) => {
      console.error('Mirror failed:', error);
    });

    mirrorReq.end();
  }

  // Return success (mirroring is fire-and-forget)
  res.status(200).send('OK');
};

Deployment:

# 1. Cloud Functions deployen
gcloud functions deploy mirror-function \
  --runtime nodejs18 \
  --trigger-http \
  --allow-unauthenticated \
  --region us-central1 \
  --set-env-vars SAMPLE_PERCENTAGE=50,SHADOW_HOST=shadow.example.com \
  --entry-point mirrorRequest

# 2. Function URL abrufen
gcloud functions describe mirror-function \
  --region us-central1 \
  --format='value(httpsTrigger.url)'

# 3. API Gateway Config generieren
gal generate -c config.yaml -p gcp_apigateway -o openapi.yaml

# 4. API Gateway deployen
gcloud api-gateway apis create user-api \
  --project=my-project

gcloud api-gateway api-configs create user-api-config \
  --api=user-api \
  --openapi-spec=openapi.yaml \
  --project=my-project \
  --backend-auth-service-account=backend-sa@my-project.iam.gserviceaccount.com

gcloud api-gateway gateways create user-gateway \
  --api=user-api \
  --api-config=user-api-config \
  --location=us-central1 \
  --project=my-project

Hinweise: - ⚠️ Cloud Functions erforderlich: Kein natives Mirroring in GCP API Gateway - ⚠️ HTTP Trigger: Cloud Function muss HTTP-Trigger haben - ✅ Sample Percentage: Via Environment Variables konfigurierbar - ✅ Custom Headers: Im Cloud Function Code definierbar - ⚠️ Zusätzliche Latenz: Cloud Function Call → Mirror Request

Alternativen: - Cloud Run + Envoy Sidecar für natives Request Mirroring - Apigee (Google Cloud's Enterprise API Gateway) mit nativen Mirroring-Policies - Cloud Load Balancer mit Traffic Mirroring (Packet Mirroring)

Monitoring:

# Cloud Functions Logs
gcloud functions logs read mirror-function \
  --region us-central1 \
  --limit 50

# Cloud Functions Metrics
gcloud monitoring metrics-descriptors list \
  --filter="resource.type=cloud_function AND resource.labels.function_name=mirror-function"

Vollständige Dokumentation: Siehe Request Mirroring Guide

---