Kong cluster, Traditional Deployment 방식 구성 가이드

이 포스트에서는 2개의 Kong Gateway 인스턴스를 하나의 Postgresql DB에 연결하여, Traditional Deployment 방식으로 Kong cluster 를 구성하는 방법에 관해 설명합니다. 또한 Kong cluster의 Kong Gateway 인스턴스 간 설정 동기화 관련 옵션들에 대해 알아보겠습니다.

Kong cluster 구성을 통해 다수의 Kong Gateway 인스턴스가 동일한 데이터베이스에 연결되어 동일한 설정을 공유하며 동작합니다.

목차

1. Kong cluster 이란?
2. 환경 구성
3. Kong cluster 구성
 3-1. PostgreSQL 접근 설정
 3-2. Kong Gateway 설정
 3-3. 설정 공유 확인
4. Kong cluster 설정 공유 옵션
5. 결론

1. Kong cluster 이란?

Kong cluster

Kong cluster는 다수의 Kong Gateway 인스턴스가 하나의 데이터베이스에 연결되어, 다수의 Kong Gateway 인스턴스가 서로 같은 설정을 공유하는 방식입니다. 이러한 구성을 통해서 필요에 따라 Kong Gateway 인스턴스를 손쉽게 확장할 수 있습니다.

주의할 점은, Kong cluster를 구성했다고 해서 클라이언트의 요청이 Kong Gateway 인스턴스에 자동적으로 로드 밸런싱이 되지 않습니다. 트래픽 분산을 위해서는 별도의 로드 밸런서 구성이 필요합니다.

2. 환경 구성

버전 정보
  • Kong Gateway(OSS) 버전 : 3.6.1
  • PostgreSQL 버전 : 16.3
서버 IP 정보
  • Kong Gateway server1 IP : 192.168.200.105
  • Kong Gateway server2 IP : 192.168.200.106
  • PostgreSQL server IP : 192.168.200.107

3. Kong cluster 구성

먼저 Kong Gateway 및 PostgreSQL을 설치합니다. Kong Gateway의 설치 방법은 Kong Gateway, Kong Manager 설치 및 구성하기 포스트의 2.Kong Gateway 설치하기 항목을, PostgreSQL 설치 및 데이터베이스, 유저 생성은 3-1.DB와 연동 설정 항목을 참고하세요.
PostgreSQL의 Kong 데이터베이스 설정은 다음과 같습니다.

  • user : kong_user
  • password : kongpwd
  • DB : kong_db

3-1. PostgreSQL 설정

PostgreSQL 최초 설치 시에는 localhost의 접근만이 허용되어 있습니다. Kong cluster 구성을 위해 Kong Gateway 서버의 데이터베이스 접근 설정을 하겠습니다.

1. postgresql.conf 파일의 listen_addresses 설정을 변경합니다.

해당 설정 파일은 /etc/postgresql/<버전>/main 디렉토리에 위치해 있습니다.
구성에 사용한 전체 파일은 여기에서 확인하세요.(60번 라인)

$ sudo vi /etc/postgresql/16/main/postgresql.conf

...

#------------------------------------------------------------------------------
# CONNECTIONS AND AUTHENTICATION
#------------------------------------------------------------------------------

# - Connection Settings -

listen_addresses = 'localhost, 192.168.200.107'

listen_addresses 설정을 통해 PostgreSQL 이 listen할 IP 주소를 설정합니다. 예제의 경우 localhost와 PostgreSQL 서버의 IP를 설정했습니다.

listen_addresses = '*'

위와 같이 설정 시 all 설정이 적용됩니다.

2. pg_hba.conf 파일을 수정합니다.

해당 설정 파일도 /etc/postgresql/<버전>/main 디렉토리에 위치해 있습니다.
구성에 사용한 전체 파일은 여기에서 확인하세요.(133, 134번 라인)

$ sudo vi /etc/postgresql/16/main/pg_hba.conf

...

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     peer
# IPv4 local connections:
host    all             all             127.0.0.1/32            scram-sha-256
# IPv6 local connections:
host    all             all             ::1/128                 scram-sha-256
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     peer
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256
host    kong_db         kong_user       192.168.200.105/32      scram-sha-256
host    kong_db         kong_user       192.168.200.106/32      scram-sha-256

파일 하단에 접근을 허용할 DB/USER 이름 및 IP 주소를 설정합니다.

