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

경계를 넘는 네트워킹 — 하나의 의도, 두 가지 배포

두 개의 구성 요소로 이루어진 스택 — Adminer 데이터베이스 UI와 PostgreSQL 데이터베이스 — 를 두 개의 경계로 나누며, Adminer는 경계의 이음매를 넘어 데이터베이스에 도달해야 합니다. 동일한 개발자 의도가 두 가지 방식으로 배포되며, 그 대비가 바로 교훈입니다:

  • 로컬(Docker Compose): 각 경계는 자체 compose 네트워크이며, 한 네트워크의 서비스는 다른 네트워크의 서비스에 이름으로 도달할 수 없습니다. 표준 라이브러리 core/compose-bridge Feature의 compose FeatureRecipe는 그 이음매를 넘기 위해 aggrega-gw 게이트웨이를 생성합니다.
  • Kubernetes(Helm): 각 경계는 자체 네임스페이스이며, 한 네임스페이스의 파드는 네이티브 네임스페이스 간 DNS(db-default.backend)를 통해 다른 네임스페이스의 Service에 도달합니다 — 브리지가 없습니다. 데이터베이스는 한정되지 않은 서비스 이름을 게시하고, 소비자의 core/k8s-dns-resolver 라우팅 기능이 이를 대상 네임스페이스로 한정합니다.

compose-bridge는 Kubernetes 네임스페이스와 네임스페이스 간 DNS가 기본으로 제공하는 것입니다. 이음매를 넘는 일은 대상에 따라 달라지는 Ops/Operator의 관심사이며, 개발자 의도는 바뀌지 않습니다. 동일한 aggrega.ai/namespace 경계 어노테이션이 한 변형에서는 compose 네트워크 배치를, 다른 변형에서는 Kubernetes 네임스페이스 배치를 결정합니다.

공유되는 개발자 의도

aggregate.yaml은 두 변형 모두에서 동일합니다.

components:
adminer:
type: core/devtool/adminer
uses:
databases:
primary:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant
from: host # ← the target db's provides.host
db:
type: core/datastore/postgres

하나의 uses 에지가 데이터베이스의 host를 ADMINER_DEFAULT_SERVER에 주입합니다. 그 호스트가 무엇으로 해석되는지는 Aggregate 아래에서 결정되는 Ops의 관심사입니다. 따라서 같은 에지가 compose에서는 aggrega-gw:5432를, helm에서는 db-default.backend를 만들어 내며, 개발자 의도는 바뀌지 않습니다.

예제 생성하기

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

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

Terminal window
aggrega scaffold --example cross-boundary-networking

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

Terminal window
cd cross-boundary-networking

빌드

각 변형은 하나의 Release이며, 자체 카탈로그 디렉터리를 대상으로 빌드하고 실행마다 Release 하나를 빌드합니다:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

AI 어시스턴트 사용

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

Aggrega 도구만 사용하고, 폴더는 직접 만들지 마십시오. 작업 영역 폴더에 아직 `cross-boundary-networking` 폴더가 없으면 `example`을 `cross-boundary-networking`으로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하십시오. 이 도구는 예제를 새 `cross-boundary-networking` 폴더에 씁니다. 그런 다음 `workspace_root`를 `cross-boundary-networking`으로, `release`를 `release-compose.yaml`로, `catalog_dirs`를 `catalog-compose`가 담긴 목록으로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 그런 다음 같은 방식으로 `release`를 `release-helm.yaml`로, `catalog_dirs`를 `catalog-helm`이 담긴 목록으로 설정하여 `build` 도구를 호출하십시오. 각 빌드가 쓴 파일을 알려 주십시오. 파일은 `cross-boundary-networking/dist/` 아래에 있습니다.

변형 A — 로컬(Docker Compose): 브리지

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose

상위 bridge 경계는 두 개의 하위 경계 frontend(adminer)와 backend(db)를 포함하며, 두 경계는 하나의 디렉터리를 공유하므로 단일 dist/bridge/compose/docker-compose.yaml로 병합됩니다. 각 하위 경계의 aggrega.ai/namespace 애너테이션은 compose 네트워크가 됩니다. 상위 경계(경계 범위)에 연결된 core/compose-bridge는 네트워크를 가로지르는 uses 엣지로부터 aggrega-gw 게이트웨이를 도출합니다. 그 표준 라이브러리 FeatureRecipe는 경계마다 한 번, 브리지할 엣지의 표(양 끝이 이 하나의 compose 파일 안에 있되 서로 다른 네트워크에 있는 엣지)를 계산하며, 아래의 모든 것은 자체 템플릿이 그 표에서 읽어 냅니다:

  • 그 valuesMapping은 게이트웨이의 nginx stream 구성을 기록하며, 이 구성은 마운트된 compose config(최상위 configs:, /etc/nginx/nginx.conf에 마운트됨)로 전달됩니다. 이 구성에는 resolver와 엣지별 변수 proxy_pass가 포함되어 있어 업스트림이 연결 시점에 확인됩니다(Compose의 보간이 nginx를 위해 그대로 두도록 $는 $$로 이스케이프됩니다);
  • 같은 valuesMapping이 게이트웨이의 x-aggrega-networks-of 아래에 양 끝을 지정하고 compose 프로바이더가 이를 해석하므로, 게이트웨이는 브리지되는 두 네트워크에 모두 참여합니다;
  • adminer에 대해 실행되는 그 injectMapping은 소비자의 ADMINER_DEFAULT_SERVER를 aggrega-gw:5432로 다시 작성합니다. 이 재작성은 adminer 자체의 databases 연결이 전달한 값을 대체합니다. 만약 adminer에 연결된 다른 Feature가 그 변수를 전달했다면, 빌드는 값을 대체하는 대신 둘 모두를 명시하며 중단됩니다.

