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

Recipe 입력 구성 — 세 가지 입력 종류, Workload, 아티팩트

Recipe는 대상 provider를 위한 manifest 파일을 생성합니다. 이 장에서는 Recipes가 서로 직교하는 세 가지 입력 종류, 즉 sourced, synthesized, artifacts로부터 출력을 구성하는 방식, 각 입력 종류의 구조, 그리고 어떤 provider가 어떤 출력을 생성하는지를 다룹니다. Recipe 엔터티의 개념적 역할(Developer Intent를 단일 물리적 provider에 매핑하는, Ops가 작성하는 변환 템플릿)은 04-entity-taxonomy.md에서 설명하며, 키워드 수준의 Recipe 작성 인터페이스는 ../language-reference/entities/recipe.md에서 설명합니다.

근거

각 provider의 네이티브 렌더링 도구(Helm, Docker Compose)는 이미 provider 네이티브 매니페스트를 렌더링하는 방법을 알고 있습니다. Recipe의 역할은 그 매니페스트가 무엇을 담아야 하는지를 선언하는 것입니다. 즉 어떤 컨테이너 이미지, 어떤 포트, 어떤 환경 변수, 어떤 볼륨, 어떤 서비스, 어떤 리소스 제한을 담을지입니다.

Recipe는 Deployment와 Service에 매핑되는 고정된 키 집합(예: image, environment, ports, replicas)이 담을 수 있는 것보다 더 많은 것을 표현해야 하며, 그중에는 다음이 있습니다.

  • resources(CPU/메모리 requests/limits)
  • Liveness, readiness 또는 startup 프로브
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • 다중 컨테이너 파드, 사이드카
  • ConfigMap / Secret / PVC / CRD 리소스
  • ClusterIP가 아닌 Service(LoadBalancer, NodePort, Headless)

추상화 계층은 고정된 키 집합이 아니라 전체 워크로드 형태를 기술해야 합니다. 아래에서 설명하는 세 가지 입력 종류가 바로 그 추상화입니다. Recipe는 외부에서 로드한 차트 또는 모듈(source:), provider가 provider 네이티브 매니페스트로 합성하는 추상 Workload 명세(workload:), 그리고 Recipe가 직접 내보내는 템플릿화된 provider 네이티브 매니페스트(artifacts:)로부터 출력을 더하는 방식으로 구성합니다.

세 가지 입력 종류

추가에 의한 구성

Recipe에서 프로바이더 고유 매니페스트 파일을 생성하는 방법은 세 가지이며, 이들은 상호 배제가 아니라 추가 방식으로 구성됩니다:

  1. source: — 프로바이더가 고유 방식으로 렌더링하는 외부에서 로드된 아티팩트(Helm 차트, compose 파일)로, valuesMapping:이 오버레이 값을 제공합니다.
  2. workload: — 프로바이더가 프로바이더 고유 매니페스트로 합성하는 추상 Workload 명세(플랫폼 소유 종류)입니다. 이 필드는 인라인 YAML 블록 스칼라 또는 단일 로컬 파일이나 라이브러리 항목을 가리키는 $import:를 받으며, 디스패치는 내용의 형태에 따라 결정됩니다.
  3. artifacts: — 인라인 또는 $import:로 로드된 프로바이더 고유 매니페스트의 맵으로, 전체 pillar 컨텍스트를 대상으로 Go 템플릿이 적용됩니다. 각 항목은 인라인(항목의 값이 블록 스칼라)으로 작성하거나 단일 파일 또는 라이브러리 콘텐츠를 가리키는 $import:로 작성할 수 있습니다.

세 가지 모두 컴파일러가 경계의 출력 디렉터리로 내보내는 파일을 생성합니다. 세 가지 모두 아래 검증 규칙에 따라 단일 Recipe 안에 공존할 수 있습니다. 병합 의미론은 최상위 수준에만 적용됩니다. 각 입력 종류는 완전한 파일을 생성하고, 파일은 나란히 출력되며, 출력 파일 이름이 충돌하면 치명적 오류입니다.

설명적 모드 이름

세 가지 “모드”는 문서와 진단을 위한 설명적 용어입니다. Recipe 작성자는 모드를 선언하지 않고 필요한 키워드를 작성합니다. Recipe는 주된 입력에 따라 특징지어집니다:

주된 키워드설명적 모드 이름
source: + valuesMapping: (workload: 없음, artifacts 없음)sourced
workload: (source: 없음, artifacts 없음)synthesized
artifacts: (source: 없음, workload: 없음)artifacts-only (비공식적으로: “inline”)
둘 이상의 임의 조합명시적으로 설명함 (예: “sourced with artifacts”, “synthesized with artifacts”)

mode:라는 키워드도, 열거형도 없습니다. 모드는 어떤 입력이 존재하는지에 따라 드러나는 속성입니다.

Recipe 형태 한눈에 보기

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

위의 모든 필드는 Recipe 스키마가 받아들이며, 컴파일러는 세 가지 입력 종류, 즉 sourced 렌더링, Workload 합성, artifacts 출력을 모두 처리합니다. 차이는 프로바이더별 지원, 즉 어떤 프로바이더가 어떤 입력 종류를 렌더링하는지에 있으며, 이는 이 장 끝의 Provider Capability Matrix에 정리되어 있습니다.

로드 시점 검증 규칙

Recipe 스키마와 로드 검증은 다음 구성 규칙을 적용합니다:

  1. valuesMapping:에는 source:가 필요합니다. 오버레이할 source:가 없으면 매핑된 값을 받을 대상이 없습니다. valuesMapping:은 있고 source:가 없는 Recipe는 로드 시점 오류입니다. (valuesMapping: 없는 source:는 허용되며, 이 경우 차트나 모듈은 자체 기본값으로 렌더링됩니다.)
  2. workload:는 하나의 소스만 받습니다 — 인라인 또는 $import: 중 하나이며, 둘 다는 아닙니다. Recipe는 Workload를 인라인 블록 스칼라 또는 단일 파일을 가리키는 $import:로 지정합니다. 통합 파일 가져오기 용어에 따라 $import: 형식은 단일 소스이며, workload:에서는 다중 소스 병합이 지원되지 않습니다. 잘못된 형식의 디스패치는 로드 시점 오류입니다.
  3. workload:에는 합성이 가능한 프로바이더가 필요합니다. 합성 지원은 선언된 필드가 아니라 프로바이더 자체의 속성입니다. 합성할 수 없는 프로바이더에 바인딩된 workload: Recipe는 노드가 렌더링될 때 프로바이더 기능 게이트(Provider Capability Matrix 참조)를 통해 명확한 진단과 함께 거부됩니다. 표준 라이브러리 카탈로그는 문서화된 변환 계약으로서 관례에 따라 합성이 가능한 프로바이더에 workloadSchema를 선언하지만, 게이트는 해당 필드의 존재 여부가 아니라 프로바이더가 직접 보고한 기능을 기준으로 합니다.
  4. 적어도 하나의 입력 종류가 있어야 합니다. source:+valuesMapping:, workload:, artifacts: 중 어느 것도 없는 Recipe는 출력을 생성하지 않으며 로드 시점 오류입니다.
  5. 인라인 아티팩트 항목과 $import: 아티팩트 항목은 공존할 수 있습니다. Recipe는 일부 artifacts: 항목은 인라인으로, 나머지는 항목별 $import: 지시문으로 선언할 수 있습니다. 각 항목의 키가 자체 출력의 이름을 정하므로 두 형식의 항목은 서로 충돌하지 않습니다(각 출력 파일의 이름을 정하는 것 참조).
  6. 입력 종류 간 파일 이름 충돌은 렌더링 시점 오류입니다. Recipe의 입력 종류 중 두 가지(소스 렌더링 출력, 워크로드 합성 출력, 아티팩트 출력)가 같은 이름의 파일을 생성하면, 컴파일러는 모든 기여 요소를 식별하는 치명적 오류를 내보냅니다. 이 검사는 Workload 변환 후에 실행되므로 로드 시점이 아니라 렌더링 시점에 이루어집니다.

