콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Recipe

Recipe 엔티티의 개념적 역할(Developer Intent를 물리적 형식으로 매핑하는, Ops가 작성하는 변환 템플릿)은 architecture/04-entity-taxonomy.md에서 설명합니다. 이 페이지는 Recipe 작성 표면, 즉 포인터(source), 매퍼(valuesMapping:), 네이티브 IaC 지원, 그리고 작성 예제를 다룹니다.

Recipe 아키텍처: 포인터와 매퍼

Recipe는 정확히 두 가지 기능을 수행합니다.

  1. 포인터(source): 인프라 코드가 정확히 어디에 있는지 컴파일러에 알려 줍니다.
  2. 매퍼(valuesMapping): Aggrega의 추상 컨텍스트를 기반 코드가 기대하는 특정 변수에 주입합니다. 이 필드는 세 가지 작성 모드(인라인 블록 스칼라, 파일 $import:, 라이브러리 $import:)를 갖는 단일 Go 템플릿 표면이며, 내용의 형태에 따라 디스패치됩니다. 아래의 valuesMapping 필드 — 세 가지 작성 모드를 참조하십시오.

Recipe는 렌더 기능과 엄격히 1:1 관계이므로 해당 기능(spec.capability)은 루트 수준에서 명시적으로 선언되며, 이를 통해 Go 컴파일러는 어떤 다운스트림 Wasm 렌더링 플러그인을 호출해야 하는지 정확히 알 수 있습니다.

spec.implements는 Recipe가 구현할 수 있는 카탈로그 컴포넌트 유형을 선언합니다. 컴파일러는 이를 사용해 Manifest 매핑을 검증하고(매핑된 Recipe의 implements는 매핑된 유형과 일치해야 함) 후보를 제안합니다. 후보란 매핑 없음 진단에 나열되고 편집기 자동 완성에서 가장 먼저 표시되는 레시피입니다. 이 필드가 빌드를 결정하는 일은 없습니다. Manifest 매핑은 사용자의 명시적인 배포 선택이며 lockfile에 고정됩니다. implements가 버전 없음, 정확한 버전, 또는 메이저 호환 범위인 Recipe라도 어떤 유형에 대해 자신을 제안할 뿐이며, 선택을 고정하는 것은 사용자입니다. FeatureRecipe.spec.implements는 기능 유형에 대해 동일한 역할을 합니다.

A. Wasm 기반 소스 스키마

구현상의 편향을 컴파일러에서 배제하기 위해 source 블록은 고정된 인프라 필드 집합이 아닙니다. source 필드는 두 가지 형식을 지원합니다.

  • 범용 문자열(빠르고 깔끔함): 로컬 경로, OCI 아티팩트, Git 저장소에 가장 적합합니다. 컴파일러는 문자열의 접두사와 접미사(./src, https://github.com/example/module.git, oci://...)로 가져오기 방식을 추론합니다. .git으로 끝나거나 git:// 또는 ssh://로 작성된 URL은 기본 브랜치에서 가져오는 Git 저장소이며, 저장소도 .tgz 차트도 .yaml 조각도 가리키지 않는 https:// URL은 모호하다는 이유로 거부됩니다.
  • 개방형 구조 객체: 키를 provider가 정의하는 개방형 딕셔너리(additionalProperties: true)이며, Recipe의 템플릿에 .source.*(예: .source.chart)로 노출됩니다. 설계 의도는 각 provider의 WebAssembly 소켓이 자체 소스 형태(예: Helm의 경우 registry/chart/appVersion)를 정의하고 검증하는 것입니다.

코어가 해석하는 것. 자체 소스 키를 검증하는 provider는 없습니다. 가져오는 소스는 내장 식별자로 해석되며, 그 kind가 리졸버를 선택합니다. 리졸버로는 helm-oci-chart, helm-https-chart, compose-https-fragment, git-repository가 있습니다. 가져오기를 의도한 소스는 kind와 url을 가져야 하며, 어떤 추가 좌표가 내용을 선택하는지는 kind에 따라 다릅니다. 차트 및 프래그먼트 kind는 version을 받으며 작성된 그대로 고정합니다. git-repository는 태그, 브랜치 또는 커밋인 ref를 받고, 선택적으로 저장소 안에서 아티팩트가 되는 디렉터리를 지정하는 module_subdir를 받습니다. 다른 곳을 가리키도록 바뀔 수 없는 내용을 지정하는 것은 커밋뿐이므로, 참조는 잠금 시점에 해석되며 lockfile은 작성된 참조와 그것이 해석된 커밋을 모두 기록합니다. 작성된 그대로 저장소 위로 올라가는 module_subdir(백슬래시도 구분자로 간주됨)는 아무것도 가져오기 전에 거부됩니다. 저장소는 자체 체크아웃에서 아카이브됩니다. 저장소가 커밋한 심볼릭 링크는 가리키는 대상이 저장소 안에 있으면 그 파일이나 디렉터리로 아카이브되고, 저장소 밖을 가리키는 링크는 저장소 내 위치로 해당 링크를 지목하며 pull을 중단시킵니다. url:이 파일 시스템 경로를 지정하는 구조화된 소스는 가져오지 않습니다. 단순 경로 문자열과 같은 조건으로 디스크에서 읽으며, 상대 url:은 이를 선언한 엔티티 파일이 있는 디렉터리를 기준으로 합니다. kind/url을 생략한 구조화된 소스도 가져오지 않으며, 가져오기를 의도했던 경우 아무것도 없는 것으로 조용히 해석되는 대신 잠금 시점의 소스 탐색에서 빌드가 명시적으로 중단됩니다. 내용은 항상 사전에 고정되며, 컴파일러는 실시간 런타임 상태를 가져오지 않습니다.

Recipe 옆에 고정되는 것. kind, url, chart, module_subdir, version, ref가 모두 템플릿이 아닌 값으로 작성된 가져오는 소스의 경우, aggrega pin은 가져온 내용의 다이제스트를 entity.lock에 기록합니다. 이 파일은 Recipe 자체 디렉터리에 있으며 Recipe와 함께 커밋합니다. 고정은 Recipe 작성자의 단계이며 Release가 필요하지 않습니다. 잠금 파일에 고정이 기록되지 않은 Recipe에 대한 pull은 중단되고 해당 고정을 지목합니다. 단, pull에 같은 단계를 실행하도록 요청한 경우는 예외입니다. 빌드는 그 다이제스트를 Release의 lockfile이 같은 소스에 대해 기록한 다이제스트와 비교하고, 둘이 다르면 중단됩니다. 다만 git ref:로 작성된 소스는 예외로, 그 행은 ref가 해석된 커밋으로 기록되며 비교되지 않습니다. 좌표가 템플릿으로 채워지는 가져오는 소스는 대신 Release별로, 각 Release의 lockfile에 고정됩니다. Recipe 옆의 디렉터리나 파일을 지정하는 소스는 가져오지 않습니다. aggrega pin은 그 소스가 Recipe 게시물에 포함시키는 파일마다(템플릿으로 작성된 소스의 경우 Recipe 디렉터리의 모든 파일마다) 다이제스트 하나를 기록하며, 잠금 파일에 이것이 기록되면 빌드는 provider가 소스를 읽기 전에 이와 비교하여 고정 이후 추가, 변경 또는 제거된 파일이 있으면 E0305로 중단합니다. 변경 전에 작성된 Release의 lockfile이 Recipe를 그 포함 내용으로 기록하고 있으면 먼저 E0130으로 중단합니다. 이러한 소스에 대한 고정을 기록하지 않은 잠금 파일은 빌드가 비교할 대상을 남기지 않으며, 고정하지 않는 pull이나 게시는 이를 거부합니다. Recipe 파일 자체에는 아무것도 기록되지 않습니다. aggrega pull에서 이 파일과 각 중단에 대응하는 방법을 설명합니다.

spec.capability는 implements가 취하는 형식, 즉 정확한 버전(helm:<version>) 또는 캐럿 범위(helm:^<version>)로 버전 고정을 가질 수 있으며, 이는 provider 플러그인의 어느 버전이 Recipe를 렌더링할지 선택합니다. 사용 가능한 어떤 버전도 만족하지 않는 고정은 빌드를 중단시킵니다. 고정하지 않으면(spec.capability: "helm") 사용 가능한 가장 높은 버전이 렌더링합니다. 사용 가능한 버전은 aggrega plugin list가 보여 주는 버전이며, aggrega에 내장된 provider는 컴파일러 자체의 버전을 가집니다. 고정은 Recipe 이름의 일부가 아닙니다. Manifest는 capability: "compose:1.2.3"을 선언한 Recipe를 고정되지 않은 Recipe와 똑같이 compose/<name>:<version>으로 매핑하며, 고정을 바꿔도 이름은 바뀌지 않습니다. 고정을 이름에 쓴 매핑 값(compose:1.2.3/<name>:<version>)은 무엇을 조회하기도 전에 잘못된 recipe 참조로 거부됩니다(E0095).

멘탈 모델: spec.capability는 원하는 출력 형식(예: helm, terraform, compose)을 지정하고, 컴파일러는 이를 해당 형식을 렌더링하는 Wasm 플러그인(예: provider/helm)으로 해석합니다. 사용자는 형식을 선언하고, Aggrega가 도구를 바인딩합니다.

B. 컨텍스트 주입: 의미 매핑 계층

컴파일러가 여러 환경에 걸쳐 위험하고 비결정적인 깊은 병합을 수행하지 않도록, Recipe는 매핑 계층에 대해 단일 진실 공급원만 허용합니다.

운영 엔지니어는 Wasm 렌더링 플러그인이 실행되기 전에 추상 컨텍스트를 변환하는 매핑 내용을 작성합니다. 매핑 언어는 Go 템플릿(text/template + Sprig)이며, Sprig 라이브러리는 미리 등록되어 있고, 표준 define 및 template 액션을 지원하며 include는 등록되어 있지 않습니다.

필드 이름범위 및 실행 단계최적 사용 사례
injectMapping (FeatureRecipe 전용)렌더링 전 가로채기. 기본 Recipe 보다 먼저 Go 메모리에서 평가됩니다. 출력 딕셔너리를 호출자의 .context.inject 파이프 위에 엄격하게 네이티브 깊은 병합합니다. 기본 Recipe 스키마에는 의도적으로 없습니다. 아키텍처상 근거는 entities/featurerecipe를 참조하십시오.Wasm JSONPatch 없이 호출자를 위해 주입된 env 변수를 정밀하게 재작성하거나 FQDN의 형식을 지정합니다.
valuesMapping기본 렌더링(Go 템플릿). 변수를 기반 source 인프라 차트/모듈에 매핑하기 위해 평가됩니다. 단일 필드이며 세 가지 작성 모드(인라인, 파일 $import:, 라이브러리 $import:)가 있습니다. 디스패치 방식은 아래 하위 절을 참조하십시오.표준 변수(레플리카 수나 이미지 태그 등)를 Recipe YAML에서 직접 Helm 차트에 매핑하거나, Recipe 간 재사용을 위해 $import:로 공유 템플릿을 참조합니다.

참고: injectMapping은 FeatureRecipes 전용이며 변수 가로채기를 valuesMapping과 분리합니다. 기본 Recipe의 valuesMapping은 FeatureRecipe injectMapping 블록이 생성한 재작성된 .context.inject 문자열을 알지 못한 채 소비하므로, 둘은 분리된 상태로 유지됩니다.

valuesMapping이 null로 작성한 키는 provider에 null로 전달되며, 그곳에서 어떻게 처리되는지는 provider가 정하므로 각 provider 페이지에 명시되어 있습니다. helm은 해당 키에 대한 차트 기본값을 제거하고, helm-chart는 이를 엄브렐라의 values에 기록하며, compose는 compose 파일에 기록하고, terraform은 null 모듈 인수로 기록하며, cloudformation은 이를 거부합니다.

valuesMapping 필드 — 세 가지 작성 모드

Recipe의 valuesMapping:은 세 가지 디스패치 모드를 받는 단일 Go 템플릿 표면입니다. 컴파일러는 필드 내용의 형태에 따라 디스패치하므로 $mode: 주석이 필요하지 않습니다.

모드 1: 인라인 Go 템플릿(YAML 블록 스칼라). 필드 값은 YAML 블록 스칼라 | 형식으로 작성된 문자열입니다:

spec:
valuesMapping: |
{{- with .values -}}
image:
tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }}
pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }}
architecture: {{ optional . `architecture` "standalone" }}
primary:
replicaCount: {{ optional .primary `replicaCount` 1 }}
{{- end }}

