Настройка API Gateway (KrakenD) для веб-приложения

Настройка API Gateway (KrakenD) для веб-приложения

KrakenD — stateless API Gateway на Go с декларативной конфигурацией в одном JSON/YAML файле. Особенность: агрегация ответов нескольких backend-сервисов в один ответ клиенту (API composition). Один из самых быстрых API Gateway — до 70K+ RPS на одном ядре.

Ключевые концепции

Endpoint — URL, который видит клиент. Один endpoint может обращаться к нескольким backend-сервисам и объединять ответы.

Backend — внутренний сервис. Для одного endpoint может быть несколько backends.

Aggregation — KrakenD делает параллельные запросы ко всем backends и возвращает объединённый JSON.

Установка

docker run -p 8080:8080 \
  -v $PWD/krakend.json:/etc/krakend/krakend.json \
  devopsfaith/krakend:2.7 run -c /etc/krakend/krakend.json

Конфигурация krakend.json

{
  "$schema": "https://www.krakend.io/schema/v3.json",
  "version": 3,
  "name": "MyApp API Gateway",
  "timeout": "3000ms",
  "cache_ttl": "300s",
  "output_encoding": "json",
  "port": 8080,

  "endpoints": [
    {
      "endpoint": "/api/v1/user-profile",
      "method": "GET",
      "output_encoding": "json",
      "backend": [
        {
          "url_pattern": "/users/{JWT_CLAIMS.user_id}",
          "host": ["http://users-service:3000"],
          "mapping": { "data": "user" }
        },
        {
          "url_pattern": "/subscriptions/active?user_id={JWT_CLAIMS.user_id}",
          "host": ["http://billing-service:3001"],
          "mapping": { "plan": "subscription_plan" }
        },
        {
          "url_pattern": "/preferences/{JWT_CLAIMS.user_id}",
          "host": ["http://prefs-service:3002"],
          "mapping": { "settings": "preferences" }
        }
      ],
      "extra_config": {
        "auth/validator": {
          "alg": "RS256",
          "jwk_url": "http://auth-service:4000/.well-known/jwks.json",
          "cache": true,
          "cache_duration": 300
        }
      }
    }
  ]
}

Клиент делает один GET /api/v1/user-profile, KrakenD параллельно запрашивает три backend-сервиса и возвращает:

{
  "user": { "id": "123", "name": "Alice" },
  "subscription_plan": "pro",
  "preferences": { "theme": "dark" }
}

Фильтрация полей ответа

{
  "endpoint": "/api/v1/users/{id}",
  "backend": [
    {
      "url_pattern": "/users/{id}",
      "host": ["http://users-service:3000"],
      "allow": ["id", "email", "name", "created_at"],
      "deny": ["password_hash", "internal_notes", "admin_flags"]
    }
  ]
}

Rate Limiting

{
  "endpoint": "/api/v1/search",
  "backend": [{ "url_pattern": "/search", "host": ["http://search:3000"] }],
  "extra_config": {
    "qos/ratelimit/router": {
      "max_rate": 100,
      "client_max_rate": 10,
      "strategy": "ip",
      "capacity": 100,
      "client_capacity": 10
    }
  }
}

JWT валидация

{
  "extra_config": {
    "auth/validator": {
      "alg": "RS256",
      "jwk_url": "https://auth.company.com/.well-known/jwks.json",
      "cache": true,
      "cache_duration": 900,
      "roles": ["admin", "user"],
      "roles_key": "https://company.com/roles",
      "roles_key_is_nested": false,
      "propagate_claims": [
        ["sub", "X-User-ID"],
        ["https://company.com/tenant", "X-Tenant-ID"]
      ]
    }
  }
}

Трансформация запросов (Martian)

KrakenD использует Google Martian для трансформации:

{
  "backend": [
    {
      "url_pattern": "/internal/users",
      "host": ["http://users:3000"],
      "extra_config": {
        "modifier/martian": {
          "header.Modifier": {
            "scope": ["request"],
            "name": "X-Internal-Key",
            "value": "secret-internal-key"
          }
        }
      }
    }
  ]
}

Circuit Breaker

{
  "backend": [
    {
      "url_pattern": "/payments",
      "host": ["http://payments-service:3000"],
      "extra_config": {
        "qos/circuit-breaker": {
          "interval": 60,
          "timeout": 10,
          "max_errors": 5,
          "name": "payments-cb",
          "log_status_change": true
        }
      }
    }
  ]
}

Кэширование ответов

{
  "endpoint": "/api/v1/categories",
  "cache_ttl": "1h",
  "backend": [
    {
      "url_pattern": "/categories",
      "host": ["http://catalog-service:3000"],
      "extra_config": {
        "qos/http-cache": {}
      }
    }
  ]
}

Метрики Prometheus

{
  "extra_config": {
    "telemetry/metrics": {
      "collection_time": "60s",
      "proxy_disabled": false,
      "router_disabled": false,
      "backend_disabled": false,
      "endpoint_disabled": false,
      "listen_address": ":9091"
    },
    "telemetry/opentelemetry": {
      "service_name": "krakend-gateway",
      "exporters": {
        "prometheus": [{ "port": 9090, "disable_metrics": false }],
        "otlp": [{
          "name": "jaeger",
          "host": "jaeger",
          "port": 4317,
          "use_http": false
        }]
      }
    }
  }
}

Генератор конфигурации

KrakenD Designer — web-интерфейс для визуальной генерации конфигурации: krakend.io/docs/designer/.

Срок выполнения

Базовая настройка KrakenD с агрегацией нескольких сервисов, JWT и rate limiting — 2–3 рабочих дня. Сложная конфигурация с трансформациями и observability — 4–5 дней.