Workload 종류

소유권과 위치

Workload는 apiVersion: aggrega.ai/v1beta1에 속하는 플랫폼 소유 종류입니다. 그 JSON Schema 2020-12 선언은 빌드 시점에 컴파일러 바이너리에 내장됩니다. 카탈로그 작성자는 Workload 스키마를 편집하지 않으며, 독립된 Workload YAML 파일을 카탈로그 엔터티로 작성하지도 않습니다. Workload 문법은 Recipe 또는 FeatureRecipe의 workload: 필드(인라인, 또는 단일 파일이나 WorkloadLibrary 항목에 대한 $import:) 안에서만 사용되며 그 밖의 곳에서는 사용되지 않습니다.

Workload는 플랫폼 종류이자 컴파일러 개념이며, 엔터티 분류 체계의 별도 엔터티가 아닙니다. Recipe가 작성 엔터티이고, Workload는 Recipe의 합성 입력이 취하는 형태입니다.

Recipe당 하나의 Workload

Recipe는 최대 하나의 workload:를 선언합니다. Workload는 이 Recipe가 구현하는 Component와 연결된 단일 컴퓨팅 단위를 나타냅니다. FeatureRecipe도 마찬가지로 자체 workload:를 최대 하나 선언합니다. 이는 같은 Workload 종류를 통해 합성되는 Feature 소유의 컴퓨팅 단위입니다. FeatureRecipe를 참조하십시오. 추가 부속 워크로드가 필요한 사용 사례는 다음을 통해 표현합니다.

  • artifacts: — 같은 Recipe 안에서 워크로드와 함께 두는 추가 매니페스트(인라인 또는 항목별 $import:).
  • 리소스 생성을 갖춘 Features — 별도 카탈로그 엔터티로 선언되는 횡단 관심사 부속 워크로드(예: 데이터베이스에 부착되는 백업 사이드카)로, FeatureRecipe가 자체 workload:를 합성합니다(또는 source: / artifacts:를 통해 렌더링합니다). FeatureRecipe 리소스 생성은 14-extensibility.md를 참조하십시오.

이로써 작성자당 하나의 컴퓨팅 단위라는 모델이 유지됩니다. Recipe는 Component의 워크로드를 합성하고, FeatureRecipe는 자체 워크로드를 합성합니다.

전체 표면

Workload의 필드 집합은 크고 계속 늘어납니다. 여기에 다시 적으면 사본이 계약보다 뒤처져도 이를 알려 주는 것이 없으므로, 이 장에서는 전체를 담고 있는 두 곳을 안내합니다.

  • 생성된 Workload 스키마 레퍼런스 — 모든 필드와 그 타입, 기본값, 제약 조건을 게시된 JSON Schema에서 생성하고 빌드할 때마다 이와 비교하므로, 컴파일러가 받아들이지 않는 형태를 기술할 수 없습니다.
  • Workload 작성 페이지 — 필드 수준의 작성 안내: 각 필드의 의미, 각 provider가 이를 무엇으로 렌더링하는지, 빌드가 거부하는 조합.

Workload JSON Schema 2020-12 선언이 권위 있는 기준이며 컴파일러 바이너리에 내장되어 제공됩니다. helm 및 compose 프로바이더는 인라인이든 $import:로 로드한 것이든 Recipe의 workload:를 합성합니다. provider별 지원은 Provider Capability Matrix를 참조하십시오.

featuresSchema와의 시크릿 통합

Workload의 containers.<name>.attachments 블록은 Component의 featuresSchema가 선언한 슬롯을 참조할 뿐, 새 슬롯을 선언하지 않습니다. featuresSchema 작성 표면은 ../language-reference/entities/component.md를 참조하십시오.

검증 계약:

  • 모든 attachments.<KEY>.from 값은 Component의 featuresSchema에 선언된 슬롯 이름과 일치해야 합니다. 또는 connection: <alias>로 연결을 지정하는 항목의 경우, 그 연결의 소켓이 usesSchema.<socket>.featuresSchema에 선언한 슬롯과 일치해야 합니다. 이러한 항목은 아래 규칙이 실행되기 전에 해당 연결의 attachment가 component에서 갖는 이름(<alias>.<slot>)으로 다시 작성되므로, 아래의 모든 규칙은 이를 Component 자신의 슬롯을 지정하는 항목과 똑같이 읽습니다.
  • as: 전달 방식(env 또는 file)은 해당 슬롯의 inject: 배열에 허용 목록으로 등록되어 있어야 합니다.
  • Component의 featuresSchema에서 inject: [](블랙박스)로 표시된 슬롯은 Workload attachments: 블록에 나타날 수 없습니다. 이러한 슬롯은 Workload 노출이 아니라 Recipe의 내부 배선(예: Helm existingSecret)을 통해 전달됩니다.

예:

# In the Component
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

헬스 프로브: 메커니즘이 아닌 의도

Kubernetes 프로브와 Docker Compose 헬스체크는 형태가 다릅니다. 하나의 추상적인 의도 형태가 양쪽 모두로 깔끔하게 변환됩니다.

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Providers는 각 의도를 자신의 네이티브 형태로 변환합니다.

의도Helm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

명시적 포트가 없는 http:의 포트는 두 대상 모두에서 컨테이너가 containers.<name>.ports 아래에 선언한 포트 이름 중 알파벳순으로 첫 번째 것으로 결정됩니다. 이름 있는 포트를 선언하지 않은 컨테이너는 HTTP 프로브를 가질 수 없으며, 빌드는 해당 프로브를 지목하며 중단됩니다.

Compose는 HTTP/TCP 프로브를 healthcheck 셸 명령으로 격하하며, compose 서비스는 healthcheck를 하나만 가집니다. 프로브가 둘 이상 선언된 경우 하나만 변환되고, 경고가 제외된 프로브를 알려 줍니다.

볼륨 타입

다섯 가지 볼륨 타입이 있으며, 복합 타입은 없습니다.

타입의미K8s (helm)Compose
ephemeralTmpfs / emptyDir; pod와 함께 소멸emptyDir: { sizeLimit }tmpfs: 마운트, 크기를 갖지 않음(작성된 sizeLimit은 경고로 보고됨)
configmap읽기 전용 구성 파일ConfigMap 볼륨 참조Recipe의 artifacts:가 선언한 최상위 config에 대한 서비스 수준 configs: 참조
secret읽기 전용 시크릿 파일Secret 볼륨 참조읽기 전용으로 바인드 마운트된 시크릿 파일
persistent단일 PVC; pod 재시작 후에도 유지PVC 리소스 + volume.persistentVolumeClaim이름 있는 볼륨
persistentTemplate레플리카별 PVC; form: stateful과 함께 사용StatefulSet.volumeClaimTemplates이름 있는 볼륨(격하됨; 경고 발생)

