NGINX 게이트웨이 — 업스트림으로의 리버스 프록시 라우팅, 두 대상
이 예제는 작지만 실제적인 스택, 즉 웹 백엔드 앞에 놓인 NGINX 리버스 프록시 게이트웨이를 Developer가 작성한 하나의 Aggregate에서 두 가지 대상으로 컴파일합니다.
- 로컬 개발용 Docker Compose, 그리고
- 클러스터용 합성된 Kubernetes 매니페스트.
동일한 aggregate.yaml이 두 대상을 모두 구동합니다. 대상마다 달라지는 것은
Manifest가 선택하는 Recipe 계층뿐입니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | Developer의 의도: web 백엔드(core/devtool/adminer)와, 백엔드에 대한 upstream 사용을 선언하는 proxy 게이트웨이(core/gateway/nginx). |
manifest-compose.yaml | 게이트웨이 유형을 Compose Recipe(compose/nginx)에, 백엔드를 Compose Adminer Recipe에 매핑합니다. |
manifest-helm-synth.yaml | 게이트웨이 유형을 합성 helm Recipe(helm/nginx)에, 백엔드를 오프라인 Adminer helm Recipe에 매핑합니다. |
release-compose.yaml / release-helm-synth.yaml | 두 대상에 대한 Operator 레코드. |
보여 주는 내용
- 하나의 작성 표면, 여러 대상. 하나의 Aggregate가 스택이 무엇인지에 대한 단일 진실 공급원입니다. 각 Manifest는 이를 어떻게 구현할지를 나타냅니다.
- String Pipe를 통한 업스트림 라우팅. 게이트웨이는 백엔드에 대한
upstream사용을 선언합니다. 백엔드 Recipe의provides.host와provides.port는 게이트웨이로 전달되어proxy_pass대상으로 렌더링됩니다. 컴파일러는 문자열을 해석하지 않고 라우팅하므로, 같은 엣지에서 Compose 빌드는 compose 서비스 이름을, Kubernetes 빌드는 Service 이름을 연결합니다. - Provider 고유 방식의 구성. 두 대상 모두에서 게이트웨이는 컨테이너 시작 시
주입된 업스트림으로 전달하는
proxy_pass를 가진 최소한의 NGINX server 블록을 작성한 다음 nginx를 포그라운드로 시작합니다. Kubernetes 대상은 이를 외부 Helm 차트 없이 상태 비저장 Deployment와 ClusterIP Service로 구현합니다. - 재현 가능한 이미지. Kubernetes 대상은 명시적 태그로 고정된 공식 업스트림 nginx 이미지를 실행하므로, 렌더링된 Deployment는 안정적인 이미지를 참조합니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example nginx-gateway그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd nginx-gateway빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized manifests)aggrega build --release release-helm-synth.yaml --auto-pull렌더링된 아티팩트는 dist/ 아래에 생성됩니다. Kubernetes 대상은 오프라인으로
일반 매니페스트를 렌더링하므로 차트를 가져올 필요가 없습니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. Workspace 폴더에 아직 `nginx-gateway` 폴더가 없으면 `example`을 `nginx-gateway`로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `nginx-gateway` 폴더에 예제가 작성됩니다. 그런 다음 각 Release마다 `release-compose.yaml`, `release-helm-synth.yaml` 순서로 `build` 도구를 한 번씩 호출하되, 매번 `workspace_root`를 `nginx-gateway`로, `release`를 해당 파일로, `auto_pull`을 true로, `write`를 true로 설정하십시오. 각 빌드가 작성한 파일을 알려 주십시오. 파일은 `nginx-gateway/dist/` 아래에 있습니다.주입된 업스트림의 모습
Compose에서는 게이트웨이 서비스가 백엔드의 compose 서비스 이름과 포트를 가리키는 server 블록으로 NGINX를 실행합니다.
server { listen 8000; location / { proxy_pass http://web:8080; } }Kubernetes에서는 같은 라우팅이 nginx를 시작하기 전에 server 구성을 작성하는
컨테이너 명령에 담겨 백엔드의 Service를 가리킵니다.
helm provider는 이 Service의 이름을 백엔드와 그 default 서비스 키를 따라 짓습니다.
server { listen 8080; location / { proxy_pass http://web-default:8080; } }두 경우 모두 동일한 Aggregate 엣지에서 해석됩니다. 백엔드 호스트와 포트는
upstream 사용을 통해 전달되고, 각 대상은 이를 고유한 방식으로 렌더링합니다.
실행하기(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dhttp://localhost:8000을 열면 NGINX가 요청을 백엔드로 전달합니다. 종료하려면 docker compose -f dist/app/compose/docker-compose.yaml down을 실행합니다.