경로 템플릿 변수
Release 경계의 directory: 및 subDirectory: 필드는 빌드 시점에 평가되는 Go 템플릿입니다. 이 필드들은 렌더링된 아티팩트가 디스크의 어디에 놓일지를 제어하며, 나아가 어떤 아티팩트가 함께 조립될지도 결정합니다. 동일한 (path, provider) 튜플로 평가되는 두 경계는 하나의 어셈블러를 공유하고 병합된 하나의 출력(하나의 Chart.yaml, 하나의 docker-compose.yaml)을 생성합니다. 이 페이지는 이러한 템플릿이 참조할 수 있는 변수, 엄격한 평가 의미론, 그리고 경계가 부모로부터 상속할 수 있게 하는 캐스케이드 규칙에 대한 작성 참조 문서입니다.
공간적 분리와 (path, provider)별 디스패치에 대한 개념적 설명은 architecture/16-recipe-input-composition.md를 참조하십시오. 엔터티 수준의 Release 작성 인터페이스는 entities/release.md를 참조하십시오. provider 측의 영향은 providers/architecture.md와 각 provider별 페이지에서 다룹니다.
엄격한 평가: missingkey=error
경로 템플릿은 Go의 missingkey=error 모드로 평가됩니다. 선언되지 않은 필드, 설정되지 않은 parameters.X 키, 또는 {{ .parmaeters.region }} 같은 오타를 참조하면 경로에 빈 문자열을 조용히 렌더링하는 대신 명시적인 오류가 발생합니다.
이 엄격성은 컴파일러의 나머지 부분과 비대칭입니다. valuesMapping, injectMapping 및 그 밖의 값 렌더링 영역은 Helm/Sprig 관례에 따라 missingkey=zero를 사용합니다. 경로 생성은 구조적으로 다릅니다. 빈 문자열을 생성하는 값 렌더링 템플릿은 그 결과가 한정된 manifest 필드에 들어가지만, 빈 문자열을 생성하는 경로 템플릿은 그 결과가 한정되지 않는 디렉터리 레이아웃에 들어갑니다(충돌, 깨진 조립, 유령 경로). 엄격한 경로 템플릿 체계는 이러한 실패를 배포 시점이 아닌 빌드 시점에 드러내기 위해 존재합니다.
파싱 시점 허용 목록 검증
런타임 엄격성에 더해, 경로 템플릿은 파싱 시점에 닫힌 변수 이름 허용 목록에 대해 검증됩니다. 허용 목록에 없는 변수 이름을 참조하면 렌더링 작업이 시작되기 전에 빌드가 중단되며, 문제가 된 필드와 그 필드가 나타나는 경계를 명시하는 진단이 출력됩니다.
허용 목록은 설계상 닫혀 있습니다. .context.inject, .values, .locals 같은 표면은 의도적으로 경로 템플릿에 노출되지 않습니다. 경로 출력은 구조적 관심사이지 값 렌더링 관심사가 아닙니다. 조립 경로를 컴포넌트별 값에 연결하면 경로 그래프가 데이터에 의존하게 되어 결정적 출력 불변식이 약화됩니다.
변수 매트릭스
| 변수 | directory: | subDirectory: | 설명 |
|---|---|---|---|
{{ .capability }} | 예 | 예 | 이 경로에 출력되는 아티팩트에 대해, 기여하는 컴포넌트의 Recipe가 선언하는 렌더링 기능(helm, helm-chart, compose, terraform, cloudformation)입니다. |
{{ .boundary_name }} | 예 | 예 | Release에서 작성된 경계의 이름입니다(예: production, eu-prod). |
{{ .parameters.X }} | 예 | 예 | Aggregate에 선언되고 Release가 값을 채운 모든 타입 지정 매개변수입니다. 엄격한 접근이 적용되어 .parameters.unknown을 참조하면 빌드가 중단됩니다. |
{{ .manifest.recipe_name }} | 예 | 예 | 기여하는 컴포넌트에 대해 Manifest를 통해 해석된 Recipe 이름입니다. Recipe별 아티팩트를 Recipe별 하위 폴더로 라우팅할 때 유용합니다. |
{{ .parent_boundary.* }} | 예 | 예 | 둘러싼 경계의 평가된 값에 대한 캐스케이드 접근입니다. 아래의 상위 경계 캐스케이드를 참조하십시오. |
{{ .component_id }} | — | 예 | 기여하는 컴포넌트의 인스턴스 ID입니다. 경계에 연결되고 그 FeatureRecipe가 경계당 한 번 실행되는(executionScope: boundary) Feature의 경우, 해당 연결의 리소스가 aggrega.ai/component-id 레이블에 갖는 합성 식별자입니다 — 경계 app의 연결 shared라면 bfr--app--shared이며, 연결의 프로바이더가 이름 길이를 제한하는 경우 축약됩니다 — 따라서 연결의 출력은 그 레이블의 이름을 딴 디렉터리에 놓입니다. directory:는 경계별 속성이므로 subDirectory:에서만 사용할 수 있습니다 — 디렉터리 문자열은 컴포넌트별 라우팅이 일어나기 전에 경계마다 한 번 계산됩니다. |
directory: 필드의 기본값은 boundaries/ 뒤에 경계 경로(경계 트리에서 파생된 안정적인 빌드 시점 식별자)를 붙인 것입니다. 경계를 선언하지 않고 컴포넌트를 나열하는 Release는 디렉터리 세그먼트 없이 컴포넌트를 씁니다. subDirectory: 필드의 기본값은 {{ .capability }}이므로, 생략하든 subDirectory: ""로 쓰든(이는 생략한 것과 똑같이 해석됩니다) 각 기능의 아티팩트는 경계 디렉터리 아래 각자의 하위 폴더에 놓입니다. subDirectory: "."로 설정하거나 빈 문자열로 평가되는 템플릿을 작성하면 이 그룹화가 평탄화됩니다.
이 템플릿이 결정하지 않는 것: artifacts: 배치
출력 경로의 한 세그먼트는 경로 템플릿이 설정하는 것이 아닙니다. Recipe의 artifacts: 블록이 명명하는 파일은 subDirectory:가 평가된 결과 안에서, 해당 파일을 선언한 컴포넌트의 이름을 딴 디렉터리 아래에 쓰입니다. 각 기여자를 자체 차트나 모듈에 중첩하지 않고 기여자들의 파일을 나란히 쓰는 대상의 경우, 이 세그먼트는 고정되어 있으며 항상 존재합니다.
그 이유는 파일의 이름을 정하는 주체에 있습니다. 대상이 렌더링하거나 합성하는 매니페스트는 대상이 그것이 속한 컴포넌트를 기준으로 이름을 붙이므로 이미 해당 컴포넌트를 식별합니다. 아티팩트는 작성자가 쓴 키(app-config.yaml, netpol.yaml)로 이름이 정해지며, 그 키는 컴포넌트에 대해 아무것도 알려 주지 않습니다. 아티팩트를 선언하는 Recipe는 어떤 컴포넌트가 자신에게 바인딩될지 모르기 때문입니다. 한 경계에서 하나의 Recipe에 바인딩된 두 컴포넌트는 같은 경로에 쓰게 되며, Recipe 작성자도 Release 작성자도 이를 분리할 수단을 갖고 있지 않습니다.
디렉터리만 추가되고 파일 이름은 작성된 키 그대로 유지되므로, 작성자가 출력에서 다시 읽는 파일은 자신이 쓴 이름을 가집니다.
subDirectory:가 여전히 제공하는 것과 둘의 조합 방식. subDirectory:는 기여자가 내보내는 모든 파일(렌더링된 매니페스트, 합성된 매니페스트, 아티팩트 모두)을 이동시킵니다. 따라서 단일 컴포넌트의 전체 매니페스트 집합을 대상으로 동작하는 다운스트림 도구를 위해 한 컴포넌트에 자체 디렉터리를 주거나, 여러 컴포넌트를 하나의 공유 폴더로 라우팅할 때 쓰는 도구입니다. artifacts: 세그먼트는 그 평가 결과의 아래에 적용됩니다. 따라서 Recipe가 artifacts:를 선언하는 컴포넌트에 subDirectory: "{{ .capability }}/{{ .component_id }}"를 쓰면 컴포넌트 이름이 두 번 나타납니다. 아티팩트는 <capability>/<component>/<component>/<key>에 놓이고, 해당 컴포넌트의 렌더링된 매니페스트는 <capability>/<component>/<key>에 놓입니다. 컴포넌트의 전체 출력을 모으고 싶을 때 재정의를 사용하고, 아티팩트 분리만 필요할 때는 생략하십시오. 기본값이 이미 그렇게 합니다.
.capability는 컴포넌트별로 해석되며, 경계의 directory:는 서로 다른 두 가지 목적으로 평가됩니다. 하위 경계에 .parent_boundary.directory를 공개하는 경계별 평가는 컴포넌트가 바인딩되기 전에 실행되므로 그 시점에 .capability는 비어 있습니다. 기여자의 아티팩트가 실제로 놓일 위치를 정하는 컴포넌트별 평가에는 해당 컴포넌트의 기능이 들어 있습니다. 따라서 directory: "d-{{ .capability }}"를 작성한 상위 경계는 캐스케이드 아래로 d-를 공개하지만, 자신의 아티팩트는 d-compose 아래에 놓입니다.
상위 경계 캐스케이드
중첩된 경계는 바로 위 상위 경계의 평가된 경로와 그 경계 자체의 캐스케이드로 해석된 데이터를 노출하는 .parent_boundary 뷰를 받습니다. 캐스케이드는 한 단계입니다. 경계의 .parent_boundary는 조부모가 아니라 직계 상위 경계입니다. 더 위로 거슬러 올라가려면 상위 경계 자체가 자신의 템플릿에서 .parent_boundary를 사용하여 값을 트리 아래로 명시적으로 전파합니다.
.parent_boundary 아래에서 사용할 수 있는 필드:
| 필드 | 설명 |
|---|---|
.parent_boundary.directory | 상위 경계의 평가된 directory: 값(템플릿 적용 후). |
.parent_boundary.boundary_name | 상위 경계의 작성된 이름. |
.parent_boundary.parameters | 상위 경계가 본 것과 동일한 .parameters.* 맵(매개변수 값은 Release 전역이지만, 대칭성을 위해 이 별칭이 제공됩니다). |
.parent_boundary.annotations | 상위 경계의 캐스케이드로 해석된 주석. |
표준 패턴은 directory:를 한 번 작성하는 상위 경계와, directory: "{{ .parent_boundary.directory }}"를 선언하여 자신의 아티팩트를 상위 경계 아래로 라우팅하는 하위 경계들입니다. 이렇게 하면 하위 경계들이 상위 경계의 어셈블리 경로로 합쳐져, 모든 하위 경계의 기여자를 포함하는 하나의 병합된 출력이 만들어집니다. core/compose-bridge Feature는 정확히 이 방식에 의존합니다. 브리지 기능을 보유한 상위 경계 하나, 상위 경계의 directory:를 공유하는 하위 경계 두 개(예: services-net과 data-net), 그리고 모든 구성 요소와 브리지 서비스를 포함하는 병합된 docker-compose.yaml 하나로 구성됩니다.
반대 경우는 이렇습니다. 하위 경계에서 .parent_boundary.directory를 생략하면(또는 별개의 경로로 평가되게 하면) 각 하위 경계가 자체 어셈블리를 갖습니다. 두 형태 모두 정식으로 지원됩니다.
레이아웃 예제
레이아웃 1 — 기본 경계별 분리
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}각 경계가 서로 다른 directory:로 평가되므로 각각 자체 어셈블리를 갖습니다:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...기본값 subDirectory: "{{ .capability }}"는 각 경계 디렉터리 안에서 capability별 아티팩트를 분리합니다. 경계 두 개, capability마다 어셈블리 출력 두 개이며 병합은 없습니다.
레이아웃 2 — 공유 부모 디렉터리를 통한 통합 어셈블리
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}두 자식 경계 모두 directory:를 deploy/cluster(부모의 디렉터리)로 평가하므로 모든 기여자가 하나의 어셈블리 경로에서 병합됩니다. 기본값 subDirectory: "{{ .capability }}"를 사용하면 두 자식의 compose 기여자가 deploy/cluster/compose/에 모여 병합된 docker-compose.yaml 하나를 생성합니다. 부모에 연결된 compose-bridge Feature는 한 번 실행되며(경계 범위 디스패치) 같은 병합 파일에 브리지 서비스를 추가합니다.
부모의 aggrega.ai/chart-name: "cluster-umbrella" 어노테이션은 두 자식 모두에 캐스케이드됩니다. 경계에 helm-chart 기여자도 있다면 두 자식의 helm-chart 하위 차트는 cluster-umbrella라는 이름의 umbrella 하나 아래에 구성됩니다. 한 경로의 기여자들 사이에서 chart-name 값이 일치하지 않으면 빌드가 중단됩니다.
레이아웃 3 — subDirectory:와 파라미터를 통한 컴포넌트별 라우팅
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"경계의 directory:는 deploy/eu-west-1로 평가됩니다(파라미터 치환). 컴포넌트별 subDirectory: 재정의가 각 기여자를 컴포넌트별 하위 폴더로 라우팅하며, ingress 컴포넌트는 여러 영역에 걸친 아티팩트를 위해 평탄한 shared 하위 폴더로 재정의합니다:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...이 패턴은 단일 컴포넌트의 매니페스트를 대상으로 동작하는 다운스트림 도구를 위해 컴포넌트별 아티팩트 디렉터리를 원하는 기업에 적합합니다. 컴포넌트의 Recipe가 artifacts:도 선언한다면 이 형태를 선택하기 전에 위의 이 템플릿이 결정하지 않는 것을 읽으십시오. 해당 파일에는 이미 컴포넌트 세그먼트가 있으므로 이 재정의는 두 번째 세그먼트를 추가합니다.
진단
경로 템플릿 영역은 다음 각 상황에서 빌드를 중단하며, errors/fatal-halts.md에서 이 이름으로 문서화합니다. 해당 페이지에는 각 중단이 출력하는 메시지가 인용되어 있으므로, 빌드 출력을 그 텍스트와 대조하십시오.
- Path-template references a variable outside the allowlist (경로 템플릿이 허용 목록 밖의 변수를 참조함) — 파싱 시점: 경로 템플릿이 허용 목록에 없는 변수를 참조합니다.
- Path collision (경로 충돌) — 어셈블리 시점: 두 경계 기여자가 같은 경로로 평가되지만, 해당 경로의 기여자 사이에서 동일해야 하는 속성의 값이 서로 다릅니다.
- Instance-ID collision (인스턴스 ID 충돌) — 어셈블리 시점: 같은
(path, provider)튜플로 평가되는 두 경계가 동일한 인스턴스 ID를 가진 컴포넌트를 기여합니다. - Chart-name mismatch (차트 이름 불일치) — 어셈블리 시점: 병합된 helm-chart 어셈블리가 캐스케이드로 해석된
aggrega.ai/chart-name어노테이션이 서로 충돌하는 기여자를 받습니다. - Missing template key (템플릿 키 누락) — 경로 템플릿이 값으로 해석되지 않는 열린 변수 아래의 필드를 참조합니다(예: Release가
region을 생략했을 때의{{ .parameters.region }}, 또는 부모가 없는 최상위 경계에서의.parent_boundary키).missingkey=error는 경계, 템플릿 필드(directory:또는subDirectory:), 누락된 키를 명시하는 메시지를 생성합니다..parameters와.parent_boundary는 열려 있어 그 키가 작성된 데이터인 반면,.manifest는 자신의 키를 선언하므로.manifest아래의 잘못 입력된 키는 대신 파싱 시점에 알 수 없는 참조로 거부되며, 진단에는.manifest가 정의하는 키가 나열됩니다.
상호 참조
entities/release.md— 공간적 분리와directory:/subDirectory:필드를 포함한 Release 작성.providers/architecture.md— provider 디스패치와(path, provider)별 어셈블리 모델.providers/compose.md— 병합 경로 시나리오를 포함한 compose 측의(path, provider)별 출력.providers/helm-chart.md— helm-chart 엄브렐라 구성과 병합 경로에 대한 chart-name 캐스케이드 규칙.entities/featurerecipe.md— 경계 범위 FeatureRecipes(core/compose-bridgeFeature는 이 문서에서 설명하는 병합 경로 어셈블리 모델에 의존합니다).errors/fatal-halts.md— 위에 열거한 경로 디스패치 중단을 포함한 전체 진단 목록.