configure-api-gateway

Configure API Gateway

Deploy and configure an API gateway for centralized API traffic management and policy enforcement.

When to Use

• Multiple backend services need unified API endpoint with consistent policies
• Require centralized authentication/authorization for API access
• Need rate limiting and quota management across APIs
• Want to transform requests/responses without modifying backend services
• Implementing API versioning and deprecation strategies
• Need detailed API analytics and monitoring
• Require service discovery and load balancing for microservices

Inputs

• Required: Kubernetes cluster or Docker environment
• Required: Choice of API gateway (Kong or Traefik)
• Required: Backend service endpoints to proxy
• Optional: Authentication provider (OAuth2, OIDC, API keys)
• Optional: Rate limiting requirements (requests per minute/hour)
• Optional: Custom middleware or plugin configurations
• Optional: TLS certificates for HTTPS endpoints — the gateway terminates TLS for every route behind it, so provision via cert-manager and verify auto-renewal is actually running; an expiry takes down all routes at once, not one

Procedure

See Extended Examples for complete configuration files and templates.

Roll out incrementally in step order — do not enable all plugins/middleware in one sync; verify each step's Expected block before layering the next (routing → authentication → rate limiting → transformations → advanced features).

Step 1: Install API Gateway

Deploy the API gateway with database (Kong) or file-based config (Traefik).

For Kong with PostgreSQL:

# kong-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kong
  namespace: kong
spec:
  replicas: 2
  # ... (PostgreSQL, migrations, services - see EXAMPLES.md)

For Traefik:

# traefik-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
  name: traefik
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: traefik
  namespace: traefik
spec:
  replicas: 2
  # ... (RBAC, ConfigMap, services - see EXAMPLES.md)

See EXAMPLES.md for the complete deployment manifests

Deploy:

kubectl apply -f kong-deployment.yaml  # OR traefik-deployment.yaml
kubectl wait --for=condition=ready pod -l app=kong -n kong --timeout=300s
kubectl get svc -n kong kong-proxy  # Get load balancer IP

Expected: Gateway pods running with 2 replicas. Load balancer service has external IP assigned. Admin API accessible (Kong: port 8001, Traefik: dashboard port 8080). Health checks passing. CPU/memory requests and limits set on the gateway pods — a gateway that hits its CPU limit under load is throttled, and that surfaces as rising latency, not as errors or restarts.

On failure:

• Check pod logs: kubectl logs -n kong -l app=kong
• Verify database connection (Kong): kubectl logs -n kong kong-migrations-<hash>
• Check service account permissions (Traefik): kubectl get clusterrolebinding traefik -o yaml
• Ensure ports not already bound: kubectl get svc --all-namespaces | grep 8000

Step 2: Configure Backend Services and Routes

Define upstream services and create routes to expose APIs.

For Kong (using decK for declarative config):

# Install decK CLI
curl -sL https://github.com/Kong/deck/releases/download/v1.28.0/deck_1.28.0_linux_amd64.tar.gz | tar -xz
sudo mv deck /usr/local/bin/

# Create kong.yaml with services, routes, upstreams
# (see EXAMPLES.md for complete configuration)
deck sync --kong-addr http://localhost:8001 -s kong.yaml
curl -i http://localhost:8001/routes  # Verify routes

For Traefik (using IngressRoute CRD):

# traefik-routes.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: user-api-route
spec:
  entryPoints: [websecure]
  routes:
  - match: Host(`api.example.com`) && PathPrefix(`/api/users`)
    # ... (see EXAMPLES.md for full configuration)

Apply routes:

kubectl apply -f traefik-routes.yaml
curl -H "Host: api.example.com" https://GATEWAY_IP/api/users

See EXAMPLES.md for complete routing configurations

Expected: Routes correctly proxy traffic to backend services. Weighted routing distributes traffic according to configuration. Health checks monitor backend service health.

On failure:

• Verify backend services running: kubectl get svc -n default
• Check DNS resolution: kubectl run test --rm -it --image=busybox -- nslookup user-service.default.svc.cluster.local
• Review gateway logs: kubectl logs -n kong -l app=kong --tail=50
• Validate configuration: deck validate -s kong.yaml

Step 3: Implement Authentication and Authorization

Configure authentication plugins/middleware for API security.

For Kong (API Key and JWT authentication):

# kong-auth-config.yaml (excerpt)
consumers:
- username: mobile-app
  custom_id: app-001

