Kong Gateway Service 및 Route 생성 방법

이 포스트에서는 Kong Gateway 의 기본적인 Service, Route를 생성하는 방법에 대해서 다룹니다. Service와 Route 설정을 통해 Kong Gateway를 통해 연결될 엔드포인트와, 연결될 경로를 설정할 수 있습니다.

Kong Gateway를 설치하고, Manager 대시보드를 구성하는 방법은 Kong Gateway, Kong Manager 설치 및 구성하기를 참고하세요.

목차

1. Kong Gateway 환경 구성
2. Service 생성하기
 2-1. Kong Manager 대시보드로 Kong Gateway – service 생성하기
 2-2. Kong Admin API로 service 생성하기
 2-3. kong.yml 파일로 service 생성하기(DB-less)
3. Route 생성하기
 3-1. Kong Manager 대시보드로 Kong Gateway – route 생성하기
 3-2. Kong Admin API로 route 생성하기
 3-3. kong.yml 파일로 route 생성하기(DB-less)

1. Kong Gateway 환경 구성

  • Kong Gateway 서버 : Ubuntu 24.04 LTS
  • Kong Gateway 버전 : 3.6.1
  • Kong Gateway 서버 IP: 192.168.200.132
  • 백엔드 NGINX 서버 IP: 192.168.200.160


Kong Gateway 포트 정보

  • 8000 : HTTP 트래픽 수신
  • 8443 : HTTPS 트래픽 수신
  • 8001 : Kong Admin API (HTTP)
  • 8444 : Kong Admin API (HTTPS)
  • 8002 : Kong Manager 대시보드 (HTTP)
  • 8445 : Kong Manager 대시보드 (HTTPS)

2. Service 생성하기

2-1. Kong Manager 대시보드로 Kong Gateway – service 생성하기

Kong Manager 대시보드를 통해 GUI 환경에서 service를 손쉽게 생성할 수 있습니다.

1. Kong Manager 대시보드로 접속하여 gateway service 탭으로 이동하고, 새로운 gateway service를 생성합니다.

2. (선택사항) gateway service를 관리하기 위한 이름/태그를 설정합니다.

3. gateway service의 엔드포인트를 설정합니다.
URL 입력을 통한 설정 방법과 통신 프로토콜, 호스트, 포트 번호, 경로를 개별적으로 입력하여 설정하는 방법이 있습니다.

Kong gateway service option

통신 프로토콜, 호스트는 필수적으로 입력해야 합니다. 포트 번호는 별도로 지정하지 않을 시 기본적으로 80번 포트로 설정됩니다.

4. 추가로 고급 옵션을 설정할 수 있습니다.

Kong gateway service option
  • Retries : 요청 실패 시 재시도 횟수를 지정합니다.
  • Connection Timeout: 클라이언트가 서버에 연결을 시도하는데 소요되는 제한 시간을 설정합니다.
  • Write Timeout: 클라이언트가 요청 본문을 서버로 보내는 데 걸리는 최대 시간을 설정합니다.
  • Read Timeout: 서버가 클라이언트에 응답을 보내는 데 걸리는 최대 시간을 설정합니다.

Timeout 옵션은 모두 밀리초 단위로 지정됩니다(60000 = 60초).

아래의 값들은 https 프로토콜 설정 시 설정할 수 있습니다.

  • client_certificate : Kong Gateway가 엔드포인트 서버와 TLS handshake 수행 시 전송할 클라이언트 인증서를 설정합니다.
  • ca_certificates : Kong Gateway가 엔드포인트 서버의 TLS 인증서의 유효성을 확인할 때 사용할 신뢰할 수 있는 CA 인증서를 설정합니다. null로 설정 시 NGINX의 기본 설정을 따릅니다.
  • tls_verify : 엔드포인트 서버의 TLS 인증서 확인 여부를 설정합니다. null(비활성화)로 설정 시 NGINX의 기본 설정을 따릅니다.

5. gateway service를 생성하고 확인합니다.

2-2. Kong Admin API로 service 생성하기

Kong Gateway Admin API로 요청을 전송하여 service를 생성할 수 있습니다.