따라서 트래픽은 adminer → aggrega-gw:5432 → proxy_pass db:5432 경로로 흐르며, 게이트웨이를 통해 네트워크 경계를 넘습니다.

실행하기

Terminal window
cd dist/bridge/compose
docker compose up

**http://localhost:8080**을 열고(서버에 aggrega-gw:5432가 미리 입력됨) 로그인합니다:

필드값
시스템PostgreSQL
서버aggrega-gw:5432(미리 입력됨)
사용자 이름appuser
비밀번호apppass
데이터베이스appdb

이 자격 증명은 데모 전용입니다(스택이 별도 설정 없이 바로 실행되도록 db recipe에 인라인으로 설정됨). 실제 배포에서는 자격 증명 하위 시스템을 사용합니다.

Variant B — Kubernetes (Helm): 네임스페이스 + 네임스페이스 간 DNS

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

같은 Aggregate를 Kubernetes에 배포합니다. 두 개의 형제 경계가 있으며, 각각 서로 다른 aggrega.ai/namespace 어노테이션을 가지고, 이 어노테이션은 모든 리소스에 metadata.namespace로 전파됩니다:

dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/backend/helm/db-headless-service.yaml # metadata.namespace: backend

aggrega-gw는 없습니다. helm db recipe는 provides.host에 순수한 서비스 이름을 게시합니다. helm provider는 합성된 Service의 이름을 <rendered_name>-<service-key>(db-default)로 지정하며, 네임스페이스는 포함하지 않습니다. 소비자는 core/k8s-dns-resolver 라우팅 feature를 연결하고(Release가 이를 ADMINER_DEFAULT_SERVER에 지정합니다), 이 feature는 소비자 자신의 측에서 그 순수한 호스트를 대상의 네임스페이스로 한정하여, Adminer가 렌더링되기 전에 네임스페이스 간 DNS 이름 db-default.backend를 생성합니다. 호스트는 생산자에 직접 작성되는 것이 아니라 도출됩니다:

dist/frontend/helm/adminer-deployment.yaml
- name: ADMINER_DEFAULT_SERVER
value: db-default.backend # == the rendered db Service <name>.<namespace>

이 값은 렌더링된 db Service의 metadata.name + metadata.namespace와 바이트 단위로 일치하며, 이것이 증명의 전부입니다. Kubernetes 네임스페이스 간 DNS는 결정적인 계약이므로, 렌더링된 호스트가 렌더링된 Service 식별자와 같으면 런타임에 해석됩니다. 게이트웨이도 필요 없고, 연결을 검증하기 위한 실제 클러스터도 필요 없습니다.

이중성

compose (Variant A)helm (Variant B)
경계 이음매별도의 compose 네트워크별도의 네임스페이스
경계 통과 메커니즘core/compose-bridge 게이트웨이(aggrega-gw)네이티브 네임스페이스 간 DNS
ADMINER_DEFAULT_SERVER의 해석 결과aggrega-gw:5432(재작성됨)db-default.backend(호출자 측에서 한정됨)
추가 리소스aggrega-gw 서비스와 그 구성없음
동일한 aggrega.ai/namespace가 결정하는 것compose 네트워크 배치k8s 네임스페이스 배치

개발자 의도는 하나이며, 이음매 통과는 provider별 Ops/Operator 메커니즘입니다. 평면적인 compose 네트워크에는 네임스페이스 범위의 DNS가 없기 때문에 compose 브리지가 존재하며, Kubernetes는 이를 기본으로 제공합니다.

두 끝이 서로 다른 provider에서 렌더링될 때

