[Docker] Kong API Gateway 구성

작성자:


API Gateway는 마이크로서비스 아키텍처에서 필수적인 컴포넌트입니다. 오늘은 오픈소스 API Gateway인 Kong을 Docker 환경에서 설정하고 활용하는 방법을 알아보겠습니다.

Kong이란?

Kong은 오픈소스 API Gateway로, 마이크로서비스 앞단에 위치하여 모든 API 트래픽을 관리합니다. Nginx를 기반으로 구축되었으며, 플러그인 아키텍처를 통해 인증, Rate Limiting, 로깅 등 다양한 기능을 제공합니다.

Kong의 주요 기능

  • 트래픽 제어: Rate Limiting, Request/Response 변환
  • 인증/인가: API Key, JWT, OAuth 2.0, LDAP 등
  • 보안: IP 제한, Bot Detection, CORS
  • 모니터링: 로깅, 메트릭 수집, 분석
  • 서비스 메시: 서비스 디스커버리, 로드 밸런싱

Kong의 아키텍처 이해하기

Kong은 두 가지 주요 포트로 구성됩니다:

1. Proxy Port (기본 8000)

실제 API 트래픽이 흐르는 포트입니다. 클라이언트는 이 포트로 API를 호출하고, Kong이 백엔드 서비스로 요청을 프록시합니다.

Client → Kong:8000 → Backend Service

2. Admin API Port (기본 8001)

Kong을 관리하고 설정하는 REST API 포트입니다. 서비스, 라우트, 플러그인 등을 등록하고 관리합니다.

관리자 → Kong:8001 → Kong 설정 변경

Docker Compose로 Kong 구성하기

Kong을 운영하려면 설정 정보를 저장할 데이터베이스가 필요합니다. PostgreSQL을 사용하는 기본 구성을 살펴보겠습니다.

version: '3.8'

services:
  # Kong 전용 PostgreSQL
  kong-database:
    image: postgres:15-alpine
    container_name: kong-database
    environment:
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: kong
      POSTGRES_DB: kong
    volumes:
      - kong_data:/var/lib/postgresql/data
    networks:
      - kong-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kong"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Kong 데이터베이스 마이그레이션
  kong-migration:
    image: kong:3.5
    container_name: kong-migration
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong
      KONG_PG_DATABASE: kong
    networks:
      - kong-network
    depends_on:
      kong-database:
        condition: service_healthy
    restart: on-failure

  # Kong API Gateway
  kong:
    image: kong:3.5
    container_name: kong
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong
      KONG_PG_DATABASE: kong
      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_PROXY_LISTEN: 0.0.0.0:8000
    ports:
      - "8000:8000"  # Proxy
      - "8001:8001"  # Admin API
    networks:
      - kong-network
    depends_on:
      kong-database:
        condition: service_healthy
      kong-migration:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  kong-network:
    driver: bridge

volumes:
  kong_data:

구성 설명

  1. kong-database: Kong의 설정을 저장하는 PostgreSQL 데이터베이스
  2. kong-migration: 초기 데이터베이스 스키마 생성
  3. kong: 실제 API Gateway 서비스

Konga: Kong 관리 웹 UI

Kong Admin API는 강력하지만, CLI로만 관리하기엔 불편할 수 있습니다. Konga는 Kong을 시각적으로 관리할 수 있는 오픈소스 웹 대시보드입니다.

Konga의 주요 기능

  • 직관적인 대시보드: Kong의 전체 상태를 한눈에 확인
  • Service & Route 관리: 클릭 몇 번으로 서비스 등록
  • 플러그인 관리: 드롭다운으로 플러그인 추가/설정
  • Consumer 관리: API 사용자 관리 및 인증 정보 발급
  • Health Check: 서비스 상태 모니터링
  • 스냅샷 기능: 설정 백업 및 복원

Konga가 포함된 Docker Compose

version: '3.8'

