템플릿 확장 매트릭스
템플릿 확장 참조 — 전체 매트릭스
Aggrega DSL은 YAML 엔터티 전반의 여러 위치에서 Go text/template 확장(Sprig 라이브러리가 미리 등록됨)을 지원합니다. 각 위치에는 컴파일이 진행되면서 데이터가 구체화되는 시점에 따라 정해지는 사용 가능한 참조 집합이 있습니다. 이 페이지는 어디에서 무엇을 참조할 수 있는지에 대한 참조 문서입니다.
1. 파이프라인 타이밍 트리(데이터가 구체화되는 시점)
사용 가능한 참조를 이해하려면 각 데이터가 언제 해석되는지 이해해야 합니다. 아래 단계는 실행 순서대로 나열되어 있으며, 각 단계는 하는 일에 따라 이름이 붙어 있습니다. 이 페이지의 나머지 부분에서는 그 이름으로 각 단계를 가리킵니다.
Resolution — resolver and syntax validator ├── .parameters → Interpolated into the Aggregate's text; the merged map │ then stays readable to path templates only ├── .values → schema-validated against the Component's pillar schema, concrete ├── .infra → Release-merged into target components/features, concrete └── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction ├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db") └── .context.labels → From Catalog + label-transform mutations
Graph finalization ├── .context.annotations.release → Cascaded from boundary hierarchy ├── .context.annotations.catalog → From Component metadata.annotations ├── .context.annotations.aggregate → Cascaded from subsystem hierarchy └── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides ├── .context.rendered_name → Asked of each node's provider before the preamble; present only where │ that provider derives a name for the node's output ├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings └── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution └── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution └── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception └── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering └── Full template context → Everything available
The plugin pipeline — post-render mutation └── Full template context + .steps → Inter-step pipeline outputs available2. 템플릿 확장 매트릭스
DSL에서 Go 템플릿 표현식이 평가되는 모든 위치와 각 위치에서 사용 가능한 참조는 정확히 다음과 같습니다.
| # | Location | 엔터티 | 평가 단계 | 사용 가능한 참조 |
|---|---|---|---|---|
| 1 | Aggregate YAML 문자열의 {{ .parameters.X }} | Aggregate | 해석(보간) | .parameters만 가능합니다. 다른 모든 데이터는 아직 해석되지 않았습니다. |
| 2 | Release YAML 문자열의 {{ .parameters.X }} | Release | 평가되지 않음 | 없음. Release의 문자열은 작성된 그대로 읽힙니다. infra: 아래, 어노테이션 안, 또는 parameters: 값으로 쓴 {{ .parameters.X }}는 그 리터럴 텍스트 그대로 목적지에 도달합니다. Release는 매개변수 값을 제공하며(인라인 parameters: 맵과 $import:로 불러온 값이 병합된 매개변수 맵으로 결합됨), Aggregate의 문자열이 이를 읽고(#1), 경로 템플릿도 읽습니다(#3). |
| 3 | directory / subDirectory 템플릿 | Release 경계 | 렌더링(경로 평가) | .capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.*, 그리고 .component_id(subDirectory:에서만 가능하며, directory: 템플릿은 이를 거부합니다). |
| 4 | Component inject value: 문자열 | Aggregate 컴포넌트 | 자기 주입 해석 | .values, .infra, .context.instance_id, .context.labels, .context.annotations.*(3개 버킷 모두), .metadata.*(release_name, release_version, environment, aggregate_name). 금지: .context.inject(순환 — 파이프가 구성되는 중), .context.uses(컴포넌트 간 연결에는 대신 uses[].inject를 사용). 이 템플릿은 Aggregate의 텍스트 안에 있고 #1의 매개변수 보간이 그 텍스트를 먼저 읽으므로, 이 단계에 도달하려면 이스케이프하여 작성합니다 — value: '{{"{{"}} .metadata.release_name }}'. 그대로 작성하면 보간이 이를 평가하고 중단됩니다. Aggregate의 텍스트는 .parameters 외에는 어떤 루트도 정의하지 않기 때문입니다. |
| 5 | source 필드 문자열(최상위 문자열 또는 구조화된 source: 맵의 문자열 값 하위 필드) | Recipe / FeatureRecipe | 소스 해석 | 소스가 가리키는 대상에 따라 정해지는 두 가지 표면. 원격 좌표 — 레지스트리, 차트 저장소 또는 git 저장소를 가리키는 구조화된 블록의 version, chart, ref, module_subdir — 는 aggrega pull이 아티팩트를 고정하기 위해 해석할 때 평가됩니다. 이때는 .values, .infra, .locals와 정적 문자열만 사용할 수 있고, Aggrega 자체 헬퍼(optional, capitalizedWords, index)만 쓸 수 있으며 Sprig 함수는 쓸 수 없고, .context 루트도 없습니다. 이때 평가되는 .locals 항목은 해당 필드가 직접 또는 다른 항목을 거쳐 읽는 항목이며, 필드가 특정 항목 하나를 지정하지 않는 방식으로 .locals를 읽는 경우에는 모든 항목이 평가됩니다. 따라서 어떤 필드도 읽지 않는 항목은 렌더링 단계로 남겨집니다. 워크스페이스 경로를 가리키는 소스는 엔터티가 렌더링될 때 평가됩니다. .context.instance_id, .values, .infra, .locals(선언 엔터티의 해석된 블록 전체), 정적 문자열을 사용할 수 있습니다. 이 경우 FeatureRecipe의 소스는 추가로 .attachment_name을 읽으며(해석 대상이 어태치먼트이므로), 그 .context.instance_id는 호스트 컴포넌트를 가리키고, 호스트 컴포넌트가 보고한 이름인 .context.rendered_name도 함께 읽습니다(#9 참조). 경계 범위 FeatureRecipe는 .boundary.*를 읽으며 컴포넌트별 필라는 하나도 읽지 않습니다. 양쪽 모두 금지: .context.inject, .context.uses, .provides(자기 완결성 불변식 — 워크스페이스 소스 표면은 선언 엔터티 자체의 locals와 컨텍스트를 공유하므로 둘은 같은 참조를 허용하고 거부하며, 원격 좌표는 그 컨텍스트의 일부를 읽습니다. 소스 해석은 토폴로지 파이프가 하이드레이션되기 전, 그리고 차트, 모듈 또는 아티팩트 본문이 로드되기 전에 완료되어야 합니다). |
| 6 | Recipe provides 템플릿 | Recipe | provides 평가 | .context.instance_id, .context.rendered_name(노드의 provider가 해당 노드에 대해 렌더링하는 출력에 부여하는 이름 — 작성자가 제공한 소스에서 오거나 provider가 합성하는 워크로드에서 옴. provider가 그런 이름을 보고하지 않는 노드에서 이를 읽으면 중단됩니다 — 렌더링된 리소스의 이름 지정 참조), .values, .infra, .locals(노드의 해석된 블록 전체 — locals는 이 단계의 서두에서 provides보다 먼저 해석됩니다), 정적 문자열. 금지: 그 밖의 모든 루트 — .context.inject, .context.uses(노드 간), .context.annotations.*, .context.labels, .context.metadata, .metadata.*(배치/배포에 결합됨), 그리고 .attachment_name(기본 Recipe의 provides 평가 중에는 해석되는 어태치먼트가 없음). 이 검사는 명시적 허용 목록 방식입니다. provides 컨텍스트가 노출하지 않는 루트를 참조하면 중단됩니다(자기 완결성 불변식 — 토폴로지 정렬 없이 병렬 평가를 가능하게 함). locals 블록이 선언하지 않은 키를 가리키는 .locals.<key>도 중단됩니다. 이 필라는 루트 검사만으로는 단속할 수 없는 개방형 키 맵이기 때문입니다. |
| 7 | Recipe valuesMapping(인라인, 파일 $import:, 또는 라이브러리 $import:) | Recipe | 기본 렌더링 | 전체 템플릿 컨텍스트: .values, .infra, .context.*(instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. 인라인으로 작성된 .context.rendered_name 참조는 #6과 마찬가지로 provider가 그런 이름을 보고하지 않는 노드에서 중단됩니다. $import:로 불러온 본문 안의 참조는 검사되지 않으며, 그런 노드에서는 빈 값으로 렌더링됩니다. |
| 8 | FeatureRecipe injectMapping | FeatureRecipe | inject 매핑 | 전체 템플릿 컨텍스트: .values, .infra, .context.*(.context.inject — 가로채는 파이프 — 와 .context.uses 포함). 여기서 .context.used_by는 비어 있습니다. 매핑의 출력은 호스트 자체의 전달 파이프에 도달하기 때문입니다. .context.render_facts는 없습니다. 매핑은 호스트가 렌더링되기 전에 실행되기 때문입니다. .context.rendered_name은 #9와 마찬가지로 호스트 컴포넌트가 보고한 이름입니다. 이를 읽는 매핑은 검사되지 않으며, provider가 이름을 보고하지 않는 호스트에서는 빈 값으로 렌더링합니다. FeatureRecipe의 executionScope와 관계없이 컨텍스트는 같습니다. 경계 범위 FeatureRecipe의 매핑은 부착이 도달하는 각 컴포넌트마다 한 번씩 실행되어 그 컴포넌트의 .context.*를 읽고, .features.<attachment>.provides와 .locals는 한 번의 경계 평가 결과로 읽습니다. 금지: .boundary — 어떤 컴포넌트의 컨텍스트도 이를 담지 않으므로 참조하면 빌드가 중단됩니다. |
| 9 | FeatureRecipe valuesMapping(및 그 workload:와 artifacts:) | FeatureRecipe | 기본 렌더링 | 전체 템플릿 컨텍스트 + .attachment_name, .inject(부착이 inject: 블록을 작성한 경우의 부착 자체 inject: 항목), .context.render_facts — 호스트의 provider가 호스트의 렌더링에 대해 보고한 내용 — 및 .context.used_by — 호스트를 사용하는 컴포넌트들로, FeatureRecipe가 readsCallerRenderFacts: true를 설정한 경우 각각 자체 렌더 팩트를 가짐. FeatureRecipe가 readsTargetRenderFacts: true를 설정한 경우 .context.uses의 각 연결은 대상의 렌더 팩트를 .render_facts에 가집니다. .context.instance_id와 .context.rendered_name은 호스트 컴포넌트의 식별자와 호스트 자체의 provider가 보고한 이름으로, 호스트의 Recipe가 읽는 것과 같은 값이며 FeatureRecipe의 locals:와 provides:에서도 같습니다. 인라인으로 작성된 .context.rendered_name 참조는 provider가 그런 이름을 보고하지 않는 호스트에서 중단됩니다. .source는 FeatureRecipe 자체의 평가된 source:로, 호스트 컴포넌트의 것이 되는 일은 없으며 FeatureRecipe가 선언하지 않으면 아무것도 담지 않습니다. |
| 10 | 파이프라인 with: 블록 | Recipe / FeatureRecipe | 플러그인 파이프라인 | 전체 템플릿 컨텍스트 + .steps(앞선 파이프라인 단계의 단계 간 출력). 여기서 .context.used_by는 비어 있으며, .context.uses의 어떤 연결도 대상의 렌더 팩트를 가지지 않습니다. 단계가 호스트 자체의 문서를 다시 쓸 수 있기 때문입니다. 어태치된 FeatureRecipe의 단계는 #9와 마찬가지로 호스트 자체의 렌더 팩트인 .context.render_facts를 읽습니다. |
| 11 | Recipe workload: 본문(인라인이든 $import:로 불러왔든 내부의 모든 템플릿 필드) | Recipe | 기본 렌더링 | 전체 템플릿 컨텍스트. Workload 본문 안의 모든 필드 — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — 는 Workload 문자열 전체를 처리하는 동일한 템플릿 평가의 일부입니다. Workload 내용은 전체 템플릿 컨텍스트에 대해 한 번 평가되는 단일 Go 템플릿이며, 내부의 필드 수준 템플릿은 별도의 평가가 아니라 같은 평가에서 해석됩니다. |
자기 완결성 참고. source 문자열(#5)은 provides 자기 완결성 불변식(#6)을 공유합니다. 두 표면 모두 .context.inject 및 .context.uses 참조를 거부합니다. 소스 해석은 .context.inject를 채우는 inject 하이드레이션보다 먼저, 그리고 하위 단계에서 해석된 소스를 소비하기 전에 실행되므로, 규칙과 그 근거가 두 표면 모두에 그대로 적용됩니다. 둘이 다른 점은 provides 필라입니다. 워크스페이스 source는 선언 엔터티의 locals와 컨텍스트를 공유하고 원격 좌표는 그 일부를 읽으므로 둘 다 .provides를 거부하지만, provides는 그 자체가 해석되는 표면입니다. 둘 다 .locals를 읽습니다. 이 규칙은 Recipe에 적용되는 것과 같은 조건으로 FeatureRecipe의 source에도 적용되며, 각각 해당 엔터티 자체의 locals 표면에 대해 검사됩니다.
Workload 본문 템플릿 참고(#11). Workload 본문은 렌더러가 전체로 평가한 뒤 그 결과를 Workload 문서로 파싱하는 하나의 템플릿 문자열입니다. 내부의 필드 수준 템플릿(여기의 replicas: {{ .infra.replicas | default 1 }}, 저기 containers.app.variables 안의 LOG_LEVEL: "{{ .values.log_level }}")은 별도의 템플릿 평가 위치가 아니며, 모두 Workload를 생성하는 단일 기본 렌더링 평가에 참여합니다. 작성자는 Workload 내부 필드에 대해 별도의 사용 가능성 규칙을 알 필요가 없습니다. Workload 전체에 대한 규칙(#11)이 내부의 모든 필드 수준 템플릿을 다룹니다.
Workload 본문 내 판별 인식 폴백. 위의 replicas: {{ .infra.replicas | default 1 }} 예시는 “작성자가 replicas를 설정하지 않음”과 “작성자가 replicas를 0으로 설정함”을 구분하지 못합니다. default는 두 경우 모두 작동합니다. Release가 scale-to-zero를 표현하기 위해 정당하게 infra.replicas: 0을 작성하는 경우(흔한 Knative / KEDA 패턴), | default 1 형태는 그 의도를 조용히 덮어씁니다. 판별 인식 형태는 replicas: {{ optional .infra "replicas" 1 }}입니다. optional은 키의 존재 여부를 확인하여 키가 설정된 경우 작성된 값(작성된 0 포함)을 반환하고, 키가 없을 때만 1로 폴백합니다. 전체 의미와 언제 이를 선호해야 하는지에 대한 안내는 sprig-functions.md를 참조하십시오.
3. 금지된 참조와 근거
| Location | 금지된 참조 | 근거 |
|---|---|---|
Component inject value: (#4) | .context.inject | 그 시점에는 inject 파이프가 구성되는 중입니다. 자체 inject value: 템플릿은 자신이 기여하는 파이프에서 읽을 수 없습니다. |
Component inject value: (#4) | .context.uses | 컴포넌트 간 연결은 uses[].inject에 있습니다. 컴포넌트의 자체 inject value: 템플릿은 해당 컴포넌트 자신의 데이터에만 닫혀 있습니다. |
Recipe provides (#6) | .context.inject | Provides 템플릿은 임의의 순서로 평가되며 노드 자신의 데이터(.values, .infra, .locals, .context.instance_id, .context.rendered_name)에만 닫혀 있습니다. inject 파이프는 inject 하이드레이션 전까지 채워지지 않으며, inject 하이드레이션은 모든 노드의 provides가 평가된 후에 실행됩니다. |
Recipe provides (#6) | .attachment_name | 기본 Recipe의 provides 단계는 어떤 attachment도 해석하지 않으므로 이름이 빈 값으로 렌더링됩니다. 이 루트는 빈 값으로 전달되는 대신 거부됩니다. |
source (#5) | .provides | 어느 소스 표면도 provides 필러를 갖지 않습니다. 워크스페이스 소스 표면은 선언 엔터티 자신의 locals와 컨텍스트를 공유하는데 거기에는 provides 필러가 없으며, 원격 좌표는 그 컨텍스트의 일부를 읽습니다. Locals는 provides보다 먼저 해석되므로 provides:가 .locals를 읽을 수 있습니다. 소스 템플릿은 provides를 거슬러 참조하는 대신 같은 locals를 읽습니다. |
Recipe locals (#6 사전 단계) | .provides | Locals는 provides보다 먼저 해석되므로, local이 평가될 때 노드 자신의 provides는 아직 존재하지 않습니다. provides도 게시하는 값이 필요한 local은 .values / .infra에서 직접 그 값을 계산하고, 그런 다음 provides 항목이 그 local을 읽습니다. |
Recipe locals (#6 사전 단계) | .context.rendered_name | Recipe의 locals는 source 템플릿(#5)과 컨텍스트를 공유하며, 그 표면은 이 이름을 제공하지 않습니다. 노드가 소스를 제공하는지 여부는 source 템플릿이 결정하며, 이것이 이름이 의존하는 요소 중 하나이기 때문입니다. 이 참조는 알 수 없는 루트 진단과 함께 중단되며, 이 진단은 그 위치에서 .context가 정의하는 것으로 .context.instance_id를 나열합니다. 대신 provides 항목이나 기본 렌더링 단계의 템플릿에서 이 키를 읽으십시오. |
Recipe provides (#6) | .context.uses | .context.uses는 다른 노드의 provides를 참조하며, provides 평가는 이를 임의의 순서로 실행합니다. Provides 템플릿은 평가가 순서에 무관하도록 자체 완결성을 유지합니다. |
FeatureRecipe locals, provides, source (#5) 및 인라인 렌더 템플릿(#9, #10), provider가 이름을 보고하지 않는 호스트에서 | .context.rendered_name | Feature attachment에서 이 키는 호스트 컴포넌트가 보고한 이름을 담습니다. 아티팩트 세트만 배치하는 호스트나 그런 이름을 도출하지 않는 provider를 통해 렌더링하는 호스트는 담을 이름이 없습니다. 이 참조는 알 수 없는 루트 진단과 함께 중단되며, 이 진단은 그 위치에서 .context가 정의하는 것 중 하나로 .context.instance_id를 나열합니다. 대신 식별자를 읽으십시오. 그런 호스트에서는 호스트 자신의 리소스가 이 식별자를 따라 이름 지어집니다. |
source (#5) | .context.inject | 소스 해석은 .context.inject를 채우는 inject 하이드레이션보다 먼저 실행됩니다. 소스 URI가 평가될 때 파이프는 아직 채워져 있지 않습니다. |
source (#5) | .context.uses | 소스 해석은 하위 단계에서 선언 엔터티의 차트, 모듈 또는 아티팩트 본문을 로드하기 전에 완료되어야 합니다. 노드 간 참조를 허용하면 소스 해석이 토폴로지 순회 순서에 결합되는데, 소스 해석은 의도적으로 이를 피합니다. |
| Parameters (경로 템플릿을 제외한 모든 곳) | 보간 이후의 모든 값 템플릿 표면 | 보간은 작성된 YAML의 모든 {{ .parameters.X }} 참조를 소비하고 그 자리에 해석된 값을 기록하므로, 값 템플릿 표면은 parameter 필러 대신 해석된 리터럴을 받습니다. 운영자가 작성한 경로 템플릿은 유일한 예외로서 .parameters.X를 직접 읽습니다. |
4. 자체 inject 해석 경로
자체 inject 해석은 inject 하이드레이션의 전반부이며, 모든 노드의 provides가 평가된 후에 실행됩니다. 컴포넌트가 컴포넌트 수준의 inject: 블록을 선언하면 컴파일러는 이 시점에 이를 평가합니다.
- 리터럴
value:문자열: 값에 Go 템플릿 표현식이 포함되어 있으면 컴파일러는 매트릭스 #4 행의 컨텍스트(.values,.infra,.context.instance_id,.metadata.*등)로 이를 평가하며, 표현식은 #4 행에 나온 대로 이스케이프하여 작성합니다. 일반 문자열은 변경 없이 그대로 전달됩니다. from:참조: 컴파일러는 그 시점에 이미 해석된 노드 자신의provides딕셔너리에서 키를 조회합니다. 키가 존재하지 않으면 컴파일러는 invalid-inject-key 오류와 함께 빌드를 중단합니다.- 충돌 검사:
.context.inject파이프에 병합하기 전에 컴파일러는 어떤 키도 inject 하이드레이션의 후반부가 해석하는 uses-inject 키와 충돌하지 않는지 확인합니다. 충돌이 있으면 duplicate-delivery-key 오류와 함께 빌드가 중단됩니다.
결과 문자열은 해당 uses-inject 해석 결과와 함께 .context.inject.env, .context.inject.file, .context.inject.arg(및 모든 사용자 정의 메커니즘)에 병합됩니다. inject 매핑(injectMapping)이 실행될 무렵에는 파이프에 두 소스의 개발자 작성 inject 값이 모두 포함되어 있습니다.