1. Kong Gateway Admin API의 /service 경로로 POST 요청을 보내 서비스를 생성합니다.

$ curl -i -X POST http://192.168.200.132:8001/services \    # Kong Gateway Admin API
    --data name=NGINX-API \                                 # gateway service 이름
    --data url='http://192.168.200.160'                     # 엔드포인트 설정

생성 성공 시 다음과 같이 gateway service의 정보를 포함한 응답을 받습니다.

HTTP/1.1 201 Created
Date: Tue, 04 Jun 2024 06:11:48 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: http://192.168.200.132:8002
Access-Control-Allow-Credentials: true
Content-Length: 374
X-Kong-Admin-Latency: 10
Server: kong/3.6.1

{"write_timeout":60000,"tags":null,"ca_certificates":null,"retries":5,"name":"NGINX-API","id":"a7d51ef7-ac40-45a8-b150-99d88e24add1","updated_at":1717481508,"port":80,"tls_verify_depth":null,"protocol":"http","client_certificate":null,"path":null,"tls_verify":null,"host":"192.168.200.160","connect_timeout":60000,"created_at":1717481508,"read_timeout":60000,"enabled":true}
  • enabled : 해당 gateway service의 활성화 여부
  • tls_verify_depth : 엔드포인트 서버의 인증서를 확인할 때, 인증서 체인의 깊이를 설정합니다. 0으로 설정 시 서버 인증서만을 확인하며, 숫자가 증가할수록 상위 인증서까지 확인합니다.

이외의 옵션들은 Kong Manager 대시보드를 통한 생성의 옵션들과 동일합니다.

2. Kong Gateway Admin API의 /service/<gateway service 이름 혹은 id> 경로로 GET 요청을 보내 설정을 확인할 수 있습니다.

$ curl -X GET http://192.168.200.132:8001/services/NGINX-API