keyauth_credentials:
- consumer: mobile-app
  key: mobile-secret-key-123

plugins:
- name: key-auth
  service: user-api
  # ... (see EXAMPLES.md for full configuration)

deck sync --kong-addr http://localhost:8001 -s kong-auth-config.yaml
curl -i -H "apikey: mobile-secret-key-123" http://GATEWAY_IP/api/users

For Traefik (BasicAuth and ForwardAuth middleware):

# traefik-auth-middleware.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: basic-auth-middleware
spec:
  basicAuth:
    secret: basic-auth
    removeHeader: true
# ... (see EXAMPLES.md for OAuth2, rate limiting)

kubectl apply -f traefik-auth-middleware.yaml
curl -u user1:password https://GATEWAY_IP/api/protected

See EXAMPLES.md for complete authentication configurations

Expected: Unauthenticated requests return 401. Valid credentials allow access. Rate limiting returns 429 after threshold. JWT tokens validate correctly. ACL enforces group permissions.

On failure:

• Verify consumer creation: curl http://localhost:8001/consumers
• Check plugin enabled: curl http://localhost:8001/plugins | jq .
• Test with verbose: curl -v to see response headers
• Validate JWT: use jwt.io to decode token

Step 4: Configure Request/Response Transformation

Add middleware to transform requests and responses.

For Kong:

# kong-transformations.yaml (excerpt)
plugins:
- name: request-transformer
  service: user-api
  config:
    add:
      headers: [X-Gateway-Version:1.0, X-Request-ID:$(uuid)]
    remove:
      headers: [X-Internal-Token]
- name: correlation-id
  # ... (see EXAMPLES.md for full configuration)

deck sync --kong-addr http://localhost:8001 -s kong-transformations.yaml

For Traefik:

# traefik-transformations.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: add-headers
spec:
  headers:
    customRequestHeaders:
      X-Gateway-Version: "1.0"
    # ... (see EXAMPLES.md for circuit breaker, retry, chain)

kubectl apply -f traefik-transformations.yaml
curl -v https://GATEWAY_IP/api/users | grep X-Gateway

See EXAMPLES.md for complete transformation configurations

Expected: Request headers added/removed as configured. Response headers include gateway metadata. Large requests rejected with 413. Circuit breaker trips on repeated failures. Retries occur for transient errors.

On failure:

• Verify middleware order in chain
• Check for header conflicts with backend services
• Test transformations individually before chaining
• Review logs for transformation errors

Step 5: Enable Monitoring and Analytics

Configure metrics, logging, and dashboards for API visibility.

Kong monitoring setup:

# kong-monitoring.yaml (excerpt)
plugins:
- name: prometheus
  config:
    per_consumer: true
- name: http-log
  service: user-api
  # ... (see EXAMPLES.md for Datadog, file-log configuration)

deck sync --kong-addr http://localhost:8001 -s kong-monitoring.yaml

# Deploy ServiceMonitor (see EXAMPLES.md)
kubectl apply -f kong-servicemonitor.yaml
curl http://localhost:8100/metrics

Traefik monitoring (built-in):

# ServiceMonitor (excerpt - see EXAMPLES.md for Grafana dashboard)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: traefik-metrics
spec:
  endpoints:
  - port: metrics
    path: /metrics
    interval: 30s

kubectl port-forward -n traefik svc/traefik-dashboard 8080:8080
# Open http://localhost:8080/dashboard/

See EXAMPLES.md for complete monitoring configurations

Expected: Prometheus scraping gateway metrics successfully. Dashboards show request rates, latency percentiles, error rates. Logs forwarding to aggregation system. Metrics segmented by service, route, and consumer.

On failure:

• Verify ServiceMonitor: kubectl get servicemonitor -A
• Check Prometheus targets in UI
• Ensure metrics port accessible: kubectl port-forward -n kong svc/kong-metrics 8100:8100
• Validate log endpoint reachability

Step 6: Implement API Versioning and Deprecation

Configure version management and graceful API deprecation.

Kong versioning strategy:

# kong-versioning.yaml (excerpt)
services:
- name: user-api-v1
  url: http://user-service-v1.default.svc.cluster.local:8080
  routes:
  - name: user-v1-route
    paths: [/api/v1/users]
  plugins:
  - name: response-transformer
    config:
      add:
        headers:
        - X-Deprecation-Notice:"API v1 deprecated on 2024-12-3

---

*Content truncated.*