경계를 넘는 네트워킹 — 하나의 의도, 두 가지 배포
두 개의 구성 요소로 이루어진 스택 — Adminer 데이터베이스 UI와 PostgreSQL 데이터베이스 — 를 두 개의 경계로 나누며, Adminer는 경계의 이음매를 넘어 데이터베이스에 도달해야 합니다. 동일한 개발자 의도가 두 가지 방식으로 배포되며, 그 대비가 바로 교훈입니다:
- 로컬(Docker Compose): 각 경계는 자체 compose 네트워크이며, 한 네트워크의 서비스는 다른 네트워크의 서비스에 이름으로 도달할 수 없습니다. 표준 라이브러리
core/compose-bridgeFeature의 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 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example cross-boundary-networking그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd cross-boundary-networking빌드
각 변형은 하나의 Release이며, 자체 카탈로그 디렉터리를 대상으로 빌드하고 실행마다 Release 하나를 빌드합니다:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmAI 어시스턴트 사용
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): 브리지
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega 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은 게이트웨이의 nginxstream구성을 기록하며, 이 구성은 마운트된 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 경로로 흐르며, 게이트웨이를 통해
네트워크 경계를 넘습니다.
실행하기
cd dist/bridge/composedocker compose up**http://localhost:8080**을 열고(서버에 aggrega-gw:5432가 미리 입력됨) 로그인합니다:
| 필드 | 값 |
|---|---|
| 시스템 | PostgreSQL |
| 서버 | aggrega-gw:5432(미리 입력됨) |
| 사용자 이름 | appuser |
| 비밀번호 | apppass |
| 데이터베이스 | appdb |
이 자격 증명은 데모 전용입니다(스택이 별도 설정 없이 바로 실행되도록 db recipe에 인라인으로 설정됨). 실제 배포에서는 자격 증명 하위 시스템을 사용합니다.
Variant B — Kubernetes (Helm): 네임스페이스 + 네임스페이스 간 DNS
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helm같은 Aggregate를 Kubernetes에 배포합니다. 두 개의 형제 경계가 있으며, 각각 서로 다른 aggrega.ai/namespace
어노테이션을 가지고, 이 어노테이션은 모든 리소스에 metadata.namespace로 전파됩니다:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendaggrega-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를 생성합니다. 호스트는 생산자에 직접 작성되는 것이 아니라 도출됩니다:
- 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 대상입니다.