콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Kong 스택 — 모듈로 구성된 데이터베이스 기반 API 게이트웨이

이 예제는 작지만 실제적인 스택인 데이터베이스 기반 API 게이트웨이를 Developer가 작성한 하나의 Aggregate에서 합성된 Kubernetes 매니페스트로 컴파일합니다.

게이트웨이는 단일 컴포넌트가 아닙니다. 게이트웨이는 모듈, 즉 단일 워크로드 컴포넌트 두 개를 구성하는 재사용 가능한 하위 aggregate입니다 —

  • 프록시 포트에서 클라이언트 트래픽을 종단하고 로컬 상태를 보관하지 않는 게이트웨이, 그리고
  • 게이트웨이의 구성을 보관하고 이를 볼륨에 영속화하는 백엔드인 PostgreSQL입니다.

모듈은 게이트웨이에서 백엔드로 향하는 자체 내부 엣지를 연결하고 게이트웨이를 공개 엔드포인트 proxy로 내보냅니다. 최상위 Aggregate는 모듈을 이름으로 가져와 구성된 스택을 렌더링하며, 운영자는 Release에서 모듈의 내부 컴포넌트 크기를 지정합니다.

파일

파일역할
aggregate.yamlDeveloper 의도: API 게이트웨이 모듈(core/kong)을 가져옵니다.
manifest-helm-synth.yaml게이트웨이 및 백엔드 타입을 해당 synth helm Recipes에 매핑합니다.
release-helm-synth.yamlKubernetes 대상에 대한 운영자 레코드입니다. 모듈 범위 ID로 모듈의 내부 컴포넌트 크기를 지정하며, 스키마 기본값에 맡긴 항목은 자체 완결적으로 렌더링됩니다.

보여 주는 내용

  • 모듈로서의 구성. 다중 워크로드 기능, 즉 실제로는 프록시와 구성 데이터베이스로 이루어진 API 게이트웨이는 하나의 단일체 컴포넌트가 아니라 단일 워크로드 컴포넌트 두 개를 구성하는 하위 aggregate로 패키징됩니다. 모듈은 이름으로 가져오며 게이트웨이가 필요한 곳 어디에서나 재사용됩니다.
  • 모듈 내부의 내부 엣지. 게이트웨이는 백엔드 사용을 선언합니다. 백엔드 Recipe의 provides 호스트, 포트, 사용자, 데이터베이스가 게이트웨이로 전달되어 PostgreSQL 연결로 구성됩니다. 컴파일러는 이 문자열을 해석하지 않고 라우팅합니다.
  • 공개 엔드포인트. 모듈은 게이트웨이를 proxy로 내보냅니다. 이는 소비자가 연결하는 안정적인 공개 이름으로, 모듈의 내부 컴포넌트 이름과 분리되어 있습니다.
  • 내부 컴포넌트에 대한 운영자의 크기 지정. Release는 모듈의 내부 컴포넌트를 모듈 범위 ID(gateway.backend, gateway.gateway)로 지정하여 컴퓨팅 자원을 설정하며, 개발자의 Aggregate가 물리적 크기를 다시 명시할 필요가 없습니다.
  • 서비스 시작 전에 실행되는 마이그레이션 단계. 게이트웨이는 메인 게이트웨이 컨테이너가 시작되기 전에 완료될 때까지 실행되는 init 컨테이너를 통해 데이터베이스 스키마를 프로비저닝하므로, 준비된 스키마를 기반으로 서비스합니다. 부트스트랩은 멱등적이므로 이미 프로비저닝된 데이터베이스에 대해 다시 실행해도 아무 작업도 하지 않습니다.
  • 공유 자격 증명. 게이트웨이는 PostgreSQL 백엔드에 인증하므로 둘은 하나의 비밀번호를 공유합니다. 이 예제는 공유 인라인 개발용 기본값을 사용하므로 스택이 외부 시크릿 없이 자체 완결적으로 실행됩니다.
  • 재현 가능한 이미지. 게이트웨이와 백엔드 모두 명시적인 이미지 태그를 고정하므로 렌더링된 매니페스트는 안정적인 이미지를 참조합니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example kong-stack

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd kong-stack

빌드

이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

렌더링된 아티팩트는 dist/ 아래에 생성됩니다. Kubernetes 대상은 오프라인으로 일반 매니페스트를 렌더링하므로 차트를 가져올 필요가 없습니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `kong-stack` 폴더가 없으면 `example`에 `kong-stack` 값을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `kong-stack` 폴더에 작성됩니다. 그런 다음 `workspace_root` 값은 `kong-stack`, `release` 값은 `release-helm-synth.yaml`, `auto_pull` 값은 true, `write` 값은 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `kong-stack/dist/` 아래에 있습니다.

구성된 스택의 모습

게이트웨이는 상태 비저장 Deployment와 프록시 포트의 ClusterIP Service, 그리고 Status API의 요청 허용 목록을 담은 ConfigMap으로 렌더링됩니다. Pod에는 메인 컨테이너보다 먼저 실행되는 마이그레이션 init 컨테이너가 있으며, 두 컨테이너 모두 백엔드 엣지에서 구성된 연결, 즉 백엔드의 클러스터 내 Service 이름, 사용자, 데이터베이스를 가집니다.

env:
- name: KONG_DATABASE
value: postgres
- name: KONG_PG_HOST
value: gateway-zdbackend-default
- name: KONG_PG_PORT
value: "5432"
- name: KONG_PG_USER
value: kong
- name: KONG_PG_DATABASE
value: kong
[… omitted: the gateway's own proxy, admin and status listen addresses, and
the allowlist file its Status API includes]
- name: KONG_PG_PASSWORD
value: apppass

게이트웨이의 readiness 및 liveness 프로브는 컨테이너 포트 status에서 Kong의 Status API인 GET /status/ready와 GET /status를 요청하므로, 해당 리스너는 Pod의 주소에 바인딩됩니다. Kong은 ConfigMap의 허용 목록을 Status API 자체의 server 블록에 포함합니다. Pod의 루프백 주소를 제외한 모든 주소에서 /status, /status/ready, /metrics에 대한 GET에는 응답하고, 그 밖의 모든 요청은 403으로 거부합니다. 여기에는 POST /status/ready도 포함되는데, 이 요청은 그렇지 않으면 게이트웨이를 드레이닝 상태로 표시하여 재시작될 때까지 Service에서 제외시킵니다.

백엔드는 /var/lib/postgresql/data에 영구 볼륨이 마운트된 StatefulSet과 ClusterIP Service, 헤드리스 Service로 렌더링됩니다.