services:
  # Kong 전용 PostgreSQL
  kong-database:
    image: postgres:15-alpine
    container_name: kong-database
    environment:
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: kong
      POSTGRES_DB: kong
    volumes:
      - kong_data:/var/lib/postgresql/data
    networks:
      - kong-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kong"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Konga 전용 PostgreSQL
  konga-database:
    image: postgres:15-alpine
    container_name: konga-database
    environment:
      POSTGRES_USER: konga
      POSTGRES_PASSWORD: konga
      POSTGRES_DB: konga
    volumes:
      - konga_data:/var/lib/postgresql/data
    networks:
      - kong-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U konga"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Kong 데이터베이스 마이그레이션
  kong-migration:
    image: kong:3.5
    container_name: kong-migration
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong
      KONG_PG_DATABASE: kong
    networks:
      - kong-network
    depends_on:
      kong-database:
        condition: service_healthy
    restart: on-failure

  # Kong API Gateway
  kong:
    image: kong:3.5
    container_name: kong
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong
      KONG_PG_DATABASE: kong
      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_PROXY_LISTEN: 0.0.0.0:8000
    ports:
      - "8000:8000"  # Proxy
      - "8001:8001"  # Admin API
    networks:
      - kong-network
    depends_on:
      kong-database:
        condition: service_healthy
      kong-migration:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Konga 데이터베이스 준비
  konga-prepare:
    image: pantsel/konga:latest
    container_name: konga-prepare
    command: "-c prepare -a postgres -u postgresql://konga:konga@konga-database:5432/konga"
    networks:
      - kong-network
    depends_on:
      konga-database:
        condition: service_healthy
    restart: on-failure

  # Konga 웹 UI
  konga:
    image: pantsel/konga:latest
    container_name: konga
    environment:
      DB_ADAPTER: postgres
      DB_HOST: konga-database
      DB_PORT: 5432
      DB_USER: konga
      DB_PASSWORD: konga
      DB_DATABASE: konga
      NODE_ENV: production
    ports:
      - "1337:1337"
    networks:
      - kong-network
    depends_on:
      konga-database:
        condition: service_healthy
      konga-prepare:
        condition: service_completed_successfully
    restart: unless-stopped

networks:
  kong-network:
    driver: bridge

volumes:
  kong_data:
  konga_data:

Konga 시작하기

1. 서비스 실행

docker-compose up -d

2. Konga 접속

브라우저에서 http://localhost:1337로 접속합니다.

3. 초기 설정

처음 접속하면 관리자 계정을 생성해야 합니다:

  • Username: admin (원하는 아이디)
  • Email: admin@example.com
  • Password: 안전한 비밀번호 설정

4. Kong 연결 설정

로그인 후 Connection 추가:

  • Name: Local Kong
  • Kong Admin URL: http://kong:8001
  • Create Connection 클릭

이제 Konga 대시보드에서 Kong을 관리할 수 있습니다!

Konga 주요 기능 사용하기

1. Service 추가하기

Admin API 방식:

curl -i -X POST http://localhost:8001/services/ \
  --data "name=my-api" \
  --data "url=http://backend-api:8080"

Konga UI 방식:

  1. 좌측 메뉴에서 Services 클릭
  2. + ADD NEW SERVICE 버튼 클릭
  3. 폼 작성:
    • Name: my-api
    • Protocol: http
    • Host: backend-api
    • Port: 8080
    • Path: (선택사항)
  4. SUBMIT SERVICE 클릭

훨씬 직관적이고 쉽습니다!

2. Route 추가하기

Service 상세 페이지에서:

  1. Routes 탭 클릭
  2. + ADD ROUTE 클릭
  3. 설정:
    • Name: api-route
    • Paths: /api
    • Strip Path: 체크 여부 선택
  4. SUBMIT ROUTE 클릭

3. Plugin 추가하기

Service 또는 Route 페이지에서:

  1. Plugins 탭 클릭
  2. + ADD PLUGIN 클릭
  3. 원하는 플러그인 선택 (Rate Limiting, Key Auth 등)
  4. 설정값 입력
  5. ADD PLUGIN 클릭

모든 플러그인 옵션이 폼으로 제공되어 설정이 매우 쉽습니다.

4. Consumer 관리

  1. 좌측 메뉴에서 Consumers 클릭
  2. + CREATE CONSUMER 클릭
  3. Username 입력
  4. Consumer 생성 후 Credentials 탭에서:
    • API KEYS 클릭하여 Key Auth 추가
    • JWT 클릭하여 JWT 설정
    • BASIC AUTH 클릭하여 Basic Auth 추가

5. 대시보드 모니터링