Compose는 레플리카별 템플릿을 표현할 수 없습니다. persistentTemplate이 compose로 변환되면 모든 레플리카가 공유하는 단일 이름 있는 볼륨으로 격하되며, 경고가 그 격하를 보고합니다. persistentTemplate 볼륨에는 form: stateful이 필요하며, 다른 form에 선언하면 빌드가 중단됩니다.

다중 서비스 노출

각 서비스는 독립적인 노출입니다. 일반적인 패턴: 포트 8080의 HTTP 서비스(ClusterIP 내부) + 포트 9090의 메트릭 서비스(ClusterIP) + 포트 9901의 관리 엔드포인트(LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

helm provider로 렌더링하면 각각 별도의 Kubernetes Service 객체가 되며, Loopback 항목이 있으면 helm provider는 대신 중단됩니다. compose에서는 NodePort 및 LoadBalancer 서비스가 compose 서비스의 모든 호스트 인터페이스에 포트를 게시하고, Loopback 서비스는 호스트의 루프백 주소에만 게시하며, ClusterIP 및 Headless 서비스는 아무것도 게시하지 않습니다.

K8s 출력의 서비스 이름에는 고유성을 위해 component의 instance_id가 접두사로 붙습니다. 포트 이름은 containers.<name>.ports에 선언된 컨테이너 포트 이름과 일치해야 합니다.

Provider 측 변환 계약: workloadSchema

provider 렌더링 Plugin(pluginType: provider)은 spec.provider.workloadSchema를 선언합니다. 이는 Workload 필드가 해당 provider의 네이티브 출력으로 어떻게 변환되는지 문서화하는 JSON Schema 2020-12 선언입니다. 이것이 자기 문서화 변환 계약입니다. spec.provider 블록을 포함한 Plugin 작성 표면은 ../language-reference/entities/plugin.md를 참조하십시오.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

workloadSchema 필드는 카탈로그 작성자와 IDE 도구에 변환 의도를 전달합니다. 이는 문서화된 변환 계약으로, 합성하는 providers에 관례에 따라 선언되지만, 합성 지원 여부는 이 필드의 존재가 아니라 provider 자체가 결정합니다. 합성할 수 없는 provider를 대상으로 workload:를 사용하는 Recipe는 provider가 workloadSchema를 선언하는지와 관계없이, 노드가 렌더링될 때 provider 기능 게이트를 통해 명확한 오류와 함께 거부됩니다.

Plugin 스키마는 spec.provider.workloadSchema를 선언하며(그 본문은 Plugin이 로드될 때 JSON Schema 2020-12로 컴파일됩니다), Recipe 측 workload: 사용도 제공됩니다. 합성 지원은 렌더링 시점에 바인딩된 provider가 보고한 기능을 기준으로 provider 기능 게이트가 적용합니다. workloadSchema는 표준 라이브러리 카탈로그가 그 기능과 동기화해 유지하는 문서화된 계약이며, 그 자체가 게이트 입력은 아닙니다. 또한 카탈로그 전체에 대해 실행되는 aggrega validate는, 카탈로그에 해당 provider의 Plugin 엔터티가 있는 경우, 합성하지 않는 provider에 바인딩된 workload: Recipe를 빌드 전에 미리 드러냅니다.

보조 리소스는 Workload 외부에 위치합니다

Workload 사양에는 additionalResources 필드도, extras도, 인라인 ConfigMap/Secret/CRD 선언도 없습니다. Workload는 워크로드의 형태만 모델링합니다. 컨테이너, 볼륨, 서비스, 레플리카, 스케줄링, 보안 컨텍스트, 서비스 계정 등 단일 컴퓨팅 단위가 실행되는 방식을 기술하는 모든 것이 여기에 해당합니다.

보조 리소스는 Workload 외부에 두 가지 정당한 위치를 가집니다.

  1. Features + FeatureRecipes — 횡단 관심사를 위한 메커니즘입니다. “메트릭을 노출하는 모든 서버”에 부착되는 ServiceMonitor는 Feature로서의 core/prometheus-exporter입니다. 서버를 호스트 이름으로 게시하는 라우팅 리소스도 Feature이며, 어느 것을 쓸지는 라우팅 형태가 결정합니다. 대상이 Ingress를 조정하는 경우에는 core/public-ingress, Gateway API를 실행하는 경우에는 core/http-route이며, 각각은 Manifest가 Release별로 선택하는 FeatureRecipe에 의해 구현됩니다. 모든 프로덕션 워크로드에 적용되는 NetworkPolicy는 프로덕션 Release가 경계 전체에 부착하는 Feature입니다. Features는 서로 독립적으로 조합되며 여러 Recipes에서 재사용할 수 있습니다. FeatureRecipe Resource Generation에 대해서는 14-extensibility.md를 참조하십시오.
  2. Recipe 수준 artifacts: — 이 특정 Recipe의 구현에 속하며 Feature를 만들 가치가 없는 리소스를 위한 것입니다. Recipe에 필요한 일회성 CRD 등록, 이 Recipe를 사용할 때만 적용되는 Recipe 전용 PodDisruptionBudget, Recipe의 Workload가 참조하는 ConfigMap 등이 그 예입니다. 각 항목은 인라인이거나 $import:로 로드됩니다. 아래의 Artifacts 메커니즘 섹션을 참조하십시오.

Feature와 아티팩트 사이의 경계는 사회적 관례입니다. 보조 리소스가 횡단적이라면(여러 Recipes에 적용되거나 셀렉터를 통해 조건부로 부착된다면) Feature입니다. 이 하나의 Recipe에 본질적이라면(Recipe가 그 리소스를 내보내지 않고서는 제 역할을 할 수 없다면) 아티팩트입니다. 작성자는 재사용과 부착 의미론을 기준으로 선택하며, 컴파일러는 그 선택을 감시하지 않습니다.

Features와 Recipe 아티팩트를 함께 사용하면 Recipe에 필요한 보조 리소스를 다룰 수 있습니다.

Artifacts 메커니즘

인라인 아티팩트와 파일에서 로드한 아티팩트

artifacts 입력 종류는 템플릿화된 프로바이더 네이티브 매니페스트 파일을 소스 렌더링 출력이나 워크로드 합성 출력과 함께 경계 출력으로 직접 내보냅니다. 작성자는 두 가지 방식으로 이를 선언합니다.

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

$import: 경로는 Recipe 디렉터리를 기준으로 하며 그 안에 있어야 합니다. Recipe의 게시본이 담는 모든 파일은 해당 디렉터리에서 가져오고(임포트가 지정하는 각 파일도 함께 이동합니다), 디렉터리 밖의 파일은 함께 이동하지 않기 때문입니다. 일반적인 관례는 이러한 파일을 ./artifacts/ 하위 디렉터리에 두는 것이지만, 컴파일러가 이를 강제하지는 않습니다. 맵 키는 내보내는 각 파일의 이름을 지정하며, 세 가지 형식 각각에서 이것이 무엇을 의미하는지는 다음 절에서 다룹니다.

각 항목(인라인 또는 $import:로 로드한 항목)은 출력 디렉터리로 내보내기 전에 전체 템플릿 컨텍스트를 대상으로 Go 템플릿 처리됩니다.

각 출력 파일의 이름을 정하는 것

맵은 항목 이름을 키로 하며, 모든 작성 형식에서 키가 해당 항목이 내보내는 것의 이름을 정합니다. 인라인 항목의 경우 키는 출력 파일 이름이며 작성된 그대로 사용됩니다.

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

configmap-config.yaml과 pdb.yaml을 생성합니다. 키는 파일 이름을 정하고, 파일이 놓이는 위치는 대상이 결정합니다. 이에 대해서는 아래의 프로바이더별 출력 절에서 다룹니다.

파일 $import: 항목의 경우에도 키가 출력 파일 이름입니다. 임포트된 파일은 내용을 제공하지만 이름은 제공하지 않으므로, 특정 출력 파일 이름을 원하는 작성자는 그 이름을 키로 씁니다.

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

.../monitor.yaml과 .../netpol.yaml을 생성합니다. 두 번째 항목이 임포트하는 파일의 이름은 some-other-name.yaml이지만, 그 이름은 출력에 반영되지 않고 키가 반영됩니다. 따라서 ./extras/shared.yaml과 ./overrides/shared.yaml처럼 우연히 이름이 같은 서로 다른 파일을 임포트하는 두 항목은 각자의 키로 이름이 정해지는 서로 다른 두 출력이 됩니다.

여러 파일의 번들을 하나의 단위로 가져오는 라이브러리 $import: 항목의 경우, 항목은 번들의 파일마다 하나의 출력으로 확장되며 각 출력은 <key>/<filename> 형태로 키 아래에 중첩됩니다. 하나의 키가 여러 파일을 가리키므로 키만으로는 각 파일의 이름을 정할 수 없습니다. 이때 키는 그중 어느 한 파일의 이름이 아니라 번들의 파일들이 놓이는 디렉터리입니다.

모든 형식이 키로부터 출력 이름을 정하므로, 키는 작성 단계에서 단일 파일 이름이 될 수 있는 형태로 제한됩니다. 즉 첫 글자는 문자 또는 숫자이고, 그 뒤에는 문자, 숫자, 점, 하이픈, 밑줄이 옵니다. 점은 소비자가 기대하는 확장자를 담으며, 이 덕분에 키를 곧바로 파일 이름으로 쓸 수 있습니다. 또한 이 문자 집합에는 /와 선행 .가 없으므로 하나의 키는 둘 이상의 경로 세그먼트를 나타낼 수 없고 상위 디렉터리 세그먼트가 될 수도 없습니다. 이 문자 집합을 벗어난 키는 워크스페이스 로드 시, aggrega validate 실행 시, 그리고 편집기 진단에서 엔벨로프 검증에 실패합니다.

같은 파일 이름을 가진 두 artifacts: 출력은 어떤 형식에서 생성되었든 노드를 렌더링할 때 빌드를 중단시킵니다. 하나의 artifacts: 맵에 있는 두 항목이 같은 출력 이름을 갖는 경우는 없습니다. 키는 한 문서 안에서 고유하고 단일 파일 이름이므로, 단일 파일 항목의 출력 이름은 그 키이고 번들 항목의 출력은 모두 그 키로 이름이 정해진 디렉터리 아래에 놓이기 때문입니다. 따라서 내보내는 모든 경로의 첫 세그먼트는 그 경로를 생성한 키이며, 서로 다른 키는 서로 다른 출력 이름으로 유지됩니다. 이 중단이 다루는 것은 입력 종류를 넘나드는 경우, 즉 두 입력 종류가 하나의 파일 이름을 제공하는 경우(예: 차트 템플릿과 아티팩트 항목이 모두 servicemonitor.yaml을 생성하는 경우)이며, 진단은 기여한 모든 출처를 명시합니다.

Artifacts의 템플릿 컨텍스트

아티팩트 템플릿은 전체 필러 컨텍스트에 접근할 수 있습니다.

  • .values, .infra, .context.*, .locals, .provides, .features, .metadata — 06-data-taxonomy-and-composition.md에 설명된 표준 Aggrega 필러입니다.
  • .workload — 이 Recipe의 파싱된 Workload 명세입니다(있는 경우). 아티팩트가 중복 없이 Workload 값을 참조할 수 있게 합니다. 예를 들어 ServiceMonitor가 .workload.services.metrics.ports.prom을 참조할 수 있습니다.
  • .source — 확인된 source: 필드 내용입니다(있는 경우).

Artifacts는 Workload가 파싱된 후에 평가되므로, .workload가 있으면 사용할 수 있습니다. workload:가 없는 Recipes에서는 .workload가 nil이며, 이를 역참조하려는 템플릿은 명확한 오류와 함께 실패합니다. source:가 없는 Recipes에서는 .source가 nil이며 실패 방식도 같습니다.

자기 완결성 불변 조건

Artifacts는 자기 완결적이어야 합니다. Artifacts는 Recipe가 선언한 입력, 즉 필러 컨텍스트, Recipe 자체의 Workload(있는 경우), Recipe 자체의 source: 값만 참조할 수 있습니다. 다음은 참조할 수 없습니다.

  • 같은 경계에 있는 다른 Recipes의 출력.
  • Recipe가 선언하지 않은 주변 Kubernetes 리소스.
  • 외부에 존재한다고 가정하는 Secret, ConfigMap 또는 기타 리소스(선언된 필러를 통해 참조하는 경우는 제외).

Workload의 volumes.*.configmap.source가 참조하는 ConfigMap 아티팩트는 이 Recipe가(해당 ConfigMap을 생성하는 artifacts:를 통해) 내보내거나 이 노드에 연결된 Feature가 내보내야 합니다. 경계 안에서 Recipe 간 의존성은 지원되지 않습니다.

이 불변 조건은 Recipe의 재사용성을 보장합니다. Recipe는 숨겨진 의존성 없이, 필러 계약을 충족하는 어떤 Aggregate + Release 조합에도 넣을 수 있습니다.

출처 레이블

변환 후에는 내보내는 모든 파일이 메타데이터에 aggrega.ai/* 출처 정보를 담습니다. 소스에서 렌더링된 것이든, 워크로드에서 합성된 것이든, 아티팩트 템플릿에서 내보낸 것이든 마찬가지입니다. 출력을 내보내는 모든 지점이 하나의 공유 빌더 집합으로 출처를 기록하므로, 같은 파일은 어떤 입력 종류가 생성했든 항상 같은 출처를 담습니다. 이 집합은 값이 Kubernetes 레이블 값 문자 집합을 충족하는지에 따라 나뉩니다. 레이블에 안전한 키는 레이블(조회 가능)이 되고, 문자 집합에 맞지 않는 키인 recipe-uri(: 포함), boundary-path(중첩 경로는 / 포함), sync-wave(음수 웨이브의 선행 -)는 값에 제약이 없는 어노테이션이 됩니다. 빌드가 레이블 규칙에 맞추도록 요구하지 않는 식별 값(애그리거트 이름, 환경, 프로바이더 이름, 컴파일러 및 프로바이더 버전)은 레이블이 허용하는 형식으로 작성된 레이블이 되며, 그 형식이 값과 다르면 원래 값 그대로가 같은 키 아래의 어노테이션도 됩니다(이름이 imported/flow인 Aggregate는 레이블 imported-flow와 어노테이션 imported/flow를 받습니다). 같은 Recipe의 출력을 담는 모든 파일은 같은 출처를 공유합니다.

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

이 분할은 세 가지 입력 종류 모두에 동일하게 적용됩니다. (Compose provider에는 어노테이션 개념이 없고 레이블 값에 제약이 없으므로, 전체 집합을 서비스 레이블로 내보냅니다.) 컴파일 시점 출처 기록에 대해서는 11-governance-and-compliance.md를 참조하십시오.

provider는 자신의 출력 형식이 출처를 담는 위치에 출처를 기록하므로, 형식상 특정 파일에 그런 위치가 없는 provider는 해당 파일을 변경하지 않고 내보내며 그 사실을 알립니다. 알아 두어야 할 경우는 Compose입니다. Compose의 출처 위치는 서비스의 labels: 블록이므로, 최상위 volumes:, configs: 또는 models:만 기여하는 compose 아티팩트 조각은 출처를 담지 않으며, 빌드는 해당 아티팩트를 명시하는 “skipped provenance label injection”(출처 레이블 주입 건너뜀) 경고를 내보냅니다. 이 경고는 그런 형태의 조각에서는 예상되는 것이며 문제의 징후가 아닙니다. 같은 component가 내보내는 서비스는 전체 집합을 담고, 내보내는 바이트는 전혀 바뀌지 않습니다. 이것이 배제하는 것은 세 번째 가능성, 즉 파일이 명시되지 않은 채 기록 없이 빌드를 빠져나가는 경우입니다.

알아 두어야 할 또 다른 경우는 CloudFormation이며, 출처가 기록되는지 여부가 아니라 어디에 기록되는지가 다릅니다. CloudFormation 템플릿에는 리소스와 함께 이동하는 문서 수준 메타데이터 블록이 없으므로, 출처는 각 리소스 자체의 Metadata 속성에 전체 집합을 담은 하나의 aggrega.ai/provenance 키 아래 기록됩니다.

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

이 위치에서 세 가지 속성이 따라 나옵니다. Metadata 속성은 유형과 관계없이 모든 리소스에서 사용할 수 있으므로, 조립된 스택이 담는 모든 리소스에 기록이 남습니다. 태그를 전혀 받지 않는 많은 리소스 유형도 포함되며, 태그 기반 기록이었다면 이들에는 기록할 자리가 없었을 것입니다. 기록은 작성자가 쓴 Metadata를 대체하지 않고 추가되므로, 작성자 자신의 항목이 그대로 함께 남습니다. 그리고 템플릿 단위가 아니라 리소스 단위이므로, 여러 component가 조립되는 스택은 각 리소스에 기여한 고유 정체성, 즉 해당 component, Recipe, 경계를 담습니다. 이는 템플릿 전체에 걸친 단일 항목으로는 표현할 수 없습니다.

전체 집합은 그 키 아래 함께 이동합니다. Metadata 값은 제약이 없는 JSON이므로 문자 집합 분할이 필요 없습니다. Kubernetes 런타임만 읽는 두 키, 즉 표준 권장 레이블 이름과 GitOps 컨트롤러가 사용하는 배포 순서 어노테이션은 둘 다 스택 안의 어떤 것도 가리키지 않으므로 제외됩니다. 일반 aggrega.ai/sync-wave 출처 항목은 컨트롤러에 지시하는 것이 아니라 component가 선언한 웨이브를 기록하는 것이므로 유지됩니다.

여기서 위치가 없는 형태는 리소스를 선언하지 않는 템플릿이나 조각, 즉 Parameters, Mappings, Conditions 또는 Rules만 기여하는 경우입니다. 이는 출처를 담지 않고, 자체 내용을 그대로 유지한 채 조립된 스택에 도달하며, 빌드는 이를 명시하는 “skipped provenance injection”(출처 주입 건너뜀) 경고를 내보냅니다. compose와 마찬가지로 이 경고는 그런 형태의 기여에서는 예상되는 것입니다. 같은 component가 다른 곳에서 기여하는 리소스는 전체 집합을 담고, 내보내는 바이트는 무엇이 이를 수신하는지와 관계없이 동일합니다.

Provider별 아티팩트 의미 체계

아래의 provider별 의미 체계는 각 provider가 아티팩트를 자신의 네이티브 출력에 통합하는 방식을 설명합니다.

helm provider: 아티팩트는 Kubernetes YAML 문서이며, 차트에서 렌더링되고 Workload에서 합성된 매니페스트를 담는 출력 디렉터리 안에서, 아티팩트를 선언한 컴포넌트의 이름을 딴 디렉터리 아래에 기록됩니다. 이유는 이름 지정에 있습니다. 렌더링되거나 합성된 매니페스트는 provider가 그것이 속한 컴포넌트를 기준으로 이름을 붙이지만, 아티팩트는 작성자가 쓴 키로 이름이 정해지며 이 키는 어느 컴포넌트인지에 대해 아무것도 말해 주지 않습니다. 따라서 하나의 Recipe에 바인딩된 두 컴포넌트가 하나의 경로에 기록하게 되고, 어느 작성자도 이를 분리할 수 없습니다. 디렉터리는 컴포넌트 자신의 이름이므로, 작성자가 출력에서 다시 읽는 파일은 한 단계 아래에 있는, 작성자가 쓴 바로 그 이름입니다.

다른 레이아웃을 원하는 운영자는 경계의 subDirectory: 템플릿을 사용할 수 있으며, 이 템플릿은 아티팩트만이 아니라 기여자가 내보내는 모든 파일을 이동합니다. ../language-reference/path-template-variables.md를 참조하십시오.

compose provider: 아티팩트는 compose 조각입니다. 최상위 키(services:, volumes:, configs:, models:)는 경계 구성 단계에서 경계별로 결합된 docker-compose.yaml에 병합됩니다.

helm-chart provider(특수한 경우): 아티팩트는 독립 파일로 출력 디렉터리에 기록되지 않습니다. 렌더링 파이프라인은 Helm이 소유하기 때문입니다. 대신 helm-chart provider는 각 artifacts: 항목을 차트 자체 안에 배치하며, 항목이 작성된 형태에 따라 배치 위치가 결정됩니다. 모든 항목은 배치에 앞서 먼저 Aggrega의 필러 컨텍스트로 Go 템플릿 처리되며, 그 이후 두 형태가 갈라집니다. $import:로 로드된 항목은 Helm 이전 템플릿 파일입니다. 이 파일은 Helm 렌더링 전에 차트의 templates/ 디렉터리에 주입되므로, Helm은 이를 소스 차트 자체의 템플릿과 함께 렌더링합니다. 인라인 블록 스칼라는 느슨한 차트 파일입니다. 이 파일은 작성된 키로 차트 루트에 배치되며 templates/ 접두사도, 병합된 출처 레이블도 갖지 않으므로, 차트 자체의 템플릿이 Helm의 .Files.Get / .Files.Glob을 통해 읽을 수 있습니다. 이것이 파일 기반 ConfigMap 패턴입니다. 이를 통해 helm-chart provider는 Helm의 차트 모델을 존중하면서, 일반 helm provider에 artifacts:가 제공하는 것과 동등한 확장 메커니즘을 갖게 됩니다.

주입된 파일은 boundaries/<bp>/charts/<nodeID>/templates/<authored-key>에 위치하며(번들의 파일은 해당 키 아래에 중첩됨), 따라서 소스 차트의 템플릿과 나란히 놓이고 Helm이 후속 렌더링 단계에서 이를 가져갑니다. 인라인 블록 스칼라는 boundaries/<bp>/charts/<nodeID>/<authored-key>, 즉 templates/보다 한 단계 위인 차트 루트에 위치합니다. .Files를 통해 읽는 파일은 차트가 찾는 위치에 있어야 하며, templates/ 아래에 배치된 파일은 대신 매니페스트로 렌더링되기 때문입니다. 두 형태 모두 작성된 키로 이름이 정해지며, 둘의 차이는 provider가 배치하는 디렉터리입니다.

helm-chart 구분자 관례. helm-chart 아티팩트 항목($import:로 로드된 항목과 인라인 항목 모두)에 대한 Aggrega의 사전 템플릿 단계는 기본 {{ }} 대신 [[ ]] 구분자를 사용하므로, 파일 안의 Helm 자체 {{ ... }} 구문은 손대지 않은 채 Helm의 렌더링 단계까지 유지됩니다. 작성자는 Aggrega 측 치환을 [[ .context.instance_id ]], [[ .values.name ]] 등으로 작성하고, Helm 측 치환은 {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }} 등으로 그대로 둡니다. 한 파일에서 두 구분자 쌍을 섞어 쓰는 것이 지원되는 작성 형태입니다.

출처와 helm-chart 아티팩트. 출처는 Helm 토큰이 보존된 채 YAML 왕복 변환을 거치는 $import: 로드 파일, 즉 [[ ]] Aggrega 컨텍스트만 사용하거나 Helm {{ }}를 따옴표로 묶인 스칼라 위치에서만 사용하는 파일에 대해 metadata.labels 및 metadata.annotations에 병합됩니다(위의 문자 집합 분할에 따름). 구조적 Helm 템플릿 액션(스칼라 리프가 아닌 YAML 구조를 내보내는 위치의 {{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }})이 있는 파일이나, 값 위치에 따옴표 없는 {{ ... }}가 있는 파일은 Aggrega의 YAML 왕복 변환을 통과하지 못합니다. 이 경우 빌드는 해당 아티팩트를 지명하는 “skipped provenance label injection”(출처 레이블 주입 건너뜀) 경고를 내보내고 파일을 변경 없이 통과시킵니다. 이 경고는 구조적 Helm 템플릿 액션이나 따옴표 없는 Helm 값 치환을 사용하는 모든 helm-chart $import: 로드 아티팩트 파일에서 예상되는 것입니다. 이는 실제 운영 Helm 작성에서 흔한 경우이며 예외적인 경우가 아닙니다. 이러한 파일에 출처 레이블이 필요한 작성자는 Aggrega의 사전 템플릿 주입이 아니라 차트 자체의 _helpers.tpl에 직접 작성하는 이름 있는 템플릿(예: aggrega.commonLabels라는 템플릿) 또는 이에 상응하는 Helm 측 메커니즘을 통해 레이블을 주입합니다.

차트 루트 파일 이름 충돌. 작성된 키가 차트 루트 파일 이름(Chart.yaml, values.yaml, .helmignore 등)과 충돌하는 $import: 로드 아티팩트는 Aggrega의 파일 이름 충돌 검사에서 감지되지 않습니다. 아티팩트는 templates/<authored-key>에 위치하고 차트 루트 파일은 차트 루트에 위치하며, 경로 접두사로 인해 Aggrega의 관점에서는 서로 구별되기 때문입니다. 작성자는 이러한 키 이름을 피합니다. 이를 사용하면 Helm이 두 파일(차트 루트에 하나, templates/ 안에 하나)을 모두 보게 되어 templates 쪽 사본을 예기치 않게 렌더링할 수 있습니다.

terraform provider: 아티팩트는 Terraform 구성 파일이며, 경계의 modules/ 트리 아래에 있는 컴포넌트 자체 디렉터리에 그대로 내보내집니다. HCL(main.tf)이 사용하기 편한 기본값이며 Terraform JSON(.tf.json)도 동등하게 허용됩니다. 둘 다 트랜스파일되거나 다시 포맷되지 않습니다. 경계의 루트 구성은 해당 컴포넌트를 source가 그 디렉터리를 가리키는 module 블록으로 선언하므로, 경계 전체가 하나의 의존성 그래프로 유지됩니다. 이는 벤더링된 모듈의 파일이 차지하는 디렉터리와 같으므로, source:와 artifacts:를 모두 선언하는 Recipe는 이들을 나란히 기록합니다. 출처는 앞부분의 Terraform 주석 블록으로 전달됩니다. 컴포넌트가 주석 구문이 없는 JSON 본문을 기여하는 경우, 모든 본문은 변경 없이 내보내지고 출처는 그 옆의 주석만 있는 동반 .tf 파일로 전달되므로, 스탬프가 두 곳에 중복되는 일은 없습니다. terraform provider 페이지를 참조하십시오.

cloudformation provider: 아티팩트는 스택 조각, 즉 전체 템플릿이 아니라 하나의 컴포넌트가 기여하는 리소스입니다. provider는 각 조각을 순수 JSON 장형 내장 함수로 정규화하고 해당 출력 디렉터리용으로 조립되는 단일 스택에 병합합니다. 이 스택에서 리소스는 하나의 Resources 맵에 합쳐지고, 컴포넌트의 provides는 게시하는 컴포넌트로 범위가 지정된 이름으로 스택 Outputs에 나타납니다. 조각의 다른 최상위 섹션 중 어느 것이 조립 후에도 유지되는지는 병합된 문서가 artifacts:에서 가져오는 것에서 다룹니다. cloudformation provider 페이지를 참조하십시오.

경계 범위: 경계의 공유 출력을 위한 파일

artifacts 메커니즘에는 두 번째 범위가 있습니다. 위에서 설명한 모든 것은 경계 출력 안에서 컴포넌트 자신의 위치에 기록됩니다. Recipe의 spec.boundary.artifacts는 같은 맵이며(같은 세 가지 형식, 같은 키-파일 이름 규칙, 같은 템플릿 컨텍스트), 대신 경계 전체를 위해 한 번 기록됩니다. 이는 대상이 경계가 배포하는 모든 것에 대해 한 번 읽는 파일, 즉 어떤 컴포넌트의 자체 위치에도 둘 수 없는 파일을 위해 존재합니다. Terraform 문서에 따르면 호출되도록 만든 모듈에는 provider 블록이 있으면 안 되며, 이 블록이 있는 모듈은 depends_on, count, for_each와 함께 호출할 수 없습니다. 따라서 provider 구성은 컴포넌트의 모듈 안이 아니라 경계의 루트 구성에 속합니다.

배치 위치. 디스패치 그룹의 조립된 출력을 담는 디렉터리에, provider 자체 조립이 그곳에 기록하는 파일 옆에 놓입니다. terraform의 경우 루트 구성 옆입니다. 컴파일러는 Recipe가 렌더링하는 컴포넌트마다 해당 컴포넌트의 컨텍스트에 대해 각 항목을 한 번씩 평가하고 파일을 직접 기록합니다. provider에는 이 파일 중 어느 것도 전달되지 않으며, 어느 컴포넌트에서 왔는지 나타내는 표시도 파일에 찍히지 않습니다. 파일은 그것을 선언한 모든 기여자에게 속하기 때문입니다.

기여자들이 만나는 방식. 하나의 디스패치 그룹에 대한 모든 기여자가 선언한 파일은 이름으로 병합됩니다. 동일한 바이트로 선언된 하나의 이름은 하나의 파일이 됩니다. 서로 다른 바이트로 선언된 하나의 이름, 또는 provider의 조립이 직접 기록하는 이름은 해당 파일과 모든 기여자를 명시하며 빌드를 중단시킵니다. 이는 두 기여자가 하나의 출력 경로에 기록할 때 받는 거부와 같습니다. 따라서 두 Recipes가 필요로 하는 provider 구성은 둘 다 하나의 이름으로 기록하며, 빌드는 두 내용이 일치하는지 확인합니다.

누가 받아들이는가. 경계의 조립된 출력 옆에 놓인 파일이 의미를 갖는지는 provider 대상의 속성이므로, 이는 provider 자체의 선언이며 입력 종류와 마찬가지로 provider 자체의 선언에서 읽습니다. 이를 선언하지 않은 provider에 대해 이 블록을 선언한 Recipe는 아무것도 렌더링되기 전에 거부됩니다. 아래 표는 이 선언을 마지막 열로 나타내며, 컴파일러와 함께 배포되는 provider 중에서는 terraform이 이를 선언합니다.

Artifacts가 아닌 것

세 가지 구조적 구분:

단일 Recipe 안에서 provider를 넘나들지 않습니다. Recipe는 spec 최상위에 정확히 하나의 capability:를 선언합니다. Recipe가 생성하는 모든 것(소스 렌더링 출력, workload 합성 출력, artifact 출력)은 해당 provider의 네이티브 형식입니다. helm Recipe의 artifacts에는 Kubernetes YAML이 들어 있습니다. compose Recipe의 artifacts에는 compose 조각이 들어 있습니다. Recipe는 하나의 provider를 대상으로 하며, 모든 출력은 해당 provider의 네이티브 형식입니다.

여러 provider에 걸친 구성은 Release 수준에서 이루어집니다. 경계는 여러 provider의 컴포넌트를 함께 담으며, 경계의 평가된 경로에 있는 각 provider의 기여자는 (경로, provider)별로 독립적으로 디스패치되고 조립됩니다. 각각 helm, helm-chart, compose를 대상으로 하는 컴포넌트를 가진 Release는 세 컴포넌트를 모두 하나의 경계에 둘 수 있습니다. 디스패치 그룹화가 이들을 provider별로 나누고, 각 provider의 기여자는 경계 경로 아래 자체 조립 출력에 배치되며, 운영자는 선택한 경계 구조를 통해 provider 간 조정을 작성합니다. provider 간 조정은 Release 작성자의 책임입니다.

Recipe 안의 Recipes가 아닙니다. Artifacts는 다른 Recipes를 로드하거나 구성하지 않습니다. 이들은 이 Recipe의 기둥으로 템플릿 처리되어 이 Recipe의 출력으로 내보내지는 인라인 매니페스트(또는 인라인 매니페스트에 대한 파일 경로)입니다. Recipe 재사용은 세 가지 메커니즘으로 이루어집니다. Component의 extends:(기본 Component를 대상으로 작성된 Recipe는 그것을 확장하는 모든 Component에 쓰이며, 상속되는 것은 출력 파일이 아니라 메타데이터와 스키마입니다. Recipe 자체는 extends:를 선언하지 않습니다), Manifest의 평면 URI 매핑(같은 Component가 카탈로그마다 다른 Recipes로 해석될 수 있음, ../language-reference/entities/manifest.md 참조), 그리고 Features + FeatureRecipes(직교적으로 연결되는 횡단 관심사)입니다.

Recipe 간 접착 계층이 아닙니다. Artifacts는 Recipe가 직접 선언하지 않은 이름, 리소스, 상태를 참조할 수 없습니다. Recipe의 Workload가 참조하는 ConfigMap artifact는 이 Recipe가 내보내야 합니다. 외부에서 프로비저닝된 Secret을 기대하는 artifact는 그 Secret이 존재한다고 가정하지 말고, .features 기둥을 통해, 즉 이를 내보내는 연결의 해석된 provides에서 그 Secret의 이름을 얻어야 합니다. 이는 위의 자기 완결성 불변식을 artifact 작성 관점에서 기술한 것입니다. 각 Recipe는 하나의 형식으로 된 파일을 내보내며, 이 파일은 하나의 도구로 하나의 경계 출력 디렉터리에 적용됩니다.

Provider 기능 매트릭스

각 provider는 자신이 렌더링하는 입력 종류를 선언합니다. 중앙의 입력 종류 게이트는 노드가 렌더링될 때 지원되는 조합을 받아들이고 나머지는 일관된 진단과 함께 거부합니다. 기능은 Recipe가 아니라 provider의 속성이며, provider는 세 가지 종류 중 일부를 렌더링합니다. artifacts: 열은 소스 기반/합성된 주 입력과 함께 실리는 artifacts와 독립형 artifacts 전용 Recipe(source:도 workload:도 없음)를 구분합니다. 마지막 두 열은 provider가 omits:를 존중한다는 주장과, Recipe가 boundary.artifacts: 아래에서 경계의 공유 출력에 기여하는 파일을 받아들인다는 주장입니다(위 참조). 둘 다 입력 종류가 아닙니다.

각 열은 따로 읽어야 합니다. 한 행은 provider가 어떤 종류를 하나씩 따로 렌더링하는지를 나타냅니다. 체크된 두 종류를 함께 선언할 수 있다는 뜻은 아닙니다. 종류들은 덧셈으로 구성되므로 선언된 각 종류는 별도로 디스패치되고 출력됩니다. 따라서 어느 열에도 나타나지 않는 이유로 조합이 거부될 수 있으며, 가장 흔한 이유는 두 종류가 같은 출력 이름으로 파일을 생성하는 경우입니다. 각 provider가 실제로 받아들이는 조합은 각 provider가 받아들이는 것 전체에서 설명합니다.

Providersource: + valuesMapping:workload:artifacts: (함께)artifacts 전용 (독립형)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ [[ ]] 구분자로 템플릿 처리❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

이 표는 컴파일러와 함께 배포되는 provider를 다룹니다. 별도로 제공되는 provider도 같은 방식으로 자신이 받아들이는 입력 종류, omits: 존중 여부, boundary.artifacts: 수용 여부를 선언하며, 컴파일러는 같은 경로로 그 선언을 읽습니다. 게시된 페이지는 본 적 없는 provider를 열거할 수 없으므로 여기에는 나열되지 않습니다.

✅로 표시된 칸은 렌더링되며, ❌는 게이트가 드러내는 provider 기능상의 거부입니다. 노드별 compose 조각은 조립 경로 단위로 병합되므로, directory:를 공유하는 경계들은 하나의 파일을 공유합니다.

각 provider가 받아들이는 것 전체

helm — 모든 조합. source: + valuesMapping:, workload:, artifacts:, 그중 두 가지, 또는 세 가지 모두입니다. 컴파일러와 함께 배포되는 provider 중 어떤 조합도 거부하지 않는 유일한 provider이며, 그 이유는 출력의 이름을 짓는 방식에 있습니다. 출력되는 각 파일은 그 안의 리소스 이름을 따르므로, 차트의 렌더링된 매니페스트와 합성된 Workload의 매니페스트가 같은 이름에 놓이는 일이 없습니다. 세 가지를 모두 선언한 Recipe는 차트의 파일, Workload의 파일, artifact 파일을 경계의 출력 디렉터리에 나란히 출력합니다.

compose — source:와 workload:가 함께 나타나는 두 가지를 제외한 모든 조합. 각 종류는 단독으로 빌드되며, artifacts:는 어느 쪽과도 함께 실릴 수 있습니다. source:와 workload:의 조합은 빌드할 수 없고, 세 가지 모두의 조합도 마찬가지입니다. 그 이유는 compose가 source와 workload를 결합할 수 없는 이유에서 설명하며, 이는 기능상의 거부가 아닙니다.

helm-chart — source: + valuesMapping:, 단독 또는 artifacts:와 함께. 그 외에는 없습니다. workload:를 합성하지 않으며 artifacts 전용 형태도 없습니다. 유일한 입력 종류가 artifacts:인 Recipe는 중단됩니다. 그 이유는 이 provider가 artifact를 컴포넌트 자체의 차트 안에 두기 때문이며, source:가 없는 Recipe는 artifact를 넣을 차트를 남기지 않습니다.

terraform — 세 가지 형태: source: + valuesMapping: 단독, artifacts: 단독, 또는 둘의 조합입니다. workload:는 합성하지 않습니다.

cloudformation — terraform과 같은 세 가지 형태이며, 같은 한 가지 제외 사항이 있습니다. source: + valuesMapping: 단독, artifacts: 단독, 또는 둘의 조합이며, workload:는 없습니다.

거부된 입력 종류의 모습

바인딩된 provider가 렌더링하지 않는 입력 종류를 선언한 Recipe는 노드가 렌더링될 때 빌드를 중단시키며, Recipe가 그 종류와 함께 무엇을 선언했든 중단됩니다. provider가 렌더링할 수 있는 source:와 workload:를 짝지어도 workload가 통과되지는 않습니다. 중단 메시지는 provider, 렌더링할 수 없는 종류, 렌더링하는 종류를 명시합니다.

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

artifacts 전용 거부도 같은 방식으로 표시되며 해당 형태를 명시합니다: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). 지속적 통합 게이트, 이슈, 런북 등에서 이 중단을 지속적으로 지칭해야 할 때 기록할 식별자는 E0265이며, 모든 조건의 표에서 이를 확인할 수 있습니다.

compose가 source와 workload를 결합할 수 없는 이유

compose provider는 컴포넌트마다 하나의 조각을 생성하고 그 조각에 컴포넌트의 이름을 붙입니다. 소스 기반 렌더링과 Workload 합성은 각각 그 하나의 이름으로 해당 컴포넌트의 조각을 생성하므로, 둘 다 선언한 Recipe는 같은 이름의 파일 두 개를 생성하고 빌드는 이 충돌로 중단됩니다.

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

조각의 이름은 컴포넌트 자체의 식별자에서 오며 이를 작성할 수 있는 수단이 없으므로, Recipe 자체의 내용을 바꿔서는 충돌을 피할 수 없습니다. 이 중단은 어느 한 종류가 아니라 조합의 속성입니다. compose는 source를 렌더링하고 Workload도 합성하므로, 표에서 둘 다 체크한 것은 옳습니다. compose에서 한 컴포넌트에 두 형태를 모두 쓰려면 두 컴포넌트로 나누거나 source의 내용을 Workload에 합치십시오.

병합된 문서가 artifacts:에서 가져가는 내용

두 provider는 기여자들을 assembly 경로마다 하나의 문서로 병합합니다. compose는 하나의 docker-compose.yaml로, cloudformation은 하나의 스택 템플릿으로 병합합니다. 병합된 문서는 해당 assembler가 모델링하는 섹션만 담을 수 있으므로, artifacts: 표시는 fragment의 내용이 어디에 배치되는지를 나타낼 뿐 fragment 안의 모든 키가 유지된다는 뜻이 아닙니다.

compose는 artifact fragment에서 services:, volumes:, configs:, models:를 x- 접두사가 붙은 확장 키와 함께 가져갑니다. fragment가 최상위 수준에 그 밖의 것을 선언하면 빌드는 해당 키를 명시하며 중단됩니다. networks:는 네트워크가 기여자로부터 누적되지 않고 boundary마다 도출되기 때문에 중단 대상이며, secrets: 블록이나 최상위 name:도 마찬가지입니다. compose provider 페이지에서 키별 병합 규칙과 네트워크 간 라우팅을 위한 대안을 설명합니다.

cloudformation은 Resources, Outputs, Parameters, Mappings, Conditions, Metadata, Rules를 가져가며, 모든 기여자의 값으로 Transform을 구성합니다. transform은 CloudFormation이 문서화한 순서로 결합되고, SAM의 Globals는 이를 읽는 transform과 함께 전달되며, 다른 기여자의 내용이 배포되는 방식을 바꿀 transform은 이름을 밝히며 빌드를 중단시킵니다. Description은 가져가지 않으며, 빌드가 이를 알립니다. 스택이 가져가지 않는 다른 최상위 키와 마찬가지로 섹션과 component를 명시하는 unsupported-field 경고를 발생시키므로, 아무것도 조용히 버려지지 않습니다. 이 경고는 권고 사항일 뿐이며, 생성된 템플릿은 경고가 없을 때와 바이트 단위로 동일하고, --no-unsupported-field-warnings로 이 경고 유형을 끌 수 있습니다. Outputs는 provider가 기여한 component로 범위를 지정한 이름으로 전달되므로, 두 component가 하나의 스택에 같은 이름의 output을 기여해도 서로 구분됩니다. 조립된 스택의 최상위 섹션에서 모든 섹션을 하나씩 설명합니다.

나머지 세 provider는 병합하지 않으므로, assembler에 의해 artifact 키가 버려질 위험이 없습니다. helm은 아무것도 조립하지 않습니다. 각 component의 manifest는 그대로 boundary의 출력 디렉터리에 도달합니다. terraform과 helm-chart는 중첩합니다. 각 component의 파일은 Terraform 모듈 디렉터리나 subchart 같은 고유한 디렉터리에 놓이고, boundary의 루트 문서가 이를 참조합니다. 따라서 artifact 항목은 공유 문서로 읽혀 들어가지 않고 하나의 온전한 파일로 배치됩니다. helm-chart artifact 항목이 어디에 놓이는지와 그 구분자 쌍이 왜 다른지는 Per-Provider Artifact Semantics에서 설명합니다.