템플릿 컨텍스트 계약
이 페이지는 컴파일러가 Recipe 및 FeatureRecipe Go 템플릿에 주입하는 런타임 뷰를 설명합니다. 즉 템플릿 컨텍스트의 형태, 컴파일 파이프라인 전반에 걸친 필드별 가용성, 그리고 컴포넌트 간 상태를 사용하는 템플릿을 작성하는 고급 작성자에게 필요한 표준 계약을 다룹니다. 템플릿 사이트별 가용성(어떤 평가 사이트에서 어떤 필드가 존재하는지)은 expansion-matrix.md에서 다루며, 이 페이지는 필드의 형태와 그 의미를 설명합니다.
개요
컴파일러는 렌더링 중에 노드마다 템플릿 컨텍스트를 구성하고, 렌더러가 해당 노드에 대해 평가하는 모든 Go 템플릿에 이를 주입합니다. 이 컨텍스트는 메모리 안에만 존재합니다. 디스크에 저장되지 않으며, 단일 페이로드로 Wasm ABI를 넘지도 않습니다. 각 템플릿 사이트는 동일한 컨텍스트 객체의 뷰를 받습니다. 일부 필드는 나중에 채워집니다(.workload는 워크로드 합성 시점에, .source는 소스 해석 시점에 채워지고, .steps는 pipeline: 실행 중 각 단계가 완료될 때마다 채워집니다. 언어의 현황 → 컴파일 파이프라인 단계를 참조하십시오).
런타임 형태의 스키마는 template-context-v1beta1.schema.json입니다(Aggrega 스키마 배포판에 포함되어 제공됩니다).
최상위 필드
최상위 필드는 템플릿 컨텍스트의 루트에 있으며, 템플릿 안에서 .field로 접근합니다.
.values(맵). Aggregate에서 개발자가 작성한 인지적 페이로드입니다. 컴포넌트별 값은 이 필드를 통해 렌더링된 Recipe로 전달됩니다. 해석 시점에 Catalog의schema:(Component 또는 Feature의 JSON Schema 2020-12 선언)로 검증됩니다. 필드에 작성된 0 / 빈 값 / false가 필드가 없는 경우와 의미상 구별될 때는default대신optional을 사용합니다(sprig-functions.md참조)..infra(맵). Release에서 운영자가 작성한 물리적 사이징입니다. 해석 시점에 Catalog의schema:(Component 또는 Feature의 JSON Schema 2020-12 선언)로 검증됩니다..values와 동일한optional대default지침이 적용됩니다. 작성된 0이나 false가 정당한 의도(0으로 스케일, 재시도 없음, 기능 플래그 꺼짐)일 때는optional을 우선 사용합니다..locals(문자열 값 맵). Recipe 전용 상태입니다. Recipe의locals:블록에 선언된 이름으로, locals 프리앰블에서 해석되어 소스 해석 시점에 이 필러에 게시됩니다. 항목은 작성 순서대로 해석되며 한 항목은 그 위에 정의된 형제 항목을 읽을 수 있으므로, 한 항목이 다른 항목을 읽는 곳에서는 순서가 중요합니다. Recipe 자체의 템플릿 안에서만 접근할 수 있으며 호출자에게는 절대 노출되지 않습니다..provides(문자열 값 맵). Recipe의 공개 출력 문자열로, 호출자의inject:블록이from:참조를 해석하는 대상이 되는 계약입니다. provides 평가 시점에 채워집니다..features(어태치먼트 맵). 이 Component에 연결된 Features(5-Tier Onion Model에 따라 Aggregate 수준 + 서브시스템 수준 + Release 수준 + Manifest 주석 기반)를 순회하며, 작성자가 어태치먼트에 부여한 인스턴스 이름을 키로 합니다. 모든 항목은 동일한 필드를 가집니다. 아래 어태치먼트 형태를 참조하십시오. Component의 연결 중 하나에 작성된 어태치먼트는 여기에 포함되지 않습니다. 이는 해당 연결 아래의.context.uses.<alias>.features.<slot>에서 읽으므로,.features를 순회하는 템플릿은 Component 자체의 어태치먼트만 만납니다..metadata(구조체). 결정적 명명을 위한 Release 식별 정보:release_name,release_version,environment,aggregate_name. 모든 렌더링에서 채워지며, 값은 Release의metadata:블록에서 비롯됩니다..source. 소스 해석 템플릿 평가로 해석된 Recipe의source:입니다. 소스가 없는 Recipes에서는nil이며, 소스 해석이 실행되기 전에도nil입니다. FeatureRecipe의 템플릿에서는 해당 FeatureRecipe 자체의source:이며, 호스트 컴포넌트의 것이 되는 일은 없습니다. Attachment FeatureRecipe 보고 위치를 참조하십시오..workload. 파싱된 Workload 객체로, 렌더링된workload:문서가 디코딩되고 이를 통제하는 검증, 즉 Workload 스키마, 컨테이너가 선언하는 모든 어태치먼트에 대한 Component의featuresSchema, 각 어태치먼트가 참조하는 대상의 해석 가능성을 통과하면 채워집니다. 합성되지 않는 Recipes에서는nil이며, 워크로드 합성이 실행되기 전에도nil입니다..steps(단계 출력 맵). Wasm 플러그인이 실행될 때pipeline:실행에 의해 채워지며, 완료된 단계가 반환한 출력을.steps.<id>.outputs를 통해 후속 단계에 노출합니다. 단계는 자신의with템플릿에서 앞선 단계의 출력을 읽으며, 단계의outputs는 그 뒤에 선언된 단계에만 보입니다. 노드가 파이프라인을 선언하지 않을 때와 노드의 첫 단계가 완료되기 전에는 비어 있습니다.
이 노드에 대해 아무것도 담지 않는 최상위 필드 — 워크로드를 합성하지 않는 Recipe의 .workload, 소스가 없는 Recipe의 .source, 어태치먼트가 없는 Component의 .features — 는 값 템플릿에서 .values 아래의 설정되지 않은 키와 정확히 같이 빈 값으로 읽힙니다. {{ .workload }}는 아무것도 렌더링하지 않고, 그에 대한 default는 대체 값을 제공하며, 그에 대한 if나 with는 false 분기를 탑니다. 그에 대한 range는 아무것도 반복하지 않습니다. 그 아래를 읽는 것 — {{ .workload.containers }} — 은 내려갈 대상이 없으므로 여전히 중단됩니다. 그리고 그런 필드를 항상 실행되는 위치 — 모든 if, with, range의 바깥 — 에서 출력하면서 그것을 반복하기도 하는 템플릿은 그 필드를 지목하며 중단됩니다. 이는 아무것도 담지 않으면서 두 방식으로 모두 읽히는 모든 경로에서와 같은데, 아무것도 없는 것으로 출력되면서 동시에 아무것도 반복하지 않는 단일 값은 없기 때문입니다. A template reads and iterates a path that holds nothing (템플릿이 아무것도 담지 않는 경로를 읽고 반복함)을 참조하십시오.
attachment의 형태
.features.<name>과 .features.<slot>은 같은 형태입니다. 하나의 attachment를 한 가지 방식으로 읽습니다.
.type(string). 연결된 Feature의 카탈로그 URI입니다..resolved_version(string). Manifest 해석 후 연결된 Feature의 버전입니다. 소비하는 쪽에서 다시 기술한 고정 버전이 아니라, 이 빌드에 실제로 바인딩된 버전입니다..context.uses.<alias>.resolved_version과 대응합니다. attachment의type이 어떤 카탈로그 엔티티로도 해석되지 않으면 비어 있습니다..labels(string-valued map). 연결된 Feature의 카탈로그 레이블로, Feature가 선언한 순서대로 그대로 전달됩니다. 어떤 것도 필터링되거나 이름이 바뀌거나 접두사가 제거되지 않으므로, 템플릿은 Feature 작성자가 쓴 내용을 정확히 읽습니다..context.uses.<alias>.labels와 대응합니다. Feature가 레이블을 선언하지 않은 경우와 attachment의type이 어떤 카탈로그 엔티티로도 해석되지 않는 경우에는 존재하지 않습니다..values(map). attachment 자체의 개발자 의도 기둥으로, Aggregate의 attachment 선언에 작성됩니다. 호스트 컴포넌트의 최상위.values와는 별개입니다..infra(map). attachment 자체의 운영 사이징 기둥으로, Release의 attachment 선언에 작성됩니다. 호스트 컴포넌트의 최상위.infra와는 별개입니다..provides(string-valued map). 이 attachment에 바인딩된 FeatureRecipe의 해석된 공개 계약입니다. 생성된 리소스의 이름, 데이터 키, 클라우드 ID, 그리고 FeatureRecipe가 게시하는 추가 키가 포함됩니다..context.uses.<alias>.provides와 마찬가지로.features.<name>.provides.<key>로 읽습니다. 소비자는 생산자가 게시한 값을 다시 유도하지 않고 그대로 읽습니다. 바인딩된 FeatureRecipe가 아무것도 게시하지 않는 attachment는 빈 맵이 아니라provides키 자체를 갖지 않으므로, 개별 키에 접근하기 전에 확인해야 합니다.
.provides는 attachment를 단순히 존재하는 것이 아니라 소비 가능한 것으로 만듭니다. schema.provides 계약을 선언한 Feature는 그 계약을 실현하는 FeatureRecipe에 대해 계약이 강제되며(FeatureRecipe는 선언된 모든 키를 게시해야 합니다), 소비자는 그 결과를 여기에서 읽습니다. 따라서 ServiceAccount를 생성하고 그 이름을 게시하는 ID Feature가 있으면, 소비하는 Recipe가 그것에 바인딩할 수 있습니다.
workload: | serviceAccount: "{{ .features.identity.provides.name }}"생성된 이름은 생산자가 한 번 기술하고 소비자가 사용합니다. 두 값이 어긋날 수 있는 소비하는 쪽에서는 절대 다시 기술하지 않습니다. workload-identity-binding 예제가 이를 처음부터 끝까지 렌더링합니다.
.labels를 사용하면 템플릿이 attachment의 이름을 매칭하거나 URI를 파싱하지 않고도 attachment가 무엇인지에 맞춰 동작할 수 있습니다. 컴파일러는 레이블을 전혀 읽지 않습니다. 문자열을 전달할 뿐이며, 그 의미는 템플릿 작성자가 결정합니다.
레이블을 선언하지 않은 Feature는 빈 맵이 아니라 .labels 자체를 갖지 않으므로, 개별 레이블에 접근하기 전에 확인해야 합니다. 존재하지 않는 키를 통해 접근하면 빌드가 중단됩니다. Feature가 선언하지 않았을 수 있는 레이블은 optional로 읽어야 합니다. index는 맵에 키가 없으면 해당 키를 명시하며 중단되기 때문입니다.
{{ if .features.db.labels }}{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}{{ end }}레이블이 그대로 전달되므로 카탈로그 작성자 자신의 네임스페이스가 변경 없이 템플릿에 도달하며, Recipe는 Feature가 선언한 것과 같은 키를 읽습니다.
.context 블록
.context는 컴파일러가 단일 노드에 대해 조립하는 실행 컨텍스트로, 렌더러가 모든 템플릿 사이트에 전달하는 식별, 토폴로지, 전달 파이프 데이터입니다. 필드는 다음과 같습니다.
.context.instance_id(string). 이름으로서의 노드 식별자입니다. 빌드 자체가 내보내는 것의 이름과 레이블을 지정하는 데 사용하는 값이므로, 이 값으로 리소스 이름이나 클러스터 내 주소를 구성하는 템플릿은 빌드가 실제로 생성하는 이름을 예측할 수 있습니다. 자신의 Aggregate가 선언하는 노드의 경우 직접 작성한 이름입니다. 가져온 Aggregate가 기여하는 노드의 경우 모듈 구분자를 풀어 쓴 평탄화된 식별자입니다(data-layer.main-db는data-layer-zdmain-db가 됩니다). 점은 리소스 이름에 포함될 수 없는 문자이고, 클러스터 주소 안에서는 서비스와 네임스페이스를 구분하기 때문입니다. 점으로 구분된 형식은 문서와 빌드 진단에서 해당 노드를 가리킬 때 사용합니다. 명명 관례를 참조하십시오..context.rendered_name(string). 노드의 provider가 해당 노드에 대해 렌더링하는 리소스에 부여하는 이름입니다. 차트가 읽는 릴리스 이름처럼 직접 제공한 소스에서 비롯되며, provider가 합성하는 워크로드의 리소스 이름을 자체 이름을 따라 지정하는 경우에도 비롯됩니다.helm이 같은 릴리스 이름으로 그렇게 합니다. 해당 provider가 이름을 도출하는 경우에만 존재합니다. Feature 어태치먼트의 템플릿에서는 호스트 컴포넌트의 이름이며, 이는 그곳의.context.instance_id가 호스트의 식별자인 것과 같습니다. 렌더링된 리소스의 이름 지정을 참조하십시오..context.labels(string 값 맵). 카탈로그에서 작성된 레이블과 토폴로지 구성 시 추가된label-transform항목입니다..context.annotations(세 개의 버킷, 아래 참조). 출처별로 그룹화된 캐스케이드 어노테이션입니다..context.inject(메커니즘 맵, 아래 참조). 사전 하이드레이션되고 인터셉트된 전달 파이프로, Recipe 템플릿이 컴포넌트 간 값을 읽는 표준 표면입니다..context.uses(연결 맵, 아래 참조). 아웃바운드 토폴로지 엣지에 대한 JOIN 프로젝션입니다..context.self_inject(메커니즘 맵, 아래 참조). 개발자가 컴포넌트 자체의inject:블록에 작성한 각 이름에 대해, 해당 항목이 전달하는 자체 provides 키 또는 해당 템플릿이 읽는 하나의 자체 값입니다..context.used_by(list, 아래 참조).uses항목이 이 컴포넌트를 가리키는 컴포넌트들입니다. 컴포넌트에 연결된 FeatureRecipe가 어태치먼트 자체 리소스를 생성하는 템플릿에서 읽으며, 그 외의 모든 곳에서는 비어 있습니다..context.render_facts(list의 맵, 아래 참조). 컴포넌트의 provider가 렌더링한 출력에 대해 보고한 내용으로, 팩트 이름을 키로 합니다. 컴포넌트에 연결된 FeatureRecipe가 컴포넌트 렌더링 후 실행되는 모든 템플릿에서 읽으며, 그 외의 모든 곳에서는 존재하지 않습니다.
.context.annotations — 세 개의 버킷
어노테이션은 출처를 키로 하는 세 개의 버킷으로 캐스케이드됩니다.
.context.annotations.release— Release 경계 어노테이션(도메인 4)입니다. 물리적 현실을 관리하는 데 사용되며, 렌더러는 적절한 경우 이를infra:필드로 라우팅합니다.aggrega.ai/*잘 알려진 어노테이션은 이 버킷에 있습니다..context.annotations.catalog— 도메인 2의 Component 메타데이터 어노테이션입니다. Architect가 작성한 변경 불가능한 고유 특성이며, 주로 Wasm 정책 플러그인이 사용합니다..context.annotations.aggregate— 도메인 1의 Aggregate 서브시스템 어노테이션입니다. 인지적 메타데이터이며, 렌더러는 적절한 경우 이를values:페이로드로 라우팅합니다.
각 버킷은 평탄한 문자열-문자열 맵입니다. 아키텍처의 분리 원칙에 따라 버킷은 서로 다른 용도를 위한 것이지만, 엔진은 이 분리를 강제하지 않으므로 작성 규율을 통해 버킷을 의도된 의미에 맞게 유지합니다. 캐스케이드 어노테이션 설계는 6장 §2 Flow 5를 참조하십시오.
.context.inject — 전달 파이프
이 파이프는 컴파일러가 사전 해석한 전달 맵입니다. 기본 렌더링에서 Recipe 템플릿이 실행될 때쯤에는 모든 inject 소스(개발자가 작성한 self-inject 리터럴, 자체 provides에 대해 해석된 self-inject from: 참조, 대상 provides에 대해 해석된 컴포넌트 간 uses[].inject 참조, FeatureRecipe injectMapping 인터셉션)가 최종 문자열 값으로 해석되어 이 맵에 병합되어 있습니다.
필드:
.context.inject.env— 환경 변수 이름 → 해석된 값의 string 값 맵입니다..context.inject.file— 파일 경로 → 해석된 값의 string 값 맵입니다..context.inject.arg— 인수 플래그 → 해석된 값의 string 값 맵입니다..context.inject.all—env/file/arg/사용자 정의 메커니즘을 하나의 평탄한 딕셔너리로 결합한 string 값 맵입니다. 파이프 전체 직렬화에 유용합니다({{ toJson .context.inject.all }}).
메커니즘은 무언가가 그것을 통해 전달될 때에만 파이프에 존재합니다. 아무것도 전달되지 않는 메커니즘 — 파일 전달이 없을 때의 .context.inject.file — 을 읽는 템플릿은 값 템플릿이 없는 키를 읽을 때처럼 이를 빈 값으로 읽고, 그에 대한 range는 아무것도 렌더링하지 않습니다. 이 읽기는 템플릿 전체에 빈 값을 제공하므로, 같은 템플릿의 {{ toJson .context.inject }}는 "file": ""을 보여 줍니다. 무언가가 그것을 통해 전달되는지는 hasKey .context.inject "file"로 알 수 있습니다.
- 사용자 정의 메커니즘(예:
ssm_param) — 핵심 세 가지와 똑같이 자체 필드 이름.context.inject.<mechanism>.<key>아래에서 읽을 수 있습니다. 사용자 정의 메커니즘의 값은 컴포넌트 수준 self-inject,uses[].inject엣지, Feature 어태치먼트의inject:매핑, FeatureRecipe의injectMapping출력에서 파이프에 도달합니다. 컴포넌트 수준 self-inject의 경우 Component의spec.inject허용 목록이 해당 메커니즘을 지정해야 하며, 허용 목록에 없는 메커니즘은 빌드를 중단시킵니다. 사용자 정의 메커니즘의 항목은 핵심 세 가지와 함께.context.inject.all에도 나타납니다. 사용자 정의 메커니즘에는all을 제외한 어떤 이름이든 붙일 수 있습니다. 그 이름은 병합된 뷰 자체이므로, 그 이름의 메커니즘은 단독으로는 결코 읽을 수 없습니다. 메커니즘all을 지정하는 inject 블록과, 그것을 나열하는 Component 또는 Feature 허용 목록(spec.inject, 소켓의inject)은 문서가 로드될 때 빌드를 중단시키며, 그 거부 메시지는 해당 이름이 이 병합된 뷰에 속한다고 설명합니다. 이름은 대소문자를 구분하므로ALL은 일반적인 사용자 정의 메커니즘입니다.
이 파이프는 인터셉션 이후의 상태입니다. Recipe 템플릿이 읽을 때쯤에는 FeatureRecipe injectMapping 블록이 inject 매핑 중에 이미 이 파이프 위에 재정의를 딥 머지한 상태입니다. 매핑은 컴포넌트 자체의 inject: 블록, 연결 중 하나의 inject: 블록 또는 자체 어태치먼트의 inject: 블록이 전달한 키를 대체할 수 있습니다. 연결된 두 Features가 inject: 블록이나 매핑을 통해 모두 전달하는 키는 두 값 중 하나로 이 파이프에 도달하는 대신 빌드를 중단시킵니다. Release 경계에 연결된 Feature도 같은 방식으로 컴포넌트에 도달합니다. 즉 그 FeatureRecipe의 injectMapping을 통해서이며, 이는 FeatureRecipe의 executionScope와 관계없이 컴포넌트 자체의 컨텍스트에서 실행됩니다. 소비자의 호스트 변수에 대한 compose 브리지의 재작성도 그러한 매핑 중 하나이며 같은 규칙을 따릅니다.
.context.self_inject — 개발자의 각 이름이 어떤 자체 값을 전달하는지
Component가 spec.inject를 선언하는 경우, 개발자는 컴포넌트 자체에 inject: 블록을 작성하고 컴포넌트 자체의 값과 provides가 전달될 이름을 선택할 수 있습니다. .context.inject는 그 항목들이 확정된 결과를 담고, .inject_raw는 작성된 그대로를 담습니다. .context.self_inject는 각 항목에 대해 그것이 전달하는 컴포넌트 자체의 provides 키 또는 해당 템플릿이 읽는 하나의 자체 값을 알려 줍니다. 이는 연결의 .context.uses.<alias>.inject와 같은 형태, 즉 메커니즘, 그다음 개발자의 이름, 그다음 키로 이루어진 형태이며, 키는 컴포넌트 자체의 provides 또는 값 중 하나를 가리킵니다:
provides.<key>—from: <key>로 작성된 항목으로, 컴포넌트 자체의 provides 중 하나를 전달합니다.values.<key>—value:템플릿이 컴포넌트 자체의 값 중 정확히 하나만 읽고 그 외에는 아무것도 읽지 않는 항목이며,<key>는 그 값의 최상위 키입니다. 읽기 주변의 텍스트나 함수는 상관없고, 템플릿이 값 안으로 얼마나 깊이 읽는지도 상관없습니다:'{{ .values.role }}','role={{ .values.role | upper }}','{{ with .values.role }}{{ . }}{{ end }}'는 모두values.role에 대응하고,'{{ .values.config.port }}','{{ index .values.config "port" }}','{{ (default dict .values.config).port }}'는 모두values.config에 대응합니다.- 빈 문자열 — 그 밖의 모든 항목: 리터럴, 두 값을 읽는 템플릿, 값 이외의 것(
.infra,.metadata,.context)을 읽는 템플릿, 그리고 텍스트상 값 읽기가 하나의 최상위 키로 귀속되지 않는 템플릿 — 루트를 통해 함수에 전달된 값(index .values "role"), 통째로 읽은 값(toJson .values, 또는{{ with .values }}안에서나.values에 바인딩된 변수를 통해 읽은 필드), 또는 넘겨진 전체 컨텍스트(toJson .).
# The developer's block on the component, in the Aggregateinject: env: - { in: SERVICE_HOST, from: host } - { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' } - { in: MODE, value: batch } - { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' } ssm_param: - { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_injectenv: SERVICE_HOST: provides.host AGENT_ROLE: values.role MODE: "" ROLE_AND_GOAL: ""ssm_param: /app/goal: values.goalAggregate에서 각 value: 템플릿은 {{가 아니라 {{"{{"}}로 시작합니다. 블록 자체의 템플릿이 평가되기 전에 Aggregate의 전체 텍스트가 매개변수 보간을 위해 한 번 템플릿으로 읽히기 때문입니다. 위 목록에 인용한 템플릿은 그 이스케이프 이후의 형태로 표시되어 있습니다. 자체 이중 중괄호를 포함하는 텍스트를 참조하십시오.
이것이 개발자 자신의 이미지를 실행하는 Recipe가 컴포넌트 자체 값에 대한 자기 변수 이름을 기본값으로 취급할 수 있게 해 주는 것입니다. 이는 표준 라이브러리 카탈로그의 관례이며, 기업 카탈로그는 다르게 선택할 수 있습니다. 이러한 Recipe는 자체 값을 자기 이름으로 전달하기 전에 개발자의 블록이 이미 그 값을 전달하는지 확인하고, 그렇다면 기본값을 건너뜁니다. 따라서 값 하나의 이름을 바꾼 개발자도 나머지 모든 기본값을 유지합니다:
workload: | containers: main: variables: {{- range $name, $value := .context.inject.env }} {{ $name }}: {{ $value | quote }} {{- end }} {{- $named := dict }} {{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }} {{- if not (hasKey $named "values.role") }} APP_ROLE: {{ .values.role | quote }} {{- end }}.context.self_inject는 모든 렌더링에 존재하며, 개발자가 블록을 작성하지 않은 경우 비어 있습니다. 메커니즘은 블록이 그것을 지정할 때만 나타나므로, 블록이 지정하지 않을 수도 있는 메커니즘을 읽을 때는 위의 with처럼 보호하십시오. 템플릿은 모든 맵과 마찬가지로, 어떻게 읽든 이름을 정렬된 상태로 접합니다. 이 맵은 개발자가 작성한 텍스트에서 읽힙니다. 그 안의 어떤 것도 확정된 값이 아니며, 컴파일러는 이름이나 키에 아무런 의미도 부여하지 않습니다.
.context.uses — JOIN 프로젝션
.context.uses는 현재 노드에서 나가는 모든 토폴로지 에지에 대한 컴파일러의 보강된 뷰입니다. 각 맵 항목은 로컬 소켓 별칭을 키로 하며(예: Aggregate가 uses: { databases: { primary: { target: ... } } }를 작성한 경우 databases.primary는 .context.uses.primary가 됩니다), 대상의 해석된 상태에 대한 JOIN 프로젝션과 호출 측 전달 계약을 담습니다.
.target(string) — 대상 노드의 인스턴스 ID입니다..socket(string) — 호출 측 소켓 이름(usesSchema키)입니다..provides(문자열 값 맵) — 대상의 해석된provides:키(provides 평가 시 대상 Recipe가 내보낸 공개 출력 문자열)입니다..inject(mechanism → key → value 맵의 맵) — 이 에지에 대한 호출 측 inject 지시문(uses[].inject선언의inject:블록)입니다. 메커니즘 키는env/file/arg/사용자 정의이며, 메커니즘별 맵 항목은 로컬 키 → 대상 provides 키 참조입니다..labels(문자열 값 맵) — 소비하는 컴포넌트가 아니라 대상의 레이블입니다. 대상 자신의.context.labels가 담는 집합, 즉 카탈로그에서 작성된 레이블과 토폴로지 구성 시 추가된label-transform항목입니다..annotations(세 개의 버킷) — 대상의release/catalog/aggregate어노테이션 버킷입니다..component(string) — 대상의 Component 타입 URI입니다..resolved_version(string) — Manifest 해석 후 대상의 Component 버전입니다..boundary_path(string) — 대상의 Release 경계 경로로, 대상이 호출자의 경계에 있든 다른 경계에 있든 설정됩니다..origin_feature(string) — 에지가 Feature 연결에 의해 합성된 경우 설정됩니다(예: 사이드카 Feature가 자격 증명 Feature로 향하는uses에지를 기여하는 경우)..values(map) — Aggregate의uses항목에 작성된, 이 연결에 대한 해석된 에지별 개발자 구성입니다. 에지가 에지별 values를 가질 때만 존재합니다..infra(map) — Release의uses항목에 작성된, 이 연결에 대한 해석된 에지별 운영자 구성입니다. 에지가 에지별 infra를 가질 때만 존재합니다..origin_release(boolean) — Aggregate가 선언한 것이 아니라 Release가 이 연결을 배선한 경우true이며, Aggregate가 선언한 연결에서는 존재하지 않습니다..features(연결 항목의 맵) — 이 연결에 작성된 연결 항목으로, 소켓이 선언한 슬롯 이름을 키로 합니다. 아래를 참조하십시오. 연결이 하나라도 가질 때만 존재합니다..render_facts(map of lists) — 대상의 렌더가 내보낸 출력에 대해 보고한 내용으로, fact 이름을 키로 하며.context.used_by의 호출자.render_facts와 같은 형태입니다. 모든 fact는 리스트이며, 대상 자신의 provider 호출이 먼저 오고 그다음 대상의 각 Features가 렌더된 순서대로 오며, 한 이름이 각각에서 받은 리스트는 하나로 합쳐집니다.readsTargetRenderFacts: true를 설정한 FeatureRecipe에서만 존재하며(그 attachment는 모든 component가 렌더된 뒤에 렌더되므로 모든 대상의 렌더가 완료된 상태입니다), 그 경우 모든 connection에 존재하고, provider가 아무것도 보고하지 않는 대상에서는 비어 있습니다. 해당 FeatureRecipe의valuesMapping:,workload:,artifacts:에서만 읽을 수 있으며, component 자신의 Recipe 템플릿,injectMapping:,pipeline:단계의with:와when:, 그리고 이 키를 설정하지 않은 모든 FeatureRecipe에는 없습니다. 그러한 FeatureRecipe의 템플릿이 이를 읽으면 아무것도 렌더되기 전에 빌드가 중단됩니다.
두 에지별 구성 맵은 모두 소비자 범위입니다. 소비하는 노드의 렌더 컨텍스트에만 들어가며, 대상의 컨텍스트에는 들어가지 않습니다.
제공된 값은 .provides.<name>에서 읽습니다. 제공된 이름은 에지에 직접 놓이지 않고 .provides 아래에 중첩되므로, .context.uses.<alias>.<name>은 어떤 필드도 가리키지 않으며 아무것도 산출하지 않습니다.
두 끝이 서로 다른 출력으로 렌더링되는 연결에서는 .provides가 값이 아니라 대체물을 담습니다. 두 출력이 모두 조립된 뒤 provider가 자체 참조로 그러한 연결을 배선하는 경우 — 예를 들어 CloudFormation 스택이 다른 스택의 값을 읽는 경우 — .context.uses.<alias>.provides가 담는 각 값은 provider가 나중에 스택 간 참조나 값 자체로 대체하는 자리 표시자이며, 이는 provider 자체 페이지에서 설명합니다. 이러한 값은 비교하지 말고 복사해야 합니다. 이는 그러한 연결이 inject 파이프로 전달하는 값이 따르는 것과 같은 규칙이며, 그 값도 같은 종류의 자리 표시자입니다. 값을 통째로 쓰거나, 더 큰 문자열 안에 쓰거나, quote처럼 값을 그대로 두는 함수를 통해 쓰십시오. .provides에서 읽은 값을 비교하거나, 그에 따라 분기하거나, 길이를 재거나, 변경하는 템플릿은 자리 표시자를 기준으로 판단하게 되므로, 대신 빌드가 중단되며 그 템플릿과 읽은 각 값을 명시합니다. 분기는 소비하는 컴포넌트 자체의 값으로 하십시오. 이 중단은 연결의 .provides를 읽는 모든 템플릿에 적용되며, 어태치된 FeatureRecipe의 injectMapping:과 같은 연결을 .boundary 아래에서 읽는 경계 범위 FeatureRecipe도 포함됩니다. 두 끝이 하나의 출력으로 렌더링되는 연결은 값을 있는 그대로 담습니다.
하나의 별칭은 하나의 연결을 가리키므로, 맵에는 컴포넌트가 만드는 모든 연결에 대한 항목이 있습니다. 맵은 연결이 어떤 소켓에 배선되든 별칭만을 키로 하며, 한 컴포넌트의 두 연결은 별칭을 공유하지 않습니다. 한 소켓에서든 두 소켓에서든, 각 연결을 어느 문서나 연결 항목이 작성했든 마찬가지입니다. 빌드는 아무것도 렌더되기 전에 두 연결과 각각이 작성된 위치를 명시하며 그러한 쌍을 거부합니다. 리스트 항목의 별칭은 그 대상이므로, 한 대상을 두 번 나열한 리스트도 그러한 쌍이며, databases 소켓의 local 연결 옆에 있는 models 소켓의 local 연결도 마찬가지입니다.
Recipe 템플릿은 IR 그래프를 순회하지 않고 대상 측 상태를 조회하기 위해 이 프로젝션을 사용합니다. FeatureRecipe injectMapping 템플릿은 경계 간 라우팅 결정을 위해 이를 통해 대상 어노테이션에 접근합니다(entities/featurerecipe.md에 문서화된 K8s DNS 리졸버 패턴이 대표적인 예제입니다).
.context.uses를 range하는 템플릿은 Aggregate가 작성한 순서가 아니라 키 순서, 즉 별칭으로 정렬된 순서로 연결을 봅니다. 템플릿이 range하는 모든 맵은 .features와 연결의 .features를 포함해 이 방식으로 방문되므로, 템플릿은 맵을 range해서 작성 순서를 복원할 수 없습니다. 순서에 의미가 있는 경우 작성 표면은 이를 리스트로 모델링합니다. 어느 경우든 렌더된 출력은 같은 입력의 빌드 간에 바이트 단위로 동일합니다.
연결의 연결 항목 — .context.uses.<alias>.features
연결에 작성된 연결 항목(Aggregate에서 컴포넌트의 uses 항목 아래 features:에, 또는 해당 연결에 대한 Release의 항목에 작성된 것)은 소켓이 선언한 슬롯을 채웁니다. 빌드가 이를 다루는 모든 측면에서 이는 소비하는 컴포넌트의 연결 항목입니다. Manifest가 그 구현을 바인딩하고, 그 FeatureRecipe는 소비자 측에서 렌더되며, 그 provides 계약이 적용됩니다. 템플릿은 그것이 작성된 연결 아래에서 이를 읽습니다.
{{- range $alias, $edge := .context.uses }}- name: {{ $alias }} api_base: {{ $edge.provides.endpoint }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} api_key_key: {{ .provides.key }} {{- end }}{{ end }}{{- end }}- 슬롯을 키로 합니다.
.context.uses.<alias>.features.<slot>은 연결의 소켓이 선언한 슬롯(위의credential)을 가리키므로, 여러 대상에 접근하는 소비자는 각 대상 자신의 자격 증명을 해당 대상의 별칭 아래에서 읽습니다. 연결 항목이 없는 연결에는.features가 없으며, 이 때문에 읽기를 보호합니다. - 연결 항목의 형태. 각 항목은 컴포넌트 자신의 연결 항목 하나에 대해
.features.<name>이 담는 것과 정확히 같은 것을 담습니다. 즉.type,.resolved_version,.labels,.values,.infra, 그리고 바인딩된 FeatureRecipe의 해석된.provides입니다. 연결 항목의 형태를 참조하십시오. 여기서 읽는 provides는 연결 항목 자신의 FeatureRecipe가 렌더할 때 사용하는 것이므로, 소비자가 참조하는 이름과 그 FeatureRecipe가 내보내는 리소스의 이름은 하나의 평가된 값입니다. .features에는 절대 없습니다. 컴포넌트 자신의.features는 자신의 블록에 작성된 연결 항목만 담습니다. 따라서.features를 range하며 타입으로 연결 항목을 골라내는 Recipe({{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}…)는 같은 Feature라 하더라도 연결의 자격 증명을 만나지 않습니다. 템플릿은 연결의 연결 항목에.features가 아니라 그 연결을 통해 접근합니다.assertions컨텍스트를 포함해 컴포넌트의 연결 항목을 보여주는 모든 표면에서도 마찬가지입니다.
이 컴포넌트를 사용하는 컴포넌트 — .context.used_by
.context.uses는 바깥쪽, 즉 컴포넌트가 만드는 연결을 봅니다. .context.used_by는 안쪽, 즉 uses 항목이 이 컴포넌트를 가리키는 컴포넌트들을 봅니다. 이 컴포넌트에 연결된 FeatureRecipe가 이를 읽으며, 그러한 연결을 설명하거나 제한하는 리소스는 여기에 속합니다. 예를 들어 이 컴포넌트를 호출하도록 선언된 컴포넌트만 허용하는 네트워크 정책이 그렇습니다:
artifacts: callers.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: {{ .context.rendered_name }}-{{ .attachment_name }} data: callers: | {{- range .context.used_by }} - component: {{ .component_id }} socket: {{ .socket }} selector: {{ .provides.selector }} {{- with .source_namespace }} namespace: {{ . }} {{- end }} {{- end }}각 항목에는 다음이 들어 있습니다:
.component_id(string) — 연결하는 컴포넌트의 인스턴스 ID를 평탄화한 형태(frontend,data-layer.etl)로 나타낸 값이며,subDirectory:경로 템플릿이.component_id로 읽는 값입니다..socket(string) — 연결하는 컴포넌트에서 이 연결이 채우는 소켓(해당 컴포넌트의usesSchema키)입니다..provides(string-valued map) — 연결하는 컴포넌트가 게시하는 값을 그 Component가 선언한 키로 좁힌 것으로, 해당 컴포넌트의 소비자가.context.uses.<alias>.provides에서 읽는 값과 같습니다. 컴포넌트의 Recipe가 게시하지만 그 Component가 선언하지 않은 키는 포함되지 않습니다..source_namespace(string) — 연결하는 컴포넌트가 배치된 네임스페이스로, 해당 컴포넌트에 적용되는aggrega.ai/namespace어노테이션이 경계를 따라 아래로 전파된 값이며 Release에 있는 컴포넌트 자체 항목이 우선합니다. Release 항목에서 네임스페이스를 설정하거나null로 지운 컴포넌트는 경계의 설정이 아닌 자체 설정을 가지므로, 이 값은 컴포넌트 자체 리소스가 렌더링되는 네임스페이스를 가리킵니다. 컴포넌트에 적용되는 네임스페이스가 없으면 존재하지 않으므로, 그대로 출력하지 말고 예시처럼with또는if를 통해 읽으십시오..source_boundary_path(string) — 연결하는 컴포넌트를 담고 있는 Release 경계의 경로로, 중첩된 경계는/로 이어집니다(edge,edge/inner)..render_facts(map of lists) — 연결하는 컴포넌트의 렌더링이 출력한 결과에 대해 보고한 내용으로, 팩트 이름을 키로 하며.context.render_facts와 같은 형태입니다. 모든 팩트는 리스트이므로 항목이 하나뿐이어도 템플릿은 항상 이를 range로 순회합니다. 항목은 연결하는 컴포넌트 자체의 렌더링과 그에 연결된 Features의 렌더링에서 올 수 있습니다. 한 이름이 각각에서 받은 리스트는 하나로 합쳐지며, 컴포넌트 자체의 provider 호출이 먼저 오고 이어서 각 Features가 렌더링된 순서대로 옵니다.readsCallerRenderFacts: true를 설정한 FeatureRecipe에만 존재하며(그 연결은 모든 컴포넌트가 렌더링된 후에 렌더링되므로 모든 호출자의 렌더링이 완료된 상태입니다), 이때는 모든 항목에 존재하고 provider가 아무것도 보고하지 않는 호출자에 대해서는 비어 있습니다. 이 키를 설정하지 않은 FeatureRecipe는 어떤 항목에서도.render_facts를 볼 수 없으며, 그 템플릿이 이를 읽으면 렌더링이 시작되기 전에 빌드가 중단됩니다.
두 배치 값은 경계 범위 FeatureRecipe가 자신의 .boundary 엣지 리스트에서 같은 연결의 항목에 대해 source_namespace와 source_boundary_path로 읽는 값과 같습니다. 두 뷰는 컴포넌트가 배치된 위치를 같은 방식으로 읽으므로 서로 어긋나지 않습니다. 이 리스트의 엣지는 각 엔드포인트의 조립 경로 — source_assembly_path와 target_assembly_path, 즉 엔드포인트의 provider가 이를 조립해 넣는 빌드 출력 디렉터리 아래의 디렉터리 — 도 담는데, .context.used_by 항목은 이를 담지 않습니다.
readsCallerRenderFacts: true를 설정한 FeatureRecipe는 호스트의 팩트를 읽는 것과 같은 방식으로 각 호출자의 팩트를 읽습니다. 각 항목에 port가 들어 있는 ports라는 팩트를 문서화한 provider의 경우:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}provider가 ports를 보고하지 않는 호출자는 실패하지 않고 빈 ports:를 렌더링합니다. 아무도 보고하지 않은 이름은 아무것도 없는 것으로 읽히기 때문입니다.
리스트의 동작 방식:
- 작성된 순서대로. 항목은 연결하는 컴포넌트가 작성된 순서를 따르고, 그다음 각 컴포넌트 자체의
uses항목 순서를 따릅니다. 두 번 연결하는 컴포넌트는 연결마다 한 번씩, 두 번 나타납니다. 맵이 아닌 리스트이므로range는 그 순서대로 호출자를 만나며, 아무것도 정렬되지 않습니다. - 연결이 자체 리소스를 렌더링하는 곳에서만. FeatureRecipe의
valuesMapping:,workload:,artifacts:가 이를 읽습니다. 컴포넌트 자체의 Recipe 템플릿,injectMapping:,pipeline:단계의with:와when:에서는 비어 있습니다. 이들 각각이 생성하는 결과가 컴포넌트 자체의 렌더링 출력에 들어갈 수 있기 때문입니다.injectMapping:은 컴포넌트의 전달 파이프를 작성하고, 파이프라인 단계는 컴포넌트의 문서를 다시 쓸 수 있습니다. 이 덕분에 누가 사용하든 컴포넌트 자체의 출력은 동일하게 유지됩니다. 컴포넌트에 호출자를 하나 더 연결하면 그 컴포넌트에 연결되어 호출자를 읽는 Feature의 출력은 바뀌지만, 컴포넌트 자체가 렌더링하는 것은 아무것도 바뀌지 않습니다. - 연결 자체에 관한 정보는 없음. 항목에는 연결별
values나infra, 그리고 연결의 어떤 attachment도 들어 있지 않습니다. 이들은 소비하는 컴포넌트의.context.uses.<alias>아래에 남습니다. - 컴포넌트를 사용하는 것이 없으면 비어 있음. 이때 이를 순회하는
range는 아무것도 렌더링하지 않습니다. - 전달할 뿐, 해석하지 않음. 식별자, 소켓, 게시된 값, 배치는 컴파일러가 그대로 전달하는 문자열이며, 렌더 팩트는 각 호출자의 provider가 보고한 내용을 이름별로 담은 것입니다. 컴파일러는 이름에서 아무것도 추론하지 않고, 아무것도 가져오지 않으며, 리소스가 어떤 호출자를 허용해야 하는지 아무것도 결정하지 않습니다. 결정은 템플릿이 합니다.
provider가 렌더링에 대해 보고한 내용 — .context.render_facts
컴포넌트의 provider는 자신이 렌더링한 출력에 관한 팩트, 즉 자신의 형식에 대한 고유한 지식으로만 알 수 있는 작성 문서의 속성을 보고할 수 있습니다. provider가 어떤 팩트를 어떤 이름으로, 각 항목에 무엇을 담아 보고하는지는 그 provider가 자체적으로 문서화한 계약입니다. provider 쪽 내용은 Reporting facts about what a guest emitted를 참고하십시오. 예를 들어 helm provider는 자신이 출력한 pod 템플릿의 레이블, 컨트롤러와 Service의 셀렉터, 컨테이너의 포트를 보고합니다. 해당 provider의 렌더 팩트를 참고하십시오. 컴포넌트에 연결된 FeatureRecipe는 컴포넌트의 provider가 보고한 내용을 .context.render_facts에서 팩트 이름을 키로 읽습니다. 각 항목에 name과 port가 들어 있는 ports라는 팩트를 문서화한 provider의 경우:
artifacts: ports.yaml: | ports: {{- range .context.render_facts.ports }} - name: {{ .name }} port: {{ .port }} {{- end }}- 모든 팩트는 리스트입니다. provider는 항목이 하나뿐이어도 모든 팩트를 리스트로 보고하므로, 템플릿은 항상 이를 range로 순회합니다. 단독으로 읽을 단일 값은 없습니다.
- 이름당 하나의 리스트로, 컴포넌트의 렌더링 전체에 걸쳐 합쳐짐. 컴포넌트 렌더링에는 provider 호출이 두 번 이상 필요할 수 있으며(예: 차트 렌더링과 artifacts 배치), 각 호출은 각자 보고합니다. 한 이름이 그 호출들에서 받은 리스트는 호출이 실행된 순서대로 하나로 합쳐집니다. 컴포넌트에 연결된 Features가 렌더링한 내용은 여기에 포함되지 않습니다. Feature는 컴포넌트의 다른 Features가 무엇을 출력했든
.context.render_facts에서 컴포넌트 자체의 렌더링만 읽습니다. - 연결된 FeatureRecipe의 모든 템플릿에서. 그
valuesMapping:,workload:,artifacts:가 이를 읽으며,pipeline:단계의with:와when:도 읽습니다. 팩트는 컴포넌트 자체의 렌더링에서 오므로, 이를 읽어도 무엇도 누가 컴포넌트에 연결하는지에 의존하게 되지 않습니다. 컴포넌트 자체의 Recipe 템플릿과injectMapping:에는 존재하지 않습니다. 이들은 컴포넌트가 렌더링되기 전에 실행되기 때문입니다. - 누락이 아니라 비어 있음. 컴포넌트의 provider가 아무것도 보고하지 않으면
.context.render_facts는 빈 맵이고, 아무도 보고하지 않은 이름은 아무것도 없는 것으로 읽히므로, 이를 순회하는range는 실패하지 않고 아무것도 렌더링하지 않습니다. - 순서. 리스트는 provider가 보고한 순서대로 항목을 유지합니다. 객체 항목은 컨텍스트의 다른 모든 맵과 마찬가지로 키가 있는 맵이므로, 이를 순회하는 템플릿은 키 순서대로 키를 만납니다.
- 전달할 뿐, 해석하지 않음. 컴파일러는 각 팩트의 값이 리스트인지만 확인합니다. 이름이나 항목이 무엇을 의미하는지는 전혀 읽지 않으며, 이를 어떻게 처리할지는 템플릿이 결정합니다.
어서션의 .uses — 소켓별, 다음으로 별칭별 키
assertions: 템플릿은 같은 연결을 자체의 더 좁은 뷰로 읽습니다. .uses는 .context 아래가 아니라 루트에 있으며, 연결 대상이 게시한 것은 아무것도 담지 않습니다. 두 어서션 단계 모두 렌더링 전에 평가되기 때문입니다. 이 뷰는 작성 형식 uses: <socket>: <alias>: { target: … }를 그대로 반영합니다. 즉 소켓별로 키가 지정되고, 각 소켓 아래에서는 그 소켓의 모든 연결의 별칭별로 키가 지정되며, 목록 항목으로 작성된 연결은 대상을 별칭으로 사용합니다. 각 연결의 항목은 target, alias, 그리고 Feature 어태치먼트가 만든 연결이라면 origin_feature를 담으며, .context.uses가 담는 사실 중 세 가지를 같은 이름과 같은 값으로 담습니다. .labels는 대상의 레이블, .values는 연결에 작성된 값, .features는 연결에 작성된 어태치먼트로 슬롯별 키가 지정됩니다. 이 세 가지는 모든 항목에 존재하며, 연결에 해당 내용이 없으면 비어 있습니다. .features 아래의 어태치먼트는 type, resolved_version, values만 담습니다. 이는 컴포넌트 자체의 어태치먼트를 포함해 어서션이 모든 어태치먼트를 읽는 형태이며, 어서션이 실행될 때는 어태치먼트의 FeatureRecipe가 아직 provides를 확정하지 않았기 때문입니다.
연결이 하나인 소켓과 여러 개인 소켓은 형태가 같으므로 어서션은 어느 쪽이든 같은 방식으로 읽습니다. Aggregate 항목에 uses: { models: { local: { target: llama }, fast: { target: turbo } } }를 작성한 컴포넌트의 경우:
assertions: two-models-wired: | {{- if lt (len (optional .uses "models" dict)) 2 -}} {{- fail "wire two models to the models socket" -}} {{- end -}} local-is-llama: | {{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}} {{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}} {{- end -}}hasKey .uses "models"는 소켓이 연결되었는지 묻고, len은 연결 수를 세며, 그 위의 range는 별칭의 알파벳 순서로 각 연결을 방문하고, .uses.models.local.target은 하나의 연결을 읽습니다. .uses.models.target은 어떤 연결도 가리키지 않으며, 어서션 영역의 missingkey=error에 의해 중단됩니다. 각 연결은 렌더 컨텍스트의 맵과 같은 이유로 자체 항목을 가집니다. 한 컴포넌트의 두 연결은 별칭을 공유하지 않는데, 빌드가 어서션이 실행되기 전에 이를 거부하기 때문입니다. 전체 어서션 컨텍스트는 assertions-block.md에 문서화되어 있습니다.
inject 관련 보고 위치
템플릿 컨텍스트에는 각각 고유한 의미를 가진 이러한 inject 형태의 필드가 있습니다. Recipe 작성자와 FeatureRecipe 작성자는 어느 보고 위치를 읽어야 하는지 알아야 합니다.
| 보고 위치 | 타입 | 채워지는 시점 | 용도 |
|---|---|---|---|
.context.inject | 메커니즘 맵(항상 존재) | 모든 렌더링 | 미리 채워진 표준 전달 파이프입니다. valuesMapping:/workload:/artifacts: 템플릿과 모든 FeatureRecipe 템플릿 위치에서 이것을 읽습니다. |
.inject (최상위) | 메커니즘 맵(null 허용) | 어태치먼트가 inject: 블록을 작성한 경우, 그 어태치먼트의 FeatureRecipe를 렌더링할 때 | 어태치먼트 자체의 inject: 항목으로, 그 블록이 지정하는 각 메커니즘 — env, file, arg, 또는 vault_ref 같은 사용자 정의 메커니즘 — 아래에 놓이며, 각 로컬 이름은 해당 from:이 지정하는 키에 매핑됩니다. 그 키는 FeatureRecipe가 자신의 provides:에 게시하는 키(컴파일러는 이를 컴포넌트의 .context.inject에도 전달합니다)이거나, .inject를 읽는 FeatureRecipe가 스스로 소비하는 키입니다. FeatureRecipe가 게시하지 않는 키를 지정하는 항목은 빌드를 중단시킵니다. 단, FeatureRecipe가 이 컨텍스트에 대해 평가하는 템플릿 — 그 valuesMapping:, workload:, artifacts:, omits:, 또는 파이프라인 단계의 with:나 when: — 이 템플릿이 지정하는 경로로 .inject를 읽는 경우는 예외입니다. 그 경로란 .inject, .inject.env, {{ with .inject }} 등이며, toJson .처럼 컨텍스트 전체를 넘기는 방식은 해당하지 않습니다. 그 injectMapping:은 포함되지 않는데, 이는 컴포넌트의 컨텍스트에 대해 평가되고 그곳에는 .inject가 없기 때문입니다. 어태치먼트의 블록에는 리터럴이 없습니다. 그곳의 value: 항목은 빌드를 중단시키며, 컴포넌트에 필요한 리터럴은 컴포넌트 자체의 inject: 블록에 작성합니다. 사용자 정의 메커니즘은 .inject.env와 똑같이 .inject.<mechanism>에서 읽히며, 그 항목은 핵심 세 가지와 함께 .inject.all에 나타납니다. 어태치먼트가 작성하지 않은 메커니즘을 점 표기로 읽으면, .context.inject.<mechanism>이 비어 있는 것으로 읽히는 if나 with 내부에서도 알 수 없는 키로 중단됩니다. 어태치먼트가 작성하지 않았을 수 있는 메커니즘은 {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}를 통해 읽으십시오. 이 방식은 어태치먼트가 해당 메커니즘이나 어떤 inject: 블록을 작성했는지와 관계없이 빌드됩니다. 기본 Recipe의 템플릿과 inject: 블록을 작성하지 않은 어태치먼트에는 없습니다. |
.inject_raw (최상위) | 메커니즘 맵(null 허용) | 개발자가 부모 component에 inject: 블록을 작성했을 때 설정됨 | inject 매핑 가로채기가 일어나기 전의 변경되지 않은 개발자 의도입니다. 블록이 지정하는 모든 메커니즘(env, file, arg, 또는 ssm_param 같은 사용자 정의 메커니즘)은 각자의 이름 아래에 있으며, 작성된 그대로의 항목(in과 함께 from 또는 value)을 작성된 순서대로 담습니다. .inject_raw.ssm_param은 .inject_raw.env가 핵심 메커니즘을 읽는 것과 같은 방식으로 사용자 정의 메커니즘을 읽습니다. “개발자가 원래 이 전달 키를 요청했는가?”를 확인하는 논리 검사에 사용하며, FeatureRecipe의 injectMapping 재작성에 영향을 받지 않습니다. 개발자가 inject: 블록을 생략했다면 nil입니다. |
.context.self_inject | 메커니즘 맵(항상 존재) | 모든 렌더링; 개발자가 컴포넌트에 inject: 블록을 작성하지 않은 경우 비어 있음 | 컴포넌트 자체 inject: 블록의 각 이름을 해당 항목이 전달하는 자체 키 — provides.<key>, values.<key> 또는 빈 값 — 에 매핑한 것입니다. 개발자가 이미 전달하는 자체 값에 대해 기본 이름을 건너뛸 때 사용합니다. 위를 참조하십시오. |
가로채기 이후 확정된 전달이 필요한 작성자는 .context.inject를 읽어야 합니다. 변경할 수 없는 원래 의도가 필요한 작성자(예: 가로채기를 감지하거나, 개발자가 inject 블록을 생략했을 때 대체 동작을 내보내기 위해)는 .inject_raw를 읽어야 합니다. 개발자가 컴포넌트 자체 값 중 어느 것에 이미 이름을 붙였는지 알아야 하는 작성자는 .context.self_inject를 읽어야 합니다.
Attachment FeatureRecipe 보고 위치
렌더러가 attachment FeatureRecipe의 템플릿을 평가할 때 최상위 필드 하나가 추가로 설정됩니다:
.attachment_name(string) — attachment의 인스턴스 이름입니다. 소유 엔터티의featuresSchema에서 그 attachment가 채우는 슬롯이거나, 작성자가 붙인 자유 이름입니다. FeatureRecipe의locals:,provides:,injectMapping:,valuesMapping:,artifacts:는 이 필드를 읽어 결정적인 리소스 식별자를 도출하고 — 호스트의 provider가helm처럼 렌더링된 이름을 보고하는 경우에는{{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, 보고하지 않는 경우에는{{ .context.instance_id }}-{{ .attachment_name }}— 처리 중인 attachment의 이름을 지정합니다.
기본 Recipe의 자체 템플릿은 attachment를 해석하는 것이 아니므로 이 필드는 해당 컨텍스트에 포함되지 않습니다. 이 필드를 참조하는 Recipe의 provides:, locals: 또는 source: 템플릿은 빈 값을 렌더링하는 대신 해당 참조를 지목하며 중단됩니다. executionScope: boundary인 FeatureRecipe는 component마다 한 번이 아니라 경계에 대해 한 번 렌더링되므로, 경계를 위해 실행되는 템플릿에서도 이 필드를 사용할 수 없습니다. 그 injectMapping:은 attachment가 도달하는 각 컴포넌트마다 실행되며 그곳에서 이 필드를 읽습니다.
attachment 자체의 리소스를 생성하는 템플릿, 즉 valuesMapping:, workload:, artifacts:에서는 attachment의 컨텍스트가 호스트를 사용하는 component 목록도 .context.used_by에 담으며, 해당 FeatureRecipe가 readsTargetRenderFacts: true를 설정한 경우에는 호스트가 연결된 각 component가 렌더링한 내용을 .context.uses.<alias>.render_facts에 담습니다. 이 템플릿들과 pipeline: 단계는 호스트의 provider가 호스트 렌더링에 대해 보고한 내용도 .context.render_facts에서 읽습니다. 경계 범위 FeatureRecipe는 호스트 component 없이, .context 없이 리소스를 렌더링하며, 대신 경계로 들어오는 모든 연결을 .boundary.internal_uses_edges와 .boundary.incoming_cross_boundary_uses_edges에서 읽습니다. 그 injectMapping:은 그것이 작성하는 템플릿 중 컴포넌트의 컨텍스트 — attachment가 도달하는 각 컴포넌트의 컨텍스트로, .context.* 포함 — 에서 실행되는 유일한 템플릿이며, 그곳에서 .boundary를 참조하면 빌드가 중단됩니다.
이 필드는 attachment의 인스턴스 이름에 접근하는 유일한 경로입니다. .context.instance_id는 attachment가 해석되는 대상인 호스트 component입니다. 컴파일러가 평가하는 모든 템플릿 보고 위치에서, FeatureRecipe 자체의 locals:를 포함해 호스트를 가리킵니다. 따라서 두 이름은 서로 바꿔 쓸 수 없으며, 어느 쪽도 다른 쪽을 대신하지 않습니다.
.source는 부착 자체의 것입니다. FeatureRecipe의 source: 템플릿은 Recipe의 것이 자체 매핑보다 먼저 평가되는 것처럼 그 valuesMapping:보다 먼저 평가되며, 그 결과가 부착의 리소스를 생성하는 템플릿(그 valuesMapping:, omits:, workload:, artifacts:)과 그 pipeline: 단계에서 .source가 담는 내용입니다. 호스트 컴포넌트의 소스가 되는 일은 없습니다. source:를 선언하지 않았거나 템플릿이 아무것도 생성하지 않는 FeatureRecipe는 호스트의 Recipe가 소스를 선언하더라도 그곳에서 아무것도 읽지 않습니다. 경계 범위 FeatureRecipe는 같은 템플릿에서 자체 소스를 읽습니다. 유일한 예외는 injectMapping:으로, 부착의 소스가 평가되기 전에 실행되며 호스트 컴포넌트 자체의 Recipe처럼 .source를 읽습니다.
.context.rendered_name도 호스트 component의 것입니다. component별 attachment의 모든 템플릿에서 이 필드는 호스트 자신의 provider가 호스트에 대해 보고하는 이름, 즉 호스트 자신의 Recipe가 읽는 값을 담습니다. 따라서 attachment는 {{ .context.rendered_name }}-{{ .attachment_name }}로 호스트를 따라 리소스 이름을 지정하며, 호스트의 식별자에 밑줄이나 대문자가 있어도 플랫폼이 허용하는 이름을 얻습니다. 이 필드는 호스트의 provider가 이름을 보고하는 곳에서는 존재하고 보고하지 않는 곳에서는 없으며, 그런 호스트에서 이 필드를 읽으면 FeatureRecipe가 인라인으로 작성한 템플릿 중 injectMapping:을 제외한 어느 템플릿에서든 빌드가 중단됩니다. 렌더링된 리소스 이름 지정을 참조하십시오.
사이트별 가용성
필드 가용성은 템플릿 사이트에 따라 다릅니다. Recipe provides: 템플릿은 provides 평가 단계에서 자체 완결된 컨텍스트(.context.inject/.context.uses 없음)로 실행됩니다. Recipe valuesMapping:은 기본 렌더링 단계에서 전체 템플릿 컨텍스트로 실행되고, FeatureRecipe injectMapping:은 inject 매핑 단계에서 가로채는 대상인 inject 파이프를 포함한 전체 템플릿 컨텍스트로 실행됩니다. 사이트별 전체 가용성 표는 expansion-matrix.md에 있으며, 이 페이지는 해당 매트릭스의 “사용 가능한 참조” 열이 가리키는 필드 형태를 설명합니다.
상호 참조
05-templates.md— 템플릿 개요.expansion-matrix.md— 템플릿 사이트별 평가 매트릭스.sprig-functions.md— 템플릿 엔진에 연결된 Sprig 헬퍼.../entities/recipe.md— Recipe 작성 인터페이스.../entities/featurerecipe.md— FeatureRecipe 작성 인터페이스(.context.uses순회를 위한 K8s DNS 리졸버 작업 예제 포함).../vocabulary/topology-triad.md— 주입 계약 명세(이중 상태 컨텍스트, 키 충돌 규칙, 작업 예제 포함).../10-status.md#compilation-pipeline-phases— inject 매핑, 기본 렌더링, 플러그인 파이프라인 인터페이스의 현재 준비 상태.