Dashboard에서 확인 가능한 정보:

  • 전체 Services 수
  • 전체 Routes 수
  • 활성화된 Plugins 수
  • Consumers 수
  • Kong 노드 상태
  • 최근 활동 로그

6. Snapshots (백업/복원)

Kong 설정을 백업하고 복원할 수 있습니다:

백업 생성:

  1. Snapshots 메뉴 클릭
  2. TAKE SNAPSHOT 클릭
  3. 스냅샷 이름 입력
  4. TAKE SNAPSHOT 클릭

복원:

  1. Snapshots 목록에서 원하는 스냅샷 선택
  2. RESTORE 클릭

이 기능은 설정을 테스트하거나 다른 환경으로 마이그레이션할 때 매우 유용합니다.

Konga vs Admin API: 언제 무엇을 사용할까?

Konga UI가 좋은 경우:

  • 처음 Kong을 배우는 단계
  • 빠른 프로토타이핑
  • 설정 확인 및 디버깅
  • 팀원들과 협업할 때
  • 복잡한 플러그인 설정

Admin API가 좋은 경우:

  • 자동화 및 CI/CD 파이프라인
  • 스크립트로 대량 설정
  • Infrastructure as Code (IaC)
  • 프로그래매틱한 관리
  • 프로덕션 배포

실제로는 두 가지를 혼용하는 것이 가장 효율적입니다. 개발 단계에서는 Konga로 빠르게 테스트하고, 프로덕션 배포는 Admin API로 자동화하는 방식이 일반적입니다.

Konga 보안 설정

프로덕션 환경에서 Konga를 사용할 때는 다음 사항을 고려해야 합니다:

1. HTTPS 설정

Konga 앞단에 Nginx를 두고 HTTPS를 설정합니다.

2. 접근 제한

VPN이나 특정 IP에서만 접근하도록 제한:

konga:
  ports:
    - "127.0.0.1:1337:1337"  # localhost에서만 접근

3. 강력한 비밀번호

관리자 계정에 강력한 비밀번호를 사용합니다.

4. 정기적인 업데이트

Konga를 최신 버전으로 유지합니다.

Konga 문제 해결

Konga가 Kong에 연결되지 않을 때:

  1. Kong이 정상 실행 중인지 확인:
curl http://localhost:8001/status
  1. Docker 네트워크에서 연결 테스트:
docker exec konga curl http://kong:8001/status
  1. Connection 설정이 올바른지 확인:
    • URL은 http://kong:8001 (Docker 내부 네트워크)
    • http://localhost:8001이 아님!

Konga 데이터베이스 에러:

# Konga 로그 확인
docker logs konga

# 데이터베이스 재준비
docker-compose restart konga-prepare
docker-compose restart konga

Kong 시작하기

1. 서비스 실행

docker-compose up -d

2. Kong 상태 확인

curl http://localhost:8001/status

정상적으로 실행되면 다음과 같은 응답을 받습니다:

{
  "database": {
    "reachable": true
  },
  "server": {
    "connections_accepted": 1,
    "connections_active": 1,
    "connections_handled": 1,
    "connections_reading": 0,
    "connections_waiting": 0,
    "connections_writing": 1,
    "total_requests": 1
  }
}

Kong에 서비스 등록하기

Kong을 통해 백엔드 API를 노출하려면 Service와 Route를 등록해야 합니다.

1. Service 등록

Service는 백엔드 API의 위치를 정의합니다.

curl -i -X POST http://localhost:8001/services/ \
  --data "name=my-api" \
  --data "url=http://backend-api:8080"

응답:

{
  "id": "4e3ad2e4-0bc4-4638-8e34-c84a417ba39b",
  "name": "my-api",
  "protocol": "http",
  "host": "backend-api",
  "port": 8080,
  "path": null,
  "retries": 5,
  "connect_timeout": 60000,
  "write_timeout": 60000,
  "read_timeout": 60000
}

2. Route 등록

Route는 클라이언트 요청을 Service로 매핑하는 규칙입니다.

curl -i -X POST http://localhost:8001/services/my-api/routes \
  --data "paths[]=/api" \
  --data "strip_path=true"

옵션 설명:

  • paths[]=/api: /api로 시작하는 요청을 처리
  • strip_path=true: 백엔드로 전달 시 /api 제거

이제 클라이언트는 다음과 같이 API를 호출할 수 있습니다:

# Kong을 통한 호출
curl http://localhost:8000/api/users

# 실제로는 다음으로 프록시됨
# http://backend-api:8080/users

Kong 플러그인 활용하기

Kong의 진정한 힘은 플러그인에 있습니다. 코드 수정 없이 다양한 기능을 추가할 수 있습니다.

1. Rate Limiting (속도 제한)

특정 시간 동안 허용되는 요청 수를 제한합니다.

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=100" \
  --data "config.hour=1000" \
  --data "config.policy=local"

이제 API는 분당 100회, 시간당 1000회로 제한됩니다. 초과 시 429 Too Many Requests 응답을 받습니다.

2. API Key Authentication (API 키 인증)

API Key를 통한 인증을 추가합니다.

Step 1: 플러그인 활성화

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=key-auth"

Step 2: Consumer 생성

Consumer는 API를 사용하는 클라이언트를 나타냅니다.

curl -X POST http://localhost:8001/consumers \
  --data "username=mobile-app"

Step 3: API Key 발급

curl -X POST http://localhost:8001/consumers/mobile-app/key-auth \
  --data "key=my-secret-api-key-12345"

Step 4: API Key로 요청

# 인증 없이 요청 (실패)
curl http://localhost:8000/api/users
# 응답: {"message":"No API key found in request"}

# API Key와 함께 요청 (성공)
curl http://localhost:8000/api/users \
  -H "apikey: my-secret-api-key-12345"

3. CORS 설정

Cross-Origin 요청을 허용합니다.

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=cors" \
  --data "config.origins=*" \
  --data "config.methods=GET,POST,PUT,DELETE,PATCH,OPTIONS" \
  --data "config.headers=Accept,Content-Type,Authorization" \
  --data "config.exposed_headers=X-Auth-Token" \
  --data "config.credentials=true" \
  --data "config.max_age=3600"

4. Request/Response 변환

요청이나 응답에 헤더를 추가/제거할 수 있습니다.

요청 헤더 추가:

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=request-transformer" \
  --data "config.add.headers=X-Service-Name:my-api" \
  --data "config.add.headers=X-Kong-Version:3.5"

응답 헤더 추가:

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=response-transformer" \
  --data "config.add.headers=X-Powered-By:Kong Gateway"

5. IP 제한

특정 IP만 접근을 허용하거나 차단합니다.

화이트리스트:

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=ip-restriction" \
  --data "config.allow=192.168.1.0/24" \
  --data "config.allow=10.0.0.0/8"

블랙리스트:

curl -X POST http://localhost:8001/services/my-api/plugins \
  --data "name=ip-restriction" \
  --data "config.deny=203.0.113.0/24"

Kong의 로드 밸런싱

Kong은 여러 백엔드 서버로 트래픽을 분산할 수 있습니다.

1. Upstream 생성

curl -X POST http://localhost:8001/upstreams \
  --data "name=my-api-upstream" \
  --data "algorithm=round-robin"

알고리즘 옵션:

  • round-robin: 순차적으로 분산
  • least-connections: 연결이 적은 서버 우선
  • consistent-hashing: 일관된 해싱 기반

2. Target 추가

# 첫 번째 백엔드 서버
curl -X POST http://localhost:8001/upstreams/my-api-upstream/targets \
  --data "target=backend-1:8080" \
  --data "weight=100"

# 두 번째 백엔드 서버
curl -X POST http://localhost:8001/upstreams/my-api-upstream/targets \
  --data "target=backend-2:8080" \
  --data "weight=100"

# 세 번째 백엔드 서버 (가중치 낮음)
curl -X POST http://localhost:8001/upstreams/my-api-upstream/targets \
  --data "target=backend-3:8080" \
  --data "weight=50"

3. Service에 Upstream 연결

curl -X PATCH http://localhost:8001/services/my-api \
  --data "host=my-api-upstream"

이제 요청이 세 서버로 분산됩니다. 가중치에 따라 backend-1과 backend-2는 더 많은 트래픽을 받습니다.

Kong Admin API 주요 엔드포인트

Kong은 완전한 REST API를 통해 관리됩니다.

Services

# 목록 조회
GET http://localhost:8001/services

# 특정 서비스 조회
GET http://localhost:8001/services/{service-id}

# 서비스 수정
PATCH http://localhost:8001/services/{service-id}

