Kong Ingress Controller 설치하기

들어가며

MSA 구조로 프로젝트를 구성하면서, 단순한 리버스 프록시 역할의 Nginx Ingress만으로는 다양한 API 요청 흐름을 세밀하게 제어하거나, 인증과 로깅과 같은 기능을 처리하는 데 한계가 있었습니다. 그래서 Kong Ingress Controller를 도입하게 되었습니다.

Kong Ingress Controller란?

Kong Ingress Controller는 Kubernetes의 Ingress 리소스를 기반으로 Kong Gateway를 통해 API Gateway 기능을 제공합니다.

주요 특징

• API Gateway (Rate limiting, 인증, 로깅 등)
• Load Balancing
• PostgreSQL을 통한 상태 관리
• 다양한 플러그인으로 확장 가능

설치 스크립트

#!/bin/bash

# 사용 예: ./install-kong.sh develop 또는 ./install-kong.sh production

ENV=$1  # 환경 설정: develop 또는 production

# DEV 환경 설치
if [[ "$ENV" == "develop" ]]; then
  echo "🚧 Deploying Kong for DEV environment..."

  helm upgrade --install ingress-kong kong/kong \
    --namespace dev-gateway \                             # dev 환경 전용 네임스페이스
    --create-namespace \                                  # 없으면 자동 생성
    --set ingressController.enabled=true \                # Kong Ingress Controller 활성화
    --set ingressController.watchNamespace="" \           # 모든 네임스페이스 감시
    --set env.database=postgres \                         # DB 유형 설정 (PostgreSQL)
    --set postgresql.enabled=true \                       # 내부 DB(PostgreSQL) 포함 설치
    --set postgresql.auth.username=kong \                 # DB 사용자 이름
    --set postgresql.auth.password=kong \                 # DB 비밀번호
    --set postgresql.auth.database=kong \                 # DB 이름
    --set env.pg_user=kong \                              # Kong이 사용할 DB 사용자
    --set env.pg_password=kong \                          # Kong이 사용할 비밀번호
    --set env.pg_database=kong \                          # Kong이 연결할 DB 이름
    --set proxy.type=LoadBalancer                         # 외부 접근을 위한 LoadBalancer 타입 서비스

# PROD 환경 설치
elif [[ "$ENV" == "production" ]]; then
  echo "🚀 Deploying Kong for PROD environment..."

  helm upgrade --install ingress-kong kong/kong \
    --namespace prod-gateway \                            # prod 환경 전용 네임스페이스
    --create-namespace \
    --set ingressController.enabled=true \
    --set ingressController.watchNamespace="" \
    --set env.database=postgres \
    --set postgresql.enabled=false \                      # 외부 DB 사용, 내부 DB는 설치 안 함
    --set env.pg_host=your-external-postgres \        # 외부 PostgreSQL 주소
    --set env.pg_user=kong \
    --set env.pg_password=secure-password \
    --set env.pg_database=kong \
    --set proxy.type=LoadBalancer \

# 잘못된 인자 처리
else
  echo "❌ Usage: $0 [develop|production]"
  exit 1
fi

echo "✅ Kong deployment completed!"

데이터베이스 설정 및 마이그레이션

Kong은 설정 정보를 메모리에만 저장하는 방식이 아니라, PostgreSQL 같은 외부 데이터베이스에 저장하여 플러그인, 라우팅, 인증 설정 등 모든 구성을 영구적으로 관리합니다. 즉, 쿠버네티스 재시작이나 pod 교체가 발생해도 설정이 유지되며, 이를 위해 DB 연동이 필수입니다. (참고로 dbless 모드도 있지만, 기능에 제한이 있습니다.)

🥲 dbless 모드에서 운영 환경으로 전환 과정에서 기존 설정과 데이터베이스 연결 간 충돌로 인한 오류 발생으로 PostgreSQL 기반 아키텍처로 재구성 및 마이그레이션을 진행하였습니다

PostgreSQL 연결 설정

Kong이 사용할 데이터베이스 정보를 아래와 같은 환경변수로 설정합니다.

env:
  database: postgres
  pg_host: postgres-kong.dev-db.svc.cluster.local
  pg_port: 5432
  pg_user: kong
  pg_password: kong
  pg_database: kong

마이그레이션 실행

kubectl run kong-migrations \
  --image=kong:3.9 \
  --rm -i --tty \
  --restart=Never \
  --namespace=dev-gateway \
  --env="KONG_DATABASE=postgres" \
  --env="KONG_PG_HOST=postgres-kong.dev-db.svc.cluster.local" \
  --env="KONG_PG_USER=kong" \
  --env="KONG_PG_PASSWORD=kong" \
  --env="KONG_PG_DATABASE=kong" \
  -- kong migrations bootstrap

마이그레이션 결과

67 migrations processed
67 executed
Database is up-to-date

트러블슈팅

‼️ CrashLoopBackOff 문제

로그 예시

NAME                                 READY   STATUS             RESTARTS   AGE
ingress-kong-kong-7fb4c6c498-4rr9m   1/2     CrashLoopBackOff   7           77m

원인

데이터베이스 연결 실패 또는 마이그레이션 미완료

해결 방법

# 1. PostgreSQL 상태 확인
kubectl get pods -n dev-db | grep postgres

# 2. DNS 해결 테스트
kubectl run dns-test --rm -i --tty --image=busybox --restart=Never -- \
  nslookup postgres-kong.dev-db.svc.cluster.local

# 3. 마이그레이션 재실행
kubectl run kong-migrations-fix \
  --image=kong:3.9 \
  --rm -i --tty \
  --restart=Never \
  --namespace=dev-gateway \
  --env="KONG_DATABASE=postgres" \
  --env="KONG_PG_HOST=postgres-kong.dev-db.svc.cluster.local" \
  --env="KONG_PG_USER=kong" \
  --env="KONG_PG_PASSWORD=kong" \
  --env="KONG_PG_DATABASE=kong" \
  -- kong migrations bootstrap

‼️ Database Connection Failed

로그 예시

failed to connect to PostgreSQL during /status endpoint check: 
DNS resolution failed: dns server error: 3 name error

해결 방법

1) PostgreSQL Pod 확인

kubectl get pods -n dev-db
kubectl get svc -n dev-db

2) PostgreSQL 수동 배포 (Pod가 없는 경우)

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres-kong
  namespace: dev-db
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres-kong
  template:
    metadata:
      labels:
        app: postgres-kong
    spec:
      containers:
      - name: postgres
        image: postgres:13
        env:
        - name: POSTGRES_DB
          value: kong
        - name: POSTGRES_USER
          value: kong
        - name: POSTGRES_PASSWORD
          value: kong
        ports:
        - containerPort: 5432
---
apiVersion: v1
kind: Service
metadata:
  name: postgres-kong
  namespace: dev-db
spec:
  selector:
    app: postgres-kong
  ports:
  - port: 5432
    targetPort: 5432
EOF

‼️ Balancer Not Found 오류

로그 예시

target create: balancer not found for 86db6ef9-6488-43a7-b159-16d76dd0628d

원인
Kong이 업스트림을 생성한 후 타겟을 추가할 때 발생하는 타이밍 이슈

해결 방법

• 일반적으로 Kong이 완전히 시작되면 자동으로 해결됨
• 지속될 경우 Kong Pod 재시작

참고 자료

Kong Official Documentation
Kong Helm Charts
Kong Kubernetes Ingress Controller