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

APISIX 스택 — 모듈로 구성한 동적 API 게이트웨이

이 예제는 작지만 실제적인 스택인 동적 API 게이트웨이를 개발자가 작성한 하나의 Aggregate에서 합성된 Kubernetes 매니페스트로 컴파일합니다.

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

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

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

파일

파일역할
aggregate.yaml개발자 의도: API 게이트웨이 모듈(core/apisix)을 가져오고, 자체 파라미터에서 받은 게이트웨이의 Admin API 키를 모듈에 전달합니다.
manifest-helm-synth.yaml게이트웨이와 저장소 타입을 해당 synth helm Recipes에 매핑하고, 모듈이 연결하는 자격 증명 Feature를 네임스페이스에 이미 있는 Secret을 읽는 구현에 매핑합니다.
release-helm-synth.yamlKubernetes 대상에 대한 운영자 기록입니다. Admin API 키를 담은 Secret의 이름을 지정하고, 모듈 범위 ID로 모듈의 내부 컴포넌트 크기를 지정합니다. 그 밖의 모든 것은 스키마 기본값에 맡깁니다.

보여 주는 내용

  • 모듈로서의 구성. 다중 워크로드 기능, 즉 실제로는 프록시와 구성 저장소로 이루어진 API 게이트웨이를 하나의 모놀리식 컴포넌트가 아니라 단일 워크로드 컴포넌트 두 개를 구성하는 하위 aggregate로 패키징합니다. 모듈은 이름으로 가져오며 게이트웨이가 필요한 곳 어디서든 재사용됩니다.
  • 모듈 내부의 내부 엣지. 게이트웨이는 저장소 사용을 선언합니다. 저장소 Recipe의 provides 호스트와 포트가 게이트웨이로 전달되어 etcd 연결로 구성됩니다. 컴파일러는 문자열을 해석하지 않고 라우팅합니다.
  • 공개 엔드포인트. 모듈은 게이트웨이를 proxy로 내보냅니다. 이는 소비자가 연결하는 안정적인 공개 이름으로, 모듈의 내부 컴포넌트 이름과 분리되어 있습니다.
  • 운영자의 내부 컴포넌트 크기 지정. Release는 모듈 범위 ID(gateway.store, gateway.gateway)로 모듈의 내부 컴포넌트를 지정해 컴퓨팅 자원을 설정하며, 개발자의 Aggregate가 물리적 크기를 다시 기술할 필요가 없습니다.
  • 런타임에 작성되는 파일과 함께 마운트되는 구성 파일. 게이트웨이는 시작 시 자신이 쓰기도 하는 디렉터리의 파일에서 구성을 읽습니다. Recipe는 그 구성을 ConfigMap으로 내보내고 단일 파일로 마운트하므로, 게이트웨이가 그곳에 쓰는 파일을 가리지 않고 게이트웨이를 구성합니다.
  • Secret에서 읽는 Admin API 키. 게이트웨이는 Admin API로 라우트를 관리하며, 그 키는 게이트웨이의 자격 증명 슬롯을 통해 전달됩니다. 이 예처럼 models 소켓에 아무것도 연결되지 않은 동안에는 게이트웨이가 이 슬롯을 필수로 요구하므로, 기본 키는 없습니다. 모듈은 키를 파라미터 admin_key로 받아 core/referenced-secret 자격 증명 Feature를 그 키와 함께 슬롯에 연결합니다. 이 Aggregate는 자체 파라미터를 선언해 아래로 전달하고, Release가 그 값을 채웁니다. Manifest는 Feature를 k8s-existing-secret에 매핑하므로, 값은 네임스페이스에 이미 존재하는 Secret의 이름입니다. 빌드는 키를 읽지도 렌더링하지도 않으며, 게이트웨이는 시작할 때 그 Secret에서 키를 읽습니다. 값을 제공하지 않는 Release는 해당 파라미터를 명시하며 빌드를 중단시킵니다.
  • 재현 가능한 이미지. 게이트웨이와 저장소 모두 명시적인 이미지 태그를 고정하므로, 렌더링된 매니페스트는 안정적인 이미지를 참조합니다.

예제 생성하기

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

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

Terminal window
aggrega scaffold --example apisix-stack

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

Terminal window
cd apisix-stack

빌드

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

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

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

적용하기 전에 Release가 지정한 Secret apisix-admin-key를 대상 네임스페이스에 만들고, 데이터 키 admin-key 아래에 직접 정한 키를 넣습니다. 키는 비어 있으면 안 되며(비어 있으면 게이트웨이가 시작 시 중지됩니다), 숫자로만 된 키처럼 APISIX가 숫자나 true 또는 false로 읽는 값이어서도 안 됩니다. 그런 경우 APISIX는 요청이 제시하는 키와 그 키를 결코 일치시키지 않기 때문입니다.

AI 어시스턴트 사용

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

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `apisix-stack` 폴더가 없으면 `example`에 `apisix-stack`을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `apisix-stack` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `apisix-stack`, `release`에 `release-helm-synth.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `apisix-stack/dist/` 아래에 있습니다.

구성된 스택의 모습

게이트웨이는 상태 비저장 Deployment와 프록시 포트의 ClusterIP Service로 렌더링됩니다. 구성은 컨테이너의 conf 디렉터리에 단일 파일로 마운트되는 ConfigMap으로 전달됩니다. 이 구성에는 저장소의 클러스터 내 Service 이름이 들어 있으며, Admin API 키가 들어갈 자리에는 APISIX가 파일을 로드할 때 키를 읽어 오는 환경 변수의 이름이 들어 있습니다.

apisix:
node_listen: 9080
deployment:
role: traditional
role_traditional:
config_provider: etcd
admin:
[… omitted: the client range the Admin API accepts]
admin_key:
- name: admin
key: ${{APISIX_ADMIN_KEY}}
role: admin
admin_listen:
ip: 0.0.0.0
port: 9180
etcd:
host:
- "http://gateway-zdstore-default:2379"
prefix: "/apisix"
timeout: 30

Deployment는 그 변수를 Secret에서 전달하므로, 키는 렌더링된 어떤 파일에도 나타나지 않습니다.

env:
- name: APISIX_ADMIN_KEY
valueFrom:
secretKeyRef:
name: apisix-admin-key
key: admin-key

저장소는 /etcd-data에 마운트된 영구 볼륨을 갖는 StatefulSet과 ClusterIP Service, 헤드리스 Service로 렌더링됩니다.