3. 명령어를 통해 PostgreSQL을 재시작하여, 변경된 설정을 적용합니다.

$ sudo systemctl restart postgresql

3-2. Kong Gateway 설정

Kong cluster 구성을 위해 Kong Gateway에 앞서 구성한 PostgreSQL 데이터베이스를 연동하고, 확인을 위해 Kong Manager 대시보드 설정을 적용하겠습니다. Kong Manager 대시보드에 대한 더 자세한 내용은 Kong Manager OSS: 사용법, 기능, GUI 소개 포스트를 참고하세요.

Kong Gateway 설정에 사용한 kong.conf 파일은 여기에서 확인하세요.(1247번 라인)

1. /etc/kong 디렉토리의 kong.conf.default 파일을 수정하여 kong.conf 파일로 저장합니다.
…

#——————————————————————————
# DATASTORE
#——————————————————————————

pg_host = 192.168.200.107 # Host of the Postgres server.
pg_port = 5432 # Port of the Postgres server.
#pg_timeout = 5000 # Defines the timeout (in ms), for connecting,
# reading and writing.

pg_user = kong_user # Postgres user.
pg_password = kongpwd # Postgres user’s password.
pg_database = kong_db # The database name to connect to.

PostgreSQL 연동을 위한 설정을 적용합니다. 두 서버 모두 적용합니다.

2. 명령어를 통해 Kong Gateway를 실행하고, Kong Manager 대시보드로 접속합니다.

$ sudo kong start
Kong Gateway server1
Kong Gateway server2

2개의 Kong Gateway서버가 동일한 PostgreSQL DB에 연동되어 구성된 것을 확인할 수 있습니다.

3-3. 설정 공유 확인

Kong cluster 의 설정 공유를 확인하기 위해 Gateway service, Route를 생성하고 확인해보겠습니다. Kong Gateway의 Gateway service, Route에 대한 자세한 내용은 Kong Gateway Service 및 Route 생성 방법 포스트를 참고하세요.

1. Kong Gateway server1의 Kong Admin API를 통해 gateway service, route를 생성합니다.

# gateway service

$ curl -X POST http://192.168.200.105:8001/services \
--data name=nginx-service \
--data url='http://192.168.200.164' | jq '.'

{
  "host": "192.168.200.164",
  "id": "d5513215-37b6-4f0c-90dc-0265cbbc6e1f",
  "tags": null,
  "ca_certificates": null,
  "protocol": "http",
  "retries": 5,
  "tls_verify": null,
  "tls_verify_depth": null,
  "port": 80,
  "path": null,
  "client_certificate": null,
  "name": "nginx-service",
  "created_at": 1721290196,
  "updated_at": 1721290196,
  "write_timeout": 60000,
  "connect_timeout": 60000,
  "enabled": true,
  "read_timeout": 60000
}

gateway service를 통해 설정된 엔드포인트는 NGINX 기본 서버입니다.

# route

$ curl -X POST http://192.168.200.105:8001/services/nginx-service/routes \
--data 'paths[]=/nginx' \
--data name=nginx-route | jq '.'

{
  "destinations": null,
  "snis": null,
  "id": "797cb179-cfe4-4559-b465-5b7c49cf3106",
  "methods": null,
  "headers": null,
  "regex_priority": 0,
  "preserve_host": false,
  "tags": null,
  "path_handling": "v0",
  "service": {
    "id": "d5513215-37b6-4f0c-90dc-0265cbbc6e1f"
  },
  "paths": [
    "/nginx"
  ],
  "hosts": null,
  "sources": null,
  "name": "nginx-route",
  "request_buffering": true,
  "response_buffering": true,
  "protocols": [
    "http",
    "https"
  ],
  "updated_at": 1721290273,
  "strip_path": true,
  "https_redirect_status_code": 426,
  "created_at": 1721290273
}

/nginx 경로의 요청은 nginx-service gateway service로 연결되도록 구성했습니다.

2. Kong Gateway server2의 Kong Admin API로 요청을 전송해 확인합니다.

$ curl -X GET http://192.168.200.106:8001/services | jq '.'

{
  "next": null,
  "data": [
    {
      "client_certificate": null,
      "connect_timeout": 60000,
      "id": "d5513215-37b6-4f0c-90dc-0265cbbc6e1f",
      "read_timeout": 60000,
      "host": "192.168.200.164",
      "name": "nginx-service",
      "tags": null,
      "ca_certificates": null,
      "path": null,
      "enabled": true,
      "port": 80,
      "retries": 5,
      "tls_verify": null,
      "tls_verify_depth": null,
      "protocol": "http",
      "created_at": 1721290196,
      "updated_at": 1721290196,
      "write_timeout": 60000
    }
  ]
}
$ curl -X GET http://192.168.200.106:8001/routes | jq '.'