# 서비스 삭제
DELETE http://localhost:8001/services/{service-id}

Routes

# 목록 조회
GET http://localhost:8001/routes

# 특정 라우트 조회
GET http://localhost:8001/routes/{route-id}

# 라우트 수정
PATCH http://localhost:8001/routes/{route-id}

# 라우트 삭제
DELETE http://localhost:8001/routes/{route-id}

Plugins

# 활성화된 플러그인 목록
GET http://localhost:8001/plugins

# 특정 플러그인 조회
GET http://localhost:8001/plugins/{plugin-id}

# 플러그인 수정
PATCH http://localhost:8001/plugins/{plugin-id}

# 플러그인 비활성화
DELETE http://localhost:8001/plugins/{plugin-id}

Consumers

# Consumer 목록
GET http://localhost:8001/consumers

# 특정 Consumer 조회
GET http://localhost:8001/consumers/{consumer-id}

# Consumer의 인증 정보
GET http://localhost:8001/consumers/{consumer-id}/key-auth
GET http://localhost:8001/consumers/{consumer-id}/jwt

실전 시나리오: 마이크로서비스 API Gateway

실제 프로젝트에서 Kong을 활용하는 시나리오를 살펴보겠습니다.

요구사항

  • 사용자 서비스 (User Service)
  • 주문 서비스 (Order Service)
  • 결제 서비스 (Payment Service)
  • 모든 API는 인증 필요
  • Rate Limiting 적용
  • 결제 API는 추가 보안 (IP 제한)

구성

1. 각 서비스 등록:

# User Service
curl -X POST http://localhost:8001/services/ \
  --data "name=user-service" \
  --data "url=http://user-api:8080"

curl -X POST http://localhost:8001/services/user-service/routes \
  --data "paths[]=/users" \
  --data "strip_path=false"

# Order Service
curl -X POST http://localhost:8001/services/ \
  --data "name=order-service" \
  --data "url=http://order-api:8080"

curl -X POST http://localhost:8001/services/order-service/routes \
  --data "paths[]=/orders" \
  --data "strip_path=false"

# Payment Service
curl -X POST http://localhost:8001/services/ \
  --data "name=payment-service" \
  --data "url=http://payment-api:8080"

curl -X POST http://localhost:8001/services/payment-service/routes \
  --data "paths[]=/payments" \
  --data "strip_path=false"

2. 전역 플러그인 (모든 서비스에 적용):

# JWT 인증 (전역)
curl -X POST http://localhost:8001/plugins \
  --data "name=jwt"

# Rate Limiting (전역)
curl -X POST http://localhost:8001/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=1000" \
  --data "config.hour=10000"

# CORS (전역)
curl -X POST http://localhost:8001/plugins \
  --data "name=cors" \
  --data "config.origins=*"

3. 서비스별 추가 플러그인:

# Payment Service에 IP 제한 추가
curl -X POST http://localhost:8001/services/payment-service/plugins \
  --data "name=ip-restriction" \
  --data "config.allow=10.0.0.0/8"

# Payment Service Rate Limiting 강화
curl -X POST http://localhost:8001/services/payment-service/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=100" \
  --data "config.hour=1000"

4. Consumer 생성 및 JWT 발급:

# Mobile App Consumer
curl -X POST http://localhost:8001/consumers \
  --data "username=mobile-app"

curl -X POST http://localhost:8001/consumers/mobile-app/jwt \
  --data "algorithm=HS256" \
  --data "secret=my-jwt-secret"

# Web App Consumer
curl -X POST http://localhost:8001/consumers \
  --data "username=web-app"

curl -X POST http://localhost:8001/consumers/web-app/jwt \
  --data "algorithm=HS256" \
  --data "secret=another-jwt-secret"

이제 클라이언트는 다음과 같이 API를 사용합니다:

# JWT 토큰으로 인증
curl http://localhost:8000/users/profile \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

curl http://localhost:8000/orders \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

curl http://localhost:8000/payments \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

모니터링과 로깅

Kong은 다양한 방식으로 모니터링과 로깅을 지원합니다.

1. File Log 플러그인

curl -X POST http://localhost:8001/plugins \
  --data "name=file-log" \
  --data "config.path=/tmp/kong.log"

2. HTTP Log 플러그인

