FeatureRecipe
FeatureRecipe 엔터티의 개념적 역할(Domain 3 — Feature 인터페이스를 Wasm 플러그인 기반으로 구현하는 것)은 architecture/04-entity-taxonomy.md에서 설명합니다. 이 페이지에서는 FeatureRecipe 카탈로그 작성 표면을 다룹니다.
카탈로그 위치
FeatureRecipes는 경로의 첫 번째 세그먼트에 provider를 두는 방식으로 구성됩니다(Recipes와 같은 패턴):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlOCI URI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version}(예: hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
작성 계약
FeatureRecipes는 implements를 통해 Feature 인터페이스에 바인딩되며 구체적인 프로바이더를 선언합니다. 작성 표면은 기본 Recipe의 입력 종류 전체에 FeatureRecipe 전용 블록 두 개를 더한 것입니다.
- 세 가지 입력 종류 —
source+valuesMapping(소싱),workload(합성),artifacts: 형태는 기본 Recipe와 동일합니다(Recipe 입력 구성 및entities/recipe.md참조). 이 중 하나라도 가진 FeatureRecipe는 리소스 생성형이며, 기본 컴포넌트와 나란히 리소스를 렌더링합니다. 이 리소스가 놓이는 위치에는 Feature가 부착된 컴포넌트와 그 부착 이름이 차례로 담기며, 대상 자체의 레이아웃이 허용하는 두 형식 중 하나를 따릅니다. 프로바이더가 각 기여자에게 고유한 위치를 부여하는 대상에서는, 해당 대상이 기여자가 위치하는 디렉터리로 부르는 곳 아래에 호스트의 디렉터리와 나란히{component}--{instance}/디렉터리로 놓입니다. 디렉터리 바로 안에 있는 파일만 읽는 대상에서는 컴포넌트 자체 파일과 나란히{component}--{instance}--파일 이름 접두사로 놓입니다. 기여자를 단일 문서로 합성하는 프로바이더에서는 Feature가 어떤 계열에 속하든 리소스가 대신 그 문서에 병합됩니다. 예를 들어ServiceMonitor또는ExternalSecretCRD는 인라인 또는$importartifacts:로, 외부 차트나 모듈은source:+valuesMapping:으로, 자체 컴퓨트(예: 사이드카 에이전트 Deployment)는workload:로 표현합니다.valuesMapping:은 기본 Recipe의 세 가지 작성 모드(인라인 블록 스칼라, 파일$import:, MappingLibrary 항목에 대한 라이브러리$import:)를 공유합니다.entities/recipe.md의 “ThevaluesMappingfield — three authoring modes”를 참조하십시오. 관례상 FeatureRecipe는 기본 컴포넌트를 수정하거나 그와 나란히 리소스를 추가하지만, 스키마는 사용할 수 있는 입력 종류를 제한하지 않습니다. 컴파일러는 바인딩된 프로바이더의 기능에 의해서만 제한된 채 FeatureRecipe가 선언한 것을 무엇이든 렌더링하며, 특정 종류가 “수정자에 적합한지”에 대해 주관이 없는 태도를 유지합니다(기본 불변식 참조). 합성(workload:)에는 이를 지원하는 프로바이더가 필요하며, 그렇지 않으면 빌드는 렌더링 단계에서 프로바이더 기능 진단과 함께 중단됩니다. injectMapping(렌더링 전 가로채기): 기본 Recipe가 렌더링되기 전에 실행되는 네이티브 Go 템플릿 블록입니다. 컴파일러가 호출자의.context.inject메모리 파이프 위에 기본적으로 깊은 병합하는 JSON 또는 YAML 딕셔너리를 출력하여, Wasm 없이 호출자 측에서 환경 변수와 연결 문자열을 변경할 수 있게 합니다.pipeline: 렌더링 후 Workload 변경을 위한 WebAssembly(Wasm) 플러그인 단계의 순차 배열입니다(예: JSONPatch로 Envoy 사이드카 주입, 시크릿 볼륨 마운트). 각 단계의plugin필드는 URI로Plugin엔터티를 지정하며, 이 URI는 항상 플러그인 자체의 소켓 유형으로 범위가 지정됩니다(<pluginType>/<name>, 버전은 선택 사항이며parser/yaml또는parser/yaml:1.0.0과 같은 형태). 빌드는 엔터티를 플러그인의 식별 정보와 구성된 레지스트리로부터 찾은 콘텐츠 주소 지정.wasm아티팩트로 해석하며, 여기서는 단독.wasm이나 아티팩트 참조를 허용하지 않습니다. 플러그인 작성 및 참조 방법은 Wasm 플러그인 개발자 가이드를, 2부 플러그인 원칙(Fetcher / Injector)은 architecture/04-entity-taxonomy.md §“Domain 3: Infrastructure Base”를 참조하십시오. 컴파일러는 선언된 순서대로 각 단계를 실행합니다. 지정된 플러그인의 게스트 익스포트를 렌더링된 출력에 대해 호출하고, 반환된 JSON Patch와 방출된 부수 효과를 적용합니다. 각 파이프라인 표면의 실행 상태는 언어 현황을 참조하십시오.pipeline:은 단독으로 존재할 수 있습니다. FeatureRecipe는 입력 종류 없이 파이프라인만 선언할 수 있으며, 이 경우 자체 리소스는 방출하지 않고, 그 효과는 오직 단계들이 빌드가 이미 렌더링한 문서에 패치하거나 그와 나란히 방출하는 내용뿐입니다.
FeatureRecipe는 이 블록을 하나도 갖지 않을 수도 있습니다. 자신이 가진 uses 엣지가 효과의 전부인 순수 연결용 Feature는 아무것도 렌더링하지 않으며, 그 FeatureRecipe는 해석을 충족하기 위해서만 존재합니다. 모든 컴포넌트가 Recipe로 해석되는 것과 마찬가지로 모든 기능 인스턴스는 FeatureRecipe로 해석됩니다. 위 블록 중 injectMapping은 기본 Recipe에 대응 항목이 없는 유일한 필드이며, 세 가지 입력 종류와 pipeline은 기본 Recipe와 공유됩니다.
FeatureRecipe 옆에 고정되는 것은 Recipe 옆에 고정되는 것과 같습니다. 즉 artifacts 항목이 가져오는 각 파일의 다이제스트와, 좌표가 전부 명시된 각 원격 source:의 다이제스트가 FeatureRecipe 자체 디렉터리의 entity.lock에 기록됩니다. 이 파일은 aggrega pin이 작성하며, 사용자는 이를 FeatureRecipe 옆에 커밋합니다. 잠금 파일에 해당 고정 정보가 기록되지 않은 FeatureRecipe에 대한 pull은, 그 단계를 실행하도록 요청받지 않는 한 중단되며 해당 단계를 명시합니다. 가져온 파일이 더 이상 다이제스트와 일치하지 않거나, 소스의 다이제스트가 Release의 잠금 파일에 기록된 값과 다르면 빌드가 중단됩니다(git ref:로 작성된 소스는 해석된 커밋으로 기록되며 비교하지 않습니다). FeatureRecipe 파일 자체에는 절대 쓰지 않습니다. 파일의 내용과 각 중단에 대응하는 방법은 aggrega pull에 설명되어 있습니다.
소스 필드 템플릿
FeatureRecipe의 source:는 Recipe의 것과 같은 조건의 템플릿 표면입니다. 템플릿은 소스 해석 시점에 평가되며, 그 결과가 이후 빌드가 해석하는 대상입니다. 두 형태 모두 Go 템플릿을 받습니다. 범용 문자열 형태와, 문자열 값 하위 필드는 템플릿으로 평가되고 문자열이 아닌 하위 필드는 그대로 전달되는 구조화 객체 형태입니다. 형태 목록, 스킴 처리, 기준 위치 해석은 entities/recipe.md의 “Source field templating”, “Source field scheme inventory”, “How a source: path is anchored”에서 설명한 것과 같으며, 이 섹션에서는 어태치먼트에서 달라지는 점만 설명합니다.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"상대 결과의 해석 기준. 그것을 선언한 FeatureRecipe 문서가 있는 디렉터리, 즉 컴포넌트의 파일이 아니라 어태치먼트 자신의 파일이 기준이며, 결과는 Recipe의 경우와 똑같이 그 디렉터리 안에 머물러야 합니다. 디렉터리 밖으로 올라가거나 절대 경로인 결과는 FeatureRecipe와 함께 이동하지 않는 파일을 가리키므로 빌드를 중단합니다. 전송 스킴을 가진 결과는 디렉터리에 결합되지 않고 가져와집니다. 레지스트리에서 해석된 FeatureRecipe는 게시된 아카이브가 담은 파일을 콘텐츠 캐시에 배치한 것에서 읽으므로, 상대 결과는 카탈로그 디렉터리에서 FeatureRecipe 옆에 해석되는 것과 똑같이 게시된 내용 안에서 해석되며, 같은 경계가 적용됩니다.
템플릿이 읽을 수 있는 것. 참조 집합은 FeatureRecipe 자신의 locals: 항목이 검사받는 집합과 같으며, 컴포넌트가 아니라 어태치먼트가 해석된다는 점에서 비롯되는 두 가지 면에서 Recipe의 집합과 다릅니다.
.attachment_name을 사용할 수 있으며, Feature가 어태치된 인스턴스 이름을 가리킵니다. Recipe의 소스 템플릿은 이를 거부합니다. Recipe의 소스는 노드에 대해 해석되며 어태치먼트가 관여하지 않기 때문입니다..context.instance_id는 어태치먼트가 아니라 어태치먼트가 해석되는 대상인 호스트 컴포넌트를 가리키며,.context.rendered_name은 호스트 자신의 provider가 호스트에 대해 보고하는 이름을 담습니다. 이 값은 그 provider가 이름을 보고하는 경우에만 존재하며, 보고하지 않으면 빌드가 중단됩니다. 렌더링된 리소스 이름 지정을 참조하십시오.
.locals는 이 FeatureRecipe의 다른 템플릿이 읽는 집합을 담습니다. 자신의 해석된 블록이 있고 그 아래에 호스트 Recipe의 블록이 있으므로, 어태치먼트가 선언한 키가 같은 이름의 호스트 키보다 우선합니다. 그 집합에 없는 키를 참조하면 키를 렌더링에서 없애는 대신 중단하고 그 키를 알려 줍니다. .provides, .context.inject, .context.uses는 Recipe의 소스 표면이 거부하는 것과 같은 자기 완결성 근거로 거부됩니다.
경계 범위 FeatureRecipe는 대신 경계를 읽습니다. FeatureRecipe가 executionScope: boundary를 선언하는 Feature는 컴포넌트마다 한 번이 아니라 경계에 대해 한 번 렌더링되므로, 소스 템플릿에는 읽을 호스트 컴포넌트가 없습니다. 소스 템플릿은 .boundary.*를 읽으며(locals:와 provides:가 읽는 것과 같은 기둥), 컴포넌트별 기둥(.context, .workload, .attachment_name, .inject)은 사용할 수 없습니다.
빈 결과. 아무것도 생성하지 않는 템플릿은 어태치먼트에 소스를 남기지 않으며, 이는 소스 없는 모드입니다. Recipe의 소스가 취하는 것과 같은 해석이며, 직접 source: ""를 작성하는 것과는 다릅니다.
이후 .source가 읽는 것. 소스는 Recipe의 소스가 그 Recipe 자신의 매핑보다 먼저 평가되는 것처럼 valuesMapping:보다 먼저 평가되며, 그 결과는 이후에 실행되는 모든 템플릿에서 .source가 됩니다. 즉 valuesMapping:, omits:, workload:와 artifacts: 본문, 그리고 pipeline: 단계입니다. 따라서 .source를 읽는 valuesMapping:은 이 FeatureRecipe 자신의 소스를 읽으며, 그것이 첨부된 컴포넌트의 소스는 결코 읽지 않습니다. 또한 이 FeatureRecipe가 소스를 선언하지 않거나 그 템플릿이 아무것도 만들어 내지 않으면 아무것도 읽지 않습니다. 경계 범위의 FeatureRecipe도 같은 방식으로 자신의 소스를 읽습니다. injectMapping:은 첨부의 소스가 평가되기 전에 실행되므로, 거기서의 .source는 호스트 컴포넌트의 것입니다.
injectMapping의 배타성
injectMapping 필드는 FeatureRecipes 전용이며, 기본 Recipe 스키마에는 의도적으로 없습니다. 이 배타성은 변수 가로채기를 valuesMapping과 분리합니다. 기본 Recipe의 valuesMapping은 FeatureRecipe injectMapping 블록이 생성한 재작성된 .context.inject 문자열을 그 사실을 모른 채 소비하므로 둘은 분리된 상태로 유지됩니다. 이 메커니즘이 어떻게 동작하는지는 아래의 inject-mapping 가로채기 섹션을, 렌더링 전 가로채기의 전체 의미론은 inject mapping에 관한 architecture/10-compilation-pipeline.md를 참조하십시오.
Inject-mapping 가로채기: injectMapping의 동작 방식
호출자가 대상에 대한 연결 문자열을 대상의 수정되지 않은 .provides.host와 다른 형태로 필요로 할 때(경계를 넘는 Kubernetes DNS를 위해 네임스페이스를 덧붙이거나, 다중 리전 게이트웨이를 위해 리전 코드를 접두사로 붙이거나, DSN에 SSL 모드 접미사를 추가하는 경우) injectMapping은 기본 Recipe의 valuesMapping이 inject 파이프를 보기 전에 호출자 측에서 그 변경을 처리합니다.
injectMapping 필드는 렌더러가 inject 매핑 단계에서, 기본 Recipe의 렌더링이 실행되기 전에 평가하는 Go text/template입니다. 템플릿은 선택적 메커니즘 키(env, file, arg, 또는 컴포넌트의 Recipe가 .context.inject.<name>에서 읽는 사용자 정의 메커니즘)를 가진 JSON 또는 YAML 딕셔너리 또는 기본적으로 env로 간주되는 평탄한 맵을 출력하며, 렌더러는 이 오버레이를 호출자 노드의 .context.inject 파이프 위에 깊은 병합합니다. injectMapping을 통한 호출자 측 라우팅은 inject 매핑 단계에서 실행되며, 단순한 문자열 조작을 위해 Wasm 샌드박스를 호출하지 않습니다. Wasm 플러그인은 pipeline 배열을 통한 구조적 AST 변경용으로 남겨 둡니다.
각 값은 toJson을 통해 작성하십시오. 렌더러는 템플릿의 출력을 YAML로 읽으므로, 따옴표 사이에 있는 그대로 삽입한 값은 큰따옴표나 백슬래시를 포함하는 순간 그 출력을 깨뜨리거나 변경된 채로 다시 읽힙니다. 비밀번호가 흔한 경우입니다. toJson은 값을 JSON 문자열로 작성하며, YAML은 이를 정확히 다시 읽으므로 값은 담고 있는 모든 문자와 함께 전달됩니다:
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}여러 조각으로 조립하는 값은 아래 예제처럼 먼저 조립한 뒤 toJson을 통해 한 번만 작성합니다.
읽을 수 없는 출력은 빌드를 중단시킵니다. 템플릿의 출력이 어느 형태로도 읽히지 않으면(흔한 원인은 안의 값 때문에 깨진 따옴표 스칼라입니다) 그 키를 하나도 전달할 수 없으므로, 빌드는 아무것도 전달되지 않은 것처럼 컴포넌트를 렌더링하는 대신 연결과 FeatureRecipe를 명시하며 중단됩니다. fatal-halts.md의 “An attached Feature’s injectMapping output cannot be read (연결된 Feature의 injectMapping 출력을 읽을 수 없음)”를 참조하십시오. 제시되는 사유는 민감하다고 선언된 값에 의존할 때 숨겨집니다. 비어 있는 출력, 또는 아무것도 전달하지 않는 딕셔너리로 파싱되는 출력은 아무것도 전달하지 않으며 실패가 아닙니다.
최상위 키는 메커니즘이며, all은 메커니즘이 아닙니다. 딕셔너리 출력의 각 최상위 키는 그 항목이 전달되는 메커니즘을 가리킵니다. env, file, arg, 또는 그 밖의 어떤 이름이든 될 수 있으며, 그 밖의 이름은 그 이름의 독자적인 메커니즘으로 전달됩니다. .context.inject.all은 병합 후 그 메커니즘들로부터 구성되며 출력에서 병합되는 일이 없으므로, all: 아래에 작성한 항목은 아무 데도 도달하지 않습니다. 대신 빌드가 중단되며, 연결, 키, FeatureRecipe를 명시하고 출력이 가질 수 있는 키를 알려 줍니다. fatal-halts.md의 “An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (연결된 Feature의 injectMapping 출력이 아무것도 전달하지 않는 키 아래에 전달 항목을 작성함)”를 참조하십시오. 그러한 항목은 컴포넌트가 읽어 들이는 메커니즘 아래에 작성하십시오.
변경은 엄격하게 호출자 로컬입니다. FeatureRecipe는 자신이 연결된 노드의 inject 파이프만 수정하며, 대상의 .provides 출력은 절대 수정하지 않습니다. 대상의 .provides.host는 클러스터 전반의 여러 호출자가 사용할 수 있습니다. 호출자 측 injectMapping은 특정 호출자의 파이프에만 병합되므로, 라우팅 변경은 그것을 요청한 엣지 범위에 머무릅니다.
매핑이 다시 쓸 수 있는 것. 매핑이 렌더링될 때에는 모든 inject: 블록이 이미 전달을 마친 상태이므로, 매핑의 출력은 항상 다른 무언가가 이미 작성한 키 위에 병합됩니다. 그리고 누가 키를 작성했는지에 따라 결과가 달라집니다. 호출자 자신의 inject: 블록이나 그 연결 중 하나의 inject: 블록이 전달한 키는 매핑이 다시 쓸 수 있습니다. 이것이 가로채기이며, 매핑의 값이 해당 항목 하나를 대체합니다. 매핑 자신의 연결이 inject: 블록을 통해 전달한 키도 마찬가지로 다시 쓸 수 있습니다. 다른 연결된 Feature가 자신의 inject: 블록이나 자신의 FeatureRecipe의 injectMapping을 통해 이미 전달한 키는 다시 쓸 수 없습니다. 이 경우 마지막에 실행된 매핑이 호출자가 읽을 값을 정하게 두는 대신, 빌드는 두 연결을 모두 명시하며 중단됩니다. 따라서 두 라우팅 Features는 각각 자신의 키를 한정할 수 있지만, 두 Features가 하나의 키를 함께 전달할 수는 없습니다. 두 라우팅 Features가 같은 연결의 키를 다시 쓰는 경우도 포함되는데, 첫 번째는 가로채기이고 두 번째는 첫 번째의 전달과 충돌하기 때문입니다. fatal-halts.md의 “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (연결된 두 Features가 하나의 키를 전달하며, 나중 것은 FeatureRecipe의 injectMapping을 통해 전달함)”을 참조하십시오.
결합 없는 대상 추론
컴파일러가 각 대상의 계단식 어노테이션을 호출자의 .context.uses 파이프에 포함하므로, injectMapping 템플릿은 Ops가 대상 식별 정보를 Feature의 infra에 하드코딩하지 않고도 라우팅 좌표를 추출할 수 있습니다.
- 템플릿은
.context.uses를 검색하여 개발자가 요청한 변수를 주입한 정확한 토폴로지 엣지를 찾습니다. - 대상의 계단식
release_annotations(예:aggrega.ai/namespace)를 추출합니다. - 정규화된 도메인 이름(FQDN) 또는 연결 문자열을 구성합니다.
- 재정의 딕셔너리를 내보냅니다.
컴파일러는 네트워킹 의미(Kubernetes 네임스페이스, 클라우드 리전, 브리지 프록시 토폴로지)에 구애받지 않으며, 템플릿이 생성한 결과로 깊은 병합을 실행할 뿐입니다. 이후 기본 Recipe의 valuesMapping이 실행되면, .context.inject.env에서 가로채어 다시 쓴 문자열을 개발자의 원본인 것처럼 사용합니다.
작업 예제: K8s DNS 리졸버
표준 카탈로그는 이를 helm FeatureRecipe와 함께 core/k8s-dns-resolver로 제공합니다. 환경 변수 이름은 컨테이너 내에서 고유해야 하므로, target_var(예: API_HOST)는 호출자 내 특정 주입 계약에 대한 전역 고유 식별자 역할을 합니다. 템플릿은 .context.uses의 명시적 엣지를 순회하며 어느 엣지가 target_var를 선언했는지 확인함으로써 올바른 대상 노드를 찾고 그 네임스페이스를 읽습니다. 유일한 매개변수는 다시 쓸 변수이며, 대상과 그 네임스페이스는 하드코딩되지 않고 탐색됩니다.
라우팅 Feature 스키마(core/k8s-dns-resolver):
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}FeatureRecipe 구현:
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}라우팅 이외의 사용 사례
injectMapping은 주로 경계를 넘는 주소 해석(위의 K8s DNS 리졸버와 같은)에 사용되지만, 이러한 호출자 측 변경은 인프라 렌더링 전에 개발자의 의도를 가로채 형식화해야 하는 모든 시나리오에 적용됩니다. 다음 두 가지 패턴이 그 범위를 보여 줍니다.
동적 보안 형식화(SSL 추가기). 기업이 모든 외부 데이터베이스 연결에 엄격한 TLS 검증을 의무화하는 경우, Feature가 개발자가 요청한 DB_URL을 가로채 필요한 SSL 모드를 덧붙여 애플리케이션이 올바른 보안 매개변수로 기동되도록 할 수 있습니다.
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}다중 리전 게이트웨이 접두사 지정. 범용 API 컴포넌트가 전역적으로 배포되는 경우, 리전 라우팅 Feature가 자체 환경 경계 어노테이션을 자율적으로 조회하여 호출자에게 주입되는 연결 문자열에 접두사를 붙일 수 있습니다.
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}injectMapping의 경계. 이 메커니즘은 .context.inject 메모리 파이프(전달 계약)를 변경하는 것으로 제한됩니다. 새 컨테이너를 추가하거나, 볼륨을 마운트하거나, 기본 Recipe의 valuesMapping 출력을 변경할 수 없습니다. 렌더링된 AST에 구조적 변경(JSON 또는 YAML 배열 등)이 필요한 변경은 WebAssembly 플러그인을 통해 실행되는 FeatureRecipe의 pipeline 배열에 속합니다.
pipeline의 패치 대상 경계. pipeline 단계는 provider가 구조화된 트리로 렌더링하는 출력만 패치합니다. YAML 및 JSON 형태의 출력은 구조화되어 있으므로(JSON으로 작성된 Terraform .tf.json 모듈 포함), 단계의 JSONPatch는 지정된 값을 제자리에서 편집하고 나머지 모든 바이트(주석, 순서, 서식)는 그대로 둡니다. 네이티브 HCL Terraform 구성처럼 provider가 불투명한 본문으로 내보내는 출력은 패치 대상이 아닙니다. 불투명한 본문에 대한 패치는 구조적으로 지정할 수 없는 텍스트를 변경하는 대신 진단과 함께 빌드를 중단합니다. 따라서 불투명한 출력에 대해 pipeline 단계를 작성하는 것은 조용한 무동작이 아니라 명시적인 중단으로 드러나는 설계 오류입니다.
벤더링된 Terraform 모듈의 입력은 패치 대상이 아니며, 이 부재는 짚어 둘 가치가 있습니다. 이 입력은 해당 컴포넌트의 module 블록 인수로, terraform provider가 경계의 루트 구성에 작성합니다. 이는 네이티브 HCL이므로 위 규칙에 따라 불투명하며, 단계가 패치하는 출력의 노드가 아니라 경계 전체의 산출물입니다. 따라서 pipeline 단계가 이를 지정할 수 있는 위치는 없으며, 소스로 가져온 Terraform 모듈이 받는 값을 바꾸기 위해 할 수 있는 일도 없습니다. 이 값들은 작성되는 곳, 즉 기본 Recipe의 valuesMapping:에서 형성됩니다.
조건부 단계 — when:
pipeline 단계에는 선택적 when: 필드를 둘 수 있습니다. 이 필드는 컴파일러가 파이프라인 순회 시점에 평가하는 인라인 Go 템플릿으로, 해당 단계의 with: 본문이 사용하는 것과 동일한 템플릿 컨텍스트와 평가기로 평가됩니다. 렌더링된 결과에 따라 단계의 실행 여부가 결정됩니다.
- 결과가 거짓 값이면 단계는 통과 처리되어 건너뜁니다. 문서 집합은 변경 없이 다음 단계로 넘어가며, 건너뛴 단계는 아무것도 기여하지 않습니다. 패치도, 부수 효과도, 실행되었다는 기록도 남기지 않습니다.
when:이 비어 있거나 없으면 단계는 항상 실행됩니다.
when:과 optional:은 서로 독립적입니다. when:은 단계의 실행 여부 자체를 결정하고, optional:은 실행 중인 단계의 실패를 완화합니다. 한 단계에 둘 다 선언할 수 있으며, 이 경우 when:이 진입을 제어하고, 단계가 실제로 실행되면 그 안에서 발생한 실패를 어떻게 처리할지는 optional:이 결정합니다. 렌더링에 실패하는 when: 템플릿은 작성상의 결함이며, optional:과 관계없이 빌드를 중단합니다.
렌더링된 when: 텍스트는 공통 불리언 템플릿 규칙에 따라 판정됩니다. 문자열 true, True, TRUE, 0이 아닌 모든 숫자, 그리고 그 밖의 비어 있지 않은 모든 문자열은 참이며, 문자열 false, False, FALSE, 빈 문자열, 그리고 0인 숫자는 거짓입니다.
자격 증명 FeatureRecipe 패턴
FeatureRecipe가 자격 증명 Feature(feature.aggrega.ai/kind: secret 레이블이 붙은 Feature)를 구현하는 경우, 이 FeatureRecipe는 Two-Part Plugin Principle을 따를 수 있습니다. 즉 Fetcher 플러그인(볼트별 CRD 생성)과 Injector 플러그인(대상 컨테이너에 시크릿 마운트)을 연결하는 pipeline으로, examples/04-secrets가 설명하는 형태입니다. 표준 라이브러리의 자격 증명 FeatureRecipes는 pipeline:을 선언하지 않고 시크릿 리소스를 직접 렌더링합니다. examples/05-credential-features를 참조하십시오.
자격 증명 FeatureRecipe는 다른 모든 어태치먼트의 FeatureRecipe와 동일한 Resource Generation 패스를 통해 렌더링되며, 그 pipeline:도 동일한 조건으로 실행됩니다. 컴파일러는 해당 패스에서 작업이 있는 모든 어태치먼트를 하나의 순서 있는 시퀀스로 순회하며 각 어태치먼트가 선언한 파이프라인을 실행하고, /own 및 /host 문서 집합 의미 체계도 동일합니다. 어태치먼트는 두 가지 이유 중 하나로 이 시퀀스에 포함됩니다. FeatureRecipe가 입력 kind를 선언하여 자체 리소스를 생성하거나, pipeline:을 선언하여 이미 출력된 문서를 재작성하는 경우입니다. 따라서 자격 증명 어태치먼트는 운영 어태치먼트와 똑같이 호스트 컴포넌트의 렌더링된 문서에 접근하여 시크릿 볼륨을 마운트하거나 env 참조를 추가할 수 있으며, 둘의 유일한 차이는 자체 생성 파일이 놓이는 위치입니다.
컴포넌트에서 Feature의 민감도 선언은 Component의 선언이 Recipe의 것을 따르는 것과 정확히 같은 방식으로 FeatureRecipe의 valuesMapping:을 따릅니다. FeatureRecipe가 valuesMapping: 없이 source:에서 렌더링하는 경우, 대상이 받는 값은 Feature가 선언한 리프 경로를 키로 가지므로 sensitive: true로 선언된 리프는 렌더링된 키를 표시합니다. FeatureRecipe가 valuesMapping:을 선언하는 경우, 키는 해당 템플릿이 자체적으로 만든 것이어서 어떤 선언도 이를 지칭하지 않으며, 빌드는 그러한 리프마다 어태치먼트, 리프, FeatureRecipe를 명시하는 권고를 하나씩 출력합니다. 경계에 연결된 Feature는 권고를 발생시키지 않습니다. 그 .values는 항상 비어 있으므로 표시할 값을 가진 선언된 리프가 없기 때문입니다. A declared-sensitive value reaches the target through a values mapping (민감한 것으로 선언된 값이 값 매핑을 통해 대상에 도달함)을 참조하십시오.
provides: 블록 — 소비자에게 게시하기
FeatureRecipe의 provides: 블록은 그 게시 출력으로, attachment 자체의 스코프(.values, .infra, FeatureRecipe의 완전히 해석된 .locals, 그리고 호스트 노드의 .context.instance_id와 .context.rendered_name)에 대해 평가되는 Go 템플릿의 문자열 값 맵입니다. locals가 먼저 해석되므로 provides: 항목은 이를 읽어 해석된 값을 받으며, locals: 블록이 선언하지 않은 키를 지정하면 빌드가 중단됩니다. 이는 attachment가 자신이 생성한 것 — 출력된 리소스의 이름, 생성된 데이터 키, 클라우드 ID — 을 소비자에게 알리는 방법이며, 소비자가 같은 입력으로부터 그 ID를 다시 도출할 필요가 없게 합니다.
소비자는 이를 .features.<instance-name>.provides.<key>(credential attachment의 경우 .features.<slot>.provides.<key>)에서 읽으며, 이는 uses 엣지의 .context.uses.<alias>.provides와 대응됩니다. attachment가 소비자의 연결 중 하나에 작성된 경우 소비자는 같은 맵을 그 연결 아래 .context.uses.<alias>.features.<slot>.provides.<key>에서 읽으며, 해당 attachment는 소비자의 .features에 포함되지 않습니다(연결의 attachment 참조). attachment 자체의 inject: 블록은 from: 참조를 같은 맵에 대해 해석하므로, 작성자는 두 채널 중 하나를 선택할 수 있습니다. 템플릿에서 읽으려면 provides를, env var, 파일 또는 arg로 전달하려면 inject를 사용합니다.
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"이 FeatureRecipe가 implements하는 Feature가 schema.provides 계약을 선언하면, 그 계약은 FeatureRecipe에 대해 강제됩니다. Feature가 선언하는 모든 키는 FeatureRecipe의 provides:에 나타나야 하며, 그렇지 않으면 누락된 키를 지정하며 빌드가 중단됩니다. 추가로 게시되는 키는 허용됩니다 — 계약은 하한이지 상한이 아닙니다. 값은 결코 검사되지 않으며, 런타임이 해석하는 불투명한 결정적 포인터입니다.
해석은 소비자가 렌더링되기 전에 attachment마다 한 번 이루어지며, 같은 해석된 맵이 소비자의 읽기, 계약 검사, 그리고 attachment 자체의 Resource Generation에 사용됩니다. 따라서 소비자가 읽는 것과 attachment가 출력하는 것은 서로 어긋날 수 없습니다.
Provider와 implements
spec.capability는 필수이며, FeatureRecipe의 출력을 렌더링하는 Wasm 렌더링 플러그인을 가진 프로바이더(helm, helm-chart, compose 등)를 지정합니다. 조건은 Recipe의 spec.capability와 같습니다(entities/recipe.md 참조). 버전 고정은 해당 플러그인의 어느 버전으로 렌더링할지를 선택하며 FeatureRecipe 이름의 일부가 아닙니다. Manifest는 capability: "compose:1.2.3"을 선언한 FeatureRecipe를 compose/<name>:<version>으로 매핑하며, 이름에 고정을 써 넣은 매핑 값은 무엇이든 조회되기 전에 잘못된 레시피 참조(E0095)로 거부됩니다. implements 필드는 FeatureRecipe를 해당 Feature 인터페이스에 바인딩하며, 정확한 일치, 메이저 호환 범위 일치, 버전 없는 일치를 지원합니다. implements 버전 매칭 의미론은 vocabulary/inheritance-and-interface를 참조하십시오.
실행 범위 — spec.executionScope
선택적 spec.executionScope 열거형은 Resource Generation의 디스패치 모델을 선택합니다. 허용되는 값은 두 가지이며, 필드를 생략하면 기본값은 component입니다.
component(기본값). FeatureRecipe의 Resource Generation은 연결된 컴포넌트 인스턴스마다 한 번씩 실행됩니다. 각 호출은.context.*를 루트로 하는 컴포넌트별 템플릿 컨텍스트를 받습니다:.context.instance_id,.context.inject,.context.uses,.context.annotations등. 그valuesMapping:,workload:,artifacts:는.context.used_by도 읽습니다. 이는uses항목이 호스트를 가리키는 컴포넌트들로, 각각 자신의 식별 정보, 소켓, 게시하는 내용, 배치된 네임스페이스와 경계를 함께 가지며, 호스트 자신이 렌더링하는 어떤 템플릿도 이를 볼 수 없습니다.boundary. Resource Generation은 경계의 하위 트리 안에서 얼마나 많은 컴포넌트가 기능을 소비하든 관계없이 연결된 경계마다 한 번 실행됩니다. 각 호출은.context.*대신.boundary.*를 루트로 하는 경계 범위 템플릿 컨텍스트를 받습니다.
위에서 설명한 injectMapping 가로채기는 executionScope와 관계없이 항상 소비자별로 이루어집니다. 기능을 사용하는 각 컴포넌트는 여전히 .context.inject에 대한 자체 호출자 측 재작성을 받습니다. Resource Generation 단계(source/valuesMapping 및 pipeline 배열)만 경계 범위에서 중복 제거됩니다.
따라서 경계 범위 FeatureRecipe의 템플릿은 두 가지 범위에서 실행됩니다. 그 injectMapping은 어태치먼트가 도달하는 각 컴포넌트마다 한 번씩, 해당 컴포넌트의 컨텍스트를 대상으로 실행됩니다. 이는 컴포넌트 범위 FeatureRecipe의 injectMapping이 읽는 컨텍스트로, .context.*, .attachment_name, .features, 그리고 어태치먼트 자체의 .values, .infra, .locals입니다. 여기서 .infra는 경계 어태치먼트의 infra: 블록이고, .locals는 경계에 대해 한 번 평가된 블록입니다. 그 밖에 작성하는 모든 템플릿(locals:, provides:, source:, valuesMapping:, artifacts:, 그리고 파이프라인 단계의 with:와 when: 포함)은 아래의 경계 범위 컨텍스트를 대상으로 경계에 대해 한 번 실행됩니다. 각 템플릿은 실행되는 범위를 기준으로 검사됩니다. .context.instance_id를 읽는 valuesMapping:은 빌드를 중단시키고, 이를 읽는 injectMapping은 해당 컴포넌트의 식별 정보를 렌더링합니다. .boundary는 어떤 컴포넌트의 컨텍스트에도 설정되지 않으므로, FeatureRecipe의 executionScope가 무엇이든 이를 읽는 injectMapping은 참조를 명시하며 빌드를 중단시킵니다.
경계 범위 템플릿 컨텍스트
executionScope: boundary일 때 FeatureRecipe의 injectMapping 이외의 템플릿은 기능이 연결된 경계의 .boundary.* 뷰를 대상으로 평가됩니다. 이 뷰는 다음을 노출합니다:
.boundary.path— 기능이 연결된 Release 경계의 경로로, 가장 바깥쪽부터 안쪽으로 경계 이름을/로 이은 것입니다(bridge,bridge/frontend). 이는 경계를 가리키며, 출력이 기록되는 디렉터리를 가리키지 않습니다. 디렉터리는directory:가 설정합니다(.context.instance_id를 대체)..boundary.assembly_path— 빌드의 출력 디렉터리를 기준으로, 어태치먼트 자체의 출력이 조립되는 디렉터리입니다. 경계의 평가된directory:와subDirectory:, 즉 빌드가 그 출력을 보내는 디렉터리입니다(bridge/compose). 연결 엔드포인트가 같은 조립 파일로 렌더링될 때에만 그 엔드포인트의source_assembly_path또는target_assembly_path와 같으므로, FeatureRecipe는 이들을 비교하여 자신의 파일 안에 있는 연결과 다른 파일에 있는 연결을 구별합니다..boundary.boundary_name— Release에서 작성된 경계의 이름입니다..boundary.components— 인스턴스 ID를 키로 하며 경계의 하위 트리에 있는 모든 컴포넌트를 담는 맵입니다(instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges— 두 끝점이 모두 이 경계의 하위 트리 안에 있는uses:엣지입니다(compose-bridge 패턴은 이를 열거하고, 두 끝점이 자신의 compose 파일로 조립되면서 그 파일의 서로 다른 네트워크에 배치된 엣지만 남겨 엣지별 프록시 구성을 도출합니다). 각 엣지는 끝점들의 해석된 provides, 주입된 환경 변수, 그리고 각 끝점의 배치를 담습니다:source_namespace와target_namespace, 즉 해당 끝점에 적용되는aggrega.ai/namespace어노테이션(자체 Release 항목에 설정이 있으면 그 설정, 없으면 해당 경계의 설정), 끝점을 담고 있는 Release 경계의 경로인source_boundary_path와target_boundary_path, 그리고 빌드의 출력 디렉터리 아래에서 프로바이더가 끝점을 조립하는 디렉터리로서 경계의 평가된directory:와subDirectory:로 구성되는source_assembly_path와target_assembly_path(bridge/compose)입니다. 조립 경로가 같은 두 끝점은 하나의 조립 파일로 렌더링되며, 적용되는 네임스페이스가 없으면 compose 프로바이더는 조립 경로를 끝점의 네트워크로 읽습니다..boundary.outgoing_cross_boundary_uses_edges— 소스가 하위 트리 안에 있고 대상이 밖에 있는 엣지입니다..boundary.incoming_cross_boundary_uses_edges— 대상이 하위 트리 안에 있고 소스가 밖에 있는 엣지입니다(인그레스 방식 집계기가 사용합니다)..boundary.cross_boundary_uses_edges— FeatureRecipe가 전체 경계 간 뷰를 원할 때 사용하는, 들어오는 경계 간 엣지와 나가는 경계 간 엣지의 합집합입니다..boundary.labels— 작성 순서를 보존한 하위 트리 레이블의 합집합입니다..boundary.annotations— 경계 자체의 어노테이션과 캐스케이드입니다..boundary.feature_attachments— 이 경계에 연결된 모든 기능입니다(필요한 경우 경계 범위 FR이 형제 기능을 살펴볼 수 있도록).
경계 범위 FR의 .infra 축은 경계에 연결된 기능의 infra: 블록(해당 경계 연결에 대해 Release 측에서 작성한 물리적 크기 설정)으로 해석됩니다. 경계 범위 FR에서 .values는 항상 비어 있습니다: Release 스키마의 축 분리 규칙은 Release 수준 Feature 연결에 values:를 금지하므로, 경계에 연결된 기능은 투영할 값을 갖지 않습니다. 매개변수 형태의 데이터가 필요한 경계 범위 FR은 .infra(경계 기능 구성을 위한 운영자의 작성 영역) 또는 .boundary.annotations(경계 또는 임의의 상위 경계에 작성되어 캐스케이드로 해석 가능한 문자열 값)를 통해 이를 소비해야 합니다. .parameters는 뷰에 포함되지 않으며, 이를 읽는 템플릿은 뷰가 정의하는 루트를 명시하며 중단됩니다. .locals는 계속 FR 자체의 locals 블록입니다. .steps와 .metadata는 변경되지 않습니다.
경계 범위 템플릿 필드 허용 목록
경계 범위 FR은 injectMapping을 제외한 모든 템플릿에서 경계 범위 뷰에서 사용할 수 있는 필드만 참조할 수 있습니다. executionScope: boundary일 때 컴포넌트별 전용 필드(예: .context.instance_id, .context.inject, .context.uses)를 참조하는 그러한 템플릿을 작성하면, FeatureRecipe는 파싱 시점에 검증에 실패하며 FR, 문제가 되는 필드, 경계 범위 뷰가 정의하는 필드를 명시하는 오류가 발생합니다. 반대 방향에도 대칭 규칙이 적용됩니다: .boundary.* 필드를 참조하는 컴포넌트 범위 FR은 동일한 검증기에서 실패합니다. injectMapping은 어느 범위에서든 자신이 실행되는 컴포넌트의 컨텍스트를 기준으로 검사되므로 .context.*를 읽을 수 있으며, 그 안에서 .boundary를 참조하면 참조와 해당 컨텍스트가 정의하는 루트를 명시하며 중단됩니다.
검증기는 경로 템플릿 변수 허용 목록이 사용하는 것과 동일한 템플릿 AST 순회를 실행하되, 범위별로 다른 참조 집합을 사용합니다.
중복 제거와 Resource Generation 출력
executionScope: boundary의 경우 컴파일러는 (boundary_path, FR-instance) 튜플로 Resource Generation을 중복 제거합니다. 같은 경계 하위 트리 안의 두 컴포넌트가 모두 동일한 경계 연결 기능을 소비하면 FR 호출은 두 번이 아니라 한 번 발생합니다. 같은 기능의 경계 간 연결은 경계마다 독립적으로 실행됩니다.
경계 범위 FR은 (boundary_path, FR-instance) 튜플마다 비중간 파일 한 세트를 내보내며, 그 위치는 프로바이더가 경계의 출력을 어떻게 결합하는지에 따라 정해집니다. 컴포넌트 범위 연결은 컴포넌트도 함께 가지지만, 여기서는 인스턴스 이름만이 좌표입니다: 경계 범위 기능은 어떤 컴포넌트가 아니라 경계에 연결되므로, 둘러싼 경계 디렉터리가 이미 컴포넌트 세그먼트가 말할 모든 것을 말해 주며, 명명할 컴포넌트도 없습니다.
각 문서를 경계 디렉터리에 직접 쓰는 프로바이더는 자신의 대상이 디렉터리 바로 안에 있는 파일만 읽는다고 선언합니다. 따라서 연결이 들어갈 둘러싼 디렉터리가 없으며, 대신 인스턴스 이름이 파일 이름 접두사가 됩니다: 경계 자체 파일 옆의 <boundary_directory>/<fr-provider>/<feature-instance>--<file>입니다. 파일 이름에는 기댈 구분자가 없으므로 인스턴스 이름은 인코딩되며, 인코딩된 어떤 좌표도 포함할 수 없는 두 글자 경계에서 파일 자체 이름과 만납니다. 따라서 같은 파일 이름을 내보내는 두 연결도 여전히 두 개의 파일에 도달합니다.
경계의 출력을 둘러싼 구조로 합성하는 프로바이더(기여자마다 차트 하나를 담는 하나의 차트, 기여자마다 모듈 하나를 담는 하나의 루트 구성)는 모든 기여자를 각자의 하위 디렉터리에 배치하며, 경계 연결도 다른 기여자와 마찬가지인 기여자입니다. 그 출력은 <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/에 위치하며, 여기서 <contributors-directory>는 해당 대상이 하위 단위가 놓이는 곳을 부르는 이름입니다. 하위 디렉터리는 연결의 인스턴스 이름, 즉 경계의 features: 블록에서 작성한 이름을 가지므로, 빌드가 생성하는 디렉터리는 작성한 내용에서 찾을 수 있습니다.
중간 출력은 FR의 평가된 경로에서 FR 자체의 spec.capability 아래로 경계의 (경로, 프로바이더)별 어셈블러에 흘러갑니다. 이것이 core/compose-bridge Feature가 같은 어셈블리 경로에서 브리지 서비스를 컴포넌트별 compose 기여자와 함께 병합하는 데 사용하는 메커니즘입니다. 이러한 출력은 그곳에서 경계의 컴포넌트들로부터 조립되는 파일의 일부로만 기록되므로, 어떤 컴포넌트도 그 경로에 도달하지 않으면(예를 들어 모든 컴포넌트가 subDirectory:에 의해 다른 곳으로 보내진 경우) 빌드는 출력을 아무 데도 기록하지 않는 대신 경계, Feature, 출력이 보내진 경로, 프로바이더를 명시하며 중단됩니다(fatal-halts.md의 “A boundary-level Feature’s output reaches no assembled file (경계 수준 Feature의 출력이 어떤 조립 파일에도 도달하지 않음)” 참조).
캐스케이드를 인식하는 provides: 해석
boundary 범위 FR은 (boundary_path, FR-instance) 튜플마다 하나의 provides: 집합을 생성하며, 이를 한 번 평가합니다. FR의 provides: 템플릿은 boundary 범위 템플릿 컨텍스트로 평가됩니다(따라서 .boundary.components, .boundary.path, .infra는 참조할 수 있지만 소비자별 필드와 .values는 참조할 수 없습니다). provides 값은 소비자에 대해 상수입니다. boundary 하위 트리의 모든 소비자는 동일한 제공 값을 봅니다.
boundary 범위 FR provides의 소비자 측 해석은 어디서나 그 한 번의 평가를 읽습니다. 어태치먼트가 도달하는 각 컴포넌트는 .features.<instance-name>.provides.<key>에서 이를 읽습니다. 자체 Recipe의 템플릿에서도, 해당 컴포넌트의 컨텍스트에서 실행되는 FeatureRecipe 자체의 injectMapping에서도 마찬가지입니다. 어태치먼트가 담고 있는 uses 에지를 통해 .context.uses.<feature-alias>.provides.<provided-name>에서 읽는 소비자 Component도 같은 값을 얻습니다. 컴파일러는 이를 소비자가 속한 boundary에 대한 boundary 범위 FeatureRecipe의 provides:로 해석하며, 연결(attachment)별 기능 인스턴스 식별 정보를 담은 소비자의 uses 에지에서 boundary 범위 FR의 provides:까지 따라갑니다. 사전 패스가 소비자 조립 전에 해당 provides를 평가하므로, 소비자의 파이프가 구성될 때 값이 이미 존재합니다.
소비자별 효과는 injectMapping이 읽는 provides: 안의 테이블입니다. 소비자마다 무언가를 바꿔야 하는 경계 범위 FeatureRecipe는 경계의 연결로부터 소비자를 키로 하는 테이블을 provides:에서 한 번 계산하고, 그 injectMapping은 현재 컴포넌트의 행(.context.instance_id를 키로 하는 (index .features .attachment_name).provides)을 읽어, 모든 매핑이 따르는 규칙에 따라 소비자 자체의 파이프를 통해 전달합니다(매핑이 재작성할 수 있는 것 참조). 컴파일러는 FeatureRecipe가 작성한 테이블을 전달할 뿐 그 안의 어떤 것도 읽지 않습니다.
compose-bridge 패턴
compose-bridge FeatureRecipe는 경계 범위 FR의 대표적인 패턴이며, 위의 메커니즘으로 작성된 카탈로그 콘텐츠입니다. 컴파일러도 compose 프로바이더도 브리지의 로직을 전혀 갖고 있지 않으므로, 카탈로그는 core/compose-bridge Feature를 다르게 구현할 수 있습니다. core/compose-bridge 기능은 directory:를 공유하는 두 하위 경계(예: services-net과 data-net)를 포함하는 상위 경계에 연결되며, 각 하위 경계는 고유한 aggrega.ai/namespace 어노테이션(aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net)을 가져 각자 별도의 네트워크에 놓입니다. 어노테이션이 없으면 둘은 compose 파일 경로를 따라 이름 붙은 하나의 네트워크를 공유하며 브리지 없이 서로 도달합니다. 이 FR의 executionScope: boundary는 상위 경계 연결마다 FR을 한 번 실행합니다.
그 provides:는 브리지 테이블을 한 번 계산합니다. .boundary.internal_uses_edges에서 두 끝점이 자신의 compose 파일로 조립되고(source_assembly_path와 target_assembly_path가 모두 .boundary.assembly_path와 같음) 그 파일의 서로 다른 네트워크에 놓인 엣지를 남깁니다. 끝점의 네트워크는 그 aggrega.ai/namespace이며, 없으면 조립 경로입니다. 두 compose 파일 사이의 엣지는 브리지되지 않으며, 그 소비자는 대상 자체의 이름을 유지합니다. 브리지되는 각 엣지는 수신 포트(대상 자체의 포트, 또는 앞선 엣지가 이미 그 포트에서 수신 중이면 어태치먼트의 portBase(기본값 10000) 이상에서 처음으로 비어 있는 포트)와 업스트림(대상이 게시한 호스트, 즉 어태치먼트의 providesField가 지정하는 provides 필드(기본값 host)와 그 port)을 받습니다. 업스트림은 엣지에서 도출되며 직접 작성하지 않습니다. 같은 테이블에서 각 소비자의 재작성도 계산합니다. 엣지가 호스트 필드에서 전달하는 변수는 aggrega-gw:<listen port>가 되며, 같은 엣지가 port에서도 변수를 전달하는 경우에는 호스트 변수가 aggrega-gw가 되고 포트 변수가 수신 포트가 됩니다.
그 injectMapping은 각 소비자의 행을 전달합니다. 각 소비자의 컨텍스트에서 실행되며, .features.<attachment>.provides에서 테이블 중 해당 소비자의 행을 읽어 소비자 자체의 연결이 전달한 값(예: DB_HOST) 위에 전달합니다. 이는 가로채기입니다. 행이 없는 소비자는 아무것도 받지 않습니다. 소비자에 연결된 다른 Feature가 그 키를 전달한 경우(그 inject: 블록 또는 그 injectMapping을 통해), 빌드는 그 전달을 대체하지 않고 두 Features를 모두 명시하며 중단됩니다(fatal-halts.md의 “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (연결된 두 Features가 하나의 키를 전달하며, 나중 것은 해당 FeatureRecipe의 injectMapping을 통함)” 참조). 게이트웨이의 listen과 소비자의 재작성은 하나의 테이블에서 읽으므로, portBase로 재할당된 충돌을 포함하여 구조상 엣지마다 일치합니다.
그 valuesMapping은 게이트웨이를 작성합니다. FeatureRecipe 자체의 compose 프래그먼트가 aggrega-gw 서비스를 선언합니다. 브리지되는 것이 있으면 그 valuesMapping이 브리지되는 엣지마다 nginx stream server 블록 하나(listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, 각 업스트림이 시작 시 한 번이 아니라 연결 시점에 해석되도록 resolver 지시어 아래에 둠. 이 변수의 $는 $$로 작성되어 Docker Compose의 $ 보간이 nginx에 리터럴 $를 남김)를 추가하며, 이를 마운트된 compose config로 전달합니다. 이는 인라인 content:를 가진 최상위 configs: 항목으로, aggrega-gw에서 참조되고 /etc/nginx/nginx.conf에 마운트됩니다(따라서 nginx는 작성된 command: 없이도 이를 로드합니다). 인라인 configs.content에는 Docker Compose ≥ 2.23.1이 필요합니다. 또한 게이트웨이의 x-aggrega-networks-of 아래에 브리지되는 모든 끝점을 지정하며, compose 프로바이더가 이를 해당 끝점들이 배치된 네트워크로 해석하므로 게이트웨이는 브리지된 엣지가 걸치는 모든 네트워크(소비자의 네트워크와 대상의 네트워크)에 참여합니다. 런타임에 소비자는 aggrega-gw:<port>에 도달할 수 있고 게이트웨이는 대상으로 proxy_pass할 수 있습니다. 브리지되는 것이 없으면 프래그먼트가 선언한 게이트웨이는 여전히 렌더링되지만 유휴 상태입니다. 구성도, 추가 네트워크도, 재작성도 없습니다.
(경로, 프로바이더)별 compose 조립기는 같은 평가 경로에서 게이트웨이를 컴포넌트별 기여자와 함께 병합하여, 모든 컴포넌트와 브리지 게이트웨이를 포함하는 하나의 docker-compose.yaml을 만듭니다. 경계의 컴포넌트 중 어느 것도 게이트웨이의 파일로 조립되지 않으면, 빌드는 게이트웨이를 아무 데도 기록하지 않는 대신 중단됩니다. 업스트림은 결정적인 컴파일 타임 compose 서비스 포인터이며, compose의 런타임 DNS가 이를 해석합니다(컴파일 타임에 런타임 해석을 하지 않음).
호출자 이후에 렌더링 — spec.readsCallerRenderFacts
선택 사항인 spec.readsCallerRenderFacts(boolean, 기본값 false)는 이 FeatureRecipe의 템플릿이 호스트에 연결하는 컴포넌트들이 렌더링한 내용, 즉 각 호출자의 provider가 자신이 출력한 결과에 대해 보고하는 렌더 팩트를 읽는다는 것을 선언합니다. provider가 무엇을 어떤 이름으로 보고하는지는 해당 provider 자체의 계약입니다. provider가 보고할 수 있는 팩트는 게스트가 출력한 내용에 대한 팩트 보고에서 설명합니다.
이러한 연결이 렌더링되는 시점. 빌드는 컴포넌트를 고정된 순서에 따라 하나씩 렌더링하며, 연결은 보통 자신이 연결된 컴포넌트 바로 다음에 렌더링됩니다. 호스트에 연결하면서 그 순서상 뒤에 오는 컴포넌트는 그 시점에 아직 렌더링되지 않았으므로, 읽을 수 있는 출력이 존재하지 않습니다. FeatureRecipe가 readsCallerRenderFacts: true를 설정한 연결은 대신 빌드의 모든 컴포넌트가 렌더링된 뒤, 이 키와 readsTargetRenderFacts 중 어느 것도 설정하지 않은 모든 연결과 함께 렌더링됩니다. 따라서 연결이 평가되기 전에 각 호출자의 렌더링이 완료됩니다. 출력은 원래 놓였을 위치에 같은 이름으로 놓입니다. 이 키는 연결이 렌더링되는 시점을 바꿀 뿐, 무엇을 렌더링하는지는 바꾸지 않습니다. 나중에 렌더링되는 데서 비롯되는 순서 하나가 있습니다. FeatureRecipe가 호스트 컴포넌트의 문서를 다시 쓰는 pipeline을 가지고 있고 호스트의 provider가 개별 문서를 쓰는 경우, 그 단계들은 연결 순서가 아니라 호스트의 다른 연결들의 파이프라인이 끝난 뒤에 실행됩니다.
읽는 내용. 키가 설정되면 .context.used_by의 각 항목은 .render_facts를 가집니다. 이는 팩트 이름을 키로 하는 호출자의 렌더 팩트입니다. 모든 렌더 팩트는 리스트이므로, 항목이 하나뿐이더라도 템플릿은 항상 이를 range로 순회합니다. 그 항목은 호출자 자체의 렌더링과 호출자에 연결된 Features의 렌더링에서 올 수 있습니다. 한 이름이 각각에서 얻은 리스트는 하나로 합쳐지며, 호출자 자체 provider의 호출이 먼저, 그다음 각 Feature가 렌더링된 순서대로 옵니다. 호출자의 Feature 중 스스로 이 키를 설정한 것도 모든 컴포넌트 이후에 렌더링되므로, 그것이 보고한 내용은 여기에 포함되지 않습니다. provider가 아무것도 보고하지 않는 호출자는 빈 .render_facts를 가지므로, 아무도 보고하지 않은 이름은 아무것도 아닌 값으로 읽힙니다.
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}어떤 팩트 이름이 존재하고 각 항목이 무엇을 담는지는 호출자 provider의 문서화된 계약입니다. 예를 들어 helm provider의 경우 그 렌더 팩트가 이에 해당하며, 렌더링한 파드의 레이블을 나타냅니다. 호출자의 팩트는 FeatureRecipe의 valuesMapping:, workload:, artifacts:가 읽는 연결에 있습니다. pipeline: 단계의 with:와 when:은 호스트에 연결하는 컴포넌트를 전혀 보지 못하므로, 단계는 호스트 자체의 팩트만 읽습니다. 컴포넌트에 연결된 모든 FeatureRecipe는 이 키의 설정 여부와 관계없이 컴포넌트 자체의 팩트를 같은 형태로 .context.render_facts에서 읽습니다. 둘 다 템플릿 컨텍스트에서 설명합니다.
템플릿이 팩트를 읽을 때는 항상 이를 선언합니다. 이 키를 설정하지 않은 FeatureRecipe에 인라인으로 작성된 템플릿, 즉 valuesMapping:, workload: 또는 artifacts: 항목이 .context.used_by 아래의 render_facts를 읽으면, 빌드는 아무것도 렌더링하기 전에 해당 참조와 그것이 작성된 필드를 명시하며 중단됩니다(fatal-halts.md의 “A template reads its callers’ render facts without declaring it (템플릿이 선언 없이 호출자의 렌더 팩트를 읽음)” 참조). 이 검사는 작성된 그대로의 템플릿을 읽으므로, 템플릿 실행 중에 만들어지는 참조나 파일 또는 라이브러리에서 가져온 내용에 작성된 참조는 보지 못합니다. 또한 .context.used_by 외의 다른 리스트에서 render_facts라는 이름의 필드를 읽는 템플릿이나, 그 옆의 {{ with .context }} 안에서 호스트 자체의 팩트를 .render_facts로 읽는 템플릿은 호출자의 팩트를 읽는 것으로 취급됩니다. 호스트 자체의 팩트는 .context.render_facts로 전부 작성합니다. 연결이 렌더링되는 시점을 결정하는 것은 검사가 아니라 키이므로, 어떤 방식으로 도달하든 템플릿이 호출자의 렌더 팩트를 읽는 모든 FeatureRecipe에 이 키를 설정합니다. 이를 설정해도 나중에 렌더링된다는 점 외에는 비용이 없습니다.
파이프라인 단계는 호스트 자체의 팩트만 읽습니다. 단계는 호스트 컴포넌트 자체의 문서를 다시 쓸 수 있고, 컴포넌트 자체의 출력은 누가 연결하든 동일하므로, 단계의 with:와 when:은 호스트에 연결하는 컴포넌트를 결코 보지 못합니다. 이는 FeatureRecipe가 이 키를 설정하든 아니든 마찬가지이며, 키는 연결이 렌더링되는 시점만 결정할 뿐 단계가 보는 내용과는 관계가 없습니다. 따라서 인라인으로 작성된 단계의 with:나 when:이 .context.used_by 아래의 render_facts를 읽으면, 빈 값을 렌더링하는 대신 빌드는 아무것도 렌더링하기 전에 짧은 코드 E0326과 함께 해당 참조와 단계의 필드를 명시하며 중단됩니다. 단계에서는 호스트 자체의 팩트를 .context.render_facts로 전부 작성하여 읽고, 호출자의 팩트는 FeatureRecipe의 valuesMapping:, workload: 또는 artifacts:에서 읽습니다. 이 검사는 작성된 그대로의 템플릿을 읽으며, 위의 검사와 같은 한계를 가집니다.
범위. 이 키는 컴포넌트마다 한 번 렌더링되는 FeatureRecipe, 즉 기본값인 executionScope: component에 적용됩니다. executionScope: boundary를 선언한 FeatureRecipe는 키 설정 여부와 관계없이 항상 렌더링되던 곳에서 렌더링되며, 그 리소스를 생성하는 템플릿은 .context 대신 .boundary를 읽습니다.
대상 이후에 렌더링하기 — spec.readsTargetRenderFacts
선택 항목인 spec.readsTargetRenderFacts(boolean, 기본값 false)는 이 FeatureRecipe의 템플릿이 호스트가 연결된 컴포넌트들이 렌더링한 내용, 즉 그 각 대상의 provider가 자신이 출력한 결과에 대해 보고하는 렌더 팩트를 읽는다고 선언합니다. 이 키는 readsCallerRenderFacts와 연결의 반대쪽 끝을 읽습니다. 즉 호스트를 가리키는 uses 항목을 가진 컴포넌트가 아니라 호스트의 uses 항목이 가리키는 컴포넌트를 읽으며, 팩트 자체에 관한 나머지 모든 사항은 동일하게 적용됩니다.
두 키 중 어느 것이든 attachment를 모든 컴포넌트 이후에 렌더링되게 합니다. FeatureRecipe가 readsCallerRenderFacts: true, readsTargetRenderFacts: true 또는 둘 다를 설정한 attachment는 위 섹션에서 설명한 대로 빌드의 모든 컴포넌트가 렌더링된 후에 렌더링됩니다. 이러한 나중 렌더링은 하나뿐이며, 그것이 attachment의 출력이 놓이는 위치와 파이프라인 단계의 순서에 미치는 영향은 어느 키가 attachment를 그곳으로 옮겼든 동일합니다. 두 키는 attachment의 컨텍스트에서 어떤 연결이 팩트를 담는지만 다릅니다. 빌드 순서에서 호스트보다 뒤에 오는 대상도 그 시점에는 이미 렌더링되었으므로, 그것이 출력한 내용을 읽을 수 있습니다.
읽는 내용. 키가 설정되면 .context.uses의 각 항목은 .render_facts를 담습니다. 이는 대상의 렌더 팩트로, 팩트 이름을 키로 하며 호출자의 항목이 담는 것과 같은 형태입니다. 모든 렌더 팩트는 리스트이므로 템플릿은 항상 이를 range로 순회합니다. 항목은 대상 자체의 렌더링과 대상에 연결된 Features의 렌더링에서 올 수 있으며, 대상 자체의 provider 호출이 먼저 오고 그다음 각 Features가 렌더링된 순서대로 옵니다. 대상의 Feature 중 그 자체로 모든 컴포넌트 이후에 렌더링되는 것은 여기에 포함되지 않습니다. provider가 아무것도 보고하지 않는 대상은 빈 .render_facts를 담습니다. 템플릿은 한 연결의 팩트를 그 별칭 아래에서 .context.uses.<alias>.render_facts.<name>으로 읽거나, 각 연결의 팩트를 차례로 읽습니다:
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}키를 설정하지 않은 FeatureRecipe는 다른 무엇을 설정하든 어떤 연결에서도 .render_facts를 보지 못합니다. 어떤 팩트 이름이 존재하는지는 각 대상 provider의 문서화된 계약입니다. 예를 들어 helm provider의 경우 그 렌더 팩트가 렌더링한 파드의 레이블, 컨트롤러 셀렉터, 컨테이너 포트를 명시하며, 이는 egress 정책이 호스트가 접근할 수 있는 파드를 정확히 선택하는 데 필요한 정보입니다.
템플릿이 팩트를 읽을 때는 항상 선언합니다. 키를 설정하지 않은 FeatureRecipe에 인라인으로 작성된 템플릿(valuesMapping:, workload: 또는 artifacts: 항목)이 .context.uses 아래의 render_facts를 읽으면, 아무것도 렌더링되기 전에 짧은 코드 E0347과 함께 참조와 그것이 작성된 필드를 명시하며 빌드가 중단됩니다(“A template reads its targets’ render facts without declaring it (템플릿이 선언 없이 대상의 렌더 팩트를 읽음)”, fatal-halts.md 참조). readsCallerRenderFacts를 설정해도 이 오류는 해소되지 않습니다. 이 검사는 작성된 그대로의 템플릿을 읽으며 호출자 검사와 같은 한계가 있습니다. 템플릿 실행 중에 만들어지는 참조나 파일 또는 라이브러리에서 가져온 내용에 작성된 참조는 보지 못합니다. 또한 .context.uses를 조금이라도 읽으면서 다른 값({{ range .context.used_by }} 내부의 호출자 항목 포함)에서 render_facts라는 필드를 읽는 템플릿은 대상의 팩트를 읽는 것으로 간주됩니다. 양쪽 끝의 팩트를 모두 읽는 템플릿은 두 키를 모두 설정합니다.
파이프라인 단계는 호스트 자체의 팩트만 읽습니다. 단계의 with:와 when:은 호스트 자체의 Recipe가 읽는 것처럼 호스트가 만드는 연결을 읽으며, FeatureRecipe가 키를 설정하든 하지 않든 그 대상의 렌더 팩트는 결코 읽지 않습니다. 단계는 호스트 컴포넌트 자체의 문서를 다시 쓸 수 있으며, 호스트 자체의 렌더링은 대상이 출력한 것이 아니라 대상이 게시하는 것을 읽습니다. 따라서 인라인으로 작성된 단계의 with: 또는 when:이 .context.uses 아래의 render_facts를 읽으면, 빈 값을 렌더링하는 대신 아무것도 렌더링되기 전에 짧은 코드 E0348과 함께 참조와 단계의 필드를 명시하며 빌드가 중단됩니다. 대상의 팩트는 FeatureRecipe의 valuesMapping:, workload: 또는 artifacts:에서 읽습니다.
범위. 호출자 키와 마찬가지로, 이 키는 컴포넌트마다 한 번씩 렌더링되는 FeatureRecipe에 적용됩니다. executionScope: boundary를 선언한 FeatureRecipe는 키 설정 여부와 관계없이 항상 렌더링되던 위치에서 렌더링되며, .boundary 아래에서 읽는 연결에는 렌더 팩트가 없습니다.
locals: 블록
FeatureRecipe.spec.locals:는 선택 사항인 이름 있는 Go 템플릿 문자열의 맵으로, 렌더링된 출력이 같은 FeatureRecipe 안의 다른 모든 템플릿에 .locals.* 맵을 노출합니다. 이는 Recipe locals:에 해당하는 FeatureRecipe 전용 기능으로, 파생 문자열을 한 번 계산해 두고 다시 계산하지 않고 injectMapping, valuesMapping, pipeline[].with, provides에서 참조하는 곳입니다. FeatureRecipe의 assertions:는 이 값들을 읽지 않습니다. assertions-block.md에서 설명하듯이 어서션의 .locals는 호스트 컴포넌트의 Recipe에 속한 것입니다. 각 항목의 렌더링된 출력은 앞뒤 공백을 제거한 상태로 저장됩니다. 이 블록은 단일 템플릿 본문이 아니라 맵이며, 이 위치의 스칼라는 스키마에서 거부됩니다.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.*는 호출마다 따로 존재합니다. 각 FR 호출은 자신의 locals: 블록을 해석하며, 그 결과는 해당 호출의 후속 템플릿에만 보입니다. 이 블록은 FR의 다른 작성 표면 템플릿이 평가되기 전에 해석되므로, 그 템플릿들은 모두 해석된 값을 봅니다.
각 항목은 독립된 컨텍스트에 대해 평가됩니다. .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra, 그리고 같은 블록에서 이미 해석된 항목들입니다. 이는 FR의 다른 템플릿이 읽는 컨텍스트보다 의도적으로 좁습니다. locals: 항목은 .context.annotations, .context.inject, .context.uses, .provides에 접근할 수 없으며, 이 중 하나를 참조하면 해당 참조를 명시하며 중단됩니다. 이러한 필러가 필요한 파생 값은 locals:가 아니라 그것을 읽는 템플릿에 두어야 합니다.
이 컨텍스트의 이름들은 서로 다른 질문에 답하며, locals: 항목은 FeatureRecipe의 다른 템플릿과 똑같이 이를 읽습니다.
- **
.context.instance_id**는 어태치먼트가 해석되는 대상인 호스트 컴포넌트입니다. 컴파일러가 평가하는 모든 템플릿 표면에서 호스트 컴포넌트를 의미하므로, 어느 엔터티의 블록을 작성하든 같은 참조는 같은 방식으로 읽힙니다. - **
.context.rendered_name**은 호스트 컴포넌트 자신의 provider가 보고하는 호스트 컴포넌트의 이름입니다.helm에서는 release 이름이며, 이는 Kubernetes 이름이 허용하는 문자 집합으로 쓴 호스트의 식별자입니다. 호스트의 provider가 이름을 보고하는 경우에만 존재하며, provider가 이름을 보고하지 않는 호스트에서 이를 읽으면 빌드가 중단됩니다. - **
.attachment_name**은 해석 중인 어태치먼트 인스턴스입니다. 소유 엔터티의featuresSchema에서 채우는 슬롯이거나, 직접 지정한 자유 이름입니다.
따라서 내보내는 리소스의 이름을 파생하는 locals: 항목은 artifacts: 템플릿과 똑같이 호스트와 어태치먼트를 조합합니다.
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target이름이 플랫폼이 받아들이는 것이어야 하고 호스트의 provider가 이름을 보고하는 경우에는 대신 .context.rendered_name으로 조합합니다. helm에서 my_api라는 호스트와 scrape 어태치먼트의 경우 {{ .context.rendered_name }}-{{ .attachment_name }}는 my-zuapi-scrape가 되며, 식별자를 쓰면 Kubernetes 이름이 거부하는 my_api-scrape가 됩니다. 렌더링된 리소스 이름 짓기를 참조하십시오.
locals: 항목의 .values와 .infra는 호스트 컴포넌트의 것이 아니라 어태치먼트 선언에 작성된 어태치먼트 자신의 필러입니다.
작성 순서가 동작을 좌우합니다
항목은 작성된 순서대로 해석되며, 항목은 자신보다 위에 정의된 형제 항목을 읽을 수 있고, 그 형제 항목의 해석된 값을 받습니다.
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above연쇄는 아래 방향으로만 진행됩니다. 한 항목이 다른 항목을 읽는 경우 항목의 순서가 빌드 성공 여부를 결정합니다. region_prefix를 bucket 아래로 옮기면 빌드가 중단됩니다. 컴파일러는 참조를 해석하기 위해 블록의 순서를 바꾸지 않으므로, locals: 블록의 순서를 바꾸는 것은 외형상의 변경이 아니라 동작의 변경입니다.
블록이 나중에 정의하는 항목을 참조하면 순서 오류를 명시하며 중단되고(정의를 읽는 쪽보다 위로 옮기십시오), 블록이 전혀 선언하지 않은 키를 참조하면 해당 키를 명시하며 중단됩니다(철자를 수정하십시오). 검사는 블록의 별칭도 따라갑니다. with .locals 본문이 다시 바인딩하는 점(dot)을 통해, 또는 .locals에 바인딩된 변수를 통해 접근한 키는 직접 쓴 경우와 정확히 같은 조건으로 중단되며, 괄호로 묶은 블록에서 읽은 키({{ (.locals).nope }} 또는 {{ ($.locals).nope }})도 마찬가지입니다. 검사를 피하는 표기는 하나뿐입니다. 템플릿 텍스트가 결과를 명명할 수 없는 호출을 통해 접근한 키({{ index .locals "nope" }} 또는 {{ (default dict .locals).nope }})입니다. 그러한 호출의 결과에서 읽은 필드는 중단되지 않고 리터럴 텍스트 <no value>를 렌더링합니다. index 읽기는 키를 명시하며 중단되는데, index는 읽는 맵에 키가 없으면 모든 템플릿 표면에서 중단되기 때문입니다. errors/fatal-halts.md의 “A template indexes a map with a key the map does not hold (템플릿이 맵에 없는 키로 맵을 인덱싱함)”를 참조하십시오. 이 FeatureRecipe의 locals는 provides보다 먼저 해석되므로 provides:는 완전히 해석된 블록을 읽으며, 선언되지 않은 키를 명시하는 provides: 템플릿은 중단됩니다. 이는 Recipe의 locals: 블록이 따르는 규칙과 같습니다. entities/recipe.md의 “locals: 블록”을 참조하십시오.
스코프별 동작. executionScope: component(기본값)에서는 locals:가 연결된 컴포넌트 인스턴스마다 위의 독립된 컨텍스트에 대해 평가됩니다. executionScope: boundary에서는 locals:가 boundary 어태치먼트마다 .boundary.*를 루트로 하는 boundary 스코프 뷰에 대해 평가됩니다. FeatureRecipe가 컴포넌트마다 한 번이 아니라 boundary에 대해 한 번 실행되므로, 컴포넌트별 필드(.context.instance_id, .context.inject, .context.uses)와 .attachment_name은 사용할 수 없습니다. boundary 스코프 템플릿 필드 허용 목록은 다른 FR 작성 표면 템플릿에 적용되는 것과 같은 방식으로 locals:에도 적용됩니다. 어태치먼트가 도달하는 각 컴포넌트마다 실행되는 injectMapping은 그 한 번의 boundary 평가를 자신의 .locals로 읽습니다. 평가 계약(작성 순서, 아래 방향으로만 허용되는 형제 읽기, 두 가지 중단)은 두 스코프에서 동일하며, 주변 컨텍스트의 형태만 다릅니다.
injectMapping 오버레이 및 pipeline[].with 매핑과의 차이. locals:는 후속 템플릿을 위해 컨텍스트에서 보이는 맵을 만들 뿐, 출력에 기여하지 않습니다. injectMapping은 소비자의 .context.inject 파이프에 씁니다(호출자 측 변경). pipeline[].with는 Wasm 플러그인의 args 페이로드를 제공합니다. 세 표면은 서로 독립적이며, FeatureRecipe는 흔히 세 가지를 함께 사용하고, locals:가 나머지 둘이 참조하는 공유 파생 문자열을 담습니다.
assertions: 블록
FeatureRecipe.spec.assertions:는 FeatureRecipe의 구현 불변 조건을 표현하는 이름 있는 규칙의 선택적 맵입니다. 이는 FeatureRecipe가 기반으로 하는 특정 Wasm 플러그인 파이프라인, 차트 또는 메커니즘을 전제로 성립하는 필드 간 규칙입니다. 각 키는 실패 메시지에 나타나는 규칙 식별자이고, 각 값은 Go 템플릿 본문입니다. Recipe 어서션과 마찬가지로 FeatureRecipe 어서션은 특정 구현의 속성이며, Feature 수준의 계약 규칙은 그보다 앞선 파이프라인 단계에서 독립적으로 적용됩니다.
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}위 규칙은 aws-secrets-manager 플러그인 1.x에만 해당하며, 다른 core/referenced-secret FeatureRecipe가 바인딩되면 적용되지 않습니다. Feature 정의의 Feature 수준 계약 규칙은 이와 함께 여전히 적용됩니다.
FeatureRecipe 어서션은 FeatureRecipe 바인딩 이후, 리소스 생성 이전에 평가됩니다. component 범위 FR의 템플릿 컨텍스트는 Recipe 어서션 컨텍스트(엔터티 인스턴스 필드와 .provides, .locals, .recipe.metadata, .recipe.source)와 같습니다. boundary 범위 FR(executionScope: boundary)의 경우 어서션은 boundary 범위 뷰를 기준으로 평가됩니다(.boundary.* 필드는 사용할 수 있고 컴포넌트별 필드는 사용할 수 없음). 전체 작성 문법과 예제는 templates/assertions-block.md를 참조하십시오.
omits: 필드 — 렌더링된 문서를 소스에서 제외하기
대부분의 FeatureRecipes에는 이 필드가 필요하지 않습니다. 이 필드는 source:가 그대로 가져다 쓰는 차트(대개 레지스트리에서 가져온 차트)이고, 그 차트가 attachment가 내보내서는 안 되는 문서를 렌더링하는 FeatureRecipe를 위한 것입니다. 예를 들어 렌더링할 때마다 차트가 새로 생성하는 Secret이나, 호스트 component 또는 운영자가 이미 제공하는 객체가 그렇습니다. omits:는 그러한 문서를 FeatureRecipe가 생성하는 결과에서 제외합니다. FeatureRecipe가 소스로 삼는 compose 파일의 경우에는 attachment가 기여해서는 안 되는 서비스, 볼륨 또는 config를, CloudFormation 템플릿의 경우에는 리소스를 제외합니다.
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboards이 키는 Recipe에서도 동일하게 작성하며, Recipe → omits: 필드가 전체 레퍼런스입니다. 각 항목 필드가 무엇을 선택하는지, when:이 먼저 평가되고 false이면 해당 항목이 제외된다는 점, 적용되는 모든 항목은 무언가를 제외해야 하며 그렇지 않으면 해당 항목을 지목하며 빌드가 중단된다는 점, 소스는 여전히 전체가 렌더링되고 그 출력만 필터링된다는 점, 그리고 어떤 providers가 이 키를 지원하는지를 다룹니다. FeatureRecipe에서 다른 점은 템플릿이 평가되는 위치뿐입니다.
- 각 항목의 템플릿은 이 FeatureRecipe의
valuesMapping:이 평가되는 컨텍스트에 대해 평가되며,executionScope가 선택하는 범위에서 평가됩니다. component 범위 FeatureRecipe의 항목은 attachment마다 한 번씩 해당 attachment의.values와.infra에 대해 평가되고, boundary 범위 FeatureRecipe의 항목은 boundary마다 한 번씩 boundary 범위 뷰와 boundary attachment의.infra에 대해 평가됩니다. attachment의 템플릿이 읽을 수 있는 대상에 관한 규칙은valuesMapping:에 적용되는 것과 같이 항목에도 적용됩니다. - 이 FeatureRecipe 자체의
source:가 렌더링하는 것만 필터링됩니다.workload:와artifacts:는 필터링되지 않으며, 호스트 component의 출력도 마찬가지입니다. attachment의 항목은 자신의 차트, 자신의 compose 파일 또는 자신의 CloudFormation 템플릿에만 적용되고 그 밖의 것에는 적용되지 않습니다. 양쪽이 함께 조립되는docker-compose.yaml에서 호스트가 같은 키로 선언한 compose 서비스는 영향을 받지 않으며, 양쪽이 함께 조립되는 스택에서 호스트가 같은 논리 ID로 선언한 리소스도 마찬가지입니다. 호스트가 렌더링하는 문서를 변경하려면 호스트의 Recipe가 항목을 선언하거나pipeline:단계에서 패치합니다.
항목으로 인한 중단은 노드, provider, 이 FeatureRecipe, 그리고 omits: 목록에서 해당 항목의 위치를 지목합니다. boundary 범위 FeatureRecipe의 경우 메시지 위의 줄이 attachment와 그 boundary를 지목합니다.
Recipe에 작성한 이 키의 실제 예제(가져온 차트가 생성하는 Secret을 제외하는 예와, 항목이 없을 때 및 아무것도 일치하지 않는 항목에서 발생하는 중단)는 ai-gateway-own-webhook-certificate를 참조하십시오.