{
  "next": null,
  "data": [
    {
      "request_buffering": true,
      "response_buffering": true,
      "https_redirect_status_code": 426,
      "strip_path": true,
      "sources": null,
      "name": "nginx-route",
      "destinations": null,
      "headers": null,
      "hosts": null,
      "methods": null,
      "tags": null,
      "preserve_host": false,
      "regex_priority": 0,
      "paths": [
        "/nginx"
      ],
      "id": "797cb179-cfe4-4559-b465-5b7c49cf3106",
      "snis": null,
      "protocols": [
        "http",
        "https"
      ],
      "service": {
        "id": "d5513215-37b6-4f0c-90dc-0265cbbc6e1f"
      },
      "created_at": 1721290273,
      "updated_at": 1721290273,
      "path_handling": "v0"
    }
  ]
}

앞서 생성한 Gateway service, Route가 동일하게 구성된 것을 확인할 수 있습니다.

3. 두 Kong Gateway에 각각 요청을 전송해 응답을 확인합니다.

$ curl http://192.168.200.105:8000/nginx

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>

...

$ curl http://192.168.200.106:8000/nginx

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>

...

4. Kong cluster 설정 공유 옵션

Kong Gateway 인스턴스는 설정(gateway service, routes, consumers, plugins 등)을 실시간으로 데이터베이스와 공유하지 않습니다. 대신 데이터베이스에 저장된 설정을 메모리에 캐시하여 사용합니다. A 인스턴스에서 설정을 변경해도, B 인스턴스는 새로운 설정을 메모리에 캐시하기 전까지 기존 설정에 따라 동작합니다.
이와 관련된 설정은 kong.conf 파일에서 관리할 수 있습니다.

db_update_frequency

Kong Gateway 인스턴스가 데이터 저장소의 설정 변경을 확인할 주기를 초단위로 설정합니다.
Kong Gateway 인스턴스는 설정한 주기마다 데이터 저장소의 설정을 확인하고, 설정이 변경되면 새로운 설정을 메모리에 캐시합니다.

기본값은 5초입니다.

db_cache_ttl

캐시된 설정의 유효 기간을 초단위로 설정합니다. 0으로 설정 시 캐시가 만료되지 않고, db_update_frequency 설정에 따라 캐시가 갱신됩니다.

기본값은 0입니다.

db_resurrect_ttl

Kong Gateway 인스턴스가 데이터 저장소에 접근할 수 없는 경우, 다음 접근 시도까지의 시간을 초단위로 설정합니다.
Kong Gateway 인스턴스가 데이터 저장소 접근 실패 시, 설정된 시간동안 기존에 캐시된 설정을 사용하고 시간이 경과하면 데이터 저장소에 다시 접근을 시도하여 캐시 갱신을 시도합니다. 접근 시도가 실패하면 이 과정을 반복합니다.

기본값은 30초입니다.

db_cache_warmup_entities

Kong Gateway가 시작할 때 메모리 캐시로 로드할 개체(gateway service, routes, consumers, plugins 등)를 설정합니다. 해당 설정을 통해서 Kong Gateway가 시작할 때 해당 개체를 빠르게 사용할 수 있도록 합니다.

기본 설정은 services가 설정되어 있습니다.

5. 결론

이번 포스트에서는 2개의 Kong Gateway 서버를 하나의 Postgresql DB에 연결하여, Traditional Deployment 방식으로 Kong cluster 를 구성하는 방법을 알아봤습니다. 추가로 Kong cluster의 Kong Gateway 서버들이 같은 설정을 유지하기 위한 설정 공유 관련 옵션에 대해서 알아봤습니다.

Kong cluster는 여러 개의 Kong Gateway 인스턴스가 단일 데이터 베이스를 통해서 설정을 공유하여 필요에 따라 동일한 설정을 공유하는 Kong Gateway 인스턴스를 간편하게 확장할 수 있습니다. 또한 설정 공유 옵션을 통해서 Kong cluster의 인스턴스들이 효율적으로 데이터를 동기화하고, 일관된 설정을 유지하도록 구성할 수 있습니다.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required