Kong Gateway 설치 가이드

1. 개요

본 문서는 gitops 저장소의 /kong 디렉터리 구조를 기반으로 Kong Gateway를 Kubernetes 클러스터에 설치하는 전체 과정을 안내합니다. Kong Gateway는 고성능 API Gateway로, Control Plane과 Data Plane 아키텍처를 지원합니다. Kustomize, Helm, Makefile을 활용한 배포 자동화, 환경별 설정, 주요 커스텀 옵션, 운영 팁을 포함합니다.

2. 사전 요구사항

  • Kubernetes 클러스터: v1.30 이상
  • 로컬 도구: kubectl, kustomize, helm 설치 완료
  • 인증서: cert-manager를 통한 TLS 인증서 발급 및 네임스페이스 간 복제 구성 준비
  • OAuth2-Proxy 설치
  • PostgreSQL: PostgreSQL
  • Redis: Redis HA-Proxy
  • DNS 등록
    • kong-manager.cnapcloud.com
    • kong-admin.cnapcloud.com
    • kong-dp-proxy.cnapcloud.com

3. 디렉터리 구조 및 역할

kong/
├── Makefile                           # 배포 자동화 스크립트
├── kustomize/
│   ├── base/                          # 공통 리소스(Helm 차트, CRD 등)
│   │   ├── helm/                      # Kong Helm 차트
│   │   ├── kustomization.yaml         # 기본 Kustomize 구성
│   │   ├── patches/                   # 패치 파일들
│   │   ├── resources/                 # 추가 리소스
│   │   └── tls/                       # TLS 관련 설정
│   └── overlays/
│       └── dev/                       # dev 환경 설정
│           ├── kustomization.yaml     # Kustomize 구성
│           ├── helm/                  # 환경별 values 파일
│           └── resources/             # 추가 리소스
  • Makefile: namespace, pull, update-manifest, preview, apply, delete 등 배포 자동화 명령어
  • kustomize/base/: 모든 환경에 공통 적용될 리소스(Helm 차트, CRD 등)
  • kustomize/overlays/dev/: dev 환경 특화 설정
  • helm/values-cp.yaml: Control Plane 설정
  • helm/values-dp.yaml: Data Plane 설정

4. 설치 단계

Kong의 Kustomize 구성은 Base에서 Helm Values를 설정하고, Helm Template을 사용하여 리소스를 생성합니다. 생성된 리소스는 Base의 Kustomization.yaml에 정의되어 배포되며, 기존의 HelmChart BuiltIn을 사용하지 않습니다. 따라서 Values 파일 변경 시 반드시 make update-manifest를 실행해야 합니다.

4.1. Helm 차트 준비

Kong Helm 차트를 다운로드합니다.

make pull

4.2. TLS 인증서 생성

Kong 클러스터링을 위한 TLS 인증서를 생성합니다.

make create-tls

4.4. values.yaml 커스터마이징

kustomize/base/helm/ 디렉터리의 values 파일들을 환경에 맞게 수정합니다.

4.4.1. Control Plane 설정 (values-cp.yaml)

Control Plane 설정에서는 postgresql, 접속 도메인을 설정합니다.

env:
  database: "postgres"

customEnv:
  # PostgreSQL 설정
  KONG_PG_HOST: "pg-cluster-rw.database.svc"
  KONG_PG_USER: "kong"
  KONG_PG_PASSWORD: "!password"
  KONG_PG_DATABASE: "kong"
  
  # URL 설정
  KONG_ADMIN_GUI_API_URL: "https://kong-manager.cnapcloud.com/admin-api"
  KONG_ADMIN_GUI_URL: "https://kong-manager.cnapcloud.com"

ingressController:
  enabled: false

admin:
  ingress:
    ingressClassName: nginx
    tls: cnapcloud.com-tls

manager:
  ingress:
    hostname: kong-manager.cnapcloud.comx
    tls: cnapcloud.com-tls

4.4.3. Data Plane 설정 (values-dp.yaml)

Data Plane 설정에서는 Redis, Kong DP Proxy 접속 도메인을 설정합니다.