위의 두 변형은 모두 하나의 개발자 의도를 유지하면서 경계 넘기를 결정적 포인터 문자열에 맡깁니다. 데이터베이스의 provides.host는 안정적인 포인터로서 경계 이음매를 넘어 전달되고, 각 대상은 그 포인터를 자신만의 방식으로 해석합니다. compose 게이트웨이 주소일 수도 있고, 네임스페이스 간 DNS 이름일 수도 있습니다. 컴파일러는 생산자와 소비자 사이에서 문자열을 해석하지 않고 그대로 전달하므로, 포인터는 항상 경계를 넘습니다.

provider는 한 걸음 더 나아가 이음매 양쪽에 있는 자신의 조립된 아티팩트 두 개 사이에 네이티브 교차 참조를 연결할 수도 있습니다. 이는 해당 provider 고유의 어휘로 된 참조로, 대상 플랫폼이 배포 시점에 해석합니다. CloudFormation provider는 스택을 넘나드는 uses 엣지에 대해 이렇게 합니다. 생산자 스택이 Export를 게시하고 소비자 스택이 Fn::ImportValue로 이를 읽습니다(providers/cloudformation.md 참조). 네이티브 교차 참조는 동일 provider 내의 개선입니다. 양쪽 끝이 같은 아티팩트 어휘를 사용하기 때문에, 한쪽이 게시한 참조를 다른 쪽이 해석할 수 있어서 동작합니다.

uses 엣지가 서로 다른 두 provider 사이의 경계를 넘을 때, 즉 생산자는 한 provider에서, 소비자는 다른 provider에서 조립될 때는 네이티브 교차 참조가 불가능합니다. 한 provider의 어휘로 만들어진 참조는 다른 provider에게 아무 의미가 없으며, 컴파일러는 둘 사이를 변환하지 않습니다. 컴파일러는 문자열을 전달할 뿐, 의미를 추론하거나 한 provider의 참조를 다른 provider의 형식으로 다시 쓰지 않습니다. 따라서 생산자의 결정적 포인터는 이음매를 그대로 넘습니다. 두 provider 중 어느 하나가 CloudFormation처럼 자체 네이티브 교차 참조를 연결하는 경우, 컴파일러는 양쪽 엔드포인트, 두 provider 이름, 소켓을 명시하는 경고를 내보냅니다. 그리고 빌드는 그 포인터로 완료됩니다. 컴파일러는 작성자를 신뢰하며 중단하지 않습니다. 작성자가 제공한 결정적 포인터는 이음매를 넘어서도 충분히 해석 가능할 수 있으며(안정적인 DNS 이름이나 인프라 보간 문자열 등), 대상 토폴로지는 작성자만이 알고 있습니다.

이렇게 하면 이음매 넘기가 본래 있어야 할 곳에 머무릅니다. provider 간 포인터가 사용 가능한지는 작성자가 책임지는 배포상의 문제입니다. 한 provider의 네이티브 참조를 다른 provider의 소비자 형식으로 변환하는 것은 주관이 개입된 provider별 작업이며, 중립적인 코어 바깥에 속합니다.

구성

cross-boundary-networking/
├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry
├── aggregate.yaml # SHARED developer intent (both variants)
├── release-compose.yaml # Variant A: parent bridge boundary + two networks
├── manifest-compose.yaml
├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)
├── release-helm.yaml # Variant B: two namespace boundaries, no bridge
├── manifest-helm.yaml
└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)

이 예제는 표준 라이브러리를 사용합니다. 각 변형은 자체 로컬 디렉터리를 가리키는 --catalog catalog-<variant>로 빌드하고, 그 디렉터리가 선언하지 않은 것은 .aggrega-config.yaml이 지정하는 기본 레지스트리인 hub.aggrega.ai에서 해석하므로, 로컬 엔터티가 공유 엔터티보다 먼저 해석됩니다. core/datastore/postgres, 공유 core/devtool/adminer UI 컴포넌트, core/compose-bridge 및 core/k8s-dns-resolver Features와 그 compose 및 helm FeatureRecipes, 그리고 compose/helm 프로바이더는 표준 카탈로그에서 가져옵니다. 로컬에 남는 것은 예제 고유의 학습용 콘텐츠, 즉 대상별 Adminer 레시피입니다. helm db 레시피는 표준 라이브러리의 helm/postgres이며, 그 provides.host는 접두사 없는 독립적인 서비스 이름입니다. 소비자는 표준 라이브러리의 core/k8s-dns-resolver 라우팅 기능을 통해 호출자 측에서 대상 네임스페이스로 이를 한정하므로, 레시피는 경계 네임스페이스를 하드코딩하지 않습니다.

빌드된 변형에는 두 범주의 파일이 있습니다. 직접 작성한 입력(위의 모든 것)과 dist/ 아래의 컴파일러가 생성한 출력(병합된 docker-compose.yaml 또는 네임스페이스별 helm 매니페스트)입니다. 후자는 직접 작성하지 않습니다. dist/는 aggrega build가 다시 생성하며 gitignore 대상입니다.