인라인 모드는 매핑 내용이 소규모에서 중간 규모(약 50줄 미만)인 Recipes의 일반적인 작성 형식입니다. 템플릿 본문이 Recipe 엔벌로프의 나머지 부분과 함께 인라인으로 위치하므로 Recipe의 내용이 자체 완결됩니다.

모드 2: 파일 $import:. 필드 값은 로컬 파일 경로를 가진 $import:만 포함하는 맵입니다:

spec:
valuesMapping:
$import: ./mappings/api-server.tmpl

컴파일러는 파일 내용(Go 템플릿)을 로드하고, 표준 Recipe 템플릿 컨텍스트에 대해 템플릿 렌더링한 다음, 그 결과를 매핑 출력으로 취급합니다. 경로는 Recipe의 디렉터리를 기준으로 해석됩니다. 상대 경로는 빌드를 실행한 디렉터리가 아니라 그 경로를 선언한 recipe.yaml이 있는 디렉터리를 기준으로 하며, 콘텐츠 경로는 Recipe 자체 디렉터리 안에 머뭅니다에서 설명하듯 경로는 그 디렉터리 안에 있어야 합니다. 파일 모드는 중간에서 대규모 매핑 내용(약 50줄 이상)과, 매핑 변경이 독립된 파일 diff로 나타나는 리뷰 방식에 적합합니다.

모드 3: 라이브러리 $import:. 필드 값은 MappingLibrary 항목에 대한 bare-name 식별자 참조를 가진 $import:만 포함하는 맵입니다:

spec:
valuesMapping:
$import: DatastoreHelpers#/mappings/MariaDBCore