외부 로깅 서비스로 로그를 전송합니다.

curl -X POST http://localhost:8001/plugins \
  --data "name=http-log" \
  --data "config.http_endpoint=https://logs.example.com/kong"

3. Prometheus 플러그인

메트릭을 Prometheus 형식으로 노출합니다.

curl -X POST http://localhost:8001/plugins \
  --data "name=prometheus"

# 메트릭 확인
curl http://localhost:8001/metrics

Kong의 DB-less 모드

Kong은 데이터베이스 없이도 실행할 수 있습니다. 설정을 YAML 파일로 관리합니다.

kong.yml 예제

_format_version: "3.0"

services:
  - name: my-api
    url: http://backend:8080
    routes:
      - name: api-route
        paths:
          - /api
    plugins:
      - name: rate-limiting
        config:
          minute: 100
      - name: key-auth

consumers:
  - username: mobile-app
    keyauth_credentials:
      - key: my-api-key-12345

Docker Compose에서 DB-less 모드 사용

kong:
  image: kong:3.5
  environment:
    KONG_DATABASE: "off"
    KONG_DECLARATIVE_CONFIG: /kong/declarative/kong.yml
  volumes:
    - ./kong.yml:/kong/declarative/kong.yml
  ports:
    - "8000:8000"

DB-less 모드는 설정이 자주 변경되지 않는 환경에 적합합니다.

보안 Best Practices

프로덕션 환경에서 Kong을 안전하게 운영하기 위한 권장사항입니다.

1. Admin API 보호

Admin API는 외부에 노출하지 않아야 합니다.

kong:
  environment:
    KONG_ADMIN_LISTEN: 127.0.0.1:8001  # localhost만 허용

또는 역방향 프록시나 VPN을 통해서만 접근하도록 설정합니다.

2. HTTPS 설정

프로덕션에서는 반드시 HTTPS를 사용해야 합니다.

curl -X POST http://localhost:8001/certificates \
  --form "cert=@/path/to/cert.pem" \
  --form "key=@/path/to/key.pem" \
  --form "snis[]=api.example.com"

3. 민감 정보 관리

데이터베이스 비밀번호, API Key 등은 환경변수나 Secrets 관리 도구를 사용합니다.

environment:
  KONG_PG_PASSWORD: ${DB_PASSWORD}  # 환경변수 사용

4. Rate Limiting 설정

DDoS 공격을 방지하기 위해 적절한 Rate Limiting을 설정합니다.

5. 정기적인 업데이트

Kong과 플러그인을 최신 버전으로 유지합니다.

문제 해결

Kong이 시작되지 않을 때

로그 확인:

docker logs kong

일반적인 원인:

  • 데이터베이스 연결 실패
  • 마이그레이션 미완료
  • 포트 충돌

502 Bad Gateway 에러

백엔드 서비스에 연결할 수 없을 때 발생합니다.

확인사항:

  • 백엔드 서비스가 실행 중인지
  • Service의 host와 port가 올바른지
  • 네트워크 설정이 올바른지
# Service 정보 확인
curl http://localhost:8001/services/my-api

# 백엔드 서비스 Health Check
curl http://backend-api:8080/health

플러그인이 작동하지 않을 때

# 플러그인 활성화 상태 확인
curl http://localhost:8001/plugins

# 특정 플러그인 상세 정보
curl http://localhost:8001/plugins/{plugin-id}

마치며

Kong API Gateway는 마이크로서비스 아키텍처에서 강력한 중앙 집중식 관리 도구입니다. 인증, Rate Limiting, 로드 밸런싱 등의 공통 기능을 Kong에서 처리함으로써 백엔드 서비스는 비즈니스 로직에만 집중할 수 있습니다.

특히 Konga를 함께 사용하면 Kong의 강력한 기능을 더욱 쉽고 직관적으로 활용할 수 있습니다. 개발 초기에는 Konga UI로 빠르게 프로토타이핑하고, 익숙해지면 Admin API로 자동화하는 방식을 권장합니다.

이 가이드에서 다룬 내용을 바탕으로 여러분의 프로젝트에 Kong을 적용해보세요. 처음에는 기본적인 프록시 기능부터 시작하여, 점진적으로 플러그인을 추가하면서 시스템을 발전시켜 나가는 것을 권장합니다.



댓글 남기기