{"write_timeout":60000,'"tags":null,"ca_certificates":null,"retries":5,"name":"NGINX-API","id":"a7d51ef7-ac40-45a8-b150-99d88e24add1","updated_at":1717481508,"port":80,"tls_verify_depth":null,"protocol":"http","client_certificate":null,"path":null,"tls_verify":null,"host":"192.168.200.160","connect_timeout":60000,"created_at":1717481508,"read_timeout":60000,"enabled":true}

3. 생성된 gateway service는 PATCH 요청을 통해 수정할 수 있습니다.

$ curl -X PATCH http://192.168.200.132:8001/services/NGINX-API 
    --data retries=6

해당 요청을 통해 설정이 수정되면, 수정된 설정을 포함한 gateway service의 전체 설정을 반환합니다.

{"write_timeout":60000,"tags":null,"ca_certificates":null,"retries":6,"name":"NGINX-API","id":"a7d51ef7-ac40-45a8-b150-99d88e24add1","updated_at":1717482282,"port":80,"tls_verify_depth":null,"protocol":"http","client_certificate":null,"path":null,"tls_verify":null,"host":"192.168.200.160","connect_timeout":60000,"created_at":1717481508,"read_timeout":60000,"enabled":true}

Kong Admin API에 대한 더 자세한 내용은 Kong Admin API 문서를 참고하세요.

2-3. kong.yml 파일로 service 생성하기(DB-less)

Kong Gateway를 DB-less로 구성한 경우, API 통신을 통한 설정 변경 및 대시보드를 통한 설정 변경이 불가능하고(읽기 전용으로 설정 확인은 가능), yml 파일을 통해서만 설정을 적용할 수 있습니다.

1. Kong Gateway 구성에 사용한 yml 파일을 수정합니다.

$ sudo vi /etc/kong/kong.yml

_format_version: "3.0"         

_transform: true
               
services:
- name: NGINX-yml              # 서비스명
  url: http://192.168.200.160  # URL
  tags:                        # tag설정
    - example
  retries: 6                   # 기타 설정
  read_timeout: 50000
  • format_version : yml 파일 문법 버전, 해당 버전(3.0)이상의 kong gateway가 읽을 수 있음
  • transform : consumer의 credential 값을 암호화 후 저장여부 설정.
    credential 값을 암호화된 값으로 입력 시 false로 설정 권장됨

2. 명령어를 통해 설정에 문제가 없는지 확인하고, 변경된 설정을 적용합니다.

$ sudo kong config -c kong.conf parse kong.yml

parse successful


$ sudo kong reload

Kong reloaded

3. Kong Manager 대시보드에서 생성된 gateway service를 확인할 수 있습니다.

Kong gateway service

4. 추가 service는 다음과 같이 – 표기로 구분하여 생성할 수 있습니다.

services:
- name: NGINX-yml
  url: http://192.168.200.160
  tags:
    - example
  retries: 6
  read_timeout: 50000
- name: service2
  protocol: http
  host: example.com
  port: 80

3. Route 생성하기

3-1. Kong Manager 대시보드로 Kong Gateway – route 생성하기

1. Kong Manager 대시보드로 접속하여 route 탭으로 이동하고, 새로운 route를 생성합니다.

기존에 생성한 gateway service에서 route를 생성할 수도 있습니다.

2. route를 통해 연결될 gateway service와 이름, 태그를 설정합니다.

Kong gateway route option

기존에 생성한 gateway service에서 생성 시 서비스 설정은 자동적으로 적용됩니다.

Kong gateway route option

3. route 설정을 작성합니다.
NGINX 서버로 연결을 위해 /nginx 경로를 설정했습니다.

추가로 다양한 라우팅 규칙을 구성할 수 있습니다.

Kong gateway route option
  • Paths : 경로를 기반으로 요청을 라우팅합니다.
  • SNIs : https 연결의 host를 기반으로 라우팅합니다.
  • Hosts : 요청의 Host 헤더를 기반으로 라우팅합니다.
  • Methods : 요청 메서드를 기반으로 라우팅합니다.
  • Headers: 요청의 특정 헤더 값을 기반으로 라우팅합니다.

4. 추가로 고급 옵션을 설정할 수 있습니다.

Kong gateway route option
  • Path Handling : 클라이언트 요청의 경로를 처리하는 방식을 설정합니다.
  • HTTPS Redirect Status Code : http 요청을 HTTPS로 리디렉션 할 때의 상태 코드를 설정합니다.
  • Regex Priority : 정규식 패턴을 기반으로 라우팅 우선순위를 설정합니다. 값이 작을수록 높은 우선순위를 가집니다.
  • Strip Path : 요청 시 Paths 항목에서 설정된 경로를 제거하고 서비스로 연결합니다.
  • Preserve Host : 클라이언트 요청의 host 헤더를 보존합니다.
  • Request buffering : 요청 버퍼링 옵션을 활성화합니다. 요청의 크기가 크거나 처리 시간이 긴 경우 효과적입니다.
  • Response buffering : 응답 버퍼링 옵션을 활성화합니다. 엔드포인트 서버의 응답 속도가 느릴 경우에 효과적입니다.

5. route를 생성하고 확인합니다.

Kong gateway route

6. 생성한 경로를 통해 gateway service에서 지정한 엔드포인트로 연결합니다.

Kong Gateway는 기본적으로 8000번 포트로 요청을 수신합니다.

Kong Gateway 서버의 8000번 포트에 /nginx 경로로 연결하고 엔드포인트인 NGINX 서버로 연결된 것을 확인할 수 있습니다.

3-2. Kong Admin API로 route 생성하기

Kong Gateway Admin API로 요청을 전송하여 route를 생성할 수 있습니다.

1. Kong Gateway Admin API의 /service/<gateway service 이름>/routes 경로로 POST 요청을 보내 서비스를 생성합니다.

$ curl -i -X POST http://192.168.200.132:8001/services/NGINX-API/routes \
    --data 'paths[]=/nginx' \         # paths 설정
    --data name=NGINX-API-route       # route 이름 설정

생성 성공 시 다음과 같이 route의 정보를 포함한 응답을 받습니다.

HTTP/1.1 201 Created
Date: Wed, 05 Jun 2024 07:36:54 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: http://192.168.200.132:8002
Access-Control-Allow-Credentials: true
Content-Length: 488
X-Kong-Admin-Latency: 14
Server: kong/3.6.1

{"name":"NGINX-API-route","paths":["/nginx"],"response_buffering":true,"id":"cf269eec-71b5-4435-98ee-dd0aed239629","https_redirect_status_code":426,"path_handling":"v0","snis":null,"tags":null,"protocols":["http","https"],"service":{"id":"a7d51ef7-ac40-45a8-b150-99d88e24add1"},"request_buffering":true,"hosts":null,"updated_at":1717573014,"headers":null,"destinations":null,"methods":null,"sources":null,"created_at":1717573014,"preserve_host":false,"strip_path":true,"regex_priority":0}

해당 옵션들은 Kong Manager 대시보드를 통한 생성의 옵션들과 동일합니다.

2. Kong Gateway Admin API의 /service/<gateway service 이름>/routes/<route 이름> 경로 및 /routes/<route 이름> 경로로 GET 요청을 보내 설정을 확인할 수 있습니다.

$ curl -X GET http://192.168.200.132:8001/services/NGINX-API/routes/NGINX-API-route

혹은

$ curl -X GET http://192.168.200.132:8001/routes/NGINX-API-route

다음과 같은 응답을 수신합니다.

{"name":"NGINX-API-route","paths":["/nginx"],"response_buffering":true,"id":"cf269eec-71b5-4435-98ee-dd0aed239629","https_redirect_status_code":426,"path_handling":"v0","snis":null,"tags":null,"protocols":["http","https"],"service":{"id":"a7d51ef7-ac40-45a8-b150-99d88e24add1"},"request_buffering":true,"hosts":null,"updated_at":1717573014,"headers":null,"destinations":null,"methods":null,"sources":null,"created_at":1717573014,"preserve_host":false,"strip_path":true,"regex_priority":0}

3. 생성된 route는 PATCH 요청을 통해 수정할 수 있습니다.

$ curl -X PATCH http://192.168.200.132:8001/services/NGINX-API/routes/NGINX-API-route 
    --data response_buffering="false"

해당 요청을 통해 설정이 수정되면, 수정된 설정을 포함한 route의 전체 설정을 반환합니다.

{"name":"NGINX-API-route","paths":["/nginx"],"response_buffering":false,"id":"cf269eec-71b5-4435-98ee-dd0aed239629","https_redirect_status_code":426,"path_handling":"v0","snis":null,"tags":null,"protocols":["http","https"],"service":{"id":"a7d51ef7-ac40-45a8-b150-99d88e24add1"},"request_buffering":true,"hosts":null,"updated_at":1717574047,"headers":null,"destinations":null,"methods":null,"sources":null,"created_at":1717573014,"preserve_host":false,"strip_path":true,"regex_priority":0}

3-3. kong.yml 파일로 route 생성하기(DB-less)

Kong Gateway를 DB-less로 구성한 경우, API 통신을 통한 설정 변경 및 대시보드를 통한 설정 변경이 불가능하고(읽기 전용으로 설정 확인은 가능), yml 파일을 통해서만 설정을 적용할 수 있습니다.

1. 구성에 사용한 kong.yml 파일을 수정합니다. 기존에 작성한 services 설정에 추가로 작성합니다.

$ sudo vi /etc/kong/kong.yml

_format_version: "3.0"

_transform: true

services:
- name: NGINX-yml              
  url: http://192.168.200.160  
  tags:                        
    - example
  retries: 6                   
  read_timeout: 50000
  routes:                       # routes 설정 추가
  - name: NGINX-yml-route
    paths:
    - /nginx

다음과 같이 별개의 route 설정에 service 이름을 명시하여 구성할 수도 있습니다.

services:
- name: NGINX-yml
  url: http://192.168.200.160
  tags:
    - example
  retries: 6
  read_timeout: 50000
  routes:
  - name: NGINX-yml-route
    paths:
    - /nginx

routes:
- name: route2
  service: NGINX-yml
  hosts: ["kong.nginx.com"]

2. 명령어를 통해 설정에 문제가 없는지 확인하고, 변경된 설정을 적용합니다.

$ sudo kong config -c kong.conf parse kong.yml

parse successful

$ sudo kong reload

Kong reloaded

3. Kong Manager 대시보드에서 생성된 route를 확인할 수 있습니다.

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

* indicates required