컴파일러는 해석된 MappingLibrary 집합(로컬 카탈로그와 lockfile에 고정된 라이브러리)에 대해 참조를 해석하고, 항목의 내용을 로드하여 매핑 출력으로 취급합니다. 본문 자체가 필드 루트 $import:인 항목은 재귀적으로 해석됩니다. 참조에는 레지스트리 호스트가 포함되지 않습니다. 라이브러리 이름은 식별자로 해석되고 버전은 Release별 lockfile에서 가져오며, 선택적으로 :<version> 최소 버전 하한(<Library>:<version>#/mappings/<entry>)을 지정할 수 있습니다. 라이브러리 내용은 표준 Recipe 템플릿 컨텍스트를 공유합니다. 라이브러리 모드는 Recipe 간 재사용, 즉 여러 Recipes에 반복되는 매핑 패턴(데이터스토어 헬퍼 로직을 공유하는 여러 데이터스토어 Recipes, 파드 템플릿 패턴을 공유하는 여러 Helm provider Recipes)에 적합합니다. MappingLibrary 엔터티는 버전 관리, lockfile 고정, 허브 UI 노출을 제공합니다.

디스패치 규칙. 컴파일러는 YAML 노드를 탐색하여 내용 형태에 따라 디스패치합니다:

  1. 노드가 문자열 스칼라이면 인라인 모드(모드 1)로 디스패치합니다.
  2. 그렇지 않으면 노드는 맵이며, $import: 키가 있는지 확인합니다.
  3. $import: 값이 bare-name 라이브러리 참조(<Library>#/mappings/<Entry>, 선택적으로 :<version> 하한 포함)이면 라이브러리 모드(모드 3)로 디스패치합니다.
  4. 그렇지 않으면(로컬 파일 경로) 파일 모드(모드 2)로 디스패치합니다.
  5. 그 밖의 형태($import:가 없는 맵, $import: 외에 추가 키가 있는 맵 등)는 빌드 시점 오류를 발생시킵니다.

단일 소스 $import:만 지원. $import:는 단일 소스만 받습니다. valuesMapping:에서는 다중 소스 병합이 지원되지 않습니다. 여러 매핑 조각을 조합해야 하는 Recipe는 내부 Go 템플릿 define / template 조합을 사용하는 MappingLibrary 항목, 형제 파일을 호출하는 Go 템플릿 template 지시문을 사용하는 로컬 파일, 또는 짧은 내용이라면 인라인 조합을 사용합니다. 라이브러리 엔터티는 entities/mappinglibrary를, 더 넓은 $ref: / $import: 구분은 vocabulary/cross-document-ref를 참조하십시오.

출처. 템플릿 렌더링 실패에 따른 오류 메시지는 모드별로 적절한 출처를 인용합니다. 인라인 템플릿은 블록 스칼라가 시작되는 Recipe의 file:line을 인용하고, 파일 가져오기는 가져온 파일의 내용을 인용하며, 라이브러리 가져오기는 MappingLibrary 항목의 소스 위치를 인용하되 호스트 없는 라이브러리 식별자(<Library>#/mappings/<entry>)를 안정적인 참조를 위한 정규 포인터로 사용합니다. 참조에 레지스트리 호스트가 있으면 거부되므로 물리적 위치는 포인터에 들어가지 않습니다.

C. 네이티브 IaC 지원

자체 Infrastructure as Code를 가져오는 Ops 팀은 이를 Recipe 자체 디렉터리(source:로 지정하는 ./src 같은 모듈 또는 템플릿 디렉터리)에 두거나, 구조화된 source:로 가져오거나(kind: git-repository를 사용해 git 저장소에서 가져오는 Terraform 모듈 등), artifacts: 아래에 템플릿화된 본문으로 작성합니다. 매핑 계층(valuesMapping:: 인라인, 파일 가져오기 또는 라이브러리 가져오기)이 그 코드에 추상 컨텍스트를 제공하고, provider는 대상 고유의 형식으로 결과를 내보냅니다. 어떤 구성 언어도 다른 구성 언어로 변환되지 않습니다:

  1. Terraform: 모듈은 파일 단위로 그대로 벤더링되고, 작성된 본문은 작성된 그대로 내보내집니다. 네이티브 HCL(main.tf)과 Terraform JSON(.tf.json) 모두 마찬가지이며, terraform CLI는 둘 다 읽습니다. 경계의 루트 구성인 aggrega.modules.tf는 각 컴포넌트의 디렉터리를 module 블록으로 호출하고, 소스 기반 모듈의 valuesMapping: 출력이 그 블록의 인수가 됩니다. terraform provider를 참조하십시오.
  2. CloudFormation: 소스 기반 템플릿(YAML 또는 JSON)과 Recipe가 작성하는 리소스 조각은 긴 형식의 JSON으로 정규화되어 경계마다 하나의 스택 템플릿으로 병합되며, valuesMapping: 출력이 소스 기반 템플릿이 선언한 파라미터를 채웁니다. cloudformation provider를 참조하십시오.

인프라가 적용된 뒤에야 존재하는 값은 대상이 해석하는 포인터(Terraform의 ${ ... } 보간, CloudFormation의 Ref 또는 Fn::GetAtt)로 남으며, 빌드 시점에 평가되지 않습니다.

예제 A: 원격 Helm 차트(인라인 매핑 및 Locals 계약)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-chart
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
# The shipped fetch form: { kind, url, version }. 'kind' selects a built-in
# resolver (helm-oci-chart, helm-https-chart, compose-https-fragment).
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
# Default chart version. Override via infra.source_version.
version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals:
primary_compute: mariadb
listen_port: "3306"
volumes_path: "/spec/template/spec/volumes"
root_path: "/-"
# The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm
# pipeline: the suffix it follows the rendered name with. A local cannot read
# .context.rendered_name, so each template writing the full name joins the two.
secret_target_db_password: "mariadb-auth"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
# Every key the Component's provides contract declares is published
user: "{{ .values.user }}"
database: "{{ .values.database }}"
protocol: "mariadb"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"
auth:
# Reads the suffix from the local rather than restating it, so the secret
# name is authored once and every reader follows that one definition
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"

예제 B: 로컬 Terraform 모듈(파일 매핑)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-s3-tf
version: 1.0.0
spec:
capability: terraform
implements: aws/s3-bucket:1.0.0
source: "./src"
locals:
primary_compute: bucket_instance
resource_path: "/resource/aws_s3_bucket/main"
root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments
valuesMapping: |
bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"
region: "{{ .infra.aws_region }}"

예제 C: 구체적인 Component Recipe(인프라 바인딩) Ops는 일반 인터페이스를 물리적 실체에 매핑합니다. (L4 네트워크 세부 사항은 여기서 바인딩됩니다. 하드코딩하거나, 아래 프록시 포트처럼 Release가 채우는 infra 블록에서 가져옵니다.)

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: kong-gateway
version: 1.0.0
spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
# A chart repository root paired with the chart's name.
kind: helm-https-chart
url: https://charts.konghq.com
chart: kong
version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides:
# The chart's proxy Service: it suffixes the name pinned below with "-proxy"
host: "{{ .context.rendered_name }}-proxy"
port: "{{ .infra.proxy_port }}"
protocol: "http"
# The contract's other keys: empty while nothing is wired to the models
# socket, and while metrics are off
endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}'
model: '{{ optional .values "model" "" }}'
metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

클라우드 리소스 명명 원칙.

클라우드 리소스 이름(S3 버킷 이름, RDS 데이터베이스 식별자, IAM 역할 이름, CloudFormation 스택 이름, 그리고 값이 클라우드 프로바이더의 전역 네임스페이스를 차지하는 기타 모든 필드)을 내보내는 Recipes는 같은 Recipe가 여러 Releases 또는 컴포넌트 인스턴스에서 실행될 때 충돌을 피하기 위해 렌더링되는 이름에 {{ .metadata.release_name }} 및/또는 {{ .context.instance_id }}를 연결해야 합니다. 예제 B의 bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data"가 표준 패턴입니다.

이 원칙은 단일 전역 네임스페이스가 이름을 제약하는 모든 곳에 적용됩니다. AWS S3 버킷 이름은 한 리전의 모든 계정에 걸쳐 하나의 전역 네임스페이스를 공유하므로, 같은 Aggregate의 두 Releases(prod-billing과 staging-billing)가 모두 customer-data라는 이름의 버킷을 배포할 수는 없습니다. 두 번째 배포는 런타임에 AWS 측의 거부로 실패합니다. release_name을 연결하면 Release별로 구분되고, context.instance_id를 연결하면 컴포넌트 인스턴스별로 구분되며, 둘 다 연결하면 Release별·컴포넌트별로 구분됩니다.

컴파일러가 검사하는 것과 검사하지 않는 것. 컴파일러는 이러한 보간이 없는 클라우드 리소스 이름 필드가 있는지 valuesMapping: 출력을 검사하지 않습니다. 이 원칙은 Recipe 작성자(대상 프로바이더에서 어떤 필드가 전역적으로 고유한 리소스의 이름을 정하는지 아는 사람)와 리뷰어(PR 리뷰에서 이름이 지정되지 않은 리소스 패턴을 잡아내는 사람)가 지킵니다. linter 플러그인이라면 valuesMapping: 출력이 release_name / instance_id 보간 없이 클라우드 리소스 이름 필드를 참조하는 Recipes를 표시할 수 있습니다. linter 소켓은 제공되며 aggrega lint를 통해 실행되지만(plugins/plugin-contract.md “Placement criterion: the linter socket vs the governance verdict roles” 참조), 게시용 linter의 규칙 중 이를 검사하는 것은 없습니다.

이 원칙은 관례로 유지되는 여러 사회 계약 중 하나로, 작성자가 컴파일러의 강제가 아니라 문서를 통해 익히는 작성 원칙입니다. 관례의 전체 목록과 각 계약 분류의 아키텍처적 근거는 vocabulary/social-contracts.md를 참조하십시오.

소스 필드 템플릿. Recipe의 source 필드 자체도 템플릿 표면입니다. source의 두 형태 모두 Go 템플릿을 허용합니다. 범용 문자열 형태

source: "{{ optional .infra `module_path` \"./src\" }}"

와 구조화된 객체 형태(문자열 값인 각 하위 필드는 템플릿으로 평가되고, 문자열이 아닌 하위 필드는 그대로 전달됨)입니다. 소스 템플릿이 무엇을 읽을 수 있는지는 소스가 원격 아티팩트를 가리키는지에 따라 달라집니다. 원격 소스의 좌표, 즉 레지스트리, 차트 저장소 또는 git 저장소를 가리키는 구조화된 블록의 version, chart, ref, module_subdir는 aggrega pull이 아티팩트를 고정하기 위해 해석할 때 평가되며, .values, .infra, .locals만을 대상으로 하고 Aggrega 자체 헬퍼(optional, capitalizedWords, index)만 사용할 수 있고 Sprig 함수는 사용할 수 없습니다. .context는 이 표면에 없으므로, 컴포넌트에 어떤 아티팩트가 고정될지는 주어진 values와 infra로 결정되며 인스턴스 이름으로 결정되는 일은 없습니다. 여기서 평가되는 locals: 항목은 해당 필드가 읽는 항목과, 그 항목이 다시 읽는 항목입니다. 어떤 소스 필드도 읽지 않는 항목은 소스를 해석하는 동안 평가되지 않으므로, 렌더링에만 필요한 local(Sprig 함수를 호출하거나 .context.instance_id를 읽는 것)은 고정에 영향을 주지 않으며 노드가 렌더링될 때 평가됩니다. {{ index .locals "version" }}처럼 특정 항목 하나를 가리키지 않는 방식으로 .locals를 읽는 필드가 있으면 모든 항목이 평가됩니다. 위의 예처럼 워크스페이스 내 경로를 가리키는 소스는 고정을 위해 해석되지 않습니다. 그 템플릿은 노드가 렌더링될 때 Recipe locals와 같은 자기 완결적 컨텍스트, 즉 .context.instance_id, .values, .infra, 그리고 노드의 해석된 블록 전체인 .locals를 대상으로 평가됩니다. 따라서 locals: 항목과 같은 참조 루트를 허용하고 거부하되, 유리한 차이가 하나 있습니다. 자기보다 위에 있는 항목뿐 아니라 블록이 선언하는 모든 항목을 읽을 수 있습니다. 원격 좌표도 마찬가지로 블록이 선언하는 모든 항목을 읽을 수 있습니다. .provides는 어느 컨텍스트에도 없으며, 소스 템플릿이 자기 노드의 provides에 접근하면 빌드가 중단되고 문제가 된 참조를 알려 줍니다. 이는 추후 작업을 기다리는 공백이 아니라 이 표면의 고정된 속성입니다. provides:가 .locals를 읽을 수 있도록 노드의 locals는 provides보다 먼저 해석되며, 소스 템플릿은 provides를 앞당겨 참조하는 대신 같은 해석된 locals를 읽습니다. .context.inject와 .context.uses에 대한 참조도 같은 자기 완결성 근거로 금지됩니다. 소스 URI는 토폴로지 파이프가 채워지기 전, 그리고 하위 단계에서 URI가 가리키는 차트, 모듈 또는 아티팩트 본문을 로드하기 전에 해석되어야 합니다. 전체 사용 가능 규칙과 금지된 참조의 근거는 Template Expansion Matrix 행 #5에 있습니다. 대표적인 용도는 Component가 노출하는 infra.source_version 재정의를 소스의 version 필드로 전달하는 것입니다(entities/component “The infra Pillar” 참조). 이렇게 하면 카탈로그는 호환되는 업스트림 버전이 올라갈 때마다 Recipe를 다시 게시하지 않아도 됩니다.

소스 필드 스킴 목록. source: 필드는 스키마에서 여러 형태 변형을 허용합니다. 각 변형의 런타임 지원은 프로바이더마다 다르며, 아래 표는 각 형태가 무엇을 하는지 설명합니다.

형태예상태
순수 상대 파일 시스템 경로source: "./charts/postgres"available — 제공되는 모든 프로바이더(helm, helm-chart, compose, terraform, cloudformation)가 순수 파일 시스템 경로 문자열을 허용합니다.
순수 절대 파일 시스템 경로source: "/abs/path/to/chart"accepted but blocked — 스키마는 이를 허용하지만 Recipe를 읽는 모든 명령이 거부합니다. 절대 경로는 Recipe 자체 디렉터리 안의 콘텐츠가 아니라 작성된 머신의 위치를 가리키므로 Recipe와 함께 옮겨지지 않습니다. 차트를 Recipe 디렉터리로 옮기고 그 디렉터리에 대한 상대 경로로 지정하십시오. Content paths stay inside the Recipe’s own directory를 참조하십시오.
빈 문자열source: ""accepted but blocked — 스키마는 빈 문자열을 허용하지만, Recipe를 로드하는 모든 명령은 Recipe를 읽을 때 이를 거부합니다. 빈 문자열은 어느 모드도 지정하지 않기 때문입니다. 거부는 모호함과 함께 이를 벗어나는 두 가지 방법을 알려 줍니다. 소스 없는 모드라면 필드를 생략하고, 소스 모드라면 실제 경로나 URI를 지정하십시오. aggrega validate <recipe-file>은 Recipe에 대해 이를 보고하고, aggrega pull, aggrega build, aggrega validate --release는 그 Recipe에 도달하는 Release에 대해 이를 보고합니다. errors/fatal-halts.md의 “Recipe source: is an empty string(Recipe의 source가 빈 문자열임)”을 참조하십시오.
url:에 전송 스킴이 있는 구조화된 객체source: { url: "oci://…/mariadb", version: "25.0.8" }available — 내장 source-resolver가 {kind, url, version, chart, ref, module_subdir} 형식을 읽고(url:의 스킴이 종류를 선택합니다 — oci:// → OCI 차트, https://….tgz → 차트 아카이브, chart:와 짝을 이룬 https:// 저장소 루트 → 저장소 차트 — 또는 kind:로 종류를 지정합니다), aggrega pull에서 아티팩트를 가져와 고정하며, 빌드는 캐시에서 이를 추출합니다. 차트를 로컬에 벤더링하는 것도 대안으로 지원되지만 필수는 아닙니다. 스키마는 열린 구조화 객체를 허용합니다. providers/helm.md “source: keyset”을 참조하십시오.
url:이 파일 시스템 경로를 지정하는 구조화 객체source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" }available — 전송 스킴이 없는 url:은 경로를 가리키므로 아무것도 가져오지 않고 아무것도 고정하지 않습니다. 빌드는 디스크에서 내용을 읽습니다. 상대 url:은 이를 선언하는 recipe.yaml이 있는 디렉터리를 기준으로 하며, 그 디렉터리를 벗어나는 경로는 절대 경로를 포함하여 거부됩니다. 이는 위의 두 순수 경로 행에 적용되는 것과 같은 해석이며, 어떤 형태로 작성했는지와 관계없이 달라지지 않습니다. 내용을 어디에서 읽을지는 오직 url:만 결정합니다. 다른 필드는 가져온다면 무엇을 가져올지를 선택하며, 여전히 .source.*로 Recipe의 템플릿에 전달됩니다.
OCI URI(oci://...)source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0"planned — 카탈로그 배포를 위한 설계 목표입니다. 현재의 3계층 resolver(Release가 경로로 지정하는 파일, 워크스페이스 카탈로그, 원격 OCI 레지스트리)는 architecture/13-catalog-and-registry.md에 문서화되어 있습니다. 엔터티 수준 resolver는 이 단계적 구조를 통해 OCI URI를 사용하지만, Recipe별 source: 필드의 OCI 형식은 현재 프로바이더에 연결되어 있지 않습니다.
기타 URL 스킴(https://, git+https:// 등)(예시)planned — 아키텍처의 플러그형 소스 로드맵에 설계 의도로 문서화되어 있으며, 현재 프로바이더 지원은 없습니다.

source: 경로의 기준 위치. 기준 위치 지정은 파일 시스템 경로에만 적용되며, 두 형태 중 어느 쪽이 경로를 담든 적용됩니다. 상대 경로는 그것을 선언한 recipe.yaml이 있는 디렉터리를 기준으로 하며, 그 디렉터리를 벗어나는 경로는 절대 경로를 포함하여 콘텐츠 경로는 Recipe 자체 디렉터리 안에 머뭅니다에서 설명하듯 거부됩니다. 전송 스킴을 담은 참조 — oci://, https://, http://, git://, ssh://, git+ssh://, 또는 .git으로 끝나는 모든 참조 — 는 경로가 아니라 가져올 대상을 지정하므로, 작성한 그대로 전달되며 디렉터리와 결합되지 않습니다.

구조화 형태에서 경로는 url: 필드이며 같은 방식으로 읽힙니다. 상대 url:은 recipe.yaml이 있는 디렉터리를 기준으로 하고, 그 디렉터리를 벗어나는 것은 거부되며, 전송 스킴을 담은 것은 가져옵니다. 구조화 source:의 다른 모든 필드는 프로바이더가 정의한 필드를 포함하여 그대로 전달됩니다.

템플릿으로 작성된 source:는 템플릿 자체의 텍스트가 아니라 템플릿이 생성한 값을 기준으로 위치가 정해집니다. 템플릿은 평가되기 전까지 아무것도 지정하지 않으므로 위의 해석은 그 결과에 적용됩니다. 결과가 상대 경로이면 recipe.yaml이 있는 디렉터리를 기준으로 하고, 그 디렉터리를 벗어나는 결과는 절대 경로를 포함하여 빌드를 중단시키며, 전송 스킴을 담은 결과는 그대로 전달되어 가져옵니다. 따라서 템플릿은 위 목록의 어떤 형태든 자유롭게 생성할 수 있고, 각각은 같은 값을 리터럴로 작성한 경우와 정확히 동일하게 처리됩니다. 차이는 경로를 판단할 수 있는 시점뿐이며, 템플릿의 경우 그 시점은 Recipe를 읽을 때가 아니라 빌드가 템플릿을 평가할 때입니다.

아무것도 생성하지 않는 템플릿, 즉 빈 결과는 Recipe에 소스가 없는 상태로 남기며, 이는 소스 없는 모드입니다. 이는 source: ""를 직접 작성하는 것과 다릅니다. 후자는 어느 모드도 지정하지 않으므로 거부됩니다. 위의 목록 행을 참조하십시오.

이 목록은 작성자가 source:에 무엇을 넣을 수 있는지에 대한 정식 참조이며, 그 레이블은 10-status.md가 정의하는 것입니다.

콘텐츠 경로는 Recipe 자체 디렉터리 안에 머뭅니다

Recipe의 콘텐츠는 Recipe 자체 디렉터리에 있습니다. Recipe를 게시할 때 포함되는 모든 파일을 그곳에서 가져오기 때문입니다. Recipe가 포함하는 콘텐츠에 대해 작성하는 모든 경로, 즉 source:(단순 경로이든 구조화된 형식의 url:이든)와 valuesMapping:, workload:, artifacts: 항목이 $import:로 가져오는 각 파일은 recipe.yaml이 있는 디렉터리를 기준으로 읽히며 그 디렉터리 안에 머물러야 합니다. 이 경로들은 게시 시 포함되는 대상이기도 합니다. 경로가 가리키는 파일은 Recipe와 함께 전달되며, 디렉터리 안의 다른 것은 전달되지 않습니다(aggrega push 참조). 디렉터리를 벗어나는 경로는 Recipe와 함께 전달되지 않을 파일을 가리키므로, 이를 사용하는 쪽에는 그 파일이 없고, 그 파일에 대해 기록된 pin은 사용하는 쪽이 얻을 수 없는 바이트를 보증하게 됩니다.

디렉터리를 벗어나는 형태는 두 가지이며, 둘 다 거부됩니다.

  • ../shared/charts/app처럼 디렉터리 위로 올라가는 경로;
  • /opt/charts/app처럼 작성된 머신의 특정 위치를 가리키는 절대 경로.

위로 올라갔다가 다시 안으로 돌아오는 경로는 디렉터리 안의 일반 경로입니다. ./charts/../values.tmpl은 Recipe 옆의 values.tmpl을 가리킵니다. 판단 기준은 경로가 도달하는 위치이며, 이는 Recipe의 디렉터리를 벗어나지 않고 그 디렉터리에서부터 측정됩니다. 따라서 1.0.0이라는 디렉터리에서 작성한 ../1.0.0/values.tmpl처럼 밖으로 나갔다가 돌아오는 길에 디렉터리 이름을 다시 지정하는 경로도 거부됩니다. 디렉터리 자체의 이름은 전달되지 않습니다. 게시된 Recipe는 사용하는 쪽의 캐시가 이름을 붙인 디렉터리에서 읽히며, 그곳에서 원래 이름으로는 아무것도 찾을 수 없습니다.

거부되는 시점. Recipe를 읽는 모든 명령은 무언가를 가져오거나 렌더링하거나 게시하기 전에, 읽는 시점에 이러한 경로를 거부합니다. 해당 명령은 카탈로그 전체 또는 Recipe 자체 파일에 대한 aggrega validate, aggrega pull, aggrega build, aggrega pin, aggrega push입니다. 템플릿으로 작성한 source:는 빌드가 평가하기 전까지 아무것도 가리키지 않으므로, 디렉터리 밖의 경로를 생성하는 템플릿은 값이 생기는 시점에 빌드에서 거부됩니다. 이때의 중단은 A path names content outside the entity’s own directory (경로가 엔터티 자체 디렉터리 밖의 콘텐츠를 가리킴)이며, 작성한 경로를 표시합니다.

대신 해야 할 일. 파일을 Recipe의 디렉터리 또는 그 아래의 디렉터리에 두고, Recipe를 기준으로 한 상대 경로로 지정합니다: ./charts/app, ./extras/netpol.yaml. 여러 Recipes가 사용하는 차트는 각 Recipe가 개별적으로 게시되므로 각 Recipe의 디렉터리에 복사합니다. 여러 Recipes가 공유하는 매핑, 워크로드 또는 아티팩트 본문은 MappingLibrary, WorkloadLibrary 또는 ArtifactLibrary에 두며, 각 Recipe는 이를 식별자로 참조합니다.

Release가 다른 이유. Release는 다른 엔터티, 즉 자신의 Aggregate, Manifest, 확장하는 Release를 가리키며 게시되지 않으므로, 읽는 어떤 것도 다른 곳으로 전달되지 않습니다. 이러한 참조와 parameters:가 가져오는 파일은 작성된 그대로 읽히며, 이 덕분에 하위 디렉터리의 Release 변형들이 하나의 Aggregate를 공유할 수 있습니다. entities/release.md를 참조하십시오.

같은 제한이 FeatureRecipe에도, 그리고 Component나 Feature가 가져오는 모든 스키마에도 적용됩니다.

workload: 필드 — 합성 입력 종류

Recipe.spec.workload:는 컴파일러가 provider 고유 리소스로 합성하는 Workload 본문을 선언합니다. 이는 Recipe가 source:(소스 기반 렌더링) 및 artifacts:(보조 매니페스트)와 함께 선언할 수 있는 세 가지 입력 종류 중 하나입니다. 모든 provider에서 셋 중 적어도 하나가 있어야 하며, 빌드가 프로비저닝하지 않는 서비스는 form: reference인 workload:를 선언합니다.

이 필드는 인라인 블록 스칼라, 파일 $import:, 라이브러리 $import:의 세 가지 작성 모드를 받습니다. 컴파일러는 필드 내용의 형태에 따라 분기하므로 $mode: 주석은 필요하지 않습니다.

모드 1: 인라인(Go 템플릿 문자열 스칼라). 값은 출력이 aggrega.ai/v1beta1 Workload로 파싱되는 YAML 블록 스칼라입니다:

spec:
capability: helm
implements: core/web-server:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra "replicas" 1 }}
containers:
app:
image: "{{ .values.image }}"
ports:
http: 8080

Workload의 필드는 문서 루트에 위치하며 spec: 래퍼가 없습니다. 또한 containers:와 각 컨테이너의 ports:는 시퀀스가 아니라 이름을 키로 하는 맵이며, 작성자가 쓴 순서가 유지됩니다. provider는 이 형태를 자체 고유 형식으로 변환하므로, 컨테이너 맵 항목은 helm의 렌더링 출력에서 키로 이름 붙은 containers[] 요소로 나타납니다. 작성하는 형태는 렌더링된 목록이 아니라 맵입니다.

모드 2: 파일 $import:. 값은 로컬 Go 템플릿 파일을 가리키는 단일 $import: 키를 가진 맵입니다:

spec:
workload:
$import: ./workload/web-server.yaml.tmpl

경로 해석은 valuesMapping:과 같습니다. 상대 경로는 빌드를 호출한 디렉터리가 아니라 해당 경로를 선언한 recipe.yaml이 있는 디렉터리를 기준으로 하며, 그 디렉터리 안에 있어야 합니다. 가져온 본문은 인라인 본문과 똑같이 Recipe의 렌더링 컨텍스트에서 평가되는 Go 템플릿입니다.

모드 3: 라이브러리 $import:. 값은 WorkloadLibrary 항목에 대한 bare-name 식별 참조를 담은 단일 $import: 키를 가진 맵입니다:

spec:
workload:
$import: BaseWorkloads#/workloads/StatelessService

Workload 항목을 선택하는 것은 #/workloads/ 프래그먼트이며, 이 참조를 valuesMapping:이 사용하는 #/mappings/ 형식과 구분하는 것도 이 프래그먼트입니다. 후자는 MappingLibrary 항목을 가리키며 Workload 본문을 지정하지 않습니다. 참조에는 레지스트리 호스트가 포함되지 않고, 해석된 버전은 Release별 lockfile에서 가져오며, 선택적인 :<version> 최소 버전 하한을 <Library>:<version>#/workloads/<Entry> 형식으로 지정할 수 있고, 본문 자체가 필드 루트 $import:인 항목은 재귀적으로 해석됩니다. 가져온 본문은 이를 사용하는 Recipe의 렌더링 컨텍스트에서 평가되는 Go 템플릿이므로, .values, .infra, .features가 인라인 본문에서와 똑같이 전달됩니다. 라이브러리 엔터티와 전체 참조 문법은 entities/workloadlibrary를 참고하십시오.

대상 provider는 합성을 지원해야 합니다(표준 라이브러리 카탈로그는 관례에 따라 그러한 provider에 workloadSchema를 선언합니다). 합성할 수 없는 provider를 대상으로 하면 노드가 렌더링될 때 provider 기능 진단과 함께 거부되며, 이 판단은 workloadSchema의 존재 여부가 아니라 provider 기능을 기준으로 합니다. 전체 Workload 문법, K8s 형태의 패스스루 필드, provider별 변환 동작은 entities/workload.md를 참고하십시오. 세 가지 입력 종류 모델 전반과, 합성 결과를 소스 렌더링 출력 및 아티팩트와 병합하는 어셈블러는 architecture/16-recipe-input-composition.md를 참고하십시오.

컴포넌트 자체의 값을 개발자 자신의 이미지에 전달하기. 개발자가 빌드하는 이미지를 실행하는 Recipe는 표준 라이브러리 카탈로그의 관례에 따라 개발자의 inject: 블록이 해석한 모든 것을 .context.inject에서 전달할 것으로 기대되며, 컴포넌트 자체의 값을 자체적으로 정한 이름으로 전달할 수도 있습니다. Component가 spec.inject를 선언하는 경우에는 개발자 자신의 블록이 이름을 정하며, .context.self_inject는 각 항목의 템플릿이 읽는 하나의 자체 값을 Recipe에 알려 줍니다. 정확히 하나의 자체 값만 읽고 그 밖에는 아무것도 읽지 않는 항목의 경우 그 값은 values.<key>입니다. 표준 라이브러리 카탈로그의 관례는 Recipe가 이 값들에 붙인 이름을 개발자의 코드가 반드시 읽어야 하는 계약이 아니라 기본값으로 취급하여, 어떤 항목도 그 값에 매핑되지 않을 때에만 그 값을 기본 이름으로 전달하는 것입니다. 엔터프라이즈 카탈로그는 다르게 선택할 수 있습니다. 템플릿 컨텍스트 계약에서 이 맵의 정확한 규칙과 완성된 템플릿 예시를 제공합니다.

artifacts: 필드 — 보조 매니페스트

Recipe.spec.artifacts:는 항목 이름 → 아티팩트 본문 작성의 맵이며, 각 항목은 Recipe의 소스 기반 또는 합성된 기본 출력과 함께 추가 매니페스트 파일을 생성합니다. 이는 세 가지 입력 종류(소스 기반 / 합성 / 아티팩트) 중 하나이며, Recipe는 artifacts:만 선언하거나 workload: 및/또는 source:와 함께 선언할 수 있습니다.

각 항목의 값은 workload:와 같은 방식으로 내용의 형태에 따라 결정되는 세 가지 모드 중 하나를 가집니다. 인라인 내용, 파일 $import:, 라이브러리 $import:입니다. 컴파일러는 값의 내용 형태에 따라 모드를 결정하므로 $mode: 주석은 필요하지 않습니다. 세 모드 모두에서 맵 키는 항목이 생성하는 대상의 이름을 지정합니다. 단일 파일 모드 두 가지에서는 출력 파일 이름이고, 번들 모드에서는 번들의 파일이 중첩되는 디렉터리입니다. 키가 출력의 이름을 지정하므로, 키는 단일 파일 이름이 될 수 있는 범위로 제한됩니다. 첫 글자는 문자 또는 숫자이고, 그 뒤로 문자, 숫자, 점, 하이픈, 밑줄이 옵니다. 점은 키가 관례적으로 가지는 확장자(main.tf, template.yaml, serviceaccount.yaml)를 유지하기 위한 것이며, 이 문자 집합은 /를 허용하지 않아 키가 파일이 아닌 경로를 지정하는 일이 없고, 선행 .도 허용하지 않아 키가 상위 디렉터리 세그먼트가 될 수 없습니다. 이 문자 집합을 벗어난 키는 워크스페이스 로드 시, aggrega validate 실행 시, 그리고 편집기 진단에서 엔벌로프 검증에 실패합니다.

spec:
capability: helm
implements: core/web-server:1.0.0
artifacts:
extra-configmap.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: "{{ .context.instance_id }}-extras"
data:
threshold: "{{ .values.threshold }}"
network-policy.yaml:
$import: ./artifacts/network-policy.tmpl
operator-support:
$import: PlatformArtifacts#/artifacts/OperatorSupport

모드 1: 인라인(Go 템플릿 문자열 스칼라). 값은 블록 스칼라이며, 맵 키는 작성된 그대로 사용되는 출력 파일 이름입니다. 위의 첫 번째 항목은 extra-configmap.yaml을 생성합니다.

모드 2: 파일 $import:. 값은 로컬 Go 템플릿 파일을 가리키는 단일 $import: 키를 가진 맵이며, 맵 키는 모드 1과 똑같이 출력 파일 이름입니다. 가져온 파일은 내용을 제공할 뿐 이름을 제공하지 않습니다. 위의 두 번째 항목은 network-policy.yaml을 키로 가지며, 가져오는 파일의 이름이 network-policy.tmpl이더라도 network-policy.yaml을 생성합니다. 따라서 특정 출력 파일 이름을 원하는 작성자는 그 이름을 키로 작성하며, 우연히 같은 이름을 가진 서로 다른 파일(./extras/shared.yaml과 ./overrides/shared.yaml)을 가져오는 두 항목은 서로 다른 두 출력입니다. 경로 해석은 valuesMapping: 및 workload:와 같습니다. 상대 경로는 빌드를 실행한 디렉터리가 아니라 해당 경로를 선언한 recipe.yaml이 있는 디렉터리를 기준으로 하며, 그 디렉터리 안에 있어야 합니다.

모드 3: 라이브러리 $import:. 값은 ArtifactLibrary 번들에 대한 단순 이름 식별 참조 <Library>#/artifacts/<name>을 담은 단일 $import: 키를 가진 맵입니다. 번들은 하나의 단위로 가져오는 파일 집합이므로, 하나의 항목은 번들의 파일마다 하나의 출력으로 확장되며, 각 출력은 맵 키 아래에 <key>/<filename>으로 중첩됩니다. 키는 사용 위치의 이름을 지정하며, 그 파일들 중 어느 하나의 이름이 아니라 파일들이 놓이는 디렉터리입니다. 위의 세 번째 항목은 operator-support를 키로 가지며, PlatformArtifacts#/artifacts/OperatorSupport가 crd.yaml과 rbac.yaml을 선언하면 이 단일 항목은 operator-support/crd.yaml과 operator-support/rbac.yaml을 생성합니다. 참조에는 레지스트리 호스트가 포함되지 않으며(호스트를 포함한 oci://… 형식은 거부됩니다), 해석되는 버전은 Release별 잠금 파일에서 가져오고, 선택적인 :<version> 최소 버전 하한을 <Library>:<version>#/artifacts/<name> 형식으로 지정할 수 있습니다. 라이브러리 엔터티와 전체 참조 문법은 entities/artifactlibrary를 참조하십시오.

파일 $import:는 Recipe 옆에 고정됩니다. aggrega pin은 가져온 각 파일 바이트의 다이제스트를 Recipe 디렉터리의 entity.lock에 항목의 맵 키를 키로 하여 기록하며, aggrega build는 파일의 다이제스트를 다시 계산하여 더 이상 일치하지 않으면 [CATALOG_ERROR E0026]으로 중단합니다. 편집 전에 작성된 Release의 잠금 파일이 Recipe를 그 내용으로 기록하고 있는 경우에는 먼저 E0130으로 중단합니다. 따라서 고정된 후 편집된 파일은 검증 없이 렌더링되지 않습니다. 변경이 의도된 것이라면 Recipe에 대해 aggrega pin을 실행하여 새 다이제스트를 기록하고, 그렇지 않으면 파일을 복원하십시오. 인라인 항목은 Recipe 파일의 일부이고, 라이브러리 항목은 잠금 파일이 기록한 라이브러리 버전으로 고정되므로, 둘 다 자체 고정을 가지지 않습니다. 이 파일에 대한 설명은 aggrega pull을 참조하십시오.

각 아티팩트 항목의 템플릿은 어느 모드가 본문을 제공했든 valuesMapping:과 같은 템플릿 컨텍스트로 평가됩니다. 같은 파일 이름을 가진 두 출력은 노드가 렌더링될 때 빌드를 중단시킵니다. 하나의 artifacts: 맵에 속한 두 항목은 같은 출력의 이름을 지정할 수 없습니다. 맵 키는 하나의 문서 안에서 고유하며 단일 파일 이름을 나타내므로, 단일 파일 항목의 출력은 그 키이고 번들 항목의 파일은 그 키로 이름 지어진 디렉터리 아래에 놓입니다. 항목이 생성하는 모든 경로의 첫 세그먼트는 그것을 생성한 키이므로, 가져온 파일의 이름이 무엇이든 서로 다른 키는 서로 다른 출력 이름으로 유지됩니다. 이 중단이 다루는 것은 서로 다른 두 입력 종류가 기여한 하나의 파일 이름입니다. 예를 들어 차트 템플릿과 아티팩트 항목이 모두 servicemonitor.yaml을 생성하는 경우이며, 이는 기여한 모든 출처를 명시하는 진단과 함께 해당 Recipe에 대해 보고됩니다.

사용 사례. artifacts:는 기본 차트나 모듈이 생성하지 않는 보조 리소스를 두는 곳입니다. 예를 들어 워크로드에 수반되는 NetworkPolicy, Deployment와 짝을 이루는 HPA, instance_id를 키로 하는 사이드카 ConfigMap 등입니다. 여러 컴포넌트에 걸쳐 적용되는 횡단 보조 리소스(예: 모든 데이터 저장소에 연결되는 백업 사이드카)는 Recipe별 artifacts:가 아니라 FeatureRecipe Resource Generation에 속합니다. FeatureRecipe 확장 영역은 entities/featurerecipe.md를 참조하십시오.

boundary: 블록 — boundary의 공유 출력을 위한 파일

대부분의 Recipes에는 이 블록이 필요하지 않습니다. Recipe가 작성하는 그 밖의 모든 것은 해당 Recipe의 컴포넌트에 속하며, 프로바이더는 이를 경계 출력 안에서 그 컴포넌트 자신의 위치 아래에 배치합니다. 그러나 일부 파일은 경계 전체에 속합니다. 경계가 배포하는 모든 것에 대해 대상이 한 번만 읽는 파일입니다. 흔한 예는 Terraform의 프로바이더 구성입니다. Terraform 문서는 다른 구성이 호출하는 모듈에 provider 블록을 두지 않도록 하며, 자체 블록을 가진 모듈은 depends_on, count 또는 for_each로 호출할 수 없습니다. spec.boundary.artifacts는 Recipe가 이러한 파일을 작성하는 곳입니다.

spec:
capability: terraform
implements: core/api-gateway/azure-api-management:1.0.0
artifacts:
main.tf:
$import: ./module/main.tf
boundary:
artifacts:
# Terraform reads this beside the root configuration; one copy serves every
# component of the boundary that declares it.
provider-azurerm.tf: |
provider "azurerm" {
features {}
}

이 블록은 두 번째 범위의 artifacts:입니다. artifacts가 유일한 멤버이며, Recipe 자체의 artifacts:와 정확히 같은 형태를 취합니다. 같은 세 가지 모드(인라인 내용, 파일 $import:, 그리고 파일이 항목의 키 아래에 <key>/<filename>으로 중첩되는 라이브러리 $import:), 같은 키-파일 이름 규칙과 같은 키 문자 집합, 그리고 같은 템플릿 컨텍스트를 사용하므로, 항목은 artifacts: 항목과 똑같이 .values, .infra, .locals 등을 읽습니다. 항목이 최소 하나 있어야 하며, boundary: 아래의 다른 멤버는 Recipe를 읽을 때 거부됩니다. FeatureRecipe에는 이러한 블록이 없습니다.

파일이 작성되는 위치. boundary의 조립된 출력을 담은 디렉터리에 한 번, provider 자체의 조립 과정이 그곳에 작성하는 파일 옆에 작성됩니다. terraform의 경우 component의 모듈 안이 아니라 aggrega.modules.tf 루트 구성 옆입니다. provider에는 이 파일들이 전혀 전달되지 않습니다. 컴파일러가 직접 평가하고 작성하며, 파일을 선언한 모든 component에 속하므로 어느 component에서 왔는지 나타내는 표시를 넣지 않습니다. 템플릿이 아무것도 렌더링하지 않는 항목은 파일을 작성하지 않습니다.

여러 기여자가 만나는 방식. 모든 항목은 Recipe가 boundary에서 렌더링하는 각 component에 대해 평가되며, boundary의 모든 기여자가 선언한 파일은 이름으로 병합됩니다. 하나의 이름이 같은 바이트로 평가되면(하나의 Recipe에 바인딩된 두 component, 또는 하나의 provider를 동일하게 구성하는 두 Recipes에 의해) 하나의 파일이 됩니다. 하나의 이름이 서로 다른 바이트로 평가되면, 어떤 단일 파일도 그들 모두가 작성한 것이 아니므로 파일과 모든 기여자를 명시하며 빌드가 중단됩니다. aggrega.modules.tf처럼 provider 자체의 조립 과정이 작성하는 이름도 마찬가지입니다. 둘 다 조립된 출력 충돌입니다. 하나의 provider를 서로 다른 두 파일 이름으로 구성하는 두 Recipes는 병합되지 않고 각 파일이 작성되며, 이 경우 중복 구성을 보고하는 것은 대상입니다. 따라서 provider 구성을 공유하려는 Recipes는 그 파일 이름을 공유하며, 관례상 구성하는 provider의 이름을 따릅니다.

이를 허용하는 providers. boundary의 조립된 출력 옆에 놓인 파일이 의미가 있는지는 provider 대상의 속성이므로, provider 자체 선언의 일부입니다. provider가 허용하지 않는데 이 블록을 선언한 Recipe는 항목이 무엇으로 렌더링되든 렌더링 전에 거부됩니다. The provider does not support boundary artifacts (provider가 boundary artifacts를 지원하지 않음)를 참조하십시오. 기능 표에 각 provider의 지원 여부가 나와 있습니다.

Providerboundary.artifacts:
terraform허용됩니다. 각 파일은 boundary의 루트 구성 옆에 작성되며, Terraform은 이를 해당 디렉터리의 다른 모든 구성 파일과 함께 읽습니다.
helm, compose, helm-chart, cloudformation렌더링 전에 거부됩니다.

여기서의 파일 $import:는 artifacts: 항목이 가져오는 파일과 같이 고정됩니다. entity lock은 그 다이제스트를 같은 artifactDigests 목록에 키만이 아니라 boundary/<key> 아래에 기록하므로, 같은 키로 작성된 각 블록의 항목은 별도로 고정됩니다. pin 단계가 이를 기록하고, pin하지 않는 pull은 pin이 없거나 더 이상 일치하지 않으면 중단되며, 빌드는 artifacts: 파일을 거부하는 것과 똑같이 고정 이후 편집된 파일을 거부합니다.

outputLabels: 필드 — 렌더링된 출력에 작성자가 선언하는 레이블

Recipe.spec.outputLabels:는 레이블 키 → 값의 맵으로, provider가 Recipe의 렌더링된 출력이 만들어 내는 모든 객체에 찍습니다. 이는 실현 특성, 즉 component가 무엇인지가 아니라 특정 Recipe가 component를 어떻게 실현하는지에 관한 속성을 두기에 알맞은 곳입니다. 실현이 데이터를 영속화하는 스토리지를 예로 들어, 아래에서는 예시 키 example.io/storage-backing으로 적습니다. PersistentVolumeClaim을 마운트하는 Helm Recipe와 이름 있는 볼륨을 마운트하는 Compose Recipe는 서로 다른 메커니즘으로 같은 component를 실현하므로, 서로 다른 outputLabels를 가지며 다운스트림 도구(비용 할당, 정책, 인벤토리)는 출력된 리소스에서 둘을 구별할 수 있습니다. 이 키는 예시입니다. example.io/는 예시 네임스페이스이며, 카탈로그는 자체 도구가 읽는 키를 고릅니다.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/storage-backing: persistent-volume
example.io/team: platform

출력 레이블은 고정된 빌드 출처 레이블과 같은 경로를 탑니다. 출력을 내보내는 모든 표면이 찍는 레이블 집합에 병합되므로, 출처 정보가 놓이는 곳이면 어디에나 놓입니다. 다른 점은 소유권입니다. 출처 키는 컴파일러가 소유하고, outputLabels는 Recipe 작성자가 소유합니다.

component 자신의 정체성 레이블은 여기에 직접 적지 않습니다. 이는 카탈로그 관례이며, 컴파일러가 강제하는 규칙이 아닙니다. 한 Recipe가 component를 어떻게 실현하는지가 아니라 component가 무엇인지를 나타내는 키, 즉 인지적 범주, 운영 유형, 역할별 기능 레이블, 기반 리소스를 누가 운영하는지, 감싸는 대상의 라이선스 등급은 Component의 metadata.labels에 선언합니다. 축에 대해서는 entities/component의 “The Semantic Label Taxonomy”를 참조하십시오. Recipe는 여기에 키와 값을 직접 적는 것이 아니라, 아래의 outputComponentLabels:에 키를 지정하여 그러한 레이블을 렌더링된 출력에 붙입니다. 그 이유는 리터럴 항목이 component가 이미 가진 값의 두 번째 사본이고, 두 번째 사본은 첫 번째와 어긋날 수 있기 때문입니다. Recipe 작성자가 Component가 다른 자세를 선언한 노드에 또 다른 자세를 적으면, 다운스트림 독자에게 그래프가 말하지 않는 내용을 전하게 됩니다. 승격된 항목은 참조로 복사하므로 어긋날 두 번째 사본이 없습니다. 코어는 아래의 예약 네임스페이스 규칙 외에는 무엇을 적든 받아들이며, 이 관례는 카탈로그 작성자가 지킵니다.

예약 네임스페이스. aggrega.ai/ 및 app.kubernetes.io/ 네임스페이스는 플랫폼 고유의 출처 정보용으로 예약되어 있습니다. 두 접두사 중 하나 아래에 outputLabels 키를 선언하는 Recipe는 로드 시 문제의 키를 명시하는 명확한 카탈로그 오류와 함께 거부됩니다. 그 밖의 모든 키는 허용됩니다. 코어는 그 외에는 키나 값을 검사하지 않습니다. 대상 엔진의 레이블 표면에서 유효하지 않은 키나 값은 작성자의 책임이며, 다운스트림 런타임이 이를 거부합니다. 컴파일러는 예약 네임스페이스 규칙 외에는 관여하지 않습니다.

provider별 표시. 각 provider는 레이블을 자체 출력 표면으로 옮깁니다.

  • helm, 워크로드 합성 — 합성이 출처 정보를 두는 위치와 같이, 객체의 metadata.labels와 파드 템플릿의 metadata.labels 모두에 붙습니다.
  • helm, 소스 렌더링 및 아티팩트 — 객체의 metadata.labels에 붙습니다.
  • compose — 각 서비스의 labels: 맵에 붙습니다.
  • terraform — 구조적으로 주소 지정이 가능한 .tf.json 아티팩트 본문에 리소스별 태그로 최선의 노력으로 붙습니다. 이미 tags(AWS/azurerm) 또는 labels(Google) 맵을 선언한 리소스 블록은 그곳에 출력 레이블을 받으며, 작성자가 선언한 키는 결코 덮어쓰지 않고, 그러한 속성이 없는 리소스는 그대로 둡니다(속성을 새로 만들지 않습니다). 네이티브 HCL 본문(main.tf, *.tf)과 벤더링된 모듈은 그대로 출력되며 주입된 태그를 갖지 않습니다. Terraform 출처 정보는 태그 경로와 별도로 계속 동반 주석 파일에 담겨 전달됩니다.

출력 레이블은 레이블일 뿐이며, 별도의 출력 어노테이션 표면은 없습니다. outputLabels는 Aggregate가 아니라 Recipe 작성자(운영 측이 작성하는 실현 계층)가 선언합니다. 이는 실현을 기술하며, 개발자의 추상 그래프상 정체성을 기술하지 않습니다.

outputComponentLabels: 필드 — 컴포넌트 자체 레이블 승격

Recipe.spec.outputComponentLabels:는 키-값 쌍이 아니라 레이블 키의 목록입니다. 프로바이더는 여기에 지정된 각 키를, 렌더링 중인 컴포넌트 인스턴스에서 그 키가 가진 값과 함께 렌더링된 출력에 찍습니다. outputLabels가 값을 명시한다면, outputComponentLabels는 값을 어디에서 읽을지를 지정합니다.

spec:
capability: helm
implements: core/datastore/postgres:1.0.0
outputLabels:
example.io/team: platform
outputComponentLabels:
- component.aggrega.ai/hosting

metadata.labels에 component.aggrega.ai/hosting: managed를 선언한 Component가 있으면, 이 Recipe가 해당 컴포넌트에 대해 렌더링하는 모든 객체는 component.aggrega.ai/hosting: managed를 가집니다. 같은 Recipe를 self-hosted를 선언한 컴포넌트에 바인딩하면 그 컴포넌트의 객체는 대신 self-hosted를 가집니다. 하나의 Recipe, 하나의 지정된 키, 컴포넌트마다의 값입니다.

승격은 참조로 이루어지며, 바로 그것이 핵심입니다. 값은 출력이 렌더링될 때마다 컴포넌트에서 읽히므로, 값이 유래한 정체성과 어긋날 수 없습니다. 컴포넌트의 레이블이 바뀔 때 함께 맞춰야 할 두 번째 사본이 없습니다. 컴포넌트의 레이블을 다시 적는 리터럴 outputLabels 항목은 바로 그 두 번째 사본이며, 둘 중 하나가 바뀌는 순간 둘은 불일치합니다. 따라서 값이 이 Recipe가 컴포넌트를 실현하는 방식의 속성이라면 outputLabels를, 값이 이미 컴포넌트에 존재하고 렌더링된 출력에도 그 값이 있어야 한다면 outputComponentLabels를 사용합니다.

승격된 키는 리터럴 키와 정확히 같은 표면에 놓입니다. 위에서 설명한 프로바이더별 표면화가 그대로 적용되며, 어떤 프로바이더도 승격된 키와 그 자리에 작성된 키를 구별하지 않습니다.

예약된 네임스페이스. aggrega.ai/와 app.kubernetes.io/ 네임스페이스는 플랫폼 고유의 출처 정보용으로 예약되어 있으며, 두 접두사 중 하나 아래의 승격된 키는 로드 시 해당 키와 그 키가 나타난 필드를 지목하는 카탈로그 오류와 함께 거부됩니다. 판정 기준은 접두사 자체입니다. component.aggrega.ai/hosting 같은 키는 예약된 루트 아래가 아니라 자체 네임스페이스에 속하므로 승격할 수 있습니다.

키는 둘 중 한 블록에만 속합니다. 같은 키를 outputLabels와 outputComponentLabels 양쪽에 선언하면 로드 시 거부되므로, 찍히는 모든 키는 단일 출처를 가집니다. 즉 Recipe에 작성된 리터럴 값이거나 컴포넌트 자체의 레이블이며, 둘 다인 경우는 없습니다.

컴포넌트가 선언하지 않은 승격 키는 아무것도 찍지 않습니다. 빌드는 계속되며 노드, Recipe, 누락된 키를 지목하는 경고를 출력합니다. 이는 의도된 것입니다. 레이블 집합이 서로 다른 컴포넌트들에 바인딩된 Recipe도 여전히 렌더링되며, 불일치는 중단 대신 드러내어 알려집니다.

단일 형태 컴포넌트 — 규칙이 아닌 관례. 승격은 컴포넌트가 선언한 값을 무엇이든 그대로 전달하며, 컴파일러는 그 값을 해석하지 않습니다. 따라서 정체성 레이블에 “다양함”을 대신하는 자리표시자를 담은 컴포넌트는 그 자리표시자를 자신에 대해 렌더링되는 모든 객체에 승격합니다. 컴포넌트가 실제로 둘 이상의 형태를 가지는 경우, 표준 라이브러리 카탈로그의 관례는 각 Recipe가 컴포넌트의 정체성 키가 아니라 Recipe가 소유한 outputLabels 키를 통해 자신의 실현 형태를 명시하는 것입니다. 정체성 키는 같은 관례에 따라 대신 outputComponentLabels:를 통해 전달됩니다. 또는 아무것도 찍지 않을 수도 있습니다. 두 키는 서로 다른 질문에 답하며 어느 쪽도 다른 쪽을 대체하지 않습니다. 정체성 키는 모든 실현에 걸쳐 컴포넌트가 무엇인지를 말하고, Recipe 소유 키는 이 하나의 실현이 무엇을 하는지를 말합니다. 이는 작성자들이 지키는 카탈로그 관례이며, 컴파일러가 강제하는 제약이 아닙니다.

locals: 블록

Recipe.spec.locals:는 Private Ops State입니다. 이름이 붙은 Go 템플릿 문자열의 맵으로, 렌더링된 출력은 Recipe의 이후 템플릿에 .locals.* 맵으로 노출됩니다. 물리적 실체(대상 컨테이너, JSON 경로, 파생 호스트 이름)를 한 번 계산하고, 다시 계산하지 않고 provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with 페이로드 전반에서 재사용하기 위한 작업 공간입니다. 각 항목의 렌더링된 출력은 앞뒤 공백을 제거한 상태로 저장됩니다.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
locals:
primary_compute: postgresql
listen_port: "5432"
secret_target_db_password: "postgres-auth"
volumes_path: "/spec/template/spec/volumes"
valuesMapping: |
primary:
auth:
existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"

locals:는 호출자에게 절대 노출되지 않습니다. uses:를 통해 이 Recipe를 사용하는 다운스트림 컴포넌트는 provides:만 볼 수 있습니다. Recipe 자신의 provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with 템플릿은 모두 해석된 .locals.* 맵을 봅니다. 키별 값은 일반 문자열이거나 Go 템플릿일 수 있습니다. 컴파일러는 해당 노드의 provides:보다 먼저 locals 프리앰블에서 블록 전체를 해석하므로, 이후의 모든 템플릿은 안정적으로 해석된 값을 관찰합니다.

각 항목은 자체 완결적인 노드 로컬 컨텍스트, 즉 .context.instance_id, .values, .infra, 그리고 같은 블록에서 이미 해석된 항목을 대상으로 평가됩니다. local은 .provides를 읽을 수 없습니다. 그 축은 이 표면에 없으며, 이를 참조하려는 항목은 중단됩니다. 또한 helm 같은 provider가 노드에 대해 렌더링하는 리소스에 부여하는 이름인 .context.rendered_name도 읽을 수 없습니다. 따라서 그러한 리소스 중 하나를 명명하는 local은 위의 secret_target_db_password처럼 그 이름 뒤의 부분만 담고, 전체 이름을 작성하는 템플릿이 두 부분을 결합합니다.

작성 순서가 동작을 좌우합니다

항목은 작성된 순서대로 해석되며, 항목은 자신보다 위에 정의된 형제 항목을 읽을 수 있고, 그 형제 항목의 해석된 값을 받습니다.

spec:
locals:
db_identifier: "{{ .context.instance_id }}-postgres" # defined first
secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above

연쇄 참조는 아래 방향으로만 진행됩니다. 한 항목이 다른 항목을 읽는 경우, 항목의 순서가 빌드의 성공 여부를 결정합니다. db_identifier를 secret_target 아래로 옮기면 빌드가 중단됩니다. 컴파일러는 참조를 해석하기 위해 블록을 정렬하거나 재배치하지 않으므로, 작성된 순서가 곧 계약입니다. locals: 블록의 순서를 바꾸는 것은 외형상의 변경이 아니라 동작의 변경입니다.

작성자가 저지를 수 있는 두 가지 실수는 해결 방법이 다르므로, 서로 다른 두 가지 중단으로 구분됩니다.

  • 블록이 나중에 정의하는 항목에 대한 참조는 순서 오류를 명시하며 중단됩니다. 해결 방법은 정의를 그것을 읽는 항목 위로 옮기는 것입니다.
  • 블록이 전혀 선언하지 않은 키에 대한 참조는 해당 키를 명시하며 중단됩니다. 해결 방법은 철자를 바로잡는 것입니다.

검사는 블록의 별칭도 따라갑니다. with .locals 본문이 다시 바인딩하는 점(dot)을 통해, 또는 .locals에 바인딩된 변수를 통해 도달하는 키는 직접 표기와 정확히 같은 조건으로 검사됩니다. {{ with .locals }}{{ .nope }}{{ end }}와 {{ $l := .locals }}{{ $l.nope }}는 {{ .locals.nope }}와 마찬가지로 모두 .locals.nope를 명시하며 중단되고, {{ (.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(템플릿이 맵에 없는 키로 맵을 인덱싱함)” 항목에 설명되어 있습니다. 따라서 index는 {{ index .locals (printf "secret_target_%s" .values.slot) }}처럼 이름 자체가 계산되는 키에 도달하는 방법으로 남으며, 블록이 선언하지 않은 계산된 이름도 여전히 그 키로 보고됩니다.

노드의 locals는 provides보다 먼저 해석되므로, provides:는 .locals를 읽고 해석된 값을 받습니다. locals 블록이 선언하지 않은 키를 명명하는 provides: 템플릿은 중단됩니다. 즉 provides: 항목과 아티팩트가 모두 필요로 하는 값은 locals:에 한 번 작성하고 양쪽에서 읽습니다.

공개 API에 해당하는 부분은 아래의 provides: 블록을 참조하십시오. FeatureRecipe 표면도 같은 규칙을 따릅니다. entities/featurerecipe.md의 “locals: 블록”을 참조하십시오.

provides: 블록

Recipe.spec.provides:는 공개 개발자 API입니다. 이 Recipe가 다운스트림 호출자의 .context.inject 및 .context.uses 파이프에 제공하는 값을 선언하는, 이름 → Go 템플릿 문자열의 맵입니다. 컴파일러는 provides: 템플릿을 provides 평가 단계(자기 완결적, 순서 무관)에서 평가하며, 호출자의 inject 키는 inject 하이드레이션 단계에서 이 값들을 기준으로 해석됩니다.

spec:
capability: helm
implements: core/postgres-db:1.0.0
source: ./charts/postgresql
provides:
# The Service this chart names after its release name, suffixed "-postgresql"
host: "{{ .context.rendered_name }}-postgresql"
port: "5432"
database: "{{ .values.db_name }}"

각 항목의 템플릿은 자기 완결적인 provides 평가 표면을 기준으로 평가됩니다. 이 표면에는 .context.instance_id, 노드의 provider가 보고하는 경우의 .context.rendered_name, .values, .infra, 노드의 해석된 .locals, 그리고 정적 텍스트가 있습니다. 노드가 배치되는 네임스페이스는 이 표면에 없으므로, 게시되는 호스트에는 네임스페이스가 포함되지 않습니다. 다른 네임스페이스의 소비자는 자신의 쪽에서 이를 한정합니다. .locals가 이 표면에 있는 이유는 노드의 locals가 같은 단계의 프리앰블에서 provides보다 먼저 해석되기 때문입니다. locals 블록이 선언하지 않은 키를 참조하는 provides 템플릿은 중단됩니다. provides 평가와 inject 하이드레이션을 분리하는 것은 동작을 좌우합니다. provides 평가가 실행될 때는 호출자가 아직 해석되지 않았으므로 Recipe의 provides:는 어떤 호출자의 상태도 참조할 수 없습니다. 아키텍처 불변 조건에 따라 provides:는 자기 완결적입니다. 이후 호출자는 자신의 템플릿에서 .context.uses.<alias>.provides.<provided-name>를 통해 이 값들을 읽습니다. 제공된 이름은 에지의 다른 필드와 나란히 에지의 provides 아래에 중첩됩니다. 에지에 inject: 허용 목록을 선언한 호출자는 대신 자신의 .context.inject 파이프를 통해 같은 값에 접근합니다.

provides: 키는 Recipe의 계약 표면의 일부입니다. 키의 이름을 바꾸거나 제거하는 것은 이전 이름에 의존하는 모든 호출자에게 호환성을 깨는 변경이며, implements: 인터페이스 버전은 계약의 변화를 반영해야 합니다. 캐스케이드 해석 의미론, inject 파이프 계약, 그리고 네임스페이스 간 및 리전 간 라우팅을 다루는 예제는 architecture/06-data-taxonomy-and-composition.md §3 및 templates/expansion-matrix.md를 참조하십시오.

첨부의 게시된 값 읽기

Recipe는 자신의 컴포넌트에 첨부된 Features를 .features.<instance-name>에서 읽고, 자격 증명 Features를 .features.<slot>에서 읽습니다. 둘 다 동일한 첨부 형태(.type, .values, .infra, .provides)이므로 어느 맵에 들어 있든 첨부는 같은 방식으로 읽습니다. 둘 사이에 다른 것은 첨부가 생성하는 내용입니다.

.provides는 첨부의 게시된 출력으로, 해당 첨부에 바인딩된 FeatureRecipe에서 해석됩니다. 이는 위의 provides: 블록을 소비하는 쪽에서 본 대응물입니다. Recipe가 호출자에게 게시하는 것처럼, 첨부는 자신의 호스트 컴포넌트에 게시합니다.

workload: |
# The identity attachment emits a ServiceAccount and publishes its name;
# the pod binds to that published name rather than restating it.
serviceAccount: "{{ .features.identity.provides.name }}"
containers:
main:
env:
DB_SECRET: "{{ .features.app_credentials.provides.name }}"

같은 values/infra 입력에서 값을 다시 계산하지 않고 게시된 값을 읽는 것은, 이름을 한 번만 진술하는 것과 서로 어긋날 수 있는 두 번의 진술 사이의 차이입니다. 가용성 규칙을 포함한 필드별 전체 형태는 templates/template-context-contract.md에 있습니다.

컴포넌트의 연결 중 하나에 작성된 첨부, 즉 컴포넌트가 하나의 대상에 제시하는 자격 증명은 해당 연결 아래 .context.uses.<alias>.features.<slot>에서 같은 형태로 읽으며, .features에는 결코 포함되지 않습니다. 여러 대상에 접근하는 Recipe는 각 대상의 자격 증명을 해당 대상의 별칭 아래에서 읽으며, .features를 순회하면서 유형별로 첨부를 골라내는 루프는 컴포넌트 자신의 첨부만 만나게 됩니다:

artifacts:
routes.yaml: |
{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
{{- end }}{{ end }}
{{- end }}

형태와 템플릿이 연결을 순회하는 순서는 연결의 첨부를 참조하십시오.

pipeline: 필드

Recipe.spec.pipeline:은 렌더링 후 렌더링된 문서 집합에 대해 실행되는 Wasm 파이프라인 단계의 순차 배열이며, 각 단계는 RFC 6902 패치와 부수 효과를 반환합니다. 각 항목은 id(단계별 식별자: 문자, 숫자, 밑줄), plugin(단계가 실행하는 Plugin 엔터티로, 플러그인 유형으로 범위가 지정되며 pipeline-step/<name> 형태이고 버전을 붙일 수도 있습니다. 단순 .wasm이나 아티팩트 참조는 거부됩니다), function(호출할 플러그인 export), 플러그인의 페이로드를 제공하는 선택적 with: Go 템플릿 본문, 그리고 단계의 실행 여부를 결정하는 선택적 when: Go 템플릿을 선언합니다. 결과가 거짓으로 평가되면 해당 단계는 통과(pass-through)로 건너뛰어지며 문서 집합은 변경되지 않습니다. when: 게이트, optional:과의 독립성, 그리고 참 여부 판정 규칙은 entities/featurerecipe.md의 “Conditional steps — when:”에서 자세히 다룹니다:

spec:
capability: helm
implements: core/web-server:1.0.0
source: { kind: helm-oci-chart, url: "oci://…", version: "…" }
pipeline:
- id: inject_sidecar
plugin: pipeline-step/envoy-sidecar:1.0.0
function: Inject
with: |
target_container: "{{ .locals.primary_compute }}"
envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"

컴파일러는 FeatureRecipe의 pipeline:을 실행하는 것과 같은 방식으로 기본 Recipe의 pipeline: 단계를 선언된 순서대로 실행합니다. 즉, 각 단계에 지정된 Wasm 플러그인을 렌더링된 출력에 대해 디스패치하고, 반환된 JSON Patch 연산을 대상 문서에 적용하며, 단계의 부수 효과를 내보냅니다. FeatureRecipe의 pipeline: 필드는 동일한 스키마 형태와 동일한 실행 방식을 공유합니다. 각 표면의 실행 상태는 entities/featurerecipe.md의 “Authoring Contract”와 언어 현황을 참조하십시오.

이 필드의 동작 방식은 FeatureRecipe의 의미론을 그대로 따릅니다. 선언된 순서대로 순차 평가되고, JSON Patch 연산이 렌더링된 문서에 적용되며, 부수 효과가 문서와 함께 내보내지고, 오류는 문제가 된 단계를 가리키는 출처 정보와 함께 보고됩니다. when: 게이트가 거짓으로 렌더링되는 단계는 통과로 건너뛰어지며, 문서 집합은 다음 단계를 위해 변경되지 않은 채로 유지됩니다.

assertions: 블록

Recipe.spec.assertions:는 Recipe의 구현 불변 조건을 표현하는 이름 있는 규칙의 선택적 맵입니다. 이는 Recipe가 소싱하는 특정 차트나 모듈을 전제로 성립하는 필드 간 규칙입니다. 각 키는 실패 메시지에 나타나는 규칙 식별자이고, 각 값은 Go 템플릿 본문입니다. 어떤 Recipe가 바인딩되는지와 무관하게 계약 수준의 불변 조건을 표현하는 Component assertions와 달리, Recipe assertions는 선택된 특정 구현의 속성입니다.

spec:
implements: core/datastore/mariadb:^1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}

위 규칙은 Bitnami 차트 20.x에 한정되며, 다른 MariaDB Recipe가 바인딩되면 적용되지 않습니다. 계약에서 온 Component 수준 규칙은 그와 함께 여전히 적용되며, 더 이른 파이프라인 단계에서 평가됩니다.

Recipe assertions는 Recipe 바인딩 이후, 렌더링 이전에, 모든 노드의 locals와 provides가 해석된 뒤 평가됩니다. 템플릿 컨텍스트에는 엔터티 인스턴스 필드(.values, .infra, .uses, .features)에 더해 Recipe의 .provides, .locals, .recipe.source가 포함됩니다. 여기서 .uses와 .features는 Recipe 템플릿의 형태가 아니라 assertion 표면의 더 좁은 형태입니다. 연결의 항목은 그 대상과 별칭, 대상의 labels, 연결 자체의 values, 그리고 연결에 features 아래 작성된 attachment를 담지만, 대상이 게시하는 것은 담지 않습니다. 또한 attachment의 항목은 component 자체의 것이든 연결의 것이든 type, resolved_version, values를 담지만 infra도 provides도 담지 않습니다. assertion이 실행될 때 attachment의 FeatureRecipe는 아직 provides를 해석하지 않았기 때문입니다. 따라서 .features.<name>.provides에 대한 참조는 중단되며, 그에 대한 존재 인식 읽기는 대체값을 반환합니다. 전체 작성 문법, 계약 수준 규칙과 구현 수준 규칙 간의 책임 분담, 그리고 실제 예제는 templates/assertions-block.md를 참조하십시오.

omits: 필드 — 렌더링된 문서를 소스에서 제외하기

대부분의 Recipes에는 이 필드가 필요하지 않습니다. 이 필드는 있는 그대로 가져다 쓰는 소스, 대개는 레지스트리에서 가져온 차트가 Release가 배포해서는 안 되는 문서를 렌더링하는 경우를 위한 것입니다. 예를 들어 차트가 렌더링할 때마다 새로 생성하는 Secret은 두 빌드의 결과를 다르게 만들고, 적용되면 운영자가 제공한 Secret을 덮어씁니다. 가져온 차트는 편집하지 않으며 어떤 ignore 규칙도 그 안까지 미치지 않으므로, omits:는 Recipe가 그러한 문서를 빌드에서 제외하는 방법입니다. 가져온 compose 파일도 마찬가지입니다. 이 파일에는 Release에 있어서는 안 되는 서비스, 볼륨 또는 config가 포함될 수 있으며, valuesMapping: 오버레이는 이를 변경할 수는 있지만 제거할 수는 없습니다. 가져온 CloudFormation 템플릿도 같습니다. 이 템플릿은 Release가 생성해서는 안 되는 리소스를 선언할 수 있으며, valuesMapping:은 템플릿이 선언한 파라미터를 채울 수는 있지만 그 리소스를 제거할 수는 없습니다.

spec:
capability: helm
implements: core/gateway/kong:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/gateway
version: "2.4.0"
omits:
# The chart generates this key on every render; the operator supplies it.
- kind: Secret
name: "{{ .context.rendered_name }}-session-key"
# Left out only where the Release asks for it.
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: "{{ .context.rendered_name }}-dashboards"
namespace: monitoring

적용 범위. source:가 렌더링하는 것만 해당합니다. workload:와 artifacts: 항목은 필터링되지 않습니다. 이것들은 Recipe에 직접 작성하므로, 원하지 않는 문서는 작성하지 않으면 됩니다. 이 키에는 source:가 필요하며, 이 규칙을 어기는 문서는 읽을 때 해당 규칙을 명시하며 거부됩니다.

항목. 각 항목은 세 개의 필드로 제외할 대상을 지정하고, 네 번째 필드로 적용 여부를 결정합니다. 앞의 세 필드가 지정하는 것은 해당 provider의 소스가 렌더링하는 것에 대한 provider 고유의 어휘이며, provider별로 아래 표에 정리되어 있습니다.

  • kind — 소스가 렌더링하는 것의 종류입니다. 차트에서는 렌더링된 문서의 종류(Secret, ConfigMap, Deployment)이고, compose 파일에서는 service, volume 또는 config이며, CloudFormation 템플릿에서는 리소스의 Type(AWS::S3::Bucket)입니다. 구조화된 source:에 있는 kind:와는 관계가 없으며, 그 키는 소스를 가져오는 방식을 나타냅니다.
  • name — 그 이름입니다. 문서의 metadata.name, services:, volumes: 또는 configs: 아래에 있는 compose 단위의 키, CloudFormation 리소스의 논리적 ID, 즉 Resources 아래의 키입니다.
  • namespace (선택 사항) — 출력에 네임스페이스가 있는 provider의 경우, 문서가 속한 네임스페이스입니다. 이 필드가 없으면 항목은 모든 네임스페이스에서 해당 kind와 name을 지정합니다. 빈 값으로 렌더링되는 namespace는 없는 것으로 취급됩니다.
  • when (선택 사항) — 항목이 이 빌드에 적용되는지 여부입니다. 가장 먼저 평가되며, 파이프라인 단계의 when:과 같은 규칙으로 해석됩니다. 결과가 거짓이면 항목이 제외되므로 나머지 필드는 평가되지 않고 provider에 전달되거나 검사되지도 않습니다. when:이 없거나 비어 있으면 항목이 유지됩니다.

kind와 name은 필수이며, 그 밖의 필드를 가진 항목은 Recipe를 읽을 때 거부됩니다.

모든 값은 템플릿입니다. valuesMapping:과 같은 컨텍스트에 대해 평가됩니다. 이 컨텍스트에는 .context.rendered_name이 포함됩니다. 이는 provider가 노드의 리소스에 부여하는 이름이자 차트가 일반적으로 리소스 이름의 기준으로 삼는 이름이므로, 항목은 차트가 붙일 이름 그대로 문서를 지정할 수 있습니다. 렌더링에 실패한 템플릿은 실패한 valuesMapping: 템플릿과 마찬가지로 빌드를 중단시킵니다.

적용되는 모든 항목은 무언가를 제외해야 합니다. provider는 각 항목이 제외한 단위의 수를 보고하며, 아무것도 제외하지 않은 항목은 해당 항목을 명시하며 빌드를 중단시킵니다. An omits entry left out nothing the source rendered (omits 항목이 소스가 렌더링한 것을 아무것도 제외하지 않았습니다)를 참조하십시오. 보통의 원인은 문서의 이름을 바꾸거나 문서를 제거한 소스 업그레이드이며, 이 중단 덕분에 이름이 바뀐 문서가 모르는 사이에 출력에 포함되지 않습니다. 문서를 경우에 따라서만 제외하려면 문서가 없기를 기대하지 말고 when:으로 명시하십시오.

소스는 여전히 전부 렌더링됩니다. 필터링되는 것은 출력뿐입니다. 차트의 모든 템플릿은 그대로 실행되므로 실패하는 템플릿은 여전히 빌드를 실패시키며, 제외된 문서도 렌더링된 뒤에 버려집니다. 버려진 문서는 이후 빌드가 하는 어떤 작업에도 도달하지 않습니다. 출력되는 파일에도, 다른 component의 이름과 비교되는 이름에도, Feature가 렌더링에 대해 읽는 사실에도, 파이프라인 단계에 전달되는 어떤 것에도 포함되지 않습니다.

Release는 infra와 parameters를 통해 이 키에 영향을 줍니다. 이 키는 Recipe에 속하므로 Release가 작성할 수 없습니다. 그래도 항목이 하는 일은 결정할 수 있습니다. 항목의 템플릿은 Release가 채우는 infra를 읽으며, Release가 제공하는 parameters는 Aggregate가 라우팅하는 곳이라면 Recipe의 .values에 도달합니다. 따라서 Release는 위의 두 번째 항목처럼 when:으로 항목을 켜거나 끌 수 있고, 항목이 무엇을 지정할지 결정할 수도 있습니다.

무엇을 제외할지는 작성자가 책임집니다. 빌드의 어떤 부분도 문서의 용도를 알지 못합니다. 차트의 나머지 부분이 런타임에 의존하는 문서(Deployment가 마운트하는 Secret, pod가 실행되는 ServiceAccount)를 제외하면, 함께 적용되는 다른 무언가가 그 문서를 제공하지 않는 한, 빌드는 문제없이 되지만 적용할 때 실패하는 출력이 만들어집니다. compose 파일과 CloudFormation 템플릿은 각자 자신의 참조를 명시하므로 빌드가 검사합니다. 남은 것 중 제외된 단위를 여전히 참조하는 것(제외된 서비스를 참조하는 서비스, 제외된 리소스를 참조하는 리소스나 출력)이 있으면 아래 표에 설명된 대로 빌드가 중단됩니다.

이 키를 지원하는 providers. 문서를 제외하는 것은 provider만 할 수 있습니다. 소스가 무엇을 렌더링하는지는 provider만 알기 때문입니다. 따라서 provider가 이 키를 지원하는지는 provider 자체 선언의 일부입니다. provider가 지원하지 않는데 omits:를 선언한 Recipe는 항목의 when:이 무엇으로 렌더링되든 렌더링 전에 거부됩니다. The provider does not support omits (provider가 omits를 지원하지 않습니다)를 참조하십시오.

Provideromits:
helm지원됩니다. 항목은 차트가 템플릿 또는 crds/ 디렉터리에서 렌더링하는 문서를 문서 자체의 kind, metadata.name, 그리고 항목이 지정한 경우 문서가 속한 네임스페이스로 지정합니다. helm → Sourced mode를 참조하십시오.
compose지원됩니다. 항목은 소스 compose 파일의 service, volume 또는 config를 services:, volumes: 또는 configs: 아래의 키로 지정하며, valuesMapping:이 파일에 병합된 뒤에 매칭되고, 네임스페이스는 지정하지 않습니다. 다른 kind나 네임스페이스를 지정하는 항목은 component가 렌더링될 때 빌드를 중단시킵니다. 남은 것이 depends_on, links, volumes_from, service: 네트워크 또는 네임스페이스 모드, extends, 빌드 컨텍스트, volumes: 또는 configs: 항목을 통해 제외된 단위를 여전히 참조하는 파일은 각 참조를 명시하며 빌드를 중단시킵니다. compose → Sourced mode를 참조하십시오.
cloudformation지원됩니다. 항목은 소스 템플릿의 리소스를 Type과 논리적 ID로 지정하며, 디렉터리 소스의 경우 모든 템플릿에 적용되고, 네임스페이스는 지정하지 않습니다. 네임스페이스를 가진 항목은 component가 렌더링될 때 빌드를 중단시킵니다. 남은 것이 Ref, Fn::GetAtt, DependsOn 또는 Fn::Sub 변수를 통해 제외된 리소스를 여전히 참조하는 템플릿은 각 참조를 명시하며 빌드를 중단시킵니다. cloudformation → Leaving resources out of a sourced template를 참조하십시오.
helm-chart, terraform거부됩니다. 이 provider는 소스를 배포 시점에 렌더링되도록 넘기므로, 빌드 시점에는 제외할 문서가 존재하지 않습니다. 로컬 차트나 모듈의 경우 대신 Recipe 옆의 .aggregaignore에 한 줄을 추가하여 그 파일을 제외합니다.

같은 키를 FeatureRecipe에도 작성할 수 있습니다. entities/featurerecipe.md를 참조하십시오.

가져온 차트가 생성하는 Secret을 제외하는 예, 항목이 없을 때 같은 차트가 겪는 결정성 중단, 아무것도 매칭하지 않는 항목에 대한 중단을 모두 실제 빌드에서 보여 주는 예제는 ai-gateway-own-webhook-certificate를 참조하십시오.