API Gateway 패턴 완벽 가이드: Rate Limiting, 인증/인가, BFF 아키텍처 설계

# Kong - Rate Limiting 플러그인 설정 (Token Bucket 기반)
# kong.yml - Declarative Configuration
_format_version: '3.0'

services:
  - name: user-service
    url: http://user-service:8080
    routes:
      - name: user-route
        paths:
          - /api/v1/users
    plugins:
      - name: rate-limiting
        config:
          # 분당 100회, 시간당 1000회 제한
          minute: 100
          hour: 1000
          # 정책: local(단일 노드), cluster(클러스터 전체), redis(Redis 기반)
          policy: redis
          redis:
            host: redis-cluster
            port: 6379
            password: null
            database: 0
            timeout: 2000
          # Rate Limit 헤더 반환
          header_name: null
          hide_client_headers: false
          # 제한 기준: consumer, credential, ip, header, path, service
          limit_by: consumer
          # Redis 장애 시 요청 허용 여부
          fault_tolerant: true

-- APISIX 커스텀 Rate Limiting 플러그인 (Sliding Window Counter)
-- apisix/plugins/sliding-window-rate-limit.lua

local core = require("apisix.core")
local ngx = ngx
local math = math

local schema = {
    type = "object",
    properties = {
        rate = { type = "integer", minimum = 1 },
        burst = { type = "integer", minimum = 0 },
        window_size = { type = "integer", minimum = 1, default = 60 },
        key_type = {
            type = "string",
            enum = { "remote_addr", "consumer_name", "header" },
            default = "remote_addr"
        },
    },
    required = { "rate" },
}

local _M = {
    version = 0.1,
    priority = 1001,
    name = "sliding-window-rate-limit",
    schema = schema,
}

function _M.access(conf, ctx)
    local key = ctx.var.remote_addr
    if conf.key_type == "consumer_name" then
        key = ctx.consumer_name or ctx.var.remote_addr
    end

    local now = ngx.now()
    local window = conf.window_size
    local current_window = math.floor(now / window) * window
    local previous_window = current_window - window
    local elapsed = now - current_window

    -- 이전 윈도우와 현재 윈도우의 가중 평균 계산
    local prev_count = get_count(key, previous_window) or 0
    local curr_count = get_count(key, current_window) or 0
    local weight = (window - elapsed) / window
    local estimated = prev_count * weight + curr_count

    if estimated >= conf.rate then
        return 429, {
            error = "Rate limit exceeded",
            retry_after = math.ceil(window - elapsed)
        }
    end

    increment_count(key, current_window)
end

return _M

# APISIX - JWT 인증 플러그인 설정
# apisix/conf/config.yaml
routes:
  - uri: /api/v1/orders/*
    upstream:
      type: roundrobin
      nodes:
        'order-service:8080': 1
    plugins:
      jwt-auth:
        # JWT 서명 검증을 위한 공개 키
        key: 'user-auth-key'
        # 토큰 위치 설정
        header: 'Authorization'
        # 토큰 전달 방식: bearer 스킴
        query: 'token'
        cookie: 'jwt_token'
      # 추가: 권한 기반 접근 제어
      consumer-restriction:
        type: consumer_group_id
        whitelist:
          - 'premium-users'
          - 'admin-group'
        rejected_code: 403
        rejected_msg: 'Access denied: insufficient permissions'

# Consumer 설정 (API 사용자 정의)
consumers:
  - username: 'mobile-app'
    plugins:
      jwt-auth:
        key: 'mobile-app-key'
        secret: 'mobile-app-secret-256bit-key-here'
        algorithm: 'HS256'
        exp: 86400 # 토큰 만료: 24시간
        # 커스텀 클레임 기반 라우팅
        base64_secret: false
  - username: 'web-frontend'
    plugins:
      jwt-auth:
        key: 'web-frontend-key'
        # RS256 사용 시 공개키 경로
        public_key: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
          -----END PUBLIC KEY-----
        algorithm: 'RS256'
        exp: 3600 # 토큰 만료: 1시간

# Kong - OpenID Connect 플러그인 설정
plugins:
  - name: openid-connect
    config:
      issuer: 'https://auth.example.com/realms/production'
      client_id: 'api-gateway'
      client_secret: 'gateway-secret-value'
      redirect_uri: 'https://api.example.com/callback'
      # 지원 인증 흐름
      auth_methods:
        - authorization_code # 웹 애플리케이션
        - client_credentials # 서비스 간 통신
        - password # 레거시 지원 (권장하지 않음)
      # 토큰 검증 설정
      token_endpoint_auth_method: client_secret_post
      # 스코프 기반 접근 제어
      scopes_required:
        - openid
        - profile
        - api:read
      # 토큰 캐싱 (성능 최적화)
      cache_ttl: 300
      # 토큰 인트로스펙션 (불투명 토큰 검증)
      introspection_endpoint: 'https://auth.example.com/realms/production/protocol/openid-connect/token/introspect'
      # 업스트림으로 전달할 헤더
      upstream_headers_claims:
        - sub
        - email
        - realm_access.roles
      upstream_headers_names:
        - X-User-ID
        - X-User-Email
        - X-User-Roles

# APISIX - BFF 라우팅 설정
# 클라이언트 유형별 전용 BFF로 라우팅
routes:
  # 웹 BFF - 풍부한 데이터, 상세 정보 포함
  - uri: /api/web/*
    name: web-bff-route
    plugins:
      proxy-rewrite:
        regex_uri:
          - '^/api/web/(.*)'
          - '/$1'
      request-id:
        header_name: X-Request-ID
      jwt-auth: {}
      rate-limiting:
        rate: 200
        burst: 50
        key_type: consumer_name
    upstream:
      type: roundrobin
      nodes:
        'web-bff:3000': 1
      timeout:
        connect: 3
        send: 10
        read: 30

  # 모바일 BFF - 경량 데이터, 페이지네이션 최적화
  - uri: /api/mobile/*
    name: mobile-bff-route
    plugins:
      proxy-rewrite:
        regex_uri:
          - '^/api/mobile/(.*)'
          - '/$1'
      jwt-auth: {}
      rate-limiting:
        rate: 100
        burst: 20
        key_type: consumer_name
      # 모바일 전용: 응답 크기 제한
      response-rewrite:
        headers:
          set:
            X-Content-Optimized: 'mobile'
    upstream:
      type: roundrobin
      nodes:
        'mobile-bff:3001': 1
      timeout:
        connect: 3
        send: 5
        read: 15

  # IoT BFF - 최소 데이터, 높은 빈도
  - uri: /api/iot/*
    name: iot-bff-route
    plugins:
      proxy-rewrite:
        regex_uri:
          - '^/api/iot/(.*)'
          - '/$1'
      key-auth: {} # IoT 디바이스는 API Key 인증
      rate-limiting:
        rate: 500
        burst: 100
        key_type: var
        key: remote_addr
    upstream:
      type: roundrobin
      nodes:
        'iot-bff:3002': 1
      timeout:
        connect: 2
        send: 3
        read: 5

클라이언트 계층          API Gateway          BFF 계층           마이크로서비스
+----------+                              +----------+
| 웹 앱    | ----+                   +--> | Web BFF  | --+--> User Service
+----------+     |    +-----------+  |    +----------+   +--> Product Service
                 +--> |           |--+                   +--> Order Service
+----------+     |    | API       |  |    +----------+
| 모바일 앱| ----+--> | Gateway   |--+--> |Mobile BFF| --+--> User Service
+----------+     |    |           |  |    +----------+   +--> Product Service
                 |    +-----------+  |
+----------+     |                   |    +----------+
| IoT 장치 | ----+                   +--> | IoT BFF  | --+--> Device Service
+----------+                              +----------+   +--> Telemetry Service

# APISIX - 다양한 로드밸런싱 전략
upstreams:
  # 가중 라운드 로빈
  - id: 1
    type: roundrobin
    nodes:
      'service-a-v1:8080': 8 # 80% 트래픽
      'service-a-v2:8080': 2 # 20% 트래픽 (카나리 배포)
    # 헬스체크 설정
    checks:
      active:
        type: http
        http_path: /health
        healthy:
          interval: 5
          successes: 2
        unhealthy:
          interval: 3
          http_failures: 3
          tcp_failures: 3
      passive:
        healthy:
          http_statuses:
            - 200
            - 201
          successes: 3
        unhealthy:
          http_statuses:
            - 500
            - 502
            - 503
          http_failures: 5
          tcp_failures: 2

  # 일관적 해시 (세션 어피니티)
  - id: 2
    type: chash
    key: remote_addr
    nodes:
      'session-service-1:8080': 1
      'session-service-2:8080': 1
      'session-service-3:8080': 1

  # 최소 연결
  - id: 3
    type: least_conn
    nodes:
      'compute-service-1:8080': 1
      'compute-service-2:8080': 1

# Kong - 서킷 브레이커 (Circuit Breaker) 구성
plugins:
  - name: ai-proxy # Kong의 업스트림 타임아웃과 결합
    # 서킷 브레이커 역할을 하는 설정
services:
  - name: payment-service
    url: http://payment-service:8080
    connect_timeout: 3000 # 연결 타임아웃: 3초
    write_timeout: 10000 # 쓰기 타임아웃: 10초
    read_timeout: 15000 # 읽기 타임아웃: 15초
    retries: 2 # 재시도 횟수
    plugins:
      # 서킷 브레이커 패턴 구현
      - name: request-termination
        enabled: false # 수동 서킷 브레이커 (장애 시 활성화)
        config:
          status_code: 503
          message: 'Service temporarily unavailable'

---
# APISIX - api-breaker 플러그인 (자동 서킷 브레이커)
routes:
  - uri: /api/v1/payments/*
    plugins:
      api-breaker:
        # 서킷 브레이커 트리거 상태 코드
        break_response_code: 503
        break_response_body: '{"error":"circuit open","retry_after":30}'
        break_response_headers:
          - key: Content-Type
            value: application/json
          - key: Retry-After
            value: '30'
        # unhealthy 판정: 연속 3회 500 에러 시 서킷 오픈
        unhealthy:
          http_statuses:
            - 500
            - 502
            - 503
          failures: 3
        # healthy 판정: 연속 2회 성공 시 서킷 클로즈
        healthy:
          http_statuses:
            - 200
            - 201
          successes: 2
        # 서킷 오픈 후 최대 대기 시간 (초)
        max_breaker_sec: 300
    upstream:
      type: roundrobin
      nodes:
        'payment-service:8080': 1

# docker-compose.kong.yml
version: '3.8'

services:
  kong-database:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: kong
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: kong_password
    volumes:
      - kong_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'kong']
      interval: 10s
      timeout: 5s
      retries: 5

  kong-migration:
    image: kong:3.6
    command: kong migrations bootstrap
    depends_on:
      kong-database:
        condition: service_healthy
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong_password

  kong:
    image: kong:3.6
    depends_on:
      kong-migration:
        condition: service_completed_successfully
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong_password
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
      KONG_ADMIN_LISTEN: '0.0.0.0:8001'
      KONG_STATUS_LISTEN: '0.0.0.0:8100'
      # 성능 튜닝
      KONG_NGINX_WORKER_PROCESSES: auto
      KONG_UPSTREAM_KEEPALIVE_POOL_SIZE: 128
      KONG_UPSTREAM_KEEPALIVE_MAX_REQUESTS: 1000
    ports:
      - '8000:8000' # 프록시 (HTTP)
      - '8443:8443' # 프록시 (HTTPS)
      - '8001:8001' # Admin API
    healthcheck:
      test: ['CMD', 'kong', 'health']
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  kong_pgdata:

# APISIX Kubernetes 배포 (Helm)
helm repo add apisix https://charts.apiseven.com
helm repo update

# APISIX 설치 (etcd 포함)
helm install apisix apisix/apisix \
  --namespace apisix \
  --create-namespace \
  --set gateway.type=LoadBalancer \
  --set ingress-controller.enabled=true \
  --set dashboard.enabled=true \
  --set etcd.replicaCount=3 \
  --set etcd.persistence.size=20Gi \
  --set apisix.nginx.workerProcesses=auto \
  --set apisix.nginx.workerConnections=65536

# APISIX 상태 확인
kubectl -n apisix get pods
kubectl -n apisix get svc

# Admin API를 통한 라우트 등록
curl -X PUT http://apisix-admin:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: admin-api-key" \
  -d '{
    "uri": "/api/v1/products/*",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "product-service.default.svc:8080": 1
      }
    },
    "plugins": {
      "jwt-auth": {},
      "limit-count": {
        "count": 200,
        "time_window": 60,
        "rejected_code": 429,
        "rejected_msg": "Rate limit exceeded. Please retry later.",
        "policy": "redis",
        "redis_host": "redis.default.svc",
        "redis_port": 6379,
        "key_type": "var",
        "key": "consumer_name"
      },
      "api-breaker": {
        "break_response_code": 503,
        "unhealthy": {
          "http_statuses": [500, 502, 503],
          "failures": 3
        },
        "healthy": {
          "http_statuses": [200],
          "successes": 2
        },
        "max_breaker_sec": 60
      }
    }
  }'

# APISIX - Prometheus 메트릭 수집 설정
plugin_attr:
  prometheus:
    export_uri: /apisix/prometheus/metrics
    export_addr:
      ip: '0.0.0.0'
      port: 9091
    # 커스텀 메트릭 레이블
    default_buckets:
      - 0.005
      - 0.01
      - 0.025
      - 0.05
      - 0.1
      - 0.25
      - 0.5
      - 1
      - 2.5
      - 5
      - 10

# 글로벌 플러그인으로 모든 라우트에 적용
global_rules:
  - id: 1
    plugins:
      prometheus:
        prefer_name: true
      # 분산 추적 (OpenTelemetry)
      opentelemetry:
        sampler:
          name: parent_based_traceidratio
          options:
            fraction: 0.1 # 10% 샘플링
        additional_attributes:
          - 'service.version'
        additional_header_prefix_attributes:
          - 'X-Custom-'

# Prometheus Alert Rules
groups:
  - name: api-gateway-alerts
    rules:
      - alert: HighErrorRate
        expr: |
          sum(rate(apisix_http_status{code=~"5.."}[5m]))
          / sum(rate(apisix_http_status[5m])) > 0.05
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: 'API Gateway 5xx 에러율 5% 초과'

      - alert: HighLatency
        expr: |
          histogram_quantile(0.99,
            sum(rate(apisix_http_latency_bucket[5m])) by (le, route)
          ) > 2000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: 'API Gateway P99 레이턴시 2초 초과'

      - alert: RateLimitExceeded
        expr: |
          sum(rate(apisix_http_status{code="429"}[5m])) > 100
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: 'Rate Limit 초과 요청 분당 100건 이상'