customEnv:
 KONG_X_SESSION_STORAGE: "redis"
 KONG_X_SESSION_REDIS_HOST: "redis-ha-haproxy.database.svc"
 KONG_X_SESSION_REDIS_PASSWORD: "redis"

proxy:
  ingress:
    hostname: kong-proxy.cnapcloud.com
    tls: cnapcloud.com-tls

4.3. Manifest 생성

Helm 템플릿을 사용하여 Kubernetes manifest를 생성합니다.

make update-manifest

4.5. Kustomize 구성

OAuth2-Proxy에 도메인 변경이 있으면 패치 파일을 수정합니다. base의 kustomization.yaml`에서 namespace, resources, patches 등 지정합니다.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: gateway
resources:
  - ../../base
  - resources/

patches:
- target:
    kind: Ingress
    name: kong-cp-admin
  path: ./patches/oauth2-proxy-api.yaml
- target:
    kind: Ingress
    name: kong-cp-manager
  path: ./patches/oauth2-proxy-ui.yaml

4.6. 배포 프로세스 (Makefile 활용)

Step 1: Namespace 생성

make namespace DEPLOY_ENV=dev

Step 2: 배포 미리보기

make preview DEPLOY_ENV=dev

Step 3: 배포 실행

make apply DEPLOY_ENV=dev

Step 4: 배포 상태 확인

kubectl get pods -n gateway -w

5. 설치 후 검증

5.1. 리소스 상태 확인

kubectl get pods,svc,ingress,secret -n gateway

확인 사항:

  • Control Plane Pod: kong-cp-* (Running)
  • Data Plane Pod: kong-dp-* (Running)
  • Service 생성 확인 (kong-cp-admin, kong-cp-manager, kong-dp-proxy)
  • Ingress 생성 확인 (kong-manager.cnapcloud.com 등)
  • Secret 생성 확인 (kong-cluster-cert 등)

5.2. Kong Manager 접근 확인

Kong Manager에 접근 가능한지 확인합니다. OAuth2-Proxy와 연계되어 admin 그룹을 가진 사용자만 Kong Manager에 접근하여 서비스를 등록하고 수정할 수 있습니다.

curl -k https://kong-manager.cnapcloud.com

확인 사항:

  • Kong Manager UI 로드 확인
  • 인증 플로우 작동 (OAuth2-Proxy 연동 시)
  • admin 그룹 사용자만 접근 및 서비스 관리 가능

5.3. API Gateway 기능 테스트

Data Plane을 통해 API 요청을 테스트합니다.

curl -k https://kong-dp-proxy.cnapcloud.com/status

확인 사항:

  • 200 OK 응답
  • Kong 헤더 포함 확인

5.4. 클러스터링 상태 확인

Control Plane과 Data Plane 간 클러스터링 상태를 확인합니다.

kubectl logs -n gateway deployment/kong-cp-kong
kubectl logs -n gateway deployment/kong-dp-kong

확인 사항:

  • 클러스터링 연결 성공 로그
  • 구성 동기화 확인

6. Kong API를 사용한 서비스 구성 예제

Kong Admin API를 사용하여 서비스를 등록하고 OIDC 인증을 구성하는 예제입니다.

6.1. 액세스 토큰 발급

Keycloak에서 액세스 토큰을 발급받습니다.

export KEYCLOAK_URL=https://keycloak.cnapcloud.com
export REALM=cnap
export CLIENT=oauth2-proxy
export CLIENT_SECRET=Ymumkx8D26WnNjUe9NZp0UMwIlqqhtS3
export USER=admin
export PASSWORD=password

export ACCESS_TOKEN=$(curl -sk -X POST "${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/token" \
  -d grant_type=password \
  -d client_id=${CLIENT} \
  -d client_secret=${CLIENT_SECRET} \
  -d request_token_type=urn:ietf:params:oauth:token_type:access_token \
  -d username=${USER} \
  -d password=${PASSWORD} \
  -d scope='openid profile email' \
| jq -r .access_token)

echo "ACCESS_TOKEN: ${ACCESS_TOKEN}"

6.2. 서비스 등록

Prometheus 서비스를 Kong에 등록합니다.

curl -sk -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -X POST https://kong-admin.cnapcloud.com/services \
    --data "name=prometheus" \
    --data "url=http://lma-kube-prometheus-stack-prometheus.lma.svc:9090"

6.3. 라우트 등록

서비스에 대한 라우트를 등록합니다.

curl -sk -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -X POST https://kong-admin.cnapcloud.com/services/prometheus/routes \
    --data "name=prometheus" \
    --data "paths[]=/" \
    --data "hosts[]=prometheus2.cnapcloud.com"

6.4. OIDC 플러그인 추가

OIDC 인증 플러그인을 서비스에 추가합니다.

CLIENT_SECRET=VIFICe0sJ5JoR7FSvjoz4Jw2JfVQfpkp
curl -sk -sk -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -X POST https://kong-admin.cnapcloud.com/services/prometheus/plugins \
  -d name=oidc \
  -d config.client_id=prometheus \
  -d config.client_secret=${CLIENT_SECRET} \
  -d config.discovery=https://keycloak.cnapcloud.com/realms/cnap/.well-known/openid-configuration \
  -d config.redirect_after_logout_uri=https://prometheus2.cnapcloud.com \
  -d config.logout_path=/logout \
| jq

7. 운영 및 Troubleshooting

7.1. Pod가 Running 상태가 아닌 경우

kubectl get pods -n gateway
kubectl describe pod <pod명> -n gateway
kubectl logs <pod명> -n gateway

주요 원인:

  • 데이터베이스 연결 실패 → PostgreSQL 서비스 및 인증 정보 확인
  • TLS 인증서 문제 → 클러스터 인증서 생성 확인
  • 클러스터링 실패 → Control Plane 엔드포인트 확인

7.2. 인증 문제

  • OAuth2-Proxy 로그 확인: kubectl logs deployment/oauth2-proxy -n security
  • Kong Manager 접근 시 인증 헤더 확인

7.3. API 라우팅 문제

  • Kong 설정 확인: Kong Manager UI 또는 Admin API 사용
  • Data Plane 로그 확인

7.4. 성능 모니터링

Kong의 메트릭을 Prometheus로 수집하도록 설정합니다.

8. 보안 및 운영 권장사항

8.1. Secret 관리

민감 정보(데이터베이스 비밀번호, 라이선스 키)는 별도 Secret으로 관리합니다.

kubectl create secret generic kong-secret --from-literal=pg-password='your-password' -n gateway

8.2. Network Policy

Kong Pod 간 네트워크 통신을 제한하는 NetworkPolicy 적용을 권장합니다.

8.3. RBAC 설정

Kong Manager 접근을 위한 RBAC 규칙을 설정합니다.

9. 배포 제거

9.1. Kong Gateway 삭제

make delete DEPLOY_ENV=dev

9.2. Namespace 삭제 (선택사항)

kubectl delete namespace gateway

주의: Namespace를 삭제하면 PVC를 포함한 모든 데이터가 영구 삭제됩니다.

10. 부록: 최종 체크리스트

설치 전:

  • Kubernetes 클러스터 준비 (v1.24+)
  • kubectl, kustomize, helm 설치
  • PostgreSQL 설치 및 설정
  • 네임스페이스(gateway) 생성
  • DNS 등록 완료
  • TLS 인증서 준비

설치:

  • make pull 실행
  • make create-tls 실행
  • values.yaml 커스터마이징 완료
  • make update-manifest 실행
  • kustomization.yaml 구성 완료
  • make namespace 실행
  • make preview 실행 및 확인
  • make apply 실행

검증:

  • 모든 Pod이 Running 상태
  • Service/Ingress 생성 확인
  • Kong Manager 접근 확인
  • API Gateway 기능 테스트
  • 클러스터링 상태 확인

운영:

  • Secret 관리 적용
  • Network Policy 구성
  • RBAC 설정
  • 모니터링 설정
💬 무